{"id":47580381,"url":"https://github.com/liujuanjuan1984/codex-a2a","last_synced_at":"2026-04-10T10:05:55.755Z","repository":{"id":344097927,"uuid":"1158605395","full_name":"liujuanjuan1984/codex-a2a","owner":"liujuanjuan1984","description":"Expose Codex through A2A with an inbound server surface and embedded outbound client.","archived":false,"fork":false,"pushed_at":"2026-03-30T11:45:49.000Z","size":971,"stargazers_count":4,"open_issues_count":20,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T13:12:05.271Z","etag":null,"topics":["a2a","a2a-client","a2a-protocol","a2a-server","ai-agent","codex","codex-cli"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liujuanjuan1984.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-15T16:41:28.000Z","updated_at":"2026-03-30T05:33:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/liujuanjuan1984/codex-a2a","commit_stats":null,"previous_names":["liujuanjuan1984/codex-a2a-serve","liujuanjuan1984/codex-a2a-server"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/liujuanjuan1984/codex-a2a","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fcodex-a2a","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fcodex-a2a/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fcodex-a2a/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fcodex-a2a/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liujuanjuan1984","download_url":"https://codeload.github.com/liujuanjuan1984/codex-a2a/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liujuanjuan1984%2Fcodex-a2a/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","a2a-client","a2a-protocol","a2a-server","ai-agent","codex","codex-cli"],"created_at":"2026-03-31T16:00:22.077Z","updated_at":"2026-04-10T10:05:55.749Z","avatar_url":"https://github.com/liujuanjuan1984.png","language":"Python","funding_links":[],"categories":["Server Implementations","⚙️ Implementations \u0026 Libraries"],"sub_categories":["🛠️ \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eDeveloper Tools"],"readme":"# codex-a2a\n\n\u003e Expose Codex through A2A.\n\n`codex-a2a` adds an A2A runtime layer to the local Codex runtime, with auth, streaming, session continuity, interrupt handling, a built-in outbound A2A client, and a clear deployment boundary.\n\n## What This Is\n\n- An A2A adapter service for the local Codex runtime, with inbound runtime exposure plus outbound peer calling.\n- It supports both roles in one process: serving as an A2A Server and hosting an embedded A2A Client for `a2a_call` and CLI-driven peer calls.\n\n## Architecture\n\n```mermaid\nflowchart TD\n    External[\"A2A Clients / a2a-client-hub / Gateways\"]\n\n    subgraph Adapter[\"codex-a2a Runtime\"]\n        Ingress[\"Inbound A2A Surface\\nHTTP+JSON + JSON-RPC\"]\n        Codex[\"Codex Runtime / Executor\"]\n        Outbound[\"Embedded A2A Client\\nCLI call + a2a_call\"]\n    end\n\n    subgraph Peers[\"Peer A2A Services\"]\n        PeerA2A[\"Peer A2A Agent\"]\n        PeerRuntime[\"Peer Runtime\"]\n        PeerA2A --\u003e PeerRuntime\n    end\n\n    External --\u003e|message/send,\\nmessage:stream| Ingress\n    Ingress --\u003e|task execution| Codex\n    Codex --\u003e|stream events / tool results| Ingress\n    Codex --\u003e|a2a_call tool| Outbound\n    Outbound --\u003e|message/send,\\nmessage:stream| PeerA2A\n    PeerA2A --\u003e|task / stream result| Outbound\n```\n\nFor internal module boundaries and maintainer-facing request call chains, see [Maintainer Architecture Guide](docs/maintainer-architecture.md).\n\n## Quick Start\n\nInstall the released CLI with `uv tool`:\n\n```bash\nuv tool install codex-a2a\n```\n\nUpgrade later with:\n\n```bash\nuv tool upgrade codex-a2a\n```\n\nInstall an exact release with:\n\n```bash\nuv tool install \"codex-a2a==\u003cversion\u003e\"\n```\n\nBefore starting the runtime:\n\n- Install and verify the local `codex` CLI itself.\n- Configure Codex with a working provider/model setup and any required credentials.\n- `codex-a2a` does not provision Codex providers, login state, or API keys for you.\n- Startup fails fast if the local `codex` runtime is missing or cannot initialize.\n\nSelf-start the released CLI against a workspace root:\n\n```bash\nDEMO_BEARER_TOKEN=\"$(python -c 'import secrets; print(secrets.token_hex(24))')\"\nA2A_STATIC_AUTH_CREDENTIALS='[{\"id\":\"local-bearer\",\"scheme\":\"bearer\",\"token\":\"'\"${DEMO_BEARER_TOKEN}\"'\",\"principal\":\"automation\"}]' \\\nA2A_HOST=127.0.0.1 \\\nA2A_PORT=8000 \\\nA2A_PUBLIC_URL=http://127.0.0.1:8000 \\\nA2A_DATABASE_URL=sqlite+aiosqlite:////abs/path/to/workspace/.codex-a2a/codex-a2a.db \\\nCODEX_WORKSPACE_ROOT=/abs/path/to/workspace \\\ncodex-a2a\n```\n\nFor the full runtime configuration matrix, outbound client settings, and deployment notes, see [Usage Guide](docs/guide.md).\n\n## Operational Notes\n\nWhen `A2A_DATABASE_URL` is unset and `CODEX_WORKSPACE_ROOT` is configured, the default SQLite database is created under `${CODEX_WORKSPACE_ROOT}/.codex-a2a/codex-a2a.db`.\n\nOn startup, `codex-a2a` auto-creates its own runtime-state tables and applies versioned runtime-state schema migrations in place. This migration ownership currently covers only the adapter-managed `a2a_*` runtime-state tables and intentionally excludes the A2A SDK task-store schema.\n\nYOLO-equivalent startup note:\n\n- `codex-a2a` does not add a separate `--yolo` flag or `YOLO` environment variable.\n- To start the underlying Codex process with YOLO-equivalent behavior, set:\n  - `CODEX_APPROVAL_POLICY=never`\n  - `CODEX_SANDBOX_MODE=danger-full-access`\n- `A2A_EXECUTION_*` settings are discovery metadata only and do not change how the Codex subprocess starts.\n\nAgent Card: `http://127.0.0.1:8000/.well-known/agent-card.json`\n\nAuthenticated extended card:\n- JSON-RPC: `agent/getAuthenticatedExtendedCard`\n- HTTP: `GET /v1/card`\n\nOutbound peer auth is configured with `A2A_CLIENT_BEARER_TOKEN` or `A2A_CLIENT_BASIC_AUTH`; see the Usage Guide for the complete client-side matrix.\n\n## When To Use It\n\nUse this project when:\n\n- you want to keep Codex as the runtime\n- you need A2A transports and Agent Card discovery\n- you want a thin service boundary instead of building your own adapter\n- you want inbound serving and outbound peer access in one deployable unit\n\nPrefer [a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub) when:\n\n- you need a broader application-facing client integration layer\n- you want higher-level A2A consumption and upstream adapter normalization\n- you want client-side integration concerns separated from the Codex runtime boundary\n\nLook elsewhere if:\n\n- you need hard multi-tenant isolation inside one shared runtime\n- you want this project to manage your process supervisor or host bootstrap\n- you want a general runtime-agnostic A2A server rather than a Codex adapter\n\n## Highlights\n\n- A2A HTTP+JSON endpoints such as `/v1/message:send` and `/v1/message:stream`\n- A2A JSON-RPC support on `POST /`\n- Embedded client access through `codex-a2a call`\n- Autonomous outbound peer calls through the `a2a_call` tool\n- SSE streaming with normalized `text`, `reasoning`, and `tool_call` blocks\n- Session continuity and session query extensions\n- Interrupt lifecycle mapping and callback validation\n- Transport selection, Agent Card discovery, timeout control, and bearer/basic auth for outbound A2A calls\n- Payload logging controls, secret-handling guardrails, and released-CLI startup / source-based runtime paths\n\n## Boundaries\n\nPortable vs Private Surface:\n\n- Treat the core A2A send / stream / task methods plus Agent Card discovery as the portable baseline.\n- Treat `codex.*` methods plus `metadata.codex.directory` and `metadata.codex.execution` as the Codex-specific control plane for Codex-aware clients.\n- Treat one deployed instance as a single-tenant trust boundary, not a hardened multi-tenant runtime.\n\nThe normative compatibility split and deployment model live in [Compatibility Guide](docs/compatibility.md) and [Security Policy](SECURITY.md).\n\n## Further Reading\n\n- [Usage Guide](docs/guide.md) Runtime configuration, outbound access, transport usage, and client examples.\n- [Extension Specifications](docs/extension-specifications.md) Stable extension URI/spec index plus public-vs-extended card disclosure rules.\n- [Architecture Guide](docs/architecture.md) System structure, boundaries, and request flow.\n- [Maintainer Architecture Guide](docs/maintainer-architecture.md) Internal module structure, request call chains, and persistence touchpoints for contributors.\n- [Compatibility Guide](docs/compatibility.md) Supported Python/runtime surface, extension stability, and ecosystem-facing compatibility expectations.\n- [External Conformance Experiments](docs/conformance.md) Manual A2A TCK experiment entrypoint and triage workflow.\n- [Security Policy](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.\n\n## Development\n\nFor contributor workflow, validation, release handling, and helper scripts, see [Contributing Guide](CONTRIBUTING.md) and [Scripts Reference](scripts/README.md). Use that workflow to create a PR from the working branch and merge into `main` after human review.\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliujuanjuan1984%2Fcodex-a2a","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliujuanjuan1984%2Fcodex-a2a","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliujuanjuan1984%2Fcodex-a2a/lists"}