# Agent boundaries — __PROJECT_NAME__

Operational scope for this agent. Read before extending tools, adding endpoints,
or wiring new data sources. Defaults are conservative; widen explicitly.

## Network scope

Egress is allow-listed. The agent MAY reach:

| Endpoint                       | Purpose                          | Protocol | Default port |
|--------------------------------|----------------------------------|----------|--------------|
| `llm-api.d-ma.be` (LiteLLM)    | Model inference                  | HTTPS    | 443          |
| `brain-mcp.d-ma.be`            | Knowledge base (BM25 + synth)    | HTTPS    | 443          |
| `gitea-mcp.d-ma.be`            | Repo/issue/PR ops                | HTTPS    | 443          |
| `jaeger.d-ma.be`               | OTLP trace export                | HTTP     | 4318         |
| In-cluster DNS (`kube-dns`)    | Service discovery                | UDP      | 53           |

Egress MUST be blocked to:

- Public Slack / Discord / Telegram / email
- Third-party LLM APIs (OpenAI, Anthropic, Google) unless explicitly added below
- Public package registries from runtime (proxy through build only)
- Customer/client domains not listed in the engagement scope

Add new endpoints by editing this table in the same commit that wires them, and enforce them
with whatever egress mechanism the deployment uses (e.g. a k8s NetworkPolicy in the project's
own deploy manifests).

## File scope

Read scope:

- Mounted ConfigMaps and Secrets under `/etc/__PROJECT_NAME__/`
- Working dir under `/var/lib/__PROJECT_NAME__/` (ephemeral)
- `/tmp` for streaming artifacts (size-capped via emptyDir)

Write scope:

- `/var/lib/__PROJECT_NAME__/` only
- `/tmp` only
- Never `/`, `/etc`, `/var/log`, host paths, or sibling pod volumes

Persistent state MUST live in PostgreSQL (`postgres.d-ma.be`) or object storage —
not the pod filesystem.

## Approved operations

The agent MAY:

- Issue LLM inference requests via the LiteLLM adapter
- Query the brain MCP for prior art / postmortems
- Read repos, issues, and PRs via gitea-mcp
- Emit OTLP spans for `invoke_agent`, `generate_content`, and any custom tool spans
- Write to its own k8s logs (stdout/stderr; structured `slog`)

The agent MUST NOT, without explicit opt-in in code review:

- Write to gitea (open PR, push branch, comment) — requires `--write` flag and audit log
- Execute shell commands in non-sandboxed contexts
- Mutate k8s resources (no kubectl/Helm/Flux operations from runtime)
- Forward LLM outputs to external systems before redaction
- Hold conversation logs longer than the session TTL (24h default)

## Failure posture

- Outbound DNS failure → fail closed, retry with jitter, surface to caller
- LLM 5xx → bounded retry (3 attempts), then return error to caller
- Brain MCP unavailable → continue without prior-art lookup; log degraded mode
- OTLP unavailable → drop spans silently; never block request path

## Review triggers

Bump this doc (and the deployment's egress enforcement) when:

- A new external endpoint is added
- A new tool with side effects is wired in
- The agent gains write access to anything (repo, DB table, filesystem path)
- A client engagement narrows or widens the data scope