codex-a2a 0.5.3__tar.gz → 0.6.1__tar.gz

{codex_a2a-0.5.3 → codex_a2a-0.6.1}/.gitignore

@@ -43,6 +43,8 @@ logs/
 run/
 .codex-a2a/
 *.db
+*.db-shm
+*.db-wal
 
 # Unit test / coverage reports
 htmlcov/

{codex_a2a-0.5.3 → codex_a2a-0.6.1}/CONTRIBUTING.md

@@ -35,10 +35,11 @@ uv sync --all-extras
 - verify `codex` is installed and available on `PATH` (or set `CODEX_CLI_BIN`)
 - verify Codex provider/auth configuration already works outside this repository
 
-3. Generate a local bearer token:
+3. Generate a local inbound credential registry:
 
 ```bash
-export A2A_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_hex(24))')"
+export DEMO_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_hex(24))')"
+export A2A_STATIC_AUTH_CREDENTIALS='[{"id":"local-bearer","scheme":"bearer","token":"'"${DEMO_BEARER_TOKEN}"'","principal":"automation"}]'
 ```
 
 4. Start this service from the source tree:
@@ -50,7 +51,7 @@ CODEX_WORKSPACE_ROOT=/abs/path/to/workspace uv run codex-a2a
 5. Inspect the discovery surfaces:
 
 - `http://127.0.0.1:8000/.well-known/agent-card.json`
-- `curl -H "Authorization: Bearer ${A2A_BEARER_TOKEN}" http://127.0.0.1:8000/v1/card`
+- `curl -H "Authorization: Bearer ${DEMO_BEARER_TOKEN}" http://127.0.0.1:8000/v1/card`
 
 ## Validation Baseline
 

{codex_a2a-0.5.3/src/codex_a2a.egg-info → codex_a2a-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-a2a
-Version: 0.5.3
+Version: 0.6.1
 Summary: Codex A2A runtime adapter
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -77,6 +77,8 @@ flowchart TD
     PeerA2A -->|task / stream result| Outbound
 ```
 
+For internal module boundaries and maintainer-facing request call chains, see [Maintainer Architecture Guide](docs/maintainer-architecture.md).
+
 ## Quick Start
 
 Install the released CLI with `uv tool`:
@@ -107,7 +109,8 @@ Before starting the runtime:
 Self-start the released CLI against a workspace root:
 
 ```bash
-A2A_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_hex(24))')" \
+DEMO_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_hex(24))')"
+A2A_STATIC_AUTH_CREDENTIALS='[{"id":"local-bearer","scheme":"bearer","token":"'"${DEMO_BEARER_TOKEN}"'","principal":"automation"}]' \
 A2A_HOST=127.0.0.1 \
 A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
@@ -116,8 +119,14 @@ CODEX_WORKSPACE_ROOT=/abs/path/to/workspace \
 codex-a2a
 ```
 
+For the full runtime configuration matrix, outbound client settings, and deployment notes, see [Usage Guide](docs/guide.md).
+
+## Operational Notes
+
 When `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`.
 
+On 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.
+
 YOLO-equivalent startup note:
 
 - `codex-a2a` does not add a separate `--yolo` flag or `YOLO` environment variable.
@@ -134,6 +143,27 @@ Authenticated extended card:
 
 Outbound peer auth is configured with `A2A_CLIENT_BEARER_TOKEN` or `A2A_CLIENT_BASIC_AUTH`; see the Usage Guide for the complete client-side matrix.
 
+## When To Use It
+
+Use this project when:
+
+- you want to keep Codex as the runtime
+- you need A2A transports and Agent Card discovery
+- you want a thin service boundary instead of building your own adapter
+- you want inbound serving and outbound peer access in one deployable unit
+
+Prefer [a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub) when:
+
+- you need a broader application-facing client integration layer
+- you want higher-level A2A consumption and upstream adapter normalization
+- you want client-side integration concerns separated from the Codex runtime boundary
+
+Look elsewhere if:
+
+- you need hard multi-tenant isolation inside one shared runtime
+- you want this project to manage your process supervisor or host bootstrap
+- you want a general runtime-agnostic A2A server rather than a Codex adapter
+
 ## Highlights
 
 - A2A HTTP+JSON endpoints such as `/v1/message:send` and `/v1/message:stream`
@@ -151,37 +181,17 @@ Outbound peer auth is configured with `A2A_CLIENT_BEARER_TOKEN` or `A2A_CLIENT_B
 Portable vs Private Surface:
 
 - Treat the core A2A send / stream / task methods plus Agent Card discovery as the portable baseline.
