opencode-a2a 0.7.1__tar.gz → 0.8.0__tar.gz

opencode_a2a-0.8.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 1
+    commit-message:
+      prefix: "deps"
+    labels:
+      - "dependencies"
+    groups:
+      uv-all-updates:
+        patterns:
+          - "*"

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/CONTRIBUTING.md

@@ -44,10 +44,11 @@ uv run opencode-a2a serve
 Run the default validation baseline before opening a PR:
 
 ```bash
-uv run pre-commit run --all-files
-uv run pytest
+bash ./scripts/doctor.sh
 ```
 
+`doctor.sh` is the primary repository validation entrypoint. It currently runs locked-environment sync, dependency compatibility checks, `pre-commit`, `mypy`, `pytest`, the repository coverage gate, package build, and a built-wheel smoke test.
+
 If you change shell scripts, also run `bash -n` on each modified script, for example:
 
 ```bash
@@ -63,7 +64,7 @@ bash ./scripts/conformance.sh
 
 Treat that output as investigation input. Do not fold it into `doctor.sh` or the default CI quality gate unless the repository explicitly decides to promote a specific experiment into a maintained policy.
 
-If you change extension methods, extension metadata, or Agent Card/OpenAPI contract surfaces, also run:
+If you change extension methods, extension metadata, or Agent Card/OpenAPI contract surfaces, also make sure the targeted contract checks stay green:
 
 ```bash
 uv run pytest tests/contracts/test_extension_contract_consistency.py
@@ -107,7 +108,7 @@ Update docs together with code whenever you change:
 - user-facing request or response shapes
 - operational scripts
 
-Keep compatibility guidance centralized in [docs/guide.md](docs/guide.md) unless a new standalone document is clearly necessary.
+Keep usage details in [docs/guide.md](docs/guide.md) and compatibility-sensitive stability guidance in [docs/compatibility.md](docs/compatibility.md).
 
 When changing extension contracts, update [`src/opencode_a2a/contracts/extensions.py`](src/opencode_a2a/contracts/extensions.py) first and keep these generated/documented surfaces aligned:
 

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a
-Version: 0.7.1
+Version: 0.8.0
 Summary: OpenCode A2A runtime
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -19,7 +19,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: a2a-sdk==0.3.25
+Requires-Dist: a2a-sdk==0.3.26
 Requires-Dist: aiosqlite<1.0,>=0.20
 Requires-Dist: fastapi<1.0,>=0.110
 Requires-Dist: httpx<1.0,>=0.27
@@ -139,7 +139,7 @@ curl http://127.0.0.1:8000/.well-known/agent-card.json
 - Declared supported protocol lines: `0.3`, `1.0`
 - `0.3` is the stable interoperability baseline for the current runtime surface.
 - `1.0` currently covers version negotiation plus protocol-aware JSON-RPC and REST error shaping, while transport payloads, enums, pagination, signatures, and interface-level protocol declarations still follow the shipped SDK baseline.
-- The detailed compatibility matrix and machine-readable support boundary are documented in [`docs/guide.md`](docs/guide.md).
+- The detailed compatibility matrix and machine-readable support boundary are documented in [`docs/guide.md`](docs/guide.md) and [`docs/compatibility.md`](docs/compatibility.md).
 
 ## Peering Node / Outbound Access
 
@@ -203,7 +203,11 @@ Read before deployment:
 
 ## Further Reading
 
+- [docs/architecture.md](docs/architecture.md) Service responsibility boundaries and request flow.
+- [docs/maintainer-architecture.md](docs/maintainer-architecture.md) Internal module boundaries and maintainer call chains.
+- [docs/compatibility.md](docs/compatibility.md) Compatibility-sensitive surface and contract-honesty guidance.
 - [docs/guide.md](docs/guide.md) Usage guide, transport details, streaming behavior, extensions, and examples.
