codex-a2a-gateway: Instructions file for Codex

Repository guidance

These instructions apply to the entire repository. Codex and other coding agents should read this file before changing code, tests, documentation, packaging, or release metadata.

Mission and scope

codex-a2a-gateway gives Codex a bidirectional A2A v1.0 integration:

• Outbound: Codex calls the local MCP stdio server, which delegates to the configured loopback Hermes A2A peer.
• Inbound: an A2A client calls the HTTP/SSE gateway, which maps the task to a Codex App Server thread and turn.

Hermes is the first verified outbound peer, not the product boundary. Do not turn this project into Hermes administration, a general arbitrary-URL proxy, or a multi-tenant service without an explicit architecture and security decision.

Architecture ownership

• src/codex_a2a_gateway/server.py, core.py, and a2a.py: outbound MCP-to-A2A adapter.
• src/codex_a2a_gateway/gateway.py and inbound.py: inbound A2A transport and task lifecycle.
• src/codex_a2a_gateway/codex_backend.py: Codex App Server and CLI compatibility adapters.
• src/codex_a2a_gateway/store.py: SQLite schema, mappings, tasks, messages, events, and migrations.
• src/codex_a2a_gateway/settings.py: environment contract and network policy.
• tests/: mirrors these boundaries with fake-server and protocol regression coverage.

Treat docs/durable-jobs.md, docs/architecture-v0.2.md, docs/inbound-gateway.md, and the current README as the implemented contract. Files labelled as v0.1 or research are historical evidence, not the current specification.

Non-negotiable invariants

• MCP stdout contains protocol frames only. Send diagnostics to stderr.
• Outbound endpoints and discovered interfaces remain loopback-only. Never accept a model-supplied URL or credential.
• Inbound non-loopback bind or public URL requires bearer authentication. Remote deployment also requires TLS at a trusted proxy.
• Read secrets from environment variables. Never log, persist, echo, or commit tokens.
• Do not persist the original outbound prompt. Results and artifacts can still be sensitive and require restrictive file permissions and retention.
• Never automatically resend a mutating A2A request after an ambiguous transport outcome. Reconcile only by saved task ID or exact request message identity, never context/unique-candidate inference; preserve outcome_unknown when evidence is ambiguous.
• Cancellation remains best-effort. Never claim that the underlying agent computation stopped unless an upstream protocol proves it.
• Preserve A2A v1 task and event shapes. Do not reintroduce the legacy stream field final.
• Codex App Server over stdio is the default inbound backend. CLI mode is an explicit compatibility path and may not take over a context that already owns an App Server thread.
• Preserve per-context serialization, bounded admission, and the one-active-writer assumption for each SQLite state file.
• SQLite migrations must be additive and backward-compatible. Never discard existing context, task, message, or event records.
• Live tests and smoke are opt-in, use harmless prompts, and never run in CI.
• The bundled Hermes codex_a2a plugin is the reliable Hermes → Codex client path. Keep its endpoint loopback-only, persist only task/context handles in ctx.state, submit with returnImmediately, and never resend after an ambiguous result. The built-in Hermes a2a_call remains synchronous.
• Execution preferences are inbound-only and require the negotiated Agent Card extension (A2A-Extensions, message.extensions, and message.metadata.executionPreferences). Query App Server model/list; receiver policy may narrow that catalog but must not invent support. Persist requested/effective decisions, send only model and effort to turn/start, and reject the extension in CLI mode.