codex-a2a 0.7.3__tar.gz → 1.0.0__tar.gz

codex_a2a-1.0.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 1
+    commit-message:
+      prefix: "deps"
+    labels:
+      - "dependencies"
+    ignore:
+      - dependency-name: "fastapi"
+        update-types:
+          - "version-update:semver-minor"
+      - dependency-name: "httpx"
+        update-types:
+          - "version-update:semver-minor"
+      - dependency-name: "protobuf"
+        update-types:
+          - "version-update:semver-major"
+      - dependency-name: "setuptools-scm"
+        update-types:
+          - "version-update:semver-major"
+      - dependency-name: "uvicorn"
+        update-types:
+          - "version-update:semver-minor"
+    groups:
+      uv-all-updates:
+        patterns:
+          - "*"

{codex_a2a-0.7.3 → codex_a2a-1.0.0}/.github/workflows/ci.yml

@@ -17,6 +17,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Setup Python
         uses: actions/setup-python@v6

{codex_a2a-0.7.3 → codex_a2a-1.0.0}/.github/workflows/publish.yml

@@ -67,10 +67,6 @@ jobs:
           RELEASE_TAG: ${{ steps.release_tag.outputs.tag }}
 
       - name: Build package artifacts
-        env:
-          PYTHONWARNINGS: >-
-            ignore::UserWarning:vcs_versioning._backends._git,
-            ignore::UserWarning:vcs_versioning.overrides
         run: uv build --no-sources
 
       - name: Capture built wheel path

{codex_a2a-0.7.3 → codex_a2a-1.0.0}/CONTRIBUTING.md

@@ -45,7 +45,7 @@ export A2A_STATIC_AUTH_CREDENTIALS='[{"id":"local-bearer","scheme":"bearer","tok
 4. Start this service from the source tree:
 
 ```bash
-CODEX_WORKSPACE_ROOT=/abs/path/to/workspace uv run codex-a2a
+CODEX_WORKSPACE_ROOT=/abs/path/to/workspace uv run codex-a2a serve
 ```
 
 5. Inspect the discovery surfaces:

