# 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 `agent-policy.yaml` AND this table in the same commit.

## 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 + `agent-policy.yaml` 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