codex-a2a 1.3.1__tar.gz → 1.3.3__tar.gz

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/.github/workflows/compatibility.yml

@@ -1,4 +1,4 @@
-name: Scheduled Compatibility
+name: Scheduled Codex Compatibility
 
 on:
   workflow_dispatch:
@@ -9,39 +9,6 @@ permissions:
   contents: read
 
 jobs:
-  a2a-tck:
-    name: A2A Mandatory TCK
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.13"
-
-      - name: Setup uv
-        uses: astral-sh/setup-uv@v7
-        with:
-          enable-cache: true
-
-      - name: Run pinned mandatory TCK
-        env:
-          CONFORMANCE_TCK_REF: 5996b79f9cefa6fc390980e383e358a66fb9e49e # pragma: allowlist secret
-        run: bash ./scripts/conformance.sh mandatory
-
-      - name: Upload TCK evidence
-        if: always()
-        uses: actions/upload-artifact@v7
-        with:
-          name: a2a-tck-evidence
-          path: run/conformance/
-          if-no-files-found: error
-          retention-days: 14
-
   live-codex:
     name: Latest Codex App Server Smoke
     runs-on: ubuntu-latest

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/.pre-commit-config.yaml

@@ -6,12 +6,21 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.14
+  - repo: local
     hooks:
       - id: ruff
+        name: ruff check (uv)
+        entry: uv run --locked --extra dev ruff check --force-exclude
+        language: system
+        types_or: [python, pyi, jupyter]
+        require_serial: true
         args: ["--fix"]
       - id: ruff-format
+        name: ruff format (uv)
+        entry: uv run --locked --extra dev ruff format --force-exclude
+        language: system
+        types_or: [python, pyi, jupyter]
+        require_serial: true
   - repo: https://github.com/Yelp/detect-secrets
     rev: v1.5.0
     hooks:

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/CONTRIBUTING.md

@@ -72,9 +72,11 @@ bash -n scripts/smoke_test_built_cli.sh
 
 If `pre-commit` rewrites files, review the rewritten output and re-run the checks until the working tree is clean.
 
+Ruff's version is declared in the `dev` extra in `pyproject.toml` and resolved in `uv.lock`. The local pre-commit hooks run `uv run --locked --extra dev ruff`, so direct commands, hooks, and CI use the same project dependency. To upgrade Ruff, update that dependency and regenerate `uv.lock`; there is no separate Ruff hook revision to maintain.
+
 ## Compatibility Expectations
 
-- The repository targets Python 3.11, 3.12, and 3.13.
+- The repository targets Python 3.11 through 3.14. CI uses 3.13 for the full quality gate and exercises 3.11, 3.12, and 3.14 in the runtime matrix.
 - Machine-readable declarations should match actual runtime behavior.
 - Custom extensions must remain stable within the current major line unless a change is explicitly documented as breaking.
 - Shared metadata and wire contracts should not drift between Agent Card, OpenAPI, and runtime behavior.

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-a2a
-Version: 1.3.1
+Version: 1.3.3
 Summary: Codex A2A runtime adapter
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -23,14 +23,14 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: a2a-sdk==1.1.2
+Requires-Dist: a2a-sdk==1.1.5
 Requires-Dist: aiosqlite<1.0,>=0.20
 Requires-Dist: fastapi<0.142,>=0.121
 Requires-Dist: httpx<0.29,>=0.28.1
-Requires-Dist: protobuf<7.0,>=6.33.5
+Requires-Dist: protobuf<8.0,>=6.33.5
 Requires-Dist: pydantic<3.0,>=2.6
 Requires-Dist: pydantic-settings<3.0,>=2.2
-Requires-Dist: sqlalchemy<3.0,>=2.0
+Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0
 Requires-Dist: sse-starlette<4.0,>=2.1
 Requires-Dist: uvicorn<0.53,>=0.29
 Provides-Extra: dev
@@ -40,8 +40,8 @@ Requires-Dist: pygments<3.0,>=2.20.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-cov<8.0,>=5.0; extra == "dev"
-Requires-Dist: diff-cover<10,>=9; extra == "dev"
-Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: diff-cover<11,>=9; extra == "dev"
+Requires-Dist: ruff==0.16.9; extra == "dev"
 Requires-Dist: mypy<2.4,>=1.11; extra == "dev"
 Dynamic: license-file
 