{codex_a2a-0.7.3/src/codex_a2a.egg-info → codex_a2a-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-a2a
-Version: 0.7.3
+Version: 1.0.0
 Summary: Codex A2A runtime adapter
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -22,18 +22,19 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: a2a-sdk==0.3.26
+Requires-Dist: a2a-sdk==1.0.2
 Requires-Dist: aiosqlite<1.0,>=0.20
-Requires-Dist: fastapi<0.136,>=0.121
+Requires-Dist: fastapi<0.137,>=0.121
 Requires-Dist: httpx<0.29,>=0.28.1
-Requires-Dist: protobuf<8.0,>=6.33.5
+Requires-Dist: protobuf<7.0,>=6.33.5
 Requires-Dist: pyasn1<1.0,>=0.6.3
+Requires-Dist: python-dotenv<2.0,>=1.2.2
 Requires-Dist: pydantic<3.0,>=2.6
 Requires-Dist: pydantic-settings<3.0,>=2.2
 Requires-Dist: requests<3.0,>=2.33.0
 Requires-Dist: sqlalchemy<3.0,>=2.0
 Requires-Dist: sse-starlette<4.0,>=2.1
-Requires-Dist: uvicorn<0.45,>=0.29
+Requires-Dist: uvicorn<0.46,>=0.29
 Provides-Extra: dev
 Requires-Dist: pip-audit<3.0,>=2.9; extra == "dev"
 Requires-Dist: pre-commit>=3.7; extra == "dev"
@@ -47,8 +48,25 @@ Dynamic: license-file
 
 # codex-a2a
 
+```text
+               _                  ___
+              | |                |__ \
+  ___ ___   __| | _____  __   __ _   ) |__ _
+ / __/ _ \ / _` |/ _ \ \/ /  / _` | / // _` |
+| (_| (_) | (_| |  __/>  <  | (_| |/ /| (_| |
+ \___\___/ \__,_|\___/_/\_\  \__,_|____\__,_|
+```
+
 > Expose Codex through A2A.
 
+Repository: https://github.com/liujuanjuan1984/codex-a2a
+
+Install: `uv tool install --upgrade codex-a2a`
+
+Protocol: A2A `1.0` only.
+
+Start the runtime explicitly with `codex-a2a serve`.
+
 `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.
 
 ## What This Is
@@ -121,7 +139,7 @@ A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
 A2A_DATABASE_URL=sqlite+aiosqlite:////abs/path/to/workspace/.codex-a2a/codex-a2a.db \
 CODEX_WORKSPACE_ROOT=/abs/path/to/workspace \
-codex-a2a
+codex-a2a serve
 ```
 
 For the full runtime configuration matrix, outbound client settings, and deployment notes, see [Usage Guide](docs/guide.md).

{codex_a2a-0.7.3 → codex_a2a-1.0.0}/README.md

@@ -1,7 +1,24 @@
 # codex-a2a
 
+```text
+               _                  ___
+              | |                |__ \
+  ___ ___   __| | _____  __   __ _   ) |__ _
+ / __/ _ \ / _` |/ _ \ \/ /  / _` | / // _` |
+| (_| (_) | (_| |  __/>  <  | (_| |/ /| (_| |
+ \___\___/ \__,_|\___/_/\_\  \__,_|____\__,_|
+```
+
 > Expose Codex through A2A.
 
+Repository: https://github.com/liujuanjuan1984/codex-a2a
+
+Install: `uv tool install --upgrade codex-a2a`
+
+Protocol: A2A `1.0` only.
+
+Start the runtime explicitly with `codex-a2a serve`.
+
 `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.
 
 ## What This Is
@@ -74,7 +91,7 @@ A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
 A2A_DATABASE_URL=sqlite+aiosqlite:////abs/path/to/workspace/.codex-a2a/codex-a2a.db \
 CODEX_WORKSPACE_ROOT=/abs/path/to/workspace \
-codex-a2a
+codex-a2a serve
 ```
 
 For the full runtime configuration matrix, outbound client settings, and deployment notes, see [Usage Guide](docs/guide.md).

codex_a2a-1.0.0/docs/a2a-extension-baseline.md

@@ -0,0 +1,93 @@
+# A2A 1.0 Extension Baseline
+
+This document defines the phase-1 baseline for how `codex-a2a` classifies, documents, and publishes A2A 1.0 extensions and extension-like contracts.
+
+Phase 1 is intentionally internal-facing. It does not change the external extension URI strategy yet. The goal is to establish a single source of truth for extension inventory, disclosure surfaces, and negotiation posture before any breaking URI migration or Agent Card expansion.
+
+## Goals
+
+- Define which runtime surfaces are true A2A extensions versus auxiliary machine-readable contracts.
+- Define the intended responsibilities of the public Agent Card, authenticated extended Agent Card, and OpenAPI metadata.
+- Centralize extension inventory so that Agent Card, OpenAPI, compatibility guidance, and documentation stop drifting independently.
+- Preserve current externally visible behavior during phase 1 unless a change is required to remove ambiguity.
+
+## Extension Classes
+
+`codex-a2a` uses three classes during phase 1:
+
+1. Shared A2A extensions
+
+- These are cross-repository conventions layered onto standard A2A requests, responses, or task streams.
+- They belong in `capabilities.extensions`.
+- They may participate in request-level extension negotiation when the behavior is activation-sensitive.
+
+2. Provider-private extensions
+
+- These are adapter-managed `codex.*` or shared-repo callback contracts that remain specific to this deployment family.
+- They are still treated as extensions conceptually, but their public disclosure remains conservative.
+- They should be declared through authenticated extended Agent Card `capabilities.extensions`.
+- Their detailed contract payloads remain machine-readable through OpenAPI and human-discoverable through authenticated skill inventory.
+
+3. Machine-readable contract metadata
+
+- These describe compatibility posture, wire-level method availability, and service behavior summaries.
+- They are not negotiated runtime extensions.
+- They should not be modeled as fake chat/task capabilities just to fit the Agent Card surface.
+
+## Disclosure Responsibilities
+
+### Public Agent Card
+
+- Anonymous discovery surface.
+- Declares only the minimum shared extension surface needed for safe interoperability.
+- Must not be used as a hiding mechanism for real shared extensions.
+- Should remain small even after later phases expand authenticated disclosures.
+
+### Authenticated Extended Agent Card
+
+- Authenticated discovery surface with deployment-aware detail.
+- Provider-private extensions that are part of the declared contract should appear here through standard `capabilities.extensions`.
+- Skills and examples remain additive discovery aids rather than the primary declaration path.
+
+### OpenAPI Metadata
+
+- Full machine-readable contract surface.
+- Remains the detailed source for provider-private request/response method contracts, transport notes, and compatibility metadata.
+- Should be derived from the same registry as Agent Card declarations whenever possible.
+
+## Negotiation Rules
+
+- Shared request/response extensions are the only extensions treated as negotiated by default in phase 1.
+- Shared request/response extensions use request-level `A2A-Extensions` activation only when the request depends on that negotiated behavior.
+- Provider-private `codex.*` contracts and shared callback contracts marked `declaration_only` are discovered through the authenticated extended Agent Card and OpenAPI, then used by directly invoking their documented provider-private methods. They do not require a separate `A2A-Extensions` activation header.
+- Compatibility and wire-profile documents are not negotiable extensions.
+
+## Inventory Rules
+
+Every extension-like surface tracked by this repository must define at least:
+
+- stable key
+- stable URI
+- classification
+- disclosure surfaces
+- negotiation posture
+- contract parameter builder source
+
+That inventory must be reusable by:
+
+- Agent Card extension builders
+- OpenAPI extension contract builders
+- compatibility taxonomy reporting
+- extension specification index documentation
+
+## Phase 1 Non-Goals
+
+- No migration from `urn:` to HTTPS extension URI yet.
+- No public expansion of provider-private extension declarations.
+- No compatibility shim for A2A 0.3 behavior.
+
+## Follow-On Phases
+
+Phase 2 will unify request-level negotiation, disclosure layering, and runtime behavior around the authenticated extension declaration model.
+
+Canonical URI and spec-hosting strategy remain a separate follow-up track after declaration-path convergence.

{codex_a2a-0.7.3 → codex_a2a-1.0.0}/docs/architecture.md

@@ -62,7 +62,7 @@ The service keeps a shared session continuation contract around `metadata.shared
 When Codex asks for permission or answers, the service exposes:
 
 - shared asked/resolved lifecycle metadata in stream status events
-- callback methods through A2A JSON-RPC extensions
+- callback methods through the provider-private JSON-RPC control surface
 - lifecycle and type validation before forwarding callback replies
 
 ## Boundary Model

{codex_a2a-0.7.3 → codex_a2a-1.0.0}/docs/compatibility.md

@@ -5,13 +5,13 @@ This document explains the compatibility promises this repository currently trie
 ## Runtime Support
 
 - Python versions: 3.11, 3.12, 3.13
-- A2A SDK line: `0.3.x`
-- A2A protocol version advertised by default: `0.3.0`
-- Normalized protocol compatibility lines declared today: `0.3`, `1.0`
+- A2A SDK line: `1.0.x`
+- A2A protocol version advertised by default: `1.0`
+- Normalized protocol compatibility lines declared today: `1.0`
 
 The repository pins the SDK version in `pyproject.toml` and validates the published CLI build in CI. Upgrade the SDK deliberately rather than relying on floating dependency resolution.
 
-The authenticated compatibility profile and wire contract publish `default_protocol_version`, `supported_protocol_versions`, and `protocol_compatibility`. Request-time `A2A-Version` negotiation currently supports the default `0.3` line plus a partial `1.0` compatibility line for response header echo, PascalCase JSON-RPC method aliases, and protocol-aware error shaping. Transport payload schemas, enums, pagination, and push-notification behavior remain SDK-owned `0.3` behavior until separately implemented.
+The OpenAPI-published compatibility profile and wire contract publish `default_protocol_version`, `supported_protocol_versions`, and `protocol_compatibility`. Request-time `A2A-Version` negotiation now targets the repository's `1.0` baseline only, and the published contracts should describe the implemented `1.0` transport surface rather than any legacy compatibility line.
 
 ## Contract Honesty
 
@@ -19,7 +19,7 @@ Machine-readable discovery surfaces must reflect actual runtime behavior:
 
 - public Agent Card
 - authenticated extended card
-- OpenAPI metadata
+- OpenAPI metadata, including `x-a2a-extension-contracts` and `x-codex-contracts`
 - JSON-RPC wire contract
 - compatibility profile
 
@@ -28,7 +28,10 @@ If runtime support is not implemented, do not expose it as a supported machine-r
 Open-source consumption guidance:
 
 - Treat the core A2A send / stream / task methods as the portable baseline.
+- Treat the Agent Card `supported_interfaces[].url` value as the shared service discovery root. For `HTTP+JSON`, this repository uses that URL as the REST base root rather than as a concrete method path.
+- Treat `POST /` as the shared JSON-RPC surface for both core A2A methods and provider-private extension methods.
 - 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 `a2a.interrupt.*` reply methods as a shared provider-private callback contract on `POST /`, declared on authenticated discovery surfaces but not activated through `A2A-Extensions`.
 - 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.
 
@@ -54,7 +57,7 @@ This repository still ships as an alpha project. Within that alpha line, these d
 
 Changes to those surfaces should be treated as compatibility-sensitive and should include corresponding test updates.
 
-Service-level behavior layered on top of those core methods should also be declared explicitly when this repository depends on it for interoperability. Current example: terminal `tasks/resubscribe` replay-once behavior is published as a service-level contract, not as a claim about generic A2A runtime semantics.
+Service-level behavior layered on top of those core methods should also be declared explicitly when this repository depends on it for interoperability. Current example: terminal `SubscribeToTask` replay-once behavior is published as a service-level contract, not as a claim about generic A2A runtime semantics.
 
 Task-store resilience is also service-level behavior in this deployment:
 
@@ -90,19 +93,19 @@ Execution-environment boundary fields are also published through the runtime pro
 ## Extension Stability
 
 - Shared metadata and extension contracts should stay synchronized across Agent Card, OpenAPI, and runtime behavior.
-- Public Agent Card should stay intentionally minimal. Detailed extension params belong in the authenticated extended card and OpenAPI, not back in the anonymous discovery surface.
+- Public Agent Card should stay intentionally minimal. Negotiated shared extension params belong in public `capabilities.extensions`; provider-private and machine-readable extension contracts belong in authenticated extended card `capabilities.extensions`, with OpenAPI `x-codex-contracts` carrying the full payloads and skill decomposition remaining additive discovery guidance.
+- Only shared request/response extensions currently participate in request-level `A2A-Extensions` negotiation. Provider-private extension URIs declared on the authenticated extended card are declaration-only unless explicitly documented otherwise; clients discover them there and then invoke their documented methods directly.
 - Product-specific extensions should remain stable within the current major line unless explicitly documented otherwise.
 - Deployment-conditional methods must be declared as conditional rather than silently disappearing.
-- `codex.sessions.shell` is compatibility-sensitive as a one-shot shell snapshot contract. Future interactive exec support must use a separate extension family rather than silently widening this method's behavior.
-- Rich input mapping is compatibility-sensitive across both `codex.sessions.prompt_async` and the core A2A message surface. Changes to supported part types, FilePart image handling, or DataPart mention/skill mapping should be treated as wire-level behavior changes.
+- Rich input mapping is compatibility-sensitive across the core A2A message surface and `codex.turns.steer`. Changes to supported part types, `Part(url|raw)` image handling, or `Part(data)` mention/skill mapping should be treated as wire-level behavior changes.
 - `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.
+- Provider-private Agent Card skill decomposition is also compatibility-sensitive. Renaming or re-merging `codex.sessions.query`, `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 tasks, negotiated output modes are lifecycle-scoped. `SendMessage`, `SendStreamingMessage`, `GetTask`, `SubscribeToTask`, 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
@@ -128,8 +131,8 @@ Current repository judgment under those rules:
 - `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.
+- `codex.exec.*` sits closest to the adapter boundary because it exposes standalone interactive command execution semantics instead of a stable session/message projection. It should stay deployment-conditional and provider-private rather than being treated as a generic extension template.
+- Current default posture keeps `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.
 
@@ -140,11 +143,12 @@ This repository distinguishes between three layers:
 - core A2A surface
   - standard send / stream / task methods
 - shared extensions
-  - repo-family conventions such as session binding, stream hints, and interrupt callbacks (`permission`, `question`, `permissions`, and `elicitation` reply surfaces)
-- Codex-specific extensions
+  - repo-family conventions such as session binding and stream hints
+- provider-private control contracts
+  - `a2a.interrupt.*` reply methods on `POST /`
   - `codex.*` JSON-RPC methods plus `metadata.codex.directory` and `metadata.codex.execution`
   - this now includes:
-    - session query/control
+    - session query
     - discovery/query surfaces
     - discovery watch task bridge
     - thread lifecycle watch-task bridge
@@ -162,8 +166,9 @@ Discovery note:
 - `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.
+- `codex.review.start` remains a control-handle surface; clients should use `codex.review.watch` plus `SubscribeToTask` for review lifecycle observation.
+- `codex.interrupts.list` is always-on but adapter-local and identity-scoped. `codex.turns.steer`, `codex.review.*`, and `codex.exec.*` remain deployment-conditional surfaces and should be discovered from machine-readable contracts before use.
+- `a2a.interrupt.*` reply methods remain shared repo-family callback contracts. They are declared on authenticated discovery surfaces, mirrored in OpenAPI, and used directly rather than through `A2A-Extensions` activation.
 - `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.7.3 → codex_a2a-1.0.0}/docs/conformance-triage.md

@@ -4,18 +4,18 @@ This document is the standing triage template for local `./scripts/conformance.s
 
 ## Standards Used For Triage
 
-- `a2a-sdk==0.3.26` as installed in this repository.
-- The default A2A protocol version advertised by this repository: `0.3.0`.
+- `a2a-sdk==1.0.2` as installed in this repository.
+- The default A2A protocol version advertised by this repository: `1.0.0`.
 - Repository compatibility policy:
   - machine-readable Agent Card and OpenAPI contracts must reflect implemented runtime behavior;
   - external TCK results are investigation input rather than default merge gates;
-  - unsupported `1.0` behavior should be tracked as future compatibility work, not silently declared as supported.
+  - unsupported behavior should be tracked as implementation work, not silently declared as supported.
 
 ## Classification Labels
 
 - `Runtime issue`: the failure reproduces against the repository's declared runtime behavior and should be fixed here.
-- `TCK mismatch`: the failure appears to conflict with the installed SDK line or this repository's declared v0.3 baseline.
-- `Future protocol gap`: the failure is not a v0.3 regression, but it identifies work needed for stronger v1.0 compatibility.
+- `TCK mismatch`: the failure appears to conflict with the installed SDK line or this repository's declared `1.0` baseline.
+- `Protocol gap`: the failure identifies work needed to complete the repository's declared `1.0` surface.
 - `Local experiment artifact`: the failure comes from the dummy-backed SUT, local auth, local URLs, timing, or other experiment setup details.
 - `Needs repro`: the failure needs a focused local probe before assigning ownership.
 
@@ -25,7 +25,7 @@ For each failed or errored node ID:
 
 1. Copy the node ID from `failed-tests.json`.
 2. Inspect the corresponding raw details in `pytest-report.json` and `tck.log`.
-3. Compare the expectation with `docs/compatibility.md`, authenticated Agent Card params, and OpenAPI `x-a2a-extension-contracts`.
+3. Compare the expectation with `docs/compatibility.md`, authenticated extended card skills/examples, and OpenAPI `x-a2a-extension-contracts` plus `x-codex-contracts`.
 4. Assign one classification label.
 5. Record whether the next action belongs in this repository, the TCK, or a future protocol compatibility issue.
 
@@ -44,6 +44,6 @@ Keep the summary short and separate:
 
 - Count clean runtime issues.
 - Count TCK mismatches.
-- Count future protocol gaps.
+- Count protocol gaps.
 - Count local experiment artifacts.
 - List follow-up issue numbers when created.

{codex_a2a-0.7.3 → codex_a2a-1.0.0}/docs/conformance.md

@@ -68,11 +68,11 @@ Each run keeps the following artifacts in the selected output directory:
 When a TCK run fails, inspect the raw report before changing the runtime:
 
 - Some failures may point to real runtime gaps.
-- Some failures may come from TCK assumptions that do not match `a2a-sdk==0.3.26`.
-- Some failures may come from A2A v0.3 versus v1.0 naming or schema drift.
+- Some failures may come from TCK assumptions that do not match `a2a-sdk==1.0.2`.
+- Some failures may come from older A2A naming or schema expectations that no longer match the repository's `1.0` contract.
 - Some failures may be local experiment artifacts from the dummy-backed runtime.
 
 The experiment is useful only if those categories stay separate during triage.
-Use the authenticated compatibility profile and wire contract `protocol_compatibility` fields as the repository-owned declaration of which protocol lines are supported today, partially supported for compatibility, or reserved for future work.
+Use the authenticated compatibility profile and wire contract `protocol_compatibility` fields as the repository-owned declaration of which protocol lines are supported today.
 
 Record first-pass classifications in [conformance-triage.md](./conformance-triage.md).

codex_a2a-1.0.0/docs/extension-specifications.md

@@ -0,0 +1,135 @@
+# Extension Specifications
+
+This document is the stable specification index for the shared-extension and provider-private contract URIs used by `codex-a2a`. It is intentionally a compact URI/spec map, not the main consumer guide. For the phase-1 extension classification and disclosure baseline, see [a2a-extension-baseline.md](./a2a-extension-baseline.md). For runtime behavior, request examples, and operational setup, see [guide.md](./guide.md). For compatibility promises and stability expectations, see [compatibility.md](./compatibility.md).
+
+## Discovery Surface Note
+
+`codex-a2a` now splits Agent Card discovery into two layers:
+
+- Public Agent Card: minimal anonymous discovery for core interfaces and shared A2A extensions
+- Authenticated extended card: standard extension declarations plus authenticated skill inventory and deployment-aware examples for provider-private controls
+- OpenAPI metadata: full machine-readable contract payloads via `x-a2a-extension-contracts` and `x-codex-contracts`
+
+Use the public card for lightweight discovery. Fetch the authenticated extended card when you need authenticated skill discovery or deployment-aware examples. Use OpenAPI when you need the full provider-private contract payloads, compatibility metadata, or detailed transport notes.
+
+Provider-private contract 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.
+
+Negotiation note:
+
+- `urn:a2a:session-binding/v1` and `urn:a2a:stream-hints/v1` are the only current request-level negotiated extensions in this repository family.
+- Provider-private `codex.*` extension URIs and the shared interrupt callback URI are declaration-only contracts. Discover them from the authenticated extended Agent Card or OpenAPI, then invoke the documented JSON-RPC methods directly; no additional `A2A-Extensions` activation header is required for those methods.
+- `wire_contract` and `compatibility_profile` are descriptive metadata contracts, not activatable runtime extensions.
+
+## Shared Session Binding v1
+
+URI: `urn:a2a:session-binding/v1`
+
+- Scope: shared A2A request metadata for rebinding to an existing upstream session
+- Public Agent Card: capability declaration plus minimal routing metadata for `shared.session.id` only
+- Authenticated extended card: full profile, notes, and detailed contract metadata
+- OpenAPI: shared contract payload under `x-a2a-extension-contracts.session_binding`
+- Runtime field: `metadata.shared.session.id`
+
+## Shared Stream Hints v1
+
+URI: `urn:a2a:stream-hints/v1`
+
+- Scope: shared canonical metadata for block, usage, interrupt, and session hints
+- Public Agent Card: metadata roots plus the minimum discoverability fields for block identity, status source, interrupt lifecycle, session identity, and basic token usage
+- Authenticated extended card: full shared stream contract including detailed block payload mappings and extended usage metadata
+- OpenAPI: shared contract payload under `x-a2a-extension-contracts.streaming`
+- Runtime fields: `metadata.shared.stream`, `metadata.shared.usage`, `metadata.shared.interrupt`, `metadata.shared.session`
+
+## Codex Session Query v1
+
+URI: `urn:codex-a2a:codex-session-query/v1`
+
+- Scope: provider-private Codex session history and low-risk control methods
+- Discovery surface: authenticated extended card `capabilities.extensions` plus skill inventory, with full payload mirrored in OpenAPI `x-codex-contracts.session_query`
+- Transport: provider-private JSON-RPC methods on `POST /`
+- Negotiation: declaration-only; discover first, then invoke the documented methods directly
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces
+
+## Codex Discovery v1
+
+URI: `urn:codex-a2a:codex-discovery/v1`
+
+- Scope: provider-private skills/apps/plugins discovery methods and discovery watch bridge
+- Discovery surface: authenticated extended card `capabilities.extensions` plus skill inventory, with full payload mirrored in OpenAPI `x-codex-contracts.discovery`
+- Transport: provider-private JSON-RPC methods on `POST /`
+- Negotiation: declaration-only; discover first, then invoke the documented methods directly
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces
+
+## Codex Thread Lifecycle v1
+
+URI: `urn:codex-a2a:codex-thread-lifecycle/v1`
+
+- Scope: provider-private thread lifecycle control and lifecycle watch bridge
+- Discovery surface: authenticated extended card `capabilities.extensions` plus skill inventory, with full payload mirrored in OpenAPI `x-codex-contracts.thread_lifecycle`
+- Transport: provider-private JSON-RPC methods on `POST /`
+- Negotiation: declaration-only; discover first, then invoke the documented methods directly
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces
+
+## Codex Turn Control v1
+
+URI: `urn:codex-a2a:codex-turn-control/v1`
+
+- Scope: provider-private active-turn steering for already-running regular turns
+- Discovery surface: authenticated extended card `capabilities.extensions` plus skill inventory, with full payload mirrored in OpenAPI `x-codex-contracts.turn_control`
+- Transport: provider-private JSON-RPC methods on `POST /`
+- Negotiation: declaration-only; discover first, then invoke the documented methods directly
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces
+
+## 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
+- Discovery surface: authenticated extended card `capabilities.extensions` plus skill inventory, with full payload mirrored in OpenAPI `x-codex-contracts.review_control`
+- Transport: provider-private JSON-RPC methods on `POST /`
+- Negotiation: declaration-only; discover first, then invoke the documented methods directly
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces
+
+## Codex Exec v1
+
+URI: `urn:codex-a2a:codex-exec/v1`
+
+- Scope: provider-private standalone interactive command execution
+- Discovery surface: authenticated extended card `capabilities.extensions` plus skill inventory, with full payload mirrored in OpenAPI `x-codex-contracts.exec_control`
+- Transport: provider-private JSON-RPC methods on `POST /`
+- Negotiation: declaration-only; discover first, then invoke the documented methods directly
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces
+
+## Shared Interactive Interrupt v1
+
+URI: `urn:a2a:interactive-interrupt/v1`
+
+- Scope: shared interrupt callback reply methods
+- Discovery surface: authenticated extended card `capabilities.extensions` plus skill inventory, with full payload mirrored in OpenAPI `x-codex-contracts.interrupt_callback`
+- Transport: provider-private JSON-RPC methods on `POST /`
+- Negotiation: declaration-only; discover first, then invoke the documented methods directly
+- Note: this URI identifies a shared repo-family callback contract and is published on authenticated discovery surfaces
+
+## A2A Compatibility Profile v1
+
+URI: `urn:codex-a2a:compatibility-profile/v1`
+
+- Scope: compatibility profile describing core baselines, extension retention, and declared service behaviors
+- Discovery surface: authenticated extended card `capabilities.extensions`, with full payload mirrored in OpenAPI `x-codex-contracts.compatibility_profile`
+- Transport: provider-private machine-readable contract metadata
+- Negotiation: not applicable; descriptive metadata only
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces
+
+## A2A Wire Contract v1
+
+URI: `urn:codex-a2a:wire-contract/v1`
+
+- Scope: wire-level contract for supported methods, endpoints, and error semantics
+- Discovery surface: authenticated extended card `capabilities.extensions`, with full payload mirrored in OpenAPI `x-codex-contracts.wire_contract`
+- Transport: provider-private machine-readable contract metadata
+- Negotiation: not applicable; descriptive metadata only
+- Note: this URI remains a stable contract identifier and is published only on authenticated discovery surfaces