Local Agent E2e

Local Agent E2E

Run a persistent endpoint stack against the published Backend contract:

Codex or Claude Code -> explicit abyss-broker proxy -> provider
                              |
                              v
                    abyss-delivery-plugin
                              |
                              v
              published abyss-backend -> PostgreSQL

Backend source, migrations, frontend behavior, and service deployment are owned by the abyss-backend and abyss-services repositories. Do not recreate or patch those concerns in this endpoint repository.

Protect Existing Tests

• Do not reuse resources owned by scripts/blackbox_*.sh or scripts.agent_e2e_ci.
• Keep persistent state under /tmp/abyss-local-agent-e2e by default and prefix Docker resources with abyss-local-agent-e2e.
• Do not install the E2E CA in the system trust store. Pass its PEM only to the Agent process under test.
• Never print the deployment bearer, broker token, or CA private key.
• Reuse only a healthy stack proven to belong to this skill. Do not kill an unrelated process to claim a port.

Backend Stack

1. Read the immutable image reference from scripts/ci/abyss-backend-image.txt. Pull it as linux/amd64 unless an intentionally selected compatible image declares another platform.
2. Create a random raw bearer and store it mode 0600 under the runtime root. Compute its lowercase SHA-256 hex digest without printing either value.
3. Create a dedicated Docker network and start postgres:16 with an empty abyss database. Wait for pg_isready.
4. Start the published Backend image on the same network and expose it only on a loopback host port. Configure:

ABYSS_BACKEND_ADDR=0.0.0.0:8080
ABYSS_BACKEND_ENV=blackbox
ABYSS_BACKEND_BLACKBOX_ALLOW_NON_LOOPBACK=true
ABYSS_BACKEND_API_TOKEN_SHA256=<sha256-of-raw-bearer>
ABYSS_BACKEND_DATABASE_URL=postgres://abyss:abyss@abyss-local-agent-e2e-postgres:5432/abyss?sslmode=disable
ABYSS_BACKEND_RUN_MIGRATIONS=true

5. Wait for /readyz. Do not seed app_users, native_auth_sessions, or any other Backend-owned database table; standalone authentication is the deployment bearer configured at process startup.

Broker and Delivery

Build current endpoint binaries:

cargo build --locked --package abyss-broker --package abyss-delivery-plugin

Generate a short-lived CA under the runtime root with the filenames required by abyss-mitm:

abyss-root-ca.pem
abyss-root-ca.der
abyss-root-ca-key.pem

Write runtime-only broker-config.toml, runtime-policy.toml, and product-config.json files using the public broker and policy defaults in crates/abyss-cli/defaults plus a deployment-local product profile following docs/configuration.md. Select explicit proxy mode, intercept only the provider domains being tested, enable the desired Harness, and configure the delivery plugin endpoint as:

http://127.0.0.1:<backend-port>/v1/agent-usage/events

Store Bearer <raw-bearer> in a mode 0600 authorization file referenced by the delivery configuration. Start the Broker first, discover its automatically selected REST API from startup-info.json, then start the delivery plugin. Require Broker health, proxy status, and a running delivery process before sending provider traffic.

Run and Verify an Agent

Set proxy and CA variables only for the Agent child process. Keep Backend and Broker loopback addresses in NO_PROXY and clear unrelated proxy values.

For Codex:

HTTP_PROXY=http://127.0.0.1:<proxy-port> \
HTTPS_PROXY=http://127.0.0.1:<proxy-port> \
NO_PROXY=localhost,127.0.0.1,::1 \
CODEX_CA_CERTIFICATE=<runtime-root>/ca/abyss-root-ca.pem \
SSL_CERT_FILE=<runtime-root>/ca/abyss-root-ca.pem \
codex exec <arguments>

For Claude Code, also set NODE_EXTRA_CA_CERTS to the same PEM. Use a disposable workspace and a prompt that triggers the content being validated.

Verify every boundary:

1. The real Agent request succeeds through the explicit proxy.
2. Broker and delivery logs contain no parse, upload, or spool failures.
3. An authenticated GET /v1/agent-usage/events using the deployment bearer contains the matching session and event markers.
4. Tool call/result identifiers, turn identifiers, content policy, and provider usage fields match the captured exchange.
5. The delivery spool is empty after successful upload.

Stop or Preserve

Keep the stack running unless the user asks to stop it. On stop, resolve exact PIDs and Docker resource names first, stop only this skill's processes and containers, remove only its dedicated network, and preserve the runtime root by default for diagnostics.