-- Treat `codex.*` methods and `metadata.codex.directory` as the Codex-specific control plane for Codex-aware clients.
+- Treat `codex.*` methods plus `metadata.codex.directory` and `metadata.codex.execution` as the Codex-specific control plane for Codex-aware clients.
 - Treat one deployed instance as a single-tenant trust boundary, not a hardened multi-tenant runtime.
 
 The normative compatibility split and deployment model live in [Compatibility Guide](docs/compatibility.md) and [Security Policy](SECURITY.md).
 
-## When To Use It
-
-Use this project when:
-
-- you want to keep Codex as the runtime
-- you need A2A transports and Agent Card discovery
-- you want a thin service boundary instead of building your own adapter
-- you want inbound serving and outbound peer access in one deployable unit
-
-Look elsewhere if:
-
-- you need hard multi-tenant isolation inside one shared runtime
-- you want this project to manage your process supervisor or host bootstrap
-- you want a general client integration layer rather than a runtime adapter
-
-## Recommended Client Side
-
-If you want a broader application-facing client integration layer, prefer [a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub).
-
-It is a better place for higher-level client concerns such as A2A consumption, upstream adapter normalization, and application-facing integration, while `codex-a2a` stays focused on the runtime boundary around Codex plus embedded peer calling.
-
 ## Further Reading
 
 - [Usage Guide](docs/guide.md) Runtime configuration, outbound access, transport usage, and client examples.
 - [Extension Specifications](docs/extension-specifications.md) Stable extension URI/spec index plus public-vs-extended card disclosure rules.
 - [Architecture Guide](docs/architecture.md) System structure, boundaries, and request flow.
+- [Maintainer Architecture Guide](docs/maintainer-architecture.md) Internal module structure, request call chains, and persistence touchpoints for contributors.
 - [Compatibility Guide](docs/compatibility.md) Supported Python/runtime surface, extension stability, and ecosystem-facing compatibility expectations.
 - [Security Policy](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 

{codex_a2a-0.5.3 → codex_a2a-0.6.1}/README.md

@@ -35,6 +35,8 @@ flowchart TD
     PeerA2A -->|task / stream result| Outbound
 ```
 
+For internal module boundaries and maintainer-facing request call chains, see [Maintainer Architecture Guide](docs/maintainer-architecture.md).
+
 ## Quick Start
 
 Install the released CLI with `uv tool`:
@@ -65,7 +67,8 @@ Before starting the runtime:
 Self-start the released CLI against a workspace root:
 
 ```bash
-A2A_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_hex(24))')" \
+DEMO_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_hex(24))')"
+A2A_STATIC_AUTH_CREDENTIALS='[{"id":"local-bearer","scheme":"bearer","token":"'"${DEMO_BEARER_TOKEN}"'","principal":"automation"}]' \
 A2A_HOST=127.0.0.1 \
 A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
@@ -74,8 +77,14 @@ CODEX_WORKSPACE_ROOT=/abs/path/to/workspace \
 codex-a2a
 ```
 
+For the full runtime configuration matrix, outbound client settings, and deployment notes, see [Usage Guide](docs/guide.md).
+
+## Operational Notes
+
 When `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`.
 
+On 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.
+
 YOLO-equivalent startup note:
 
 - `codex-a2a` does not add a separate `--yolo` flag or `YOLO` environment variable.
@@ -92,6 +101,27 @@ Authenticated extended card:
 
 Outbound peer auth is configured with `A2A_CLIENT_BEARER_TOKEN` or `A2A_CLIENT_BASIC_AUTH`; see the Usage Guide for the complete client-side matrix.
 
+## When To Use It
+
+Use this project when:
+
+- you want to keep Codex as the runtime
+- you need A2A transports and Agent Card discovery
+- you want a thin service boundary instead of building your own adapter
+- you want inbound serving and outbound peer access in one deployable unit
+
+Prefer [a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub) when:
+
+- you need a broader application-facing client integration layer
+- you want higher-level A2A consumption and upstream adapter normalization
+- you want client-side integration concerns separated from the Codex runtime boundary
+
+Look elsewhere if:
+
+- you need hard multi-tenant isolation inside one shared runtime
+- you want this project to manage your process supervisor or host bootstrap
+- you want a general runtime-agnostic A2A server rather than a Codex adapter
+
 ## Highlights
 
 - A2A HTTP+JSON endpoints such as `/v1/message:send` and `/v1/message:stream`
@@ -109,37 +139,17 @@ Outbound peer auth is configured with `A2A_CLIENT_BEARER_TOKEN` or `A2A_CLIENT_B
 Portable vs Private Surface:
 
 - Treat the core A2A send / stream / task methods plus Agent Card discovery as the portable baseline.
