contraagent 0.1.0__tar.gz

contraagent-0.1.0/.dockerignore

@@ -0,0 +1,13 @@
+# The build context of Dockerfile (the developer's hub image) is the repository root; only what the image installs
+# enters it. Everything else (.git, .venv, node_modules, web/, runs, .claude/, tokens)
+# stays out.
+*
+!pyproject.toml
+!uv.lock
+!LICENSE
+!src/
+**/__pycache__
+**/*.py[cod]
+**/.env
+src/contraagent/docs/examples/hub/secrets
+src/contraagent/docs/examples/hub/*.whl

contraagent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,130 @@
+# Lint, type-check and test on every supported Python on Linux and on one
+# Python on macOS and Windows, plus one run against the lowest versions of the
+# direct dependencies that pyproject.toml allows. release.yml runs it too, on
+# a release's tag, so a push of a tag starts no run of its own here.
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+# A newer push to the same branch cancels the run still going for an older one.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python: "3.13"
+          - os: windows-latest
+            python: "3.13"
+    steps:
+      # The files as committed: a CRLF checkout on Windows would change bytes the tests compare.
+      - run: git config --global core.autocrlf false
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}   # overrides .python-version
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      # Every OS's branches type-check on every runner.
+      - run: uv run pyright --pythonplatform Linux
+      - run: uv run pyright --pythonplatform Darwin
+      - run: uv run pyright --pythonplatform Windows
+      - run: uv run lint-imports
+      # pyproject.toml's addopts leave out the live, e2e and perf tests; the e2e
+      # tests need docker and run on Linux only (`uv run pytest -m e2e`).
+      - run: uv run pytest --cov
+
+  lowest-direct:
+    name: Lowest direct dependencies (Python 3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          # 3.12: the lowest pydantic-core has no wheel for 3.14.
+          python-version: "3.12"
+          enable-cache: true
+      # Deselected here only: the committed openapi.json documents of the
+      # monitor and the hub are generated by the locked fastapi/pydantic and
+      # differ byte-for-byte under the oldest ones, and starlette's old
+      # TestClient cannot parse an IPv6 base URL.
+      - run: >-
+          uv run --isolated --resolution lowest-direct pytest
+          --deselect tests/test_monitor_api.py::test_the_committed_openapi_document_is_current
+          --deselect tests/test_hub_server.py::test_the_committed_openapi_document_is_current
+          --deselect tests/test_monitor_api.py::test_only_local_host_names_are_answered
+
+  web:
+    name: Web UI (types, lint, tests, committed build)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v6
+      # The docs site renders the packages' documentation with `contraagent.docs`.
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+        working-directory: .
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      # The generated API types match the committed OpenAPI document.
+      - run: pnpm gen --check
+      # Every message is extracted, translated, and built into src/locales.
+      - run: pnpm i18n
+      - run: git diff --exit-code -- packages/ui/xliff packages/ui/src/locales
+      - run: pnpm --filter @contraagent/ui i18n:check
+      - run: pnpm typecheck
+      - run: pnpm lint
+      - run: pnpm test
+      # The monitor serves the built UI from src/contraagent/_internal/monitor/static,
+      # which is committed: rebuilding must not change it.
+      - run: pnpm build
+      # What an npm consumer gets: the built packages' types resolve on their own.
+      - run: pnpm check:dist
+      - run: git diff --exit-code -- ../src/contraagent/_internal/monitor/static
+      - run: test -z "$(git status --porcelain -- ../src/contraagent/_internal/monitor/static)"
+
+  web-e2e:
+    name: Web UI end to end (Back, Forward, reload)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+        working-directory: web
+      - run: pnpm exec playwright install --with-deps chromium
+        working-directory: web
+      # Builds the page, runs the demo pipeline, serves it with the real monitor.
+      - run: pnpm e2e
+        working-directory: web

contraagent-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,57 @@
+# Build the documentation site (web/apps/docs) and deploy it to GitHub Pages,
+# https://t-tani.github.io/contraagent/, on every push to main. The site is
+# built for that base path (web/apps/docs/site.ts).
+name: Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deploy at a time; a newer push waits for the deploy in progress, which
+# runs to its end.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build the documentation site
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v6
+      # The docs site renders the packages' documentation with `contraagent.docs`.
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+        working-directory: .
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: web/apps/docs/dist
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

contraagent-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,254 @@
+# Publish a release: a push of the tag `X.Y.Z` publishes the Python package
+# `contraagent` to PyPI and @contraagent/api, @contraagent/elements and
+# @contraagent/ui to npm, both through Trusted Publishing (OIDC, no tokens), and
+# creates the GitHub release with that version's section of CHANGELOG.md.
+#
+# Run by hand (workflow_dispatch) with `testpypi` on, it is a dry run: the
+# Python package goes to TestPyPI (environment `testpypi`), `npm publish
+# --dry-run` checks each npm tarball, and no GitHub release is made. With `testpypi` off it must run on a
+# tag, and it publishes that tag as a push would.
+#
+# The steps for the person who releases: docs/releasing.md.
+name: Release
+
+on:
+  push:
+    tags: ["[0-9]+.[0-9]+.[0-9]+"]
+  workflow_dispatch:
+    inputs:
+      testpypi:
+        description: "Dry run: publish to TestPyPI and run npm publish --dry-run"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+# One release at a time for one ref, never cancelled half-way. The group must
+# differ from ci.yml's, which runs here with this workflow's name and ref.
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  check:
+    name: Versions and changelog
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.versions.outputs.version }}
+      dry: ${{ steps.versions.outputs.dry }}
+    steps:
+      - uses: actions/checkout@v6
+      # The tag, pyproject.toml and the three package.json name one version, and
+      # the npm packages depend on each other at it (`workspace:*`, which
+      # `pnpm pack` writes as the exact version, or that version itself).
+      - id: versions
+        env:
+          DRY: ${{ github.event_name == 'workflow_dispatch' && inputs.testpypi }}
+          REF_TYPE: ${{ github.ref_type }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          python3 - <<'EOF'
+          import json, os, re, sys, tomllib
+          from pathlib import Path
+
+          dry = os.environ["DRY"] == "true"
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          errors = []
+          if not re.fullmatch(r"\d+\.\d+\.\d+", version):
+              errors.append(f"pyproject.toml: version {version} is not X.Y.Z")
+          if os.environ["REF_TYPE"] == "tag":
+              if os.environ["REF_NAME"] != version:
+                  errors.append(f"tag {os.environ['REF_NAME']} differs from pyproject.toml's version {version}")
+          elif not dry:
+              errors.append(f"a release runs on a tag, not on {os.environ['REF_TYPE']} {os.environ['REF_NAME']}")
+          manifests = [json.loads(Path(f"web/packages/{d}/package.json").read_text()) for d in ("api", "elements", "ui")]
+          names = {m["name"] for m in manifests}
+          for m in manifests:
+              if m["version"] != version:
+                  errors.append(f"{m['name']}: version {m['version']}, not {version}")
+              for field in ("dependencies", "peerDependencies", "optionalDependencies"):
+                  for name, spec in m.get(field, {}).items():
+                      if name in names and spec not in ("workspace:*", version):
+                          errors.append(f"{m['name']}: {field}.{name} is {spec}, not workspace:* or {version}")
+
+          # The version's section of CHANGELOG.md, which `towncrier build` writes:
+          # from its `## [X.Y.Z]` heading to the next release's heading.
+          text = Path("CHANGELOG.md").read_text()
+          section = re.search(rf"^## \[{re.escape(version)}\][^\n]*\n(.*?)(?=^## \[|\Z)", text, re.M | re.S)
+          if section and section.group(1).strip():
+              Path("notes.md").write_text(section.group(1).strip() + "\n")
+          elif dry:
+              print(f"::warning::CHANGELOG.md has no section for {version}; a release needs one")
+          else:
+              errors.append(f"CHANGELOG.md has no section for {version}: uv run towncrier build --version {version}")
+
+          for e in errors:
+              print(f"::error::{e}")
+          if errors:
+              sys.exit(1)
+          with open(os.environ["GITHUB_OUTPUT"], "a") as out:
+              out.write(f"version={version}\ndry={'true' if dry else 'false'}\n")
+          print(f"version {version}, {'dry run' if dry else 'release'}")
+          EOF
+      - if: steps.versions.outputs.dry == 'false'
+        uses: actions/upload-artifact@v7
+        with:
+          name: notes
+          path: notes.md
+          if-no-files-found: error
+
+  # Every job of ci.yml: the full test suite on every platform, and the web checks.
+  test:
+    name: CI
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    name: Python and npm packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - run: uvx twine check --strict dist/*
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+        working-directory: web
+      # The tarballs as npm receives them: each dependency on another of the
+      # three names its exact version.
+      - run: pnpm tarballs:registry
+        working-directory: web
+      - run: node scripts/packed.mjs tarballs/*.tgz
+        working-directory: web
+      - uses: actions/upload-artifact@v7
+        with:
+          name: python
+          path: dist/
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v7
+        with:
+          name: npm
+          path: web/tarballs/
+          if-no-files-found: error
+
+  pypi:
+    name: PyPI
+    needs: [check, test, build]
+    if: needs.check.outputs.dry == 'false'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/contraagent
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: python
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+
+  # The dry run's upload, in its own environment: `pypi` accepts only tags.
+  testpypi:
+    name: TestPyPI
+    needs: [check, test, build]
+    if: needs.check.outputs.dry == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/contraagent
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: python
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # TestPyPI keeps a version once uploaded: a second dry run of it passes.
+          skip-existing: true
+
+  npm:
+    name: npm
+    needs: [check, test, build]
+    if: needs.check.outputs.dry == 'false'
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+      url: https://www.npmjs.com/org/contraagent
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: npm
+          path: tarballs/
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      # Trusted publishing needs npm 11.5.1 or later; Node 22 brings npm 10.
+      - run: npm install --global npm@11.21.0
+      # In the order they depend on each other: api, elements, ui. A version
+      # already on npm stays as it is: the first one, which the owner publishes
+      # by hand (docs/releasing.md), or one from a run that failed part way.
+      - env:
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          for name in api elements ui; do
+            if npm view "@contraagent/$name@$VERSION" version >/dev/null 2>&1; then
+              echo "::notice::@contraagent/$name@$VERSION is on npm already"
+              continue
+            fi
+            npm publish "tarballs/contraagent-$name-$VERSION.tgz" --access public --provenance
+          done
+
+  # The dry run's npm side: the same npm and the same tarballs, with nothing
+  # sent, so it needs neither the `npm` environment nor a token.
+  npm-dry-run:
+    name: npm (dry run)
+    needs: [check, test, build]
+    if: needs.check.outputs.dry == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: npm
+          path: tarballs/
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npm install --global npm@11.21.0
+      - env:
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          for name in api elements ui; do
+            npm publish "tarballs/contraagent-$name-$VERSION.tgz" --access public --dry-run
+          done
+
+  release:
+    name: GitHub release
+    needs: [check, pypi, npm]
+    if: needs.check.outputs.dry == 'false'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: python
+          path: dist/
+      - uses: actions/download-artifact@v8
+        with:
+          name: notes
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.check.outputs.version }}
+        run: >-
+          gh release create "$TAG" dist/*
+          --repo "$GITHUB_REPOSITORY" --verify-tag
+          --title "$TAG" --notes-file notes.md

contraagent-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.venv/
+dist/
+build/
+*.egg-info/
+# what the demo and the live test leave behind
+demo-runs/
+demo-out/
+inputs/
+live-demo/
+.claude/worktrees/
+# what make-tokens writes beside the hub's compose example
+src/contraagent/docs/examples/hub/.env
+src/contraagent/docs/examples/hub/secrets/*
+!src/contraagent/docs/examples/hub/secrets/*.example
+src/contraagent/docs/examples/hub/*.whl
+.import_linter_cache/

contraagent-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+# pre-commit reads this file from the repository root.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.0
+    hooks:
+      - id: ruff-check
+      - id: ruff-format
+  - repo: local
+    hooks:
+      # Whole-project check against the locked environment, not per file.
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+      # The web UI: types and lint, when anything under web/ changes.
+      - id: web-check
+        name: web (typecheck, lint)
+        entry: bash -c 'cd web && pnpm typecheck && pnpm lint'
+        language: system
+        files: ^web/
+        pass_filenames: false

contraagent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

contraagent-0.1.0/AGENTS.md

@@ -0,0 +1,137 @@
+# contraagent
+
+`contraagent` runs coding-agent CLIs (`claude -p`, `omp -p`, Codex, opencode, pi)
+as typed, supervised tasks: a Python package (`src/contraagent/`) and a web monitor
+(`web/`). This file is for agents changing contraagent itself. Before changing
+anything under `web/`, read `web/AGENTS.md`.
+
+## Commands
+
+```
+uv run ruff check . && uv run ruff format --check .
+uv run pyright                # 0 errors; the "yaml" source warning is expected
+uv run pytest                 # parallel (xdist, at most 6 workers; -n0 for one); runs lint-imports too
+uv run pytest -m e2e          # the hub and relays as processes over Postgres and RustFS (docker)
+CONTRAAGENT_LIVE=1 uv run pytest -m live   # real coding agents; spends tokens
+```
+
+A committed file that a test compares against goes stale when its source changes;
+the test names it. Rewrite it with:
+
+| After changing | Run |
+|---|---|
+| the public API | `uv run python tests/api/snapshot.py` (`tests/api/contraagent.api.txt`) |
+| a command's arguments or help | `uv run python tests/cli/help.py` (`tests/cli/help.txt`, on the Python of `.python-version`) |
+| a monitor response model or route | `uv run contraagent monitor --openapi src/contraagent/_internal/monitor/openapi.json`, then `pnpm gen` in `web/` |
+| a run record model or the config's tables | `uv run python -m contraagent._internal.execution.file_schemas` (`src/contraagent/docs/schemas/`) |
+| what the monitor returns | `uv run python web/apps/docs/scripts/fixture.py` (the docs site's fixtures) |
+| what the CLI prints on the demo | `uv run python web/apps/docs/scripts/landing.py` |
+| the omp version | `uv run python tests/fixtures/omp/record.py` (spends a few cents), then `tests/test_omp_wire.py` |
+
+Release checks: `uv run pyright --verifytypes contraagent --ignoreexternal` (no unknown
+type outside `contraagent.docs`), `uv run griffe check --search src contraagent --against
+<last tag>` (breaking changes since a release; tags are `<version>`),
+`docker build -t contraagent-hub:dev .` (the hub's image).
+
+### Releasing
+
+A pushed tag `X.Y.Z` releases: `.github/workflows/release.yml` checks that the tag,
+pyproject.toml, the three package.json and CHANGELOG.md agree, runs ci.yml, and
+publishes to PyPI and npm. The steps and the one-time setup are in
+[docs/releasing.md](docs/releasing.md).
+
+A test never waits out a retry's backoff (`RetryingRunner.backoff` is 0 in the tests).
+Tests that share something across a module (one hub, the `live-demo` directory, an
+agent's rate limits) carry an `xdist_group`.
+
+## One word, one meaning
+
+The glossary is `src/contraagent/docs/concepts.md`. Every word there means exactly
+one thing in the code, the files a run writes, the monitor (API and UI), the
+documentation and the examples. Do not use one of these words in another sense, and
+do not add a second word for the same thing; a new word goes into the glossary first.
+The monitor's UI shows its own reader-facing words for the same terms
+(`web/packages/ui/WORDS.md`).
+
+Some names stay although they look like a second word: `--agent` (Claude Code's flag,
+from `Launch.role`), `Backend`/`create_backend`/`register_backend`/`known_agents` (keyed
+by agent name), `[tasks.<kind>]` and `kind`, `Route`/`Router`/hop (the failover chain:
+a route is one entry, a hop one launch on one route), `ambient` (the host's own
+credential), `effort`/`max_turns`/`max_budget_usd` (the agents' flag names), cursor
+`stage`, `streams/` and `*.stream.jsonl`, `hollow` (see `LaunchResult`), `RoutingPlan`
+(`plan.jsonl` is the queue).
+
+## Public API and layers
+
+The implementation is under `src/contraagent/_internal/`. Users import only the
+public modules (`contraagent`, `.config`, `.backends`, `.engine`, `.plugins`,
+`.monitor`, `.monitor.api`, `.testing`); each only re-exports names from `_internal`
+and calls `publish(__name__, __all__)`. A name that a user, the documentation or an
+example uses gets one public home; everything else stays in `_internal`. Keep public
+signatures small: a helper hides behind a method, a value returns the type it behaves
+as, and a function a user passes is a `Protocol`. `tests/test_public_api.py` checks
+the rest (one path per object, every reached type exported, no `**kwargs`, full types).
+
+Inside `_internal`, a layer imports only the layers listed before it in the
+`_internal/__init__.py` docstring; pass a callback or a protocol instead of importing
+a later layer. Every reader and writer of a run's files goes through `runs/`.
+`uv run lint-imports` checks this (pyproject.toml's
+`[tool.importlinter]`; an exception only as a commented `ignore_imports` line), and
+`tests/test_layers.py` runs it.
+
+## Documentation
+
+Each package holds its own documentation; its index lists its topics, and that list
+is the site's sidebar and what `contraagent docs` prints:
+`src/contraagent/docs/README.md`, `web/packages/ui/README.md`,
+`web/packages/elements/README.md`, `web/packages/api/README.md`.
+
+- The package documentation, the docstrings and the messages of `contraagent check`
+  are written for a coding agent that writes a pipeline from them alone: every fact it
+  needs is reachable from `contraagent docs`, without contraagent's source. The root
+  `README.md` and the monitor are for the person who asks for the pipeline, runs it
+  and reviews it.
+- Code is quoted, never pasted: `::code{file="..." from="..." to="..."}`. The examples
+  run in the tests (`tests/test_docs.py`), so update them with any API change. The root
+  `README.md` writes its code out, after `<!-- ::code{...} -->` lines that the same
+  test checks.
+- Facts live in the code (docstrings, `--help`, `examples/reference/pipeline.toml`,
+  `custom-elements.json`, `openapi.json`); prose points to them.
+- The site (`web/apps/docs`) is built from the packages' documentation by
+  `scripts/collect.py`; see `web/AGENTS.md`.
+
+Prose style, for the READMEs and topics: plain declarative sentences and short
+paragraphs. A paragraph or list item starts with a sentence that carries its point,
+not a bold run-in label; a part that needs a label gets a heading. Bold marks at most
+a few words in a page. A link sits on the words it names, never in a parenthetical
+after them. No slogan fragments, no "Label: fragment" sentences; vary the openings.
+Write global English: common words, no idioms, phrasal verbs or slang, no
+abbreviations but API, JSON, CLI, USD and units; the text must keep its meaning
+through machine translation.
+
+## Changes and commits
+
+- A user-visible change adds a fragment `changelog.d/<slug>.<type>.md` (types and
+  rules in `changelog.d/README.md`); towncrier writes `CHANGELOG.md` at a release.
+  `uv run towncrier check --compare-with origin/main` checks a branch.
+- Commit messages follow Google's CL description style: a short imperative first
+  line, a blank line, then a body that says what changed and why, wrapped at about
+  72 columns. No attribution trailers (`Co-Authored-By`, session links), no model
+  names, no local paths.
+
+## Compatibility
+
+The public API is what `src/contraagent/docs/compatibility.md` lists: the public
+modules' `__all__`, the command line, the config file, the files a run writes and the
+monitor's `openapi.json`. `contraagent._internal` is not public: change it freely,
+with no aliases or shims.
+
+- Until 0.1.0 is tagged, rename the public API freely too: no compatibility aliases,
+  no deprecation shims, no readers for old run directories; a changelog fragment
+  records each rename as old → new.
+- From 0.1.0, a public API change is deliberate: the snapshots show it, a fragment
+  records it, and it waits for a minor release (from 1.0, a major one, after
+  `ContraagentDeprecationWarning` for two minor releases, through `migration()` in
+  `_internal/public.py`). A run record change that the current reader cannot read
+  raises `FORMAT` in `_internal/runs/layout.py` and adds a fixture beside
+  `tests/fixtures/runs/v1/`; the monitor reads every format in `FORMATS`.