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:
1 parent
456f9816f4
commit
0e21730b9f
5 files changed
+117
-7
No files matched your search
@@ -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):
|
||||
|
||||
Reference in new issue
Block a user