@@ -66,7 +66,7 @@ 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.
+`codex-a2a` is an independent community adapter that adds an A2A service and control boundary to the local Codex CLI/App Server, with auth, streaming, session continuity, interrupt handling, and a built-in outbound A2A client. It is not an OpenAI or A2A Project distribution or endorsement.
 
 ## What This Is
 
@@ -172,7 +172,7 @@ 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 a maintained adapter/service contract instead of owning A2A transport, persistence, auth, and Codex-specific control mappings yourself
 - 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 integration layer or higher-level A2A consumption (see [Ecosystem](#ecosystem) for details).
@@ -212,24 +212,25 @@ The normative compatibility split and deployment model live in [Compatibility Gu
 - [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.
-- [External Conformance Experiments](docs/conformance.md) Manual A2A TCK experiment entrypoint and triage workflow.
+- [Optional External TCK Experiment](docs/conformance.md) Manual, non-normative investigation guidance; it is not part of CI or compatibility claims.
 - [Security Policy](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 
 ## Ecosystem
 
-`codex-a2a` is part of a growing landscape of A2A-compliant projects. Depending on your architecture, you may find these related projects useful:
+`codex-a2a` is an independent integration built on public upstream projects. The links below distinguish normative upstreams from community projects; inclusion does not imply endorsement or verified interoperability.
 
-### Foundations (Upstream)
+### Normative Upstreams
 
-- **[Intelligent-Internet/a2a-python](https://github.com/Intelligent-Internet/a2a-python)**: The core protocol implementation and SDK used by this adapter.
-- **Codex**: The underlying local agent runtime (Proprietary).
+- **[A2A Protocol](https://github.com/a2aproject/A2A)**: The Linux Foundation open protocol implemented by this adapter at the declared A2A `1.0` line.
+- **[a2aproject/a2a-python](https://github.com/a2aproject/a2a-python)**: The official Apache-2.0 Python SDK; this repository pins the `a2a-sdk` package to `1.1.2`.
+- **[openai/codex](https://github.com/openai/codex)**: The Apache-2.0 Codex CLI repository containing the local App Server used by this adapter. OpenAI's [open-source component list](https://developers.openai.com/codex/open-source) identifies the IDE extension and Codex cloud as not open source. Desktop and web product behavior is also separate from this local runtime and outside this repository's compatibility claim.
 
-### Gateways & Hubs (Vertical Integration)
+### Community Gateways and Hubs
 
-- **[liujuanjuan1984/a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub)**: An application-facing integration layer that consumes A2A-compliant instances (like `codex-a2a`) and provides higher-level normalization.
+- **[liujuanjuan1984/a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub)**: An application-facing integration layer for consuming A2A services such as `codex-a2a` and providing higher-level normalization.
 - **[jinyitao123/a2a-gateway](https://github.com/jinyitao123/a2a-gateway)**: Operates at the protocol-bridging layer, sitting between agent platforms and the A2A/MCP ecosystem to handle discovery and routing.
 
-### Alternative Implementations & Runtimes (Horizontal Differences)
+### Community Implementations and Runtimes
 
 - **[Intelligent-Internet/opencode-a2a](https://github.com/Intelligent-Internet/opencode-a2a)**: A complementary Python runtime implementation that shares similar protocol patterns and output negotiation practices.
 - **[MyPrototypeWhat/codex-a2a](https://github.com/MyPrototypeWhat/codex-a2a)**: A lightweight **TypeScript** Express middleware implementation. Ideal for developers looking for in-process SDK integration within a Node.js environment.

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/README.md

@@ -19,7 +19,7 @@ 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.
+`codex-a2a` is an independent community adapter that adds an A2A service and control boundary to the local Codex CLI/App Server, with auth, streaming, session continuity, interrupt handling, and a built-in outbound A2A client. It is not an OpenAI or A2A Project distribution or endorsement.
 
 ## What This Is
 
@@ -125,7 +125,7 @@ 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 a maintained adapter/service contract instead of owning A2A transport, persistence, auth, and Codex-specific control mappings yourself
 - 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 integration layer or higher-level A2A consumption (see [Ecosystem](#ecosystem) for details).
@@ -165,24 +165,25 @@ The normative compatibility split and deployment model live in [Compatibility Gu
 - [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.
-- [External Conformance Experiments](docs/conformance.md) Manual A2A TCK experiment entrypoint and triage workflow.
+- [Optional External TCK Experiment](docs/conformance.md) Manual, non-normative investigation guidance; it is not part of CI or compatibility claims.
 - [Security Policy](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 
 ## Ecosystem
 
-`codex-a2a` is part of a growing landscape of A2A-compliant projects. Depending on your architecture, you may find these related projects useful:
+`codex-a2a` is an independent integration built on public upstream projects. The links below distinguish normative upstreams from community projects; inclusion does not imply endorsement or verified interoperability.
 
-### Foundations (Upstream)
+### Normative Upstreams
 
-- **[Intelligent-Internet/a2a-python](https://github.com/Intelligent-Internet/a2a-python)**: The core protocol implementation and SDK used by this adapter.
-- **Codex**: The underlying local agent runtime (Proprietary).
+- **[A2A Protocol](https://github.com/a2aproject/A2A)**: The Linux Foundation open protocol implemented by this adapter at the declared A2A `1.0` line.
+- **[a2aproject/a2a-python](https://github.com/a2aproject/a2a-python)**: The official Apache-2.0 Python SDK; this repository pins the `a2a-sdk` package to `1.1.2`.
+- **[openai/codex](https://github.com/openai/codex)**: The Apache-2.0 Codex CLI repository containing the local App Server used by this adapter. OpenAI's [open-source component list](https://developers.openai.com/codex/open-source) identifies the IDE extension and Codex cloud as not open source. Desktop and web product behavior is also separate from this local runtime and outside this repository's compatibility claim.
 
-### Gateways & Hubs (Vertical Integration)
+### Community Gateways and Hubs
 
-- **[liujuanjuan1984/a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub)**: An application-facing integration layer that consumes A2A-compliant instances (like `codex-a2a`) and provides higher-level normalization.
+- **[liujuanjuan1984/a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub)**: An application-facing integration layer for consuming A2A services such as `codex-a2a` and providing higher-level normalization.
 - **[jinyitao123/a2a-gateway](https://github.com/jinyitao123/a2a-gateway)**: Operates at the protocol-bridging layer, sitting between agent platforms and the A2A/MCP ecosystem to handle discovery and routing.
 
-### Alternative Implementations & Runtimes (Horizontal Differences)
+### Community Implementations and Runtimes
 
 - **[Intelligent-Internet/opencode-a2a](https://github.com/Intelligent-Internet/opencode-a2a)**: A complementary Python runtime implementation that shares similar protocol patterns and output negotiation practices.
 - **[MyPrototypeWhat/codex-a2a](https://github.com/MyPrototypeWhat/codex-a2a)**: A lightweight **TypeScript** Express middleware implementation. Ideal for developers looking for in-process SDK integration within a Node.js environment.

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/docs/architecture.md

@@ -93,7 +93,7 @@ Use the docs by responsibility:
 - [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
-- [External Conformance Experiments](conformance.md): manual A2A TCK experiment entrypoint and triage workflow
+- [Optional External TCK Experiment](conformance.md): manual, non-normative investigation entrypoint and spec-first triage guidance
 - [Contributing Guide](../CONTRIBUTING.md): contributor workflow and validation
 - [Security Policy](../SECURITY.md): threat model and disclosure guidance
 

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/docs/compatibility.md

@@ -4,13 +4,21 @@ This document explains the compatibility promises this repository currently trie
 
 ## Runtime Support
 
-- Python versions: 3.11, 3.12, 3.13
-- A2A SDK line: `1.0.x`
-- A2A protocol version advertised by default: `1.0`
-- Normalized protocol compatibility lines declared today: `1.0`
+| Layer | Supported contract | Evidence and boundary |
+| --- | --- | --- |
+| Python | 3.11–3.14 | Package classifiers cover all four versions; CI runs 3.13 as the quality gate and 3.11, 3.12, and 3.14 in the runtime matrix. |
+| A2A Python SDK | Exactly `a2a-sdk==1.1.5` | Pinned in `pyproject.toml`; this is the [official A2A Python SDK](https://github.com/a2aproject/a2a-python), not a fork. |
+| Protocol Buffers | `protobuf>=6.33.5,<8.0` | The lockfile selects 7.36.2. SDK 1.1.5 supports protobuf 7; Google API Core, common protos, and proto-plus must resolve within the same range. Task retrieval delegates validation and history trimming to the SDK. |
+| SQLAlchemy | `sqlalchemy[asyncio]>=2.0,<3.0` | The `asyncio` extra explicitly installs `greenlet` for the async persistence engine, including standalone wheel installations. The lockfile selects the development version. |
+| A2A protocol | `1.0` wire line | The released upstream A2A specification is normative for portable core semantics; the current compatible release is `v1.0.1`. SDK compatibility with other protocol versions does not extend this adapter's claim. |
+| Inbound A2A transports | JSON-RPC and HTTP+JSON | Both are repository-owned runtime surfaces. gRPC is not exposed by this adapter. |
+| Codex local runtime | Codex CLI/App Server | The local [Apache-2.0 Codex CLI](https://github.com/openai/codex) is the upstream process boundary. Scheduled smoke tests install the latest stable CLI and complete a real local App Server turn. |
+| Codex App Server API | Stable methods by default | Stable and opt-in experimental schema dependencies are checked; the real turn smoke stays on the stable API. Experimental plugin methods require `CODEX_ENABLE_EXPERIMENTAL_API=true` and are not part of the default contract. |
 
 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.
 
+This repository is an independent community project. The [A2A Protocol project](https://github.com/a2aproject/A2A), its official SDK, and the OpenAI Codex CLI are upstream dependencies or specifications, not organizational ownership or endorsement of `codex-a2a`. OpenAI's [open-source component list](https://developers.openai.com/codex/open-source) identifies the IDE extension and Codex cloud as not open source. Desktop and web products are also separate product surfaces; their availability and behavior are not inherited from the open-source CLI/App Server contract and are outside this compatibility matrix.
+
 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
@@ -37,14 +45,19 @@ Open-source consumption guidance:
 
 ## Normative Sources
 
-When documentation or reference material disagrees, treat these as normative in this order:
+For portable A2A core semantics, treat these sources in this order:
 
-- runtime behavior validated by tests
-- machine-readable discovery output such as Agent Card, authenticated extended card, and OpenAPI metadata
+- the latest compatible released upstream A2A specification (`v1.0.x` for this repository's `1.0` wire line)
+- machine-readable discovery output such as Agent Card, authenticated extended card, and OpenAPI metadata, which declares the subset implemented here but cannot override the upstream core protocol
+- runtime behavior validated by tests, which is implementation evidence rather than authority when it disagrees with the protocol
 - repository-owned docs in `README.md`, `docs/`, and `CONTRIBUTING.md`
 
+The A2A TCK is deliberately excluded from this normative order and from automated repository gates. Its spec snapshot and test assumptions may lag the released protocol; maintainers may run it manually as optional investigation input, but its result does not establish or reject compatibility.
+
 Maintainer-local upstream Codex snapshots generated via `scripts/sync_codex_docs.sh` are optional reference inputs for comparison and protocol context. They do not override this repository's declared service contract.
 
+Upstream App Server stability labels also do not become repository promises automatically. Stable upstream methods enter this adapter's contract only after mapping, disclosure, and regression coverage; experimental upstream methods remain opt-in and may change with the installed Codex version.
+
 ## Compatibility-Sensitive Surface
 
 This repository still ships as an alpha project. Within that alpha line, these declared surfaces should not drift silently:
@@ -99,9 +112,9 @@ Execution-environment boundary fields are also published through the runtime pro
 - 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.
-- 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.
+- 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, `Part(data)` mention mapping, or the opaque `skill:v1` handle resolution/error contract should be treated as wire-level behavior changes. Client-supplied `skill.path` is never part of the accepted contract.
 - `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 normalized skill/app/plugin summaries and `mention_path` identifiers. Local paths (`skill.path`, marketplace paths) and raw upstream records are intentionally excluded from discovery responses; changes to normalized item fields, plugin marketplace mapping, or discovery watch task payload kinds should be treated as wire-level changes.
+- `codex.discovery.*` is compatibility-sensitive as the stable discovery contract for normalized skill/app/plugin summaries, opaque skill handles, and `mention_path` identifiers. Local paths (`skill.path`, marketplace paths) and raw upstream records are intentionally excluded from discovery responses; changes to normalized item fields, handle format/resolution, 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.
@@ -160,7 +173,8 @@ This repository distinguishes between three layers:
 
 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.skills.list` and `codex.discovery.apps.list` are stable read-only discovery methods. Experimental `codex.discovery.plugins.list` and `codex.discovery.plugins.read` are disabled and omitted from discovery by default; enable them explicitly with `CODEX_ENABLE_EXPERIMENTAL_API=true`.
+- Skill discovery returns opaque `skill:v1` handles. Core A2A skill data parts and `codex.turns.steer` accept the handle, resolve it only against the current enabled `skills/list` result, and reject client-supplied local paths.
 - `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_a2a-1.3.1 → codex_a2a-1.3.3}/docs/conformance-triage.md

@@ -1,11 +1,13 @@
-# External Conformance Triage
+# Optional TCK Observation Triage
 
 This document is the standing triage template for local `./scripts/conformance.sh` runs against the official `a2aproject/a2a-tck`.
 
-## Standards Used For Triage
+## Authorities Used For Triage
 
-- `a2a-sdk==1.1.2` as installed in this repository.
+- The latest compatible released upstream A2A specification is authoritative; currently this is `v1.0.1` for the repository's advertised `1.0` wire line.
+- `a2a-sdk==1.1.5` as installed in this repository.
 - The default A2A protocol version advertised by this repository: `1.0`.
+- TCK assertions are non-normative observations and may lag the released specification.
 - 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;
@@ -14,7 +16,7 @@ This document is the standing triage template for local `./scripts/conformance.s
 ## 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 `1.0` baseline.
+- `TCK mismatch`: the failure conflicts with the latest compatible released A2A specification or relies on a TCK-specific assumption.
 - `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,9 +27,9 @@ 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 extended card skills/examples, and OpenAPI `x-a2a-extension-contracts`.
+3. Compare the expectation first with the latest compatible released A2A specification, then with `docs/compatibility.md`, authenticated extended card skills/examples, and OpenAPI `x-a2a-extension-contracts`.
 4. Assign one classification label.
-5. Record whether the next action belongs in this repository, the TCK, or a future protocol compatibility issue.
+5. Record whether the next action belongs in this repository, the TCK, or a future protocol compatibility issue. A TCK failure alone is never sufficient evidence for a runtime change.
 
 ## Per-Test Triage
 

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/docs/conformance.md

@@ -1,13 +1,14 @@
-# External Conformance Experiments
+# Optional External TCK Experiment
 
-This repository keeps internal regression and external interoperability experiments separate on purpose.
+The A2A TCK is an optional manual investigation tool. It is not a repository compatibility dependency, protocol authority, CI job, or merge gate.
 
 ## Scope
 
 - `./scripts/validate_baseline.sh` remains the default internal regression entrypoint.
-- `./scripts/conformance.sh` is a local/manual experiment entrypoint for official external tooling.
-- External conformance output is investigation input, not an automatic merge gate.
-- `.github/workflows/compatibility.yml` runs the mandatory TCK weekly against a pinned TCK commit and preserves its evidence as a workflow artifact.
+- `./scripts/conformance.sh` is a local/manual experiment entrypoint for external tooling.
+- TCK output is untrusted investigation input and cannot establish or reject protocol compatibility.
+- The current TCK embeds an A2A `v1.0.0` specification snapshot while the compatible released protocol has advanced to `v1.0.1`; maintainers must check the released specification directly.
+- No repository workflow runs or gates on the TCK.
 
 ## Current Experiment Shape
 
@@ -33,7 +34,7 @@ bash ./scripts/conformance.sh
 Run a different TCK category:
 
 ```bash
-bash ./scripts/conformance.sh capabilities
+bash ./scripts/conformance.sh should
 ```
 
 Target an already running runtime instead of the local dummy-backed SUT:
@@ -72,13 +73,14 @@ 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==1.1.2`.
+- Some failures may reflect an outdated embedded specification or a TCK-specific interpretation. Resolve those disagreements against the latest compatible released A2A specification.
+- Some failures may come from TCK assumptions that do not match `a2a-sdk==1.1.5`.
 - 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.
+The experiment is useful only if those categories stay separate during triage. Never convert a TCK result directly into a compatibility claim or an implementation change.
 Use the authenticated compatibility profile and wire contract `protocol_compatibility` fields as the repository-owned declaration of which protocol lines are supported today.
 
-The same scheduled workflow installs the latest stable Codex CLI and runs `scripts/smoke_test_live_codex.sh`. The smoke check only verifies the real stdio app-server initialization and shutdown handshake; it does not send a model request or require provider credentials.
+The separate scheduled Codex workflow installs the latest stable Codex CLI and runs `scripts/smoke_test_live_codex.sh`. It does not invoke the A2A TCK.
 
 Record first-pass classifications in [conformance-triage.md](./conformance-triage.md).

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/docs/guide.md

@@ -271,7 +271,8 @@ These variables are forwarded to the local `codex app-server` subprocess.
 - `CODEX_WORKSPACE_ROOT`: default Codex workspace root (optional)
 - `CODEX_CLI_BIN`: Codex CLI binary path, default `codex`
   - For long-running Linux deployments managed by PM2, systemd, or similar supervisors, set this explicitly to the bundled native Codex binary.
-- `CODEX_MODEL`: default Codex model, default `gpt-5.1-codex`
+- `CODEX_ENABLE_EXPERIMENTAL_API`: opt in to Codex App Server experimental APIs, default `false`; currently enables plugin discovery only
+- `CODEX_MODEL`: optional startup model override; when unset, Codex selects its configured/default model
 - `CODEX_APPROVAL_POLICY`: default approval policy (`never`, `on-request`, etc.)
 - `CODEX_SANDBOX_MODE`: default sandbox mode (`danger-full-access`, `read-only`, etc.)
 - `CODEX_TIMEOUT`: request timeout in seconds, default `120`
@@ -371,6 +372,7 @@ These variables are forwarded to the local `codex app-server` subprocess.
 | `A2A_EXECUTION_WRITE_OUTSIDE_WORKSPACE` | Discovery write outside |
 | `CODEX_CLI_BIN` | Codex CLI path |
 | `CODEX_APP_SERVER_LISTEN` | Codex listen target |
+| `CODEX_ENABLE_EXPERIMENTAL_API` | Opt in to experimental App Server APIs |
 | `CODEX_WORKSPACE_ROOT` | Workspace root |
 | `CODEX_MODEL` | Default model |
 | `CODEX_MODEL_ID` | Turn model override |
@@ -434,7 +436,6 @@ 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_MODEL=gpt-5.1-codex \
 CODEX_APPROVAL_POLICY=never \
 CODEX_SANDBOX_MODE=danger-full-access \
 CODEX_MODEL_REASONING_EFFORT=high \
@@ -529,8 +530,9 @@ On the current npm global install layout for Linux x64, the command above resolv
 - Those provider-private skills use narrower `output_modes` where practical: query/control/watch handle surfaces declare `application/json` when their primary contract is a structured JSON-RPC result or `Part(data)` watch payload, while `codex.exec.stream` declares `text/plain` because stdout/stderr deltas and terminal summaries are emitted as `Part(text)`.
 - On the core chat surface, the `application/json` input mode is intentionally narrower than arbitrary JSON: only `Part(data={"type":"mention"|"skill", ...})` is part of the declared stable contract.
 - Image input maps to upstream `turn/start.input[].type=input_image`.
-- `mention.path` and `skill.path` are forwarded verbatim. The service does not guess app or plugin identifiers from display names.
-- Discovery responses no longer expose local `skill.path` values; callers that need rich-input skill items must supply the path from their own context.
+- `mention.path` is forwarded verbatim. The service does not guess app or plugin identifiers from display names.
+- Skill input accepts only the opaque `handle` returned by `codex.discovery.skills.list`; client-supplied `skill.path` is rejected. The service refreshes `skills/list`, verifies that the handle still resolves uniquely to an enabled skill, and only then supplies the current local name/path to Codex.
+- Skill handles use `skill:v1:<base64url-sha256>`. They are opaque, contain no reversible local path, and may expire when the discovered skill identity changes. Stable resolution errors distinguish invalid, missing/expired, disabled, ambiguous, and unavailable-discovery cases.
 - `local_image` is not part of the current declared stable rich-input contract.
 - Session query projections currently use the upstream Codex `session_id` as the A2A `contextId`. In that projection surface, `contextId` is the canonical session identity and the adapter does not duplicate the same value under `metadata.shared.session.id`.
 - Completed chat turns are persisted as `completed`; `input-required` is reserved for active interrupt asks that still need a reply.
@@ -707,12 +709,12 @@ This service exposes read-only Codex discovery methods through JSON-RPC:
 
 - `codex.discovery.skills.list`
 - `codex.discovery.apps.list`
-- `codex.discovery.plugins.list`
-- `codex.discovery.plugins.read`
+- `codex.discovery.plugins.list` (experimental; requires `CODEX_ENABLE_EXPERIMENTAL_API=true`)
+- `codex.discovery.plugins.read` (experimental; requires `CODEX_ENABLE_EXPERIMENTAL_API=true`)
 
 Use these methods before constructing rich input:
 
-- `skills.list` returns stable skill `name`/`scope` values; local skill paths are intentionally not exposed
+- `skills.list` returns stable skill metadata plus an opaque `handle`; local skill paths are intentionally not exposed
 - `apps.list` returns stable `mention_path=app://<id>` values
 - `plugins.list` and `plugins.read` return stable `mention_path=plugin://<plugin>@<marketplace>` values
 
@@ -720,7 +722,8 @@ Result-shape guidance:
 
 - use the normalized stable fields declared in Agent Card / OpenAPI first
 - discovery responses are whitelisted summaries; raw upstream records and local paths are intentionally excluded
-- `plugin/list` and `plugin/read` remain upstream experimental; this service exposes a stable minimum subset without raw passthrough
+- `plugin/list` and `plugin/read` remain upstream experimental, are disabled by default, and are advertised only after `CODEX_ENABLE_EXPERIMENTAL_API=true`; the opt-in adapter response remains a whitelisted minimum subset without raw passthrough
+- construct skill rich input as `Part(data={"type":"skill","handle":"skill:v1:..."})`; never send a server-local path
 
 ### Skills List (`codex.discovery.skills.list`)
 
@@ -734,7 +737,7 @@ curl -sS http://127.0.0.1:8000/ \
     "method": "codex.discovery.skills.list",
     "params": {
       "cwds": ["/workspace/project"],
-      "forceReload": true
+      "force_reload": true
     }
   }'
 ```
@@ -751,13 +754,15 @@ curl -sS http://127.0.0.1:8000/ \
     "method": "codex.discovery.apps.list",
     "params": {
       "limit": 20,
-      "forceRefetch": false
+      "force_refetch": false
     }
   }'
 ```
 
 ### Plugins List (`codex.discovery.plugins.list`)
 
+This method is available only when the service starts with `CODEX_ENABLE_EXPERIMENTAL_API=true`.
+
 ```bash
 curl -sS http://127.0.0.1:8000/ \
   -H 'content-type: application/json' \
@@ -768,13 +773,15 @@ curl -sS http://127.0.0.1:8000/ \
     "method": "codex.discovery.plugins.list",
     "params": {
       "cwds": ["/workspace/project"],
-      "forceRemoteSync": false
+      "force_remote_sync": false
     }
   }'
 ```
 
 ### Plugin Read (`codex.discovery.plugins.read`)
 
+This method is available only when the service starts with `CODEX_ENABLE_EXPERIMENTAL_API=true`.
+
 ```bash
 curl -sS http://127.0.0.1:8000/ \
   -H 'content-type: application/json' \
@@ -784,8 +791,8 @@ curl -sS http://127.0.0.1:8000/ \
     "id": 14,
     "method": "codex.discovery.plugins.read",
     "params": {
-      "marketplacePath": "/workspace/project/.codex/plugins/marketplace.json",
-      "pluginName": "sample"
+      "marketplace_path": "/workspace/project/.codex/plugins/marketplace.json",
+      "plugin_name": "sample"
     }
   }'
 ```

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/pyproject.toml

@@ -25,14 +25,14 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
 ]
 dependencies = [
-    "a2a-sdk==1.1.2",
+    "a2a-sdk==1.1.5",
     "aiosqlite>=0.20,<1.0",
     "fastapi>=0.121,<0.142",
     "httpx>=0.28.1,<0.29",
-    "protobuf>=6.33.5,<7.0",
+    "protobuf>=6.33.5,<8.0",
     "pydantic>=2.6,<3.0",
     "pydantic-settings>=2.2,<3.0",
-    "sqlalchemy>=2.0,<3.0",
+    "sqlalchemy[asyncio]>=2.0,<3.0",
     "sse-starlette>=2.1,<4.0",
     "uvicorn>=0.29,<0.53",
 ]
@@ -45,8 +45,8 @@ dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=5.0,<8.0",
-    "diff-cover>=9,<10",
-    "ruff>=0.5",
+    "diff-cover>=9,<11",
+    "ruff==0.16.9",
     "mypy>=1.11,<2.4",
 ]
 

{codex_a2a-1.3.1 → codex_a2a-1.3.3}/scripts/README.md

@@ -16,10 +16,11 @@ This document only explains the remaining repository-local maintainer scripts. U
 - [`scripts/check_dead_code.py`](./check_dead_code.py): run the conservative private dead-code guard used by the default validation baseline.
 - [`scripts/audit_low_call_sites.py`](./audit_low_call_sites.py): report low-call-count function and method candidates for manual wrapper/abstraction review.
 - [`scripts/validate_runtime_matrix.sh`](./validate_runtime_matrix.sh): run the reduced runtime-only validation used by the multi-version CI matrix.
-- [`scripts/conformance.sh`](./conformance.sh): run the official A2A TCK as a local/manual external compatibility experiment.
+- [`scripts/conformance.sh`](./conformance.sh): optionally run the A2A TCK as a manual investigation tool and preserve raw evidence; it is not an automated compatibility gate.
 - [`scripts/dependency_health.sh`](./dependency_health.sh): run the standalone dependency review flow (`sync`/`pip check`, outdated package listing, and dev vulnerability audit).
 - [`scripts/smoke_test_built_cli.sh`](./smoke_test_built_cli.sh): validate that a built wheel can be installed through `uv tool` and becomes healthy.
-- [`scripts/smoke_test_live_codex.sh`](./smoke_test_live_codex.sh): initialize and close a real locally installed Codex app-server without making a model request.
+- [`scripts/smoke_test_live_codex.sh`](./smoke_test_live_codex.sh): verify the installed Codex app-server stable and opt-in experimental schema dependencies, discover and resolve an opaque workspace-skill handle, and drive one real stable-API thread/turn against an isolated local Responses provider.
+- [`scripts/check_codex_app_server_schema.py`](./check_codex_app_server_schema.py): compare generated Codex app-server schema tokens with the stable adapter dependencies; pass `--include-experimental` when validating the opt-in plugin API.
 - [`scripts/sync_codex_docs.sh`](./sync_codex_docs.sh): refresh local upstream Codex reference snapshots when maintainers need them.
 
 ## Release Recovery
@@ -32,11 +33,12 @@ The `Publish` workflow now separates build, PyPI publish, and GitHub Release syn
 
 ## Notes
 
-- `conformance.sh` intentionally stays outside the default regression gate. Use it to gather external compatibility evidence, then triage results in [`docs/conformance-triage.md`](../docs/conformance-triage.md).
+- `conformance.sh` intentionally stays outside CI and the default regression baseline. Use it only for manual investigation, then adjudicate observations against the latest compatible released A2A specification; triage guidance lives in [`docs/conformance-triage.md`](../docs/conformance-triage.md).
 - `validate_baseline.sh` and `dependency_health.sh` intentionally remain separate entrypoints and share common prerequisites through [`health_common.sh`](./health_common.sh).
 - `validate_baseline.sh` now includes a conservative private dead-code check before type-checking and test execution.
 - `audit_low_call_sites.py` is intentionally advisory only. Use it to surface low-call-count candidates, then inspect the actual consumer chain before removing an abstraction.
 - `validate_baseline.sh` now blocks on runtime dependency vulnerability audit, while `dependency_health.sh` remains focused on broader dependency review (`outdated` + dev audit).
+- The baseline makes up to three runtime audit attempts (the initial attempt plus at most two retries), with a fresh cache per attempt. If every attempt fails, it returns the last audit exit code and stops before package build and wheel smoke testing. A successful retry allows validation to continue.
 - [`.github/dependabot.yml`](../.github/dependabot.yml) prefers a single weekly grouped Dependabot PR for `uv`, while the repository scripts remain the explicit audit and validation entrypoints.
 - End-user runtime startup does not use repository scripts. Prefer the published CLI command documented in [README.md](../README.md) and [docs/guide.md](../docs/guide.md).
 - Keep long-form documentation changes in `docs/` to avoid divergence.