-- Treat `codex.*` methods and `metadata.codex.directory` as the Codex-specific control plane for Codex-aware clients.
+- Treat `codex.*` methods plus `metadata.codex.directory` and `metadata.codex.execution` as the Codex-specific control plane for Codex-aware clients.
 - Treat one deployed instance as a single-tenant trust boundary, not a hardened multi-tenant runtime.
 
 The normative compatibility split and deployment model live in [Compatibility Guide](docs/compatibility.md) and [Security Policy](SECURITY.md).
 
-## When To Use It
-
-Use this project when:
-
-- you want to keep Codex as the runtime
-- you need A2A transports and Agent Card discovery
-- you want a thin service boundary instead of building your own adapter
-- you want inbound serving and outbound peer access in one deployable unit
-
-Look elsewhere if:
-
-- you need hard multi-tenant isolation inside one shared runtime
-- you want this project to manage your process supervisor or host bootstrap
-- you want a general client integration layer rather than a runtime adapter
-
-## Recommended Client Side
-
-If you want a broader application-facing client integration layer, prefer [a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub).
-
-It is a better place for higher-level client concerns such as A2A consumption, upstream adapter normalization, and application-facing integration, while `codex-a2a` stays focused on the runtime boundary around Codex plus embedded peer calling.
-
 ## Further Reading
 
 - [Usage Guide](docs/guide.md) Runtime configuration, outbound access, transport usage, and client examples.
 - [Extension Specifications](docs/extension-specifications.md) Stable extension URI/spec index plus public-vs-extended card disclosure rules.
 - [Architecture Guide](docs/architecture.md) System structure, boundaries, and request flow.
