Document coding agents and give them a sandbox image

Agents work on this repository in the agent-envs sandbox: a container
whose only way out is an egress proxy with an allowlist, which also adds
the Gitea bot token. docs/contributing/agents.md covers setting it up
for Politrack (1Password item, .env, commit identity), what it can reach
and its limits; AGENTS.md tells agents how to recognise the sandbox and
behave in it.

backend/tests/Dockerfile.debian gains a `sandbox` target: the agent-envs
agent image plus the backend's dependencies from Debian packages, the
same list as the PyPI-free test image (still the default target). The
sandbox runs `pytest` without PyPI, which the owner's PC can't reach. A
new invariant in AGENTS.md keeps that list in step with pyproject.toml.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
simonandClaude Opus 5.5 committed 2026-10-28 23:59:01 +01:00
1 parent 456f9816f4
commit 0e21730b9f
5 files changed
+117 -7

No files matched your search

+21
View File
@@ -19,6 +19,7 @@ next-intl, German by default, English at `/en`. Deployed with Docker Compose on
| UI page or new claim type in the UI | [docs/contributing/frontend.md](docs/contributing/frontend.md) |
| How the UI should look and read | [docs/design/README.md](docs/design/README.md), [design-system.md](docs/design/design-system.md) |
| Tests and fixtures | [docs/contributing/testing.md](docs/contributing/testing.md) |
| Agent sandbox: setup, what it can reach | [docs/contributing/agents.md](docs/contributing/agents.md) |
| Why it is built this way | [docs/architecture/02-comparison-and-decisions.md](docs/architecture/02-comparison-and-decisions.md) |
| Tables, claim types, identifier schemes | [docs/data-model.md](docs/data-model.md) |
| What each source allows | [docs/sources.md](docs/sources.md), [docs/legal.md](docs/legal.md) |
@@ -57,6 +58,10 @@ next-intl, German by default, English at `/en`. Deployed with Docker Compose on
- **API types:** after changing a response model, regenerate the frontend types:
`cd backend && politrack openapi --ts ../web/src/lib/api-types.ts`.
- **UI text:** every new key goes into both `web/messages/de.json` and `en.json`.
- **Backend dependencies:** a dependency added to or changed in `backend/pyproject.toml` also goes
into the Debian package list in `backend/tests/Dockerfile.debian` (usually `python3-<name>`). That
list builds both the PyPI-free test image and the agent sandbox image; without the entry, tests
there fail on the import. If Debian doesn't package it, add it to the exceptions in the file's header.
## Commands
@@ -68,6 +73,22 @@ politrack reparse <adapter> # re-parse archived respon
politrack enrich | status | review | migrate # enrichers, recent runs, legal review, schema
```
## In the agent-envs sandbox
You are in the sandbox if the repository is at `/workspace` and `HTTPS_PROXY` is `http://egress:8080`
([details](docs/contributing/agents.md)). There:
- **Network:** only allowlisted hosts. HTTP 403 "Blocked by egress policy" means the host isn't
allowed: tell the owner which host you need instead of working around it.
- **Git:** pushing and Gitea API calls over HTTPS work without credentials; the proxy adds them.
Don't set up tokens or credential helpers. The commit identity comes from the repository's config.
- **Tests:** the sandbox image has the backend's dependencies from Debian packages, so
`cd backend && python3 -m pytest -q` works without `pip install`. It comes from
`backend/tests/Dockerfile.debian` (see "Backend dependencies" above).
- **No Docker, no database.** Leave adapter runs against the database and the compose stack to the
owner. The notes below on Git's `safe.directory` don't apply in the sandbox; the PyPI and npm block
does when the session runs on the owner's PC.
## The owner's development machine
These notes apply to the owner's Windows PC (Docker Desktop, Git Bash, PowerShell):