docs(architecture): simplify coding execution gateway

[christso]

Summary

AllAgents now has an implementation-ready, industry-aligned contract for a trusted-network coding-execution gateway. The decision and plan replace the earlier distributed gateway/worker design with one fail-closed service per project workspace, exact A2A 1.0 HTTP+JSON semantics, and enforceable execution, credential, storage, and recovery boundaries for Codex and Pi.

This remains the AllAgents half of a two-repository architecture. AI Evals is the first caller and continues to own evaluation commands, datasets, assertions, scoring, retries, durable evaluation Runs, and the Promptfoo custom provider that translates callApi into A2A.

Design decisions

• Treat external network reachability as authorization. The service has no application caller identity; explicit 0.0.0.0 binding is valid when Tailscale ACLs, firewalls, or equivalent controls provide the boundary.
• Isolate invocation descendants from that boundary. Provider, MCP, and model-tool roles use separate mount, environment, descriptor, secret, and network views and cannot reach the gateway, host loopback, ingress, or management networks.
• Run one foreground gateway process per project workspace. Configure service concerns through flags and environment variables; do not add gateway.yaml, worker.yaml, a worker service, or a private dispatch protocol.
• Resolve repositories and named OCI snapshots from the project workspace. Resolve built-in targets plus launcher-backed profiles only when the profile client declares gateway.enabled: true.
• Profile A2A 1.0 instead of cloning it. The Agent Card advertises the HTTP+JSON binding and streaming capability; every operation negotiates the version and required coding-execution extension; Tasks embed integrity and produced Artifacts.
• Let AI Evals consume that boundary through its own Promptfoo ApiProvider. Static config owns source mode and logical names; bounded test variables may replace full commits or immutable digests. Secure examples disable sharing, cache, result writes, and concurrency above one.
• Enforce one active invocation with a durable server-side execution lease. Consumer concurrency settings improve efficiency but are not a correctness boundary.
• Accept exactly two source modes: the complete configured repository set with optional named revision overrides, or one named OCI workspace snapshot with immutable OCI and workspace-manifest digests. A failed mode never falls through to the other.
• Prefer a fresh, repository-scoped GitHub App token for direct acquisition. Use account-pinned, ambient-token-sanitized gh only when the App is absent or proven ineligible; a selected-App failure never falls back.
• Use a minimal OCI Distribution client with a frozen direct-image format, descriptor verification, bounded extraction, and OCI changeset semantics. Registry metadata remains same-origin; only layer blobs may redirect to exact operator-declared hosts with per-hop address and rebinding checks.
• Put durable Task truth behind the packaged Rust helper's descriptor-rooted SQLite VFS. The helper also owns gated containment, cgroup membership, process reaping, safe file access, network namespaces, and non-bypassable MCP/tool spawn mediation.
• Persist an internal outcome intent while the public Task remains nonterminal. Publish terminal status, integrity Artifact, bounded evidence, result or failure, cleanup, and lease release atomically after quiescence.
• Keep the gateway out of evaluation orchestration, automatic retry, remote-worker routing, and multi-tenant hostile-code sandbox claims.

Session-settled decisions

• The first deployment is trusted-network and single-process, with no application authentication layer.
• Codex and Pi are the initial executable backends; arbitrary launcher execution is excluded.
• Existing project and user workspace files are authoritative configuration.
• GitHub source authentication is App-first with narrowly eligible gh fallback.
• Remote workers, custom materializers, evaluator behavior, and broader backend support are deferred.

Implementation contract

The plan at docs/plans/2026-09-18-0837-feat-coding-execution-gateway-plan.md defines 19 requirements, 6 flows, 21 acceptance examples, 12 key technical decisions, and 7 dependency-ordered implementation units.

The accepted decision is docs/decisions/0002-serve-coding-agent-execution-through-an-a2a-gateway.md. Supporting research records the A2A/AHP boundary, Harbor materialization lessons, and source-credential precedents.

Audit basis

The contract was checked against the A2A 1.0 specification, Promptfoo configuration reference, OCI Image specification, OCI Distribution specification, Docker credential-helper behavior, and GitHub App token guidance.

Independent protocol, security, and feasibility re-reviews found no remaining P0/P1 contract issue after the corrections.

Related

Related: #487

Validation

• bun run build passed.
• bun run docs:build passed after the final contract corrections; Astro built 13 pages.
• git diff --check passed.
• Structural validation confirmed one complete R1-R19, F1-F6, AE1-AE21, KTD1-KTD12, and U1-U7 sequence, balanced code fences, and no stale gateway.expose spelling.
• Independent security, protocol, and feasibility re-reviews confirmed all release-blocking findings resolved.

No runtime implementation changed, so a coding-gateway E2E is not applicable to this PR. Implementation PRs own the red/green built-CLI E2E, real backend isolation probes, registry fixtures, and clean-registry helper-package install smoke defined by the plan.

Post-Deploy Monitoring & Validation

No additional operational monitoring is required for this documentation-only PR. Implementation PRs will own service telemetry, backend smoke tests, and rollout validation.

New concepts

Profile a standard instead of cloning it

An A2A profile keeps standard Agent Cards, Tasks, Artifacts, operations, errors, and capability behavior. The AllAgents extension adds only coding-specific evidence that A2A does not define, such as repository provenance, file changes, cleanup outcomes, structured-result integrity, and evidence completeness.

This preserves standard-client interoperability and gives coding evidence an explicit compatibility boundary. It should not rename standard operations or hide a parallel private lifecycle behind A2A-shaped types.

Durable Task truth is not durable provider execution

The gateway can durably preserve what was accepted, attempted, observed, and terminally decided without serializing a provider's live process or private session state. After an ambiguous start, gateway restart, or provider-process loss, the safe behavior is one truthful failed Task—not automatic replay that may duplicate side effects.

[cloudflare-workers-and-pages]

Deploying allagents with    Cloudflare Pages

Latest commit:	77a36c9
Status:	✅  Deploy successful!
Preview URL:	https://4e1cc054.allagents.pages.dev
Branch Preview URL:	https://docs-execution-gateway-adr.allagents.pages.dev

View logs