+- [Maintainer Architecture Guide](docs/maintainer-architecture.md) Internal module structure, request call chains, and persistence touchpoints for contributors.
 - [Compatibility Guide](docs/compatibility.md) Supported Python/runtime surface, extension stability, and ecosystem-facing compatibility expectations.
 - [Security Policy](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 

{codex_a2a-0.5.3 → codex_a2a-0.6.1}/SECURITY.md

@@ -8,7 +8,7 @@ The current deployment model is a single-tenant trust boundary by design.
 
 ## Security Boundary
 
-- `A2A_BEARER_TOKEN` protects access to the A2A surface, but it is not a tenant-isolation boundary inside one deployed instance.
+- Statically configured inbound bearer/basic credentials protect access to the A2A surface, but they are not a tenant-isolation boundary inside one deployed instance.
 - Within one `codex-a2a` instance, consumers share the same underlying Codex workspace/environment by default.
 - LLM provider keys are consumed by the `codex` process. Prompt injection or indirect exfiltration attempts may still expose sensitive values.
 - Payload logging is opt-in. When `A2A_LOG_PAYLOADS=true`, this service only logs JSON payload previews, applies size guards, and suppresses full payload logging for `codex.*` JSON-RPC extension calls.
@@ -20,7 +20,7 @@ This project is currently best suited for trusted or internal environments. Impo
 - Single-tenant trust boundary only; not a secure multi-tenant deployment profile
 - No per-tenant workspace isolation inside one instance
 - No hard guarantee that upstream provider keys are inaccessible to agent logic
-- Bearer-token auth only by default; stronger identity propagation is still an incremental hardening area
+- Inbound auth is deployment-scoped and static; this repository does not expose OAuth2, OIDC, or dynamic token introspection
 - Operators remain responsible for host hardening, secret rotation, and process access controls
 
 ## Reporting a Vulnerability

{codex_a2a-0.5.3 → codex_a2a-0.6.1}/docs/architecture.md

@@ -30,7 +30,7 @@ flowchart LR
     Codex --> Workspace["Shared workspace and provider credentials"]
 ```
 
-This view emphasizes service responsibility boundaries rather than internal module structure. The root [README](../README.md) keeps the more implementation-oriented logical component view for first-time readers.
+This view emphasizes service responsibility boundaries rather than internal module structure. The root [README](../README.md) keeps the more implementation-oriented logical component view for first-time readers, while [maintainer-architecture.md](./maintainer-architecture.md) covers the internal module graph and request call chains for contributors.
 
 ## Request Flow
 
@@ -90,6 +90,7 @@ Use the docs by responsibility:
 
 - [README](../README.md): project overview, quick-start path, and entry navigation
 - [Usage Guide](guide.md): configuration, transport usage, and runtime examples
+- [Maintainer Architecture Guide](maintainer-architecture.md): internal module boundaries, request call chains, and persistence touchpoints
 - [Extension Specifications](extension-specifications.md): stable extension URI/spec index and public-vs-extended disclosure rules
 - [Compatibility Guide](compatibility.md): current compatibility promises and stability expectations
 - [Contributing Guide](../CONTRIBUTING.md): contributor workflow and validation

{codex_a2a-0.5.3 → codex_a2a-0.6.1}/docs/compatibility.md

@@ -26,7 +26,7 @@ Open-source consumption guidance:
 
 - Treat the core A2A send / stream / task methods as the portable baseline.
 - Treat `urn:a2a:*` entries in this repository as shared repo-family conventions, not as claims that they are part of the A2A core baseline.
-- Treat `codex.*` methods and `metadata.codex.directory` as a Codex-specific control plane layered on top of the portable A2A surface.
+- Treat `codex.*` methods plus `metadata.codex.directory` and `metadata.codex.execution` as a Codex-specific control plane layered on top of the portable A2A surface.
 - Treat [extension-specifications.md](./extension-specifications.md) as the stable URI/spec index, not as the main usage guide.
 
 ## Normative Sources
@@ -64,6 +64,8 @@ Task durability is deployment-dependent:
 - `A2A_DATABASE_URL=<sqlalchemy-async-url>` preserves task lookup/cancel/resubscribe state across process restarts.
 - `A2A_DATABASE_URL` now defaults to a workspace-local SQLite database at `${CODEX_WORKSPACE_ROOT}/.codex-a2a/codex-a2a.db` when `CODEX_WORKSPACE_ROOT` is configured; otherwise it falls back to `sqlite+aiosqlite:///./codex-a2a.db`. Persistence therefore remains the default runtime behavior.
 - The same database-backed mode also preserves session-binding ownership state and pending interrupt callback requests that still fall within their TTL. Session-binding and ownership persistence are independent from the in-memory session cache TTL.
+- The default SQLite + WAL profile is intended for a stable local filesystem path, not for network filesystems or sync-managed folders with weaker locking behavior.
+- The repository-local migration helper remains intentionally lightweight: it supports additive, adapter-owned schema evolution such as creating tables, adding nullable columns, and writing per-scope schema versions. It should not be read as a promise that heavier schema rewrites will stay in-scope without a tooling change.
 
 ## Deployment Profile
 
@@ -93,6 +95,40 @@ Execution-environment boundary fields are also published through the runtime pro
 - `codex.exec.*` is compatibility-sensitive as the standalone interactive exec contract. Changes to handle shapes, task-stream delivery, or lifecycle method names should be treated as wire-level changes.
 - `codex.discovery.*` is compatibility-sensitive as the stable discovery contract for `skill.path` and `mention_path` identifiers. Changes to normalized item fields, plugin marketplace mapping, or discovery watch task payload kinds should be treated as wire-level changes.
 - `codex.threads.*` is compatibility-sensitive as the provider-private thread lifecycle contract. Changes to lifecycle method names, watch payload kinds, or watch-task bridge event names should be treated as wire-level changes.
+- `codex.turns.*` is compatibility-sensitive as the active-turn control contract. Changes to `expected_turn_id` semantics, same-turn rich-input handling, or rejected override fields should be treated as wire-level changes.
+- `codex.review.*` is compatibility-sensitive as the review control and watch contract. Changes to supported target types, `delivery` semantics, review watch payload kinds, or review watch event names should be treated as wire-level changes.
+- Provider-private Agent Card skill decomposition is also compatibility-sensitive. Renaming or re-merging `codex.sessions.query/control`, `codex.discovery.query/watch`, `codex.threads.control/watch`, `codex.turns.control`, `codex.review.control`, `codex.exec.control/stream`, or narrowing `codex.interrupt.callback` output modes should be treated as discoverability contract changes.
+- Agent Card media modes and `acceptedOutputModes` handling are compatibility-sensitive. Changes to declared default modes, to task-scoped persistence of negotiated modes, or to structured-output downgrade behavior should be treated as wire-level changes.
+- For core chat tasks, negotiated output modes are lifecycle-scoped. `message/send`, `message/stream`, `tasks/get`, `tasks/resubscribe`, and push notifications should not drift apart for the same task.
+- For core chat requests, explicit `acceptedOutputModes` are also a compatibility-sensitive fail-fast boundary: requests must remain compatible with declared chat output modes, and current chat turns require `text/plain`.
+
+## Extension Boundary Governance
+
+When evaluating or evolving `codex.*` methods, this repository uses the following boundary rules:
+
+- The adapter may document, validate, route, and normalize stable upstream-facing behavior, but it should not grow into a general replacement for upstream private runtime internals or host-level control planes.
+- New `codex.*` methods default to provider-private extension status. They should not be described as portable A2A baseline capabilities unless they align with shared protocol semantics.
+- Read-only discovery, compatibility-preserving projections, and low-risk control methods are preferred over stronger mutating or destructive provider controls.
+- A2A core object mappings should be used only for stable, low-ambiguity read projections. When the upstream payload is execution-control-specific or highly provider-shaped, the contract should stay as a provider-private result envelope or watch-task payload.
+- Active-turn steering, standalone interactive exec, reviewer control, subtask/subagent fan-out, task-tool internals, and similar runtime mechanisms should be treated as provider-private internals by default even when passthrough support exists.
+- Each new extension proposal should answer, in issue or design form:
+  - what client value exists beyond the current chat/session flow?
+  - is the upstream behavior stable enough to carry as a maintained contract?
+  - should the surface be provider-private, deployment-conditional, or excluded?
+  - are authorization, ownership, and destructive-side-effect boundaries enforceable?
+  - can the result shape avoid overfitting provider internals into fake A2A core semantics?
+
+Current repository judgment under those rules:
+
+- `codex.discovery.*` and the `codex.discovery.watch` bridge fit the preferred read-only and low-risk discovery pattern.
+- `codex.threads.*`, especially `codex.threads.watch` and `codex.threads.watch.release`, remain acceptable as provider-private lifecycle surfaces because they expose a bounded watch/control bridge rather than raw upstream subscription internals.
+- `codex.interrupts.list` is acceptable as an adapter-local recovery surface because it only exposes active pending interrupt handles already known to this adapter and does not mutate upstream state.
+- `codex.turns.steer` is boundary-sensitive and should remain narrowly scoped, provider-private, and resistant to scope creep into a general orchestration API.
+- `codex.review.*` is also boundary-sensitive and should stay framed as a provider-private reviewer surface rather than a generic A2A review standard.
+- `codex.sessions.shell` and `codex.exec.*` sit closest to the adapter boundary because they expose standalone command execution semantics instead of a stable session/message projection. They remain supported for internal or tightly controlled deployments, but should stay deployment-conditional and provider-private rather than being treated as generic extension templates.
+- Current default posture keeps `codex.sessions.shell`, `codex.review.*`, and `codex.exec.*` disabled unless a deployment intentionally opts into them. `codex.turns.steer` is enabled by default but remains narrowly scoped, provider-private, and deployment-configurable.
+- Inbound auth is intentionally static and deployment-scoped. The current contract requires a static multi-credential registry with stable principals; it does not claim OAuth2, OIDC, or dynamic token introspection.
+- Stable principal mapping is part of the runtime compatibility surface because session ownership, thread watch ownership, and exec ownership all key off the authenticated principal rather than a rotating token hash.
 
 ## Extension Taxonomy
 
@@ -103,12 +139,14 @@ This repository distinguishes between three layers:
 - shared extensions
   - repo-family conventions such as session binding, stream hints, and interrupt callbacks (`permission`, `question`, `permissions`, and `elicitation` reply surfaces)
 - Codex-specific extensions
-  - `codex.*` JSON-RPC methods and `metadata.codex.directory`
+  - `codex.*` JSON-RPC methods plus `metadata.codex.directory` and `metadata.codex.execution`
   - this now includes:
     - session query/control
     - discovery/query surfaces
     - discovery watch task bridge
     - thread lifecycle watch-task bridge
+    - active-turn control
+    - review start control
     - standalone interactive exec
 
 Discovery note:
@@ -116,6 +154,13 @@ Discovery note:
 - `codex.discovery.skills.list`, `codex.discovery.apps.list`, `codex.discovery.plugins.list`, and `codex.discovery.plugins.read` are declared read-only discovery methods.
 - `codex.discovery.watch` is the declared bridge for upstream `skills/changed` and `app/list/updated` notifications.
 - `codex.threads.watch` is the declared thread lifecycle watch-task bridge for upstream `thread/started`, `thread/status/changed`, `thread/archived`, `thread/unarchived`, and `thread/closed` notifications.
+- `codex.threads.watch.release` is the declared ownership-scoped control method for releasing a watch task created by `codex.threads.watch`.
+- `codex.interrupts.list` is the declared adapter-local recovery method for rediscovering still-active pending interrupt request IDs after reconnecting.
+- `codex.turns.steer` is the declared active-turn control method for appending additional input to an already-running regular turn.
+- `codex.review.start` is the declared review-start control method for `uncommittedChanges`, `baseBranch`, `commit`, and `custom` review targets.
+- `codex.review.watch` is the declared review lifecycle watch-task bridge for `review.started`, `review.status.changed`, `review.completed`, and `review.failed`.
+- `codex.review.start` remains a control-handle surface; clients should use `codex.review.watch` plus `tasks/resubscribe` for review lifecycle observation.
+- `codex.interrupts.list` is always-on but adapter-local and identity-scoped. `codex.sessions.shell`, `codex.turns.steer`, `codex.review.*`, and `codex.exec.*` remain deployment-conditional surfaces and should be discovered from machine-readable contracts before use.
 - `thread/unsubscribe` is intentionally excluded from the stable public contract until this service exposes connection-safe subscription ownership.
 - This repository does not claim a generic standalone server-push JSON-RPC transport for those notifications; the compatibility contract is the watch-task bridge published through Agent Card and OpenAPI.
 

{codex_a2a-0.5.3 → codex_a2a-0.6.1}/docs/extension-specifications.md

@@ -11,6 +11,12 @@ This document is the stable specification index for the extension URIs published
 
 Use the public card for lightweight discovery. Fetch the authenticated extended card when you need full extension params, compatibility metadata, or provider-private routing details.
 
+Provider-private extension note:
+
+- `codex.*` methods in this repository are adapter-managed provider extensions, not portable A2A baseline capabilities.
+- Prefer discovery, stable projections, and low-risk watch/control bridges before exposing stronger runtime or host-execution controls.
+- When an upstream behavior is highly runtime-internal or host-shaped, the specification should keep it provider-private and should not force it into fake A2A core object semantics.
+
 ## Shared Session Binding v1
 
 URI: `urn:a2a:session-binding/v1`
@@ -56,6 +62,24 @@ URI: `urn:codex-a2a:codex-thread-lifecycle/v1`
 - Authenticated extended card: full method contracts, stable thread fields, and watch-task bridge metadata
 - Transport: A2A JSON-RPC extension methods
 
+## Codex Turn Control v1
+
+URI: `urn:codex-a2a:codex-turn-control/v1`
+
+- Scope: provider-private active-turn steering for already-running regular turns
+- Public Agent Card: capability declaration only
+- Authenticated extended card: full method contracts, rejected override fields, and error metadata
+- Transport: A2A JSON-RPC extension methods
+
+## Codex Review Control v1
+
+URI: `urn:codex-a2a:codex-review/v1`
+
+- Scope: provider-private review-start control and review lifecycle watch bridge for uncommitted changes, branches, commits, and custom reviewer instructions
+- Public Agent Card: capability declaration only
+- Authenticated extended card: full target contracts, delivery options, watch-task bridge metadata, and error metadata
+- Transport: A2A JSON-RPC extension methods
+
 ## Codex Exec v1
 
 URI: `urn:codex-a2a:codex-exec/v1`