+- [docs/conformance.md](docs/conformance.md) External TCK experiment workflow and artifact handling.
 - [SECURITY.md](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 
 ## Development

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/README.md

@@ -98,7 +98,7 @@ curl http://127.0.0.1:8000/.well-known/agent-card.json
 - Declared supported protocol lines: `0.3`, `1.0`
 - `0.3` is the stable interoperability baseline for the current runtime surface.
 - `1.0` currently covers version negotiation plus protocol-aware JSON-RPC and REST error shaping, while transport payloads, enums, pagination, signatures, and interface-level protocol declarations still follow the shipped SDK baseline.
-- The detailed compatibility matrix and machine-readable support boundary are documented in [`docs/guide.md`](docs/guide.md).
+- The detailed compatibility matrix and machine-readable support boundary are documented in [`docs/guide.md`](docs/guide.md) and [`docs/compatibility.md`](docs/compatibility.md).
 
 ## Peering Node / Outbound Access
 
@@ -162,7 +162,11 @@ Read before deployment:
 
 ## Further Reading
 
+- [docs/architecture.md](docs/architecture.md) Service responsibility boundaries and request flow.
+- [docs/maintainer-architecture.md](docs/maintainer-architecture.md) Internal module boundaries and maintainer call chains.
+- [docs/compatibility.md](docs/compatibility.md) Compatibility-sensitive surface and contract-honesty guidance.
 - [docs/guide.md](docs/guide.md) Usage guide, transport details, streaming behavior, extensions, and examples.
+- [docs/conformance.md](docs/conformance.md) External TCK experiment workflow and artifact handling.
 - [SECURITY.md](SECURITY.md) Threat model, deployment caveats, and vulnerability disclosure guidance.
 
 ## Development

opencode_a2a-0.8.0/docs/architecture.md

@@ -0,0 +1,101 @@
+# Architecture Guide
+
+This document explains what `opencode-a2a` is responsible for, what remains inside OpenCode, and how requests move through the adapter boundary.
+
+## System Role
+
+`opencode-a2a` is an adapter layer between A2A clients and an OpenCode runtime.
+
+It is responsible for:
+
+- exposing A2A-facing HTTP+JSON and JSON-RPC endpoints
+- normalizing transport, streaming, session, and interrupt contracts
+- applying authentication, logging, persistence, and deployment-side guardrails
+- hosting an outbound A2A client for peer calls triggered by CLI usage or `a2a_call`
+
+It is not responsible for:
+
+- replacing OpenCode's own provider or model selection internals
+- hard multi-tenant isolation inside one shared deployment by default
+- acting as a general OpenCode process supervisor
+
+## Adapter Layers
+
+```mermaid
+flowchart LR
+    Client["A2A Client / Hub / Gateway"] --> Gateway["opencode-a2a"]
+    Gateway --> Contracts["A2A contracts\ntransport/session/interrupt"]
+    Gateway --> Ops["Auth / logging / persistence / deployment boundary"]
+    Contracts --> OpenCode["OpenCode runtime"]
+    Ops --> OpenCode
+    Gateway --> Peer["Embedded outbound A2A client"]
+```
+
+This view emphasizes service responsibility boundaries rather than internal module structure. The root [README](../README.md) keeps the overview path for first-time readers, while [maintainer-architecture.md](./maintainer-architecture.md) covers module boundaries and request call chains for contributors.
+
+## Request Flow
+
+### Standard send/stream flow
+
+1. A client calls the REST or JSON-RPC endpoint.
+2. FastAPI middleware validates auth, request size, protocol version, and logging policy.
+3. The adapter maps transport payloads into the OpenCode-facing execution path.
+4. The execution layer calls the upstream OpenCode runtime and consumes its stream or unary response.
+5. The service maps the result back into shared A2A-facing task, message, and stream event contracts.
+
+### Streaming flow
+
+For streaming requests, the adapter does more than simple passthrough:
+
+- classifies stream blocks into shared types such as `text`, `reasoning`, and `tool_call`
+- preserves stable event and message identity where possible
+- emits shared interrupt lifecycle state
+- avoids duplicate final snapshots when streaming already produced the final text
+
+Detailed streaming contract: [Usage Guide](guide.md)
+
+### Session flow
+
+The service keeps a shared session continuation contract around `metadata.shared.session.id` and adapter-derived `contextId`, so clients can continue work without binding directly to raw OpenCode session IDs.
+
+### Outbound peer flow
+
+The same process can also act as an embedded A2A client:
+
+- CLI calls route through the local client facade
+- server-side `a2a_call` tool execution uses the same outbound client settings
+- outbound auth, timeouts, and transport preferences are configured independently from inbound auth
+
+## Boundary Model
+
+The adapter improves the runtime boundary, but it is not a full trust-boundary replacement.
+
+### What the adapter boundary helps with
+
+- stable A2A-facing contract shape
+- auth enforcement on A2A entrypoints
+- payload logging controls
+- lightweight persistence for SDK task rows plus adapter-managed runtime state
+- compatibility metadata for clients and operators
+
+### What still belongs to the OpenCode runtime boundary
+
+- provider credential consumption
+- workspace side effects
+- upstream model/provider behavior
+- host-level process supervision and isolation
+
+That is why deployments should still be treated as trusted or controlled unless stronger isolation is added outside this repository.
+
+## Documentation Split
+
+Use the docs by responsibility:
+
+- [README](../README.md): project overview, install/start path, and entry navigation
+- [Compatibility Guide](compatibility.md): compatibility-sensitive surface and stability expectations
+- [Usage Guide](guide.md): runtime configuration, transport contracts, extensions, and 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 disclosure policy
+- [Conformance Notes](conformance.md): external TCK experiment workflow
+- [Contributing Guide](../CONTRIBUTING.md): contributor workflow and validation
+- [Security Policy](../SECURITY.md): threat model and disclosure guidance

opencode_a2a-0.8.0/docs/compatibility.md

@@ -0,0 +1,147 @@
+# Compatibility Guide
+
+This document explains the compatibility promises `opencode-a2a` currently tries to uphold for A2A consumers, operators, and maintainers.
+
+## Runtime Support
+
+- Python versions: 3.11, 3.12, 3.13
+- A2A SDK line: `0.3.x`
+- Default advertised protocol line: `0.3`
+- Declared supported protocol lines: `0.3`, `1.0`
+
+The repository pins the SDK version in `pyproject.toml`. Upgrade the SDK deliberately rather than relying on floating dependency resolution.
+
+## Contract Honesty
+
+Machine-readable discovery surfaces must reflect actual runtime behavior:
+
+- public Agent Card
+- authenticated extended card
+- OpenAPI metadata
+- JSON-RPC wire contract
+- compatibility profile
+
+If runtime support is not actually implemented, do not publish it as a supported machine-readable capability.
+
+Consumer 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 a claim that they are part of the A2A core baseline.
+- Treat `opencode.*` methods and `metadata.opencode.*` fields as provider-private OpenCode control and discovery surfaces layered on top of the portable A2A baseline.
+- Treat [extension-specifications.md](./extension-specifications.md) as the stable URI/spec index, not as the main usage guide.
+
+## Normative Sources
+
+When docs or reference material disagree, treat these as normative in this order:
+
+- runtime behavior validated by tests
+- machine-readable discovery output such as Agent Card, authenticated extended card, and OpenAPI metadata
+- repository-owned docs in `README.md`, `docs/`, and `CONTRIBUTING.md`
+
+External TCK runs and local conformance experiments are investigation inputs. They do not override the repository's declared contract by themselves.
+
+## Compatibility-Sensitive Surface
+
+This repository still ships as an alpha project. Within that alpha line, these declared surfaces should not drift silently:
+
+- core A2A send / stream / task methods
+- version negotiation and protocol-aware error shaping
+- shared session-binding metadata
+- shared model-selection metadata
+- shared streaming metadata
+- declared custom JSON-RPC extension methods
+- authenticated extended card and OpenAPI wire-contract metadata
+
+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 interoperability depends on it. Current examples:
+
+- `tasks/resubscribe` replay-once behavior for terminal updates
+- first-terminal-state-wins task persistence policy
+- task-scoped `acceptedOutputModes` negotiation persistence across send / stream / get / resubscribe
+- request-body rejection behavior for oversized transport payloads
+
+## Deployment Profile
+
+The current service profile is intentionally:
+
+- single-tenant
+- shared-workspace
+- adapter boundary around one OpenCode deployment
+
+One deployed instance should be treated as a single-tenant trust boundary, not as a secure multi-tenant runtime boundary.
+
+Execution-environment boundary fields published through the runtime profile are declarative deployment metadata. They are not promises that every host-side approval, sandbox escalation, or filesystem change will be reflected live per request.
+
+## Persistence Compatibility
+
+Task durability is deployment-dependent:
+
+- `A2A_TASK_STORE_BACKEND=database` preserves SDK task rows plus adapter-managed session and interrupt state across restarts
+- `A2A_TASK_STORE_BACKEND=memory` keeps the service in an ephemeral development profile
+
+Task-store behavior that should remain stable for clients:
+
+- once a task reaches a terminal state, later conflicting writes are dropped on a first-terminal-state-wins basis
+- task-store I/O failures are surfaced as stable service errors instead of leaking backend-specific exceptions
+- accepted output-mode negotiation for a task is persisted with the task so later reads keep the same filtered output contract
+- adapter-managed migrations only own adapter state tables; SDK-managed task schema remains SDK-owned
+
+The default SQLite-first profile is intended for local or controlled single-instance deployments. Wider SQLAlchemy dialect compatibility should be treated as implementation latitude rather than a strong public promise unless explicitly documented later.
+
+## 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.
+- Deployment-conditional methods must be declared as conditional rather than silently disappearing.
+- `opencode.sessions.prompt_async` input-part passthrough is compatibility-sensitive. Changes to supported part types, passthrough field semantics, or rejection behavior should be treated as wire-level changes.
+- `opencode.sessions.shell` is compatibility-sensitive as a deployment-conditional shell snapshot surface. It should not silently widen into a general interactive shell API.
+- `opencode.workspaces.*` and `opencode.worktrees.*` are boundary-sensitive and should remain explicitly provider-private, operator-scoped, and deployment-conditional where applicable.
+- Interrupt callback and recovery methods are compatibility-sensitive because clients may depend on request ID lifecycle, expiry semantics, and identity scoping.
+- Agent Card media modes and `acceptedOutputModes` handling are compatibility-sensitive. Changes to declared chat modes, to task-scoped negotiation persistence, or to `DataPart` -> `TextPart` downgrade behavior should be treated as wire-level changes.
+- Agent Card and OpenAPI publication of `protocol_compatibility`, `service_behaviors`, and runtime feature toggles is compatibility-sensitive discoverability surface.
+
+## Extension Boundary Governance
+
+When evaluating or evolving `opencode.*` methods, this repository uses the following 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 `opencode.*` methods default to provider-private extension status.
+- 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.
+- Subtask/subagent fan-out, task-tool internals, and similar upstream execution mechanisms should stay framed as upstream runtime behavior even when passthrough compatibility exists.
+
+Each new extension proposal should answer:
+
+- 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 and destructive-side-effect boundaries enforceable?
+- can the result shape avoid overfitting OpenCode internals into fake A2A core semantics?
+
+## Extension Taxonomy
+
+This repository distinguishes between three layers:
+
+- core A2A surface
+  - standard send / stream / task methods
+- shared extensions
+  - repo-family conventions such as session binding, model selection, stream hints, and interrupt callbacks
+- OpenCode-specific extensions
+  - `opencode.*` JSON-RPC methods plus `metadata.opencode.*`
+
+Important note:
+
+- `urn:a2a:*` extension URIs used here should be read as shared conventions in this repository family.
+- They are not a claim that those extensions are part of the A2A core baseline.
+- `opencode.*` methods are intentionally product-specific. They improve OpenCode-aware workflows but should not be assumed to transfer unchanged to unrelated A2A agents.
+
+## Non-Goals
+
+This repository does not currently promise:
+
+- hard multi-tenant isolation inside one instance
+- generic provider-auth orchestration on behalf of OpenCode
+- a claim that all declared `1.0` protocol surfaces are fully implemented beyond the documented compatibility matrix
+
+Those areas may evolve later, but they should not be implied by current machine-readable discovery output.

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/docs/extension-specifications.md

@@ -1,6 +1,6 @@
 # Extension Specifications
 
-This document is the stable specification surface referenced by the extension URIs published in the Agent Card. It is intentionally a compact URI/spec index, not the main consumer guide. For runtime behavior, request/response examples, and client integration guidance, see [`guide.md`](./guide.md).
+This document is the stable specification surface referenced by the extension URIs published in the Agent Card. It is intentionally a compact URI/spec index, not the main consumer guide. For runtime behavior, request/response examples, and client integration guidance, see [`guide.md`](./guide.md). For compatibility-sensitive surface and contract-honesty guidance, see [`compatibility.md`](./compatibility.md).
 
 ## SDK Compatibility Note
 

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/docs/guide.md

@@ -1,6 +1,6 @@
 # Usage Guide
 
-This guide covers configuration, authentication, API behavior, streaming re-subscription, and A2A client examples. It is the canonical document for implementation-level protocol contracts and JSON-RPC extension details; README stays at overview level.
+This guide covers configuration, authentication, API behavior, streaming re-subscription, and A2A client examples. It is the canonical document for implementation-level protocol contracts and JSON-RPC extension details; [README](../README.md) stays at overview level, [architecture.md](./architecture.md) explains the service boundary, [maintainer-architecture.md](./maintainer-architecture.md) covers the internal module view for contributors, and [compatibility.md](./compatibility.md) defines the compatibility-sensitive surface.
 
 ## Transport Contracts
 
@@ -199,6 +199,8 @@ If one deployment works while another fails against the same upstream provider,
 - Main chat requests that explicitly send `configuration.acceptedOutputModes` must stay compatible with the declared chat output modes.
 - Current main chat requests must continue accepting `text/plain`; requests that only accept `application/json` or other incompatible modes are rejected before execution starts.
 - `application/json` is additive structured-output support for incremental `tool_call` payloads. It does not guarantee that ordinary assistant prose can always be losslessly represented as JSON, so consumers that expect normal chat text should keep accepting `text/plain`.
+- When a client accepts `text/plain` but not `application/json`, structured `tool_call` payloads are downgraded to compact JSON text instead of being silently dropped.
+- Accepted output-mode negotiation is persisted as task-scoped metadata so later `tasks/get` and `tasks/resubscribe` reads keep the same filtered response contract as the original `message/send` or `message:stream` request.
 - Main chat input supports structured A2A `parts` passthrough:
   - `TextPart` is forwarded as an OpenCode text part.
   - `FilePart(FileWithBytes)` is forwarded as a `file` part with a `data:` URL.
@@ -220,6 +222,8 @@ If one deployment works while another fails against the same upstream provider,
 - `message.part.delta` and `message.part.updated` are merged per `part_id`; out-of-order deltas are buffered and replayed when the corresponding `part.updated` arrives.
 - Structured `tool` parts are emitted as `tool_call` blocks backed by `DataPart(data={...})`, while `text` and `reasoning` continue to use `TextPart`.
 - `tool_call` block payloads are normalized structured objects that may expose fields such as `call_id`, `tool`, `status`, `title`, `subtitle`, `input`, `output`, and `error`.
+- If `application/json` is not accepted but `text/plain` is still accepted, those `tool_call` blocks are downgraded to stable compact JSON text so text-only clients retain the same observable state transitions.
+- When a request restricts `acceptedOutputModes`, the stream applies the same output filtering before persistence so later task snapshots do not re-expose filtered structured blocks.
 - Final status event metadata may include normalized token usage at `metadata.shared.usage` with fields such as `input_tokens`, `output_tokens`, `total_tokens`, optional `reasoning_tokens`, optional `cache_tokens.read_tokens` / `cache_tokens.write_tokens`, and optional `cost`.
 - Usage is extracted from documented info payloads and supported usage parts such as `step-finish`; non-usage parts with similar fields are ignored.
 - Interrupt events (`permission.asked` / `question.asked`) are mapped to `TaskStatusUpdateEvent(final=false, state=input-required)` with details at `metadata.shared.interrupt`, including `request_id`, interrupt `type`, `phase=asked`, and a normalized minimal callback payload.

opencode_a2a-0.8.0/docs/maintainer-architecture.md

@@ -0,0 +1,132 @@
+# Maintainer Architecture Guide
+
+This document describes the internal structure, module boundaries, and main request call chains of `opencode-a2a`. It is intended for maintainers and contributors. Use [architecture.md](./architecture.md) for the higher-level service boundary view and [guide.md](./guide.md) for deployment-facing runtime configuration.
+
+## Core Component Map
+
+```mermaid
+flowchart TD
+    subgraph Inbound["Server Layer (src/opencode_a2a/server/)"]
+        App["application.py (FastAPI assembly)"]
+        Middleware["middleware.py"]
+        AgentCard["agent_card.py / openapi.py"]
+    end
+
+    subgraph Execution["Execution Layer (src/opencode_a2a/execution/)"]
+        Executor["executor.py"]
+        Coordinator["coordinator.py"]
+        StreamRuntime["stream_runtime.py"]
+        ToolOrch["tool_orchestration.py"]
+    end
+
+    subgraph Upstream["OpenCode Upstream Layer"]
+        UpstreamClient["opencode_upstream_client.py"]
+        Invocation["invocation.py"]
+    end
+
+    subgraph Extensions["Extension / Contract Layer"]
+        Jsonrpc["jsonrpc/"]
+        Contracts["contracts/extensions.py"]
+        Profile["profile/runtime.py"]
+    end
+
+    subgraph Persistence["Persistence Layer"]
+        TaskStore["server/task_store.py"]
+        StateStore["server/state_store.py"]
+        Migrations["server/migrations.py"]
+    end
+
+    Inbound --> Execution
+    Inbound --> Extensions
+    Execution --> Upstream
+    Inbound --> Persistence
+    Execution --> Persistence
+```
+
+## Request Call Chain
+
+### Inbound Message Send / Stream
+
+1. `server/application.py` assembles the FastAPI app, SDK adapters, and middleware stack.
+2. `server/middleware.py` handles auth, request sizing, protocol negotiation, logging, and response headers.
+3. The SDK-backed handler delegates execution to `execution/executor.py`.
+4. The execution layer coordinates session continuity, stream handling, tool calls, and error translation through:
+   - `execution/coordinator.py`
+   - `execution/stream_runtime.py`
+   - `execution/tool_orchestration.py`
+5. `opencode_upstream_client.py` sends requests to the upstream OpenCode runtime.
+6. The adapter maps upstream responses back into A2A tasks, messages, artifacts, and stream events.
+
+### JSON-RPC Extension Path
+
+1. `jsonrpc/application.py` owns the adapter-specific JSON-RPC application boundary.
+2. `jsonrpc/dispatch.py` and handler modules under `jsonrpc/handlers/` route provider-private methods.
+3. `contracts/extensions.py` remains the SSOT for extension metadata exposed through Agent Card and OpenAPI.
+4. Tests under `tests/contracts/` and `tests/jsonrpc/` guard contract drift.
+
+### Outbound Peer Call Path
+
+1. CLI or server-side tool execution asks `server/client_manager.py` for an outbound client.
+2. `client/` builds and configures the embedded A2A client facade.
+3. Outbound peer responses are normalized before being reintroduced into the local runtime surface.
+
+## Module Responsibilities
+
+### Server Layer
+
+- `server/application.py`: app assembly, route wiring, request handler customization, and top-level lifecycle integration
+- `server/middleware.py`: auth, protocol negotiation, payload/body guards, logging, and response decoration
+- `server/agent_card.py` / `server/openapi.py`: machine-readable contract publication
+- `server/rest_tasks.py`: SDK-owned REST task routes plus adapter-specific list behavior
+
+### Execution Layer
+
+- `execution/executor.py`: main orchestration entrypoint
+- `execution/coordinator.py`: OpenCode session coordination and request shaping
+- `execution/stream_runtime.py` / `execution/stream_events.py`: stream normalization and event conversion
+- `execution/tool_orchestration.py`: embedded peer-call tool handling
+- `execution/upstream_error_translator.py` / `execution/tool_error_mapping.py`: upstream-facing error normalization
+
+### Extension and Contract Layer
+
+- `contracts/extensions.py`: SSOT for extension metadata, compatibility profile, and wire-contract payloads
+- `jsonrpc/`: provider-private JSON-RPC extension surface
+- `profile/runtime.py`: runtime profile that feeds Agent Card, OpenAPI, and compatibility metadata
+- `protocol_versions.py`: protocol normalization and negotiation helpers
+
+### Persistence Layer
+
+- `server/task_store.py`: SDK task store construction plus adapter policy wrappers
+- `server/state_store.py`: session binding and interrupt repositories
+- `server/migrations.py`: adapter-managed state schema migrations
+
+### Client Layer
+
+- `client/`: outbound peer card discovery, request context, auth handling, polling fallback, and error mapping
+
+## Key Persistence Points
+
+- SDK task rows stored through the configured task store backend
+- adapter-managed session binding / ownership state
+- interrupt request bindings and tombstones
+- pending preferred-session claims
+
+The custom migration runner owns only adapter-managed state tables; SDK-managed task schema still follows the SDK path.
+
+## Configuration Layering
+
+Configuration is handled in [config.py](../src/opencode_a2a/config.py) with `pydantic-settings`.
+
+- `A2A_*`: inbound runtime, outbound peer client, protocol, persistence, and deployment metadata
+- `OPENCODE_*`: upstream OpenCode connection and request behavior
+
+## Practical Reading Order
+
+For maintainers new to the codebase, this order usually gives the fastest payoff:
+
+1. `README.md`
+2. `docs/architecture.md`
+3. `src/opencode_a2a/server/application.py`
+4. `src/opencode_a2a/execution/executor.py`
+5. `src/opencode_a2a/contracts/extensions.py`
+6. `docs/guide.md`

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/pyproject.toml

@@ -24,7 +24,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
 ]
 dependencies = [
-    "a2a-sdk==0.3.25",
+    "a2a-sdk==0.3.26",
     "aiosqlite>=0.20,<1.0",
     "fastapi>=0.110,<1.0",
     "httpx>=0.27,<1.0",

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/scripts/README.md

@@ -11,7 +11,7 @@ Executable scripts live in this directory. This file is the entry index for the
 
 ## Other Scripts
 
-- [`doctor.sh`](./doctor.sh): primary local development regression entrypoint (uv sync + lint + tests + coverage)
+- [`doctor.sh`](./doctor.sh): primary local development regression entrypoint (uv sync + dependency compatibility + lint + mypy + tests + coverage + built-wheel smoke test)
 - [`conformance.sh`](./conformance.sh): local/manual external A2A conformance experiment entrypoint; caches the official TCK, can launch a dummy-backed local SUT, and preserves raw artifacts under `run/conformance/`
 - [`dependency_health.sh`](./dependency_health.sh): development dependency review entrypoint (`sync`/`pip check` + outdated + dev audit), while blocking CI/publish audits focus on runtime dependencies
 - [`check_coverage.py`](./check_coverage.py): enforces the overall coverage floor and per-file minimums for critical modules
@@ -21,4 +21,6 @@ Executable scripts live in this directory. This file is the entry index for the
 ## Notes
 
 - `doctor.sh` and `dependency_health.sh` intentionally remain separate entrypoints and share common prerequisites through [`health_common.sh`](./health_common.sh).
+- `doctor.sh` covers the default local validation baseline, while `dependency_health.sh` remains focused on standalone dependency review and audit flow.
+- [`.github/dependabot.yml`](../.github/dependabot.yml) prefers a single weekly grouped Dependabot PR for `uv`, while `dependency_health.sh` remains the explicit review/audit entrypoint.
 - External conformance experiments remain intentionally separate from the default regression path. See [`../docs/conformance.md`](../docs/conformance.md).

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/scripts/doctor.sh

@@ -9,8 +9,18 @@ run_shared_repo_health_prerequisites "doctor"
 echo "[doctor] run lint"
 uv run pre-commit run --all-files
 
+echo "[doctor] run type checks"
+uv run mypy src/opencode_a2a
+
 echo "[doctor] run tests"
 uv run pytest
 
 echo "[doctor] enforce coverage policy"
 uv run python ./scripts/check_coverage.py
+
+echo "[doctor] build release artifacts"
+rm -f dist/opencode_a2a-*.whl dist/opencode_a2a-*.tar.gz
+uv build --no-sources
+
+echo "[doctor] smoke test built wheel"
+bash ./scripts/smoke_test_built_cli.sh dist/opencode_a2a-*.whl

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/src/opencode_a2a/client/polling.py

@@ -6,14 +6,8 @@ from dataclasses import dataclass
 
 from a2a.types import TaskState
 
-_TERMINAL_TASK_STATES = frozenset(
-    {
-        TaskState.completed,
-        TaskState.canceled,
-        TaskState.failed,
-        TaskState.rejected,
-    }
-)
+from ..task_states import TERMINAL_TASK_STATES
+
 _AUTO_POLLING_TASK_STATES = frozenset(
     {
         TaskState.submitted,
@@ -37,7 +31,7 @@ class PollingFallbackPolicy:
         return state in _AUTO_POLLING_TASK_STATES
 
     def is_terminal_state(self, state: TaskState) -> bool:
-        return state in _TERMINAL_TASK_STATES
+        return state in TERMINAL_TASK_STATES
 
     def next_interval_seconds(self, current_interval_seconds: float) -> float:
         return min(

{opencode_a2a-0.7.1 → opencode_a2a-0.8.0}/src/opencode_a2a/execution/executor.py

@@ -73,7 +73,7 @@ from .stream_state import (
     _StreamOutputState,
     _TTLCache,
 )
-from .tool_orchestration import handle_a2a_call_tool, maybe_handle_tools, merge_streamed_tool_output
+from .tool_orchestration import maybe_handle_tools, merge_streamed_tool_output
 from .upstream_error_translator import (
     _await_stream_terminal_signal,
     _extract_upstream_error_detail,
@@ -186,12 +186,6 @@ class OpencodeAgentExecutor(AgentExecutor):
             a2a_client_manager=self._a2a_client_manager,
         )
 
-    async def _handle_a2a_call_tool(self, part: dict[str, Any]) -> dict[str, Any]:
-        return await handle_a2a_call_tool(
-            part,
-            a2a_client_manager=self._a2a_client_manager,
-        )
-
     @staticmethod
     def _merge_streamed_tool_output(current: str, incoming: str) -> str:
         return merge_streamed_tool_output(current, incoming)