opencode-a2a 1.1.2__tar.gz → 1.3.0__tar.gz

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/.github/workflows/publish.yml

@@ -146,11 +146,30 @@ jobs:
 
           ensure_release
 
+          python - <<'PY'
+          import hashlib
+          from pathlib import Path
+
+          dist_dir = Path("dist")
+          lines = []
+          for asset in sorted(
+              (
+                  path
+                  for path in dist_dir.iterdir()
+                  if path.is_file() and path.name.endswith((".whl", ".tar.gz"))
+              ),
+              key=lambda item: item.name,
+          ):
+              digest = hashlib.sha256(asset.read_bytes()).hexdigest()
+              lines.append(f"{digest}  {asset.name}")
+          (dist_dir / "SHA256SUMS").write_text("\n".join(lines) + "\n", encoding="utf-8")
+          PY
+
           mapfile -t existing_assets < <(
             retry 3 5 gh release view "$RELEASE_TAG" --json assets --jq '.assets[].name'
           )
 
-          for asset in dist/*.tar.gz dist/*.whl; do
+          for asset in dist/*.tar.gz dist/*.whl dist/SHA256SUMS; do
             asset_name="$(basename "$asset")"
             if printf '%s\n' "${existing_assets[@]}" | grep -Fxq "$asset_name"; then
               echo "Release asset already present: $asset_name"

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a
-Version: 1.1.2
+Version: 1.3.0
 Summary: OpenCode A2A runtime
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/Intelligent-Internet/opencode-a2a
 Project-URL: Repository, https://github.com/Intelligent-Internet/opencode-a2a
 Project-URL: Issues, https://github.com/Intelligent-Internet/opencode-a2a/issues
 Keywords: a2a,opencode,fastapi,json-rpc,sse
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -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==1.0.2
+Requires-Dist: a2a-sdk==1.1.2
 Requires-Dist: aiosqlite<1.0,>=0.20
 Requires-Dist: fastapi<1.0,>=0.139
 Requires-Dist: httpx<1.0,>=0.27
@@ -133,9 +133,9 @@ curl http://127.0.0.1:8000/.well-known/agent-card.json
 
 ## Capabilities
 
-- A2A HTTP+JSON endpoints such as `/v1/message:send` and `/v1/message:stream`
+- A2A HTTP+JSON endpoints such as `/message:send` and `/message:stream`
 - A2A JSON-RPC support on `POST /`
-- SDK-owned A2A task surfaces such as `GET /v1/tasks`, task push notification config routes, JSON-RPC `GetExtendedAgentCard`, and HTTP `GET /extendedAgentCard`
+- SDK-owned A2A task surfaces such as `GET /tasks`, task push notification config routes, JSON-RPC `GetExtendedAgentCard`, and HTTP `GET /extendedAgentCard`
 - Peering capabilities: can act as a client via `opencode-a2a call`
 - Autonomous tool execution: supports `a2a_call` tool for outbound agent-to-agent communication
 - SSE streaming with normalized `text`, `reasoning`, and `tool_call` blocks
@@ -201,6 +201,8 @@ This repository improves the service boundary around OpenCode, but it does not t
 - Provider auth and default model configuration remain on the OpenCode side; deployment-time precedence details and HOME/XDG state impact are documented in [docs/guide.md](docs/guide.md#troubleshooting-provider-auth-state).
 - Use `A2A_CLIENT_BEARER_TOKEN` for server-side outbound peer calls initiated by `a2a_call`.
 - Deployment supervision is intentionally BYO. Use `systemd`, Docker, Kubernetes, or another supervisor if you need long-running operation.
+- The supported persistence profile runs one `opencode-a2a` application process against its own local SQLite database. Do not run multiple Uvicorn workers or replicas against the same database file.
+- PostgreSQL and other SQLAlchemy dialects are not part of the supported deployment matrix.
 - For mutually untrusted tenants, run separate instance pairs with isolated users, containers, workspaces, credentials, and ports.
 
 Read before deployment:
@@ -216,6 +218,7 @@ Read before deployment:
 - [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/security-architecture.md](docs/security-architecture.md) Security surface, boundaries, and residual-risk register.
 - [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.
 

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/README.md

@@ -91,9 +91,9 @@ curl http://127.0.0.1:8000/.well-known/agent-card.json
 
 ## Capabilities
 
-- A2A HTTP+JSON endpoints such as `/v1/message:send` and `/v1/message:stream`
+- A2A HTTP+JSON endpoints such as `/message:send` and `/message:stream`
 - A2A JSON-RPC support on `POST /`
-- SDK-owned A2A task surfaces such as `GET /v1/tasks`, task push notification config routes, JSON-RPC `GetExtendedAgentCard`, and HTTP `GET /extendedAgentCard`
+- SDK-owned A2A task surfaces such as `GET /tasks`, task push notification config routes, JSON-RPC `GetExtendedAgentCard`, and HTTP `GET /extendedAgentCard`
 - Peering capabilities: can act as a client via `opencode-a2a call`
 - Autonomous tool execution: supports `a2a_call` tool for outbound agent-to-agent communication
 - SSE streaming with normalized `text`, `reasoning`, and `tool_call` blocks
@@ -159,6 +159,8 @@ This repository improves the service boundary around OpenCode, but it does not t
 - Provider auth and default model configuration remain on the OpenCode side; deployment-time precedence details and HOME/XDG state impact are documented in [docs/guide.md](docs/guide.md#troubleshooting-provider-auth-state).
 - Use `A2A_CLIENT_BEARER_TOKEN` for server-side outbound peer calls initiated by `a2a_call`.
 - Deployment supervision is intentionally BYO. Use `systemd`, Docker, Kubernetes, or another supervisor if you need long-running operation.
+- The supported persistence profile runs one `opencode-a2a` application process against its own local SQLite database. Do not run multiple Uvicorn workers or replicas against the same database file.
+- PostgreSQL and other SQLAlchemy dialects are not part of the supported deployment matrix.
 - For mutually untrusted tenants, run separate instance pairs with isolated users, containers, workspaces, credentials, and ports.
 
 Read before deployment:
@@ -174,6 +176,7 @@ Read before deployment:
 - [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/security-architecture.md](docs/security-architecture.md) Security surface, boundaries, and residual-risk register.
 - [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.
 

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/SECURITY.md

@@ -24,6 +24,9 @@ This project is currently best suited for trusted or internal environments. Impo
 - static credential auth only by default; stronger identity propagation is still a follow-up hardening area
 - operators remain responsible for host hardening, secret rotation, process access controls, and reverse-proxy exposure strategy
 
+For the security surface mapping and residual-risk register, see
+[docs/security-architecture.md](./docs/security-architecture.md).
+
 ## Reporting a Vulnerability
 
 Please avoid posting active secrets, bearer tokens, or reproduction payloads that contain private data in public issues.

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/docs/architecture.md

@@ -96,6 +96,7 @@ Use the docs by responsibility:
 - [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
+- [Security Architecture](security-architecture.md): security surface mapping and residual-risk register
 - [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-1.1.2 → opencode_a2a-1.3.0}/docs/compatibility.md

@@ -7,6 +7,9 @@ This document defines the compatibility promises `opencode-a2a` currently uphold
 - Python versions: 3.11, 3.12, 3.13
 - A2A SDK line: `1.x.y`
 - Supported A2A protocol line: `1.0`
+- OpenCode runtime line: `1.18.x` (verified with `1.18.19`)
+
+This is the single canonical place where the supported upstream OpenCode version line is declared. Keep it updated together with the live integration smoke check (`./scripts/live_opencode_smoke.sh`) and do not duplicate the version line elsewhere.
 
 The repository currently pins one concrete SDK release in `pyproject.toml` within that v1 line. Upgrade the SDK deliberately rather than relying on floating dependency resolution. The SDK-owned core JSON-RPC method set follows that pinned release and is locked by repository tests so SDK upgrades trigger an explicit compatibility review.
 
@@ -41,7 +44,7 @@ External TCK runs and local conformance experiments are investigation inputs. Th
 
 ## Compatibility-Sensitive Surface
 
-This repository still ships as an alpha project. Within that alpha line, these declared surfaces should not drift silently:
+This repository ships as a beta project. Its documented public contracts are intended to remain stable, while implementation details and explicitly provider-private surfaces may continue to evolve. These declared surfaces should not drift silently:
 
 - core A2A send / stream / task methods
 - v1-only request/response payloads and enum values
@@ -88,7 +91,7 @@ Task-store behavior that should remain stable for clients:
 - 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.
+The supported persistence profile is one application process using its own local SQLite database. Multiple Uvicorn workers or application replicas must not share that SQLite file. PostgreSQL and other SQLAlchemy dialects are not supported deployment targets; any apparent dialect compatibility is implementation latitude rather than a public promise.
 
 ## Extension Stability
 
@@ -97,7 +100,7 @@ The default SQLite-first profile is intended for local or controlled single-inst
 - 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.
+- `opencode.workspaces.*` and `opencode.worktrees.*` are boundary-sensitive and should remain explicitly provider-private, operator-scoped, and deployment-conditional where applicable. Discovery responses are normalized summaries that exclude upstream local paths (`directory`, `canonical`, worktree paths) and raw/internal fields.
 - 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 output filtering of structured tool payloads 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.

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/docs/extension-specifications.md

@@ -130,6 +130,7 @@ Extension URI: `urn:opencode-a2a:extension:workspace-control:v1`
 - Methods: stable project discovery plus experimental workspace/worktree discovery and deployment-conditional mutation methods
 - Dependencies: none declared by this version
 - Security boundary: this extension is provider-private, operator-scoped, and partly deployment-conditional
+- Response hygiene: discovery responses are normalized summaries; upstream local paths (`directory`, `canonical`, worktree paths), raw entries, and credential-like fields are excluded
 - Versioning: breaking changes require a new versioned URI
 
 ## OpenCode Interrupt Recovery v1

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/docs/guide.md

@@ -5,9 +5,11 @@ This guide covers configuration, authentication, API behavior, streaming re-subs
 ## Transport Contracts
 
 - The service supports both transports:
-  - HTTP+JSON (REST endpoints such as `/v1/message:send`)
+  - HTTP+JSON (REST endpoints such as `/message:send`)
   - JSON-RPC (`POST /`)
 - Agent Card exposes both HTTP+JSON and JSON-RPC through `supportedInterfaces`.
+- HTTP+JSON REST endpoints are served at the root path (e.g. `/message:send`, `/tasks`). A2A 1.0 negotiates protocol version via the `A2A-Version` header, not a URL prefix, so the URL path carries no version segment.
+- Breaking change for earlier releases: versions through v1.1.2 served the HTTP+JSON surface under a `/v1` prefix. Deployments upgrading from those releases must repoint clients, reverse proxies, and any `/v1`-prefixed routes to the root paths.
 - The public Agent Card is intentionally slimmed to the minimum discovery surface; per-extension disclosure policy is defined in [`extension-specifications.md`](./extension-specifications.md).
 - Detailed provider-private contracts are served through the authenticated extended card endpoint `/extendedAgentCard`.
 - Agent Card responses emit weak `ETag` and `Cache-Control`; clients should revalidate cached cards instead of repeatedly fetching full payloads.
@@ -30,12 +32,15 @@ Key variables to understand protocol behavior:
 - `A2A_ALLOW_DIRECTORY_OVERRIDE`: controls whether clients may pass `metadata.opencode.directory`.
 - `A2A_ENABLE_SESSION_SHELL`: gates high-risk JSON-RPC method `opencode.sessions.shell`.
 - `A2A_ENABLE_WORKSPACE_MUTATIONS`: gates operator-only workspace/worktree mutation methods such as `opencode.workspaces.create` and `opencode.worktrees.reset`.
+- `A2A_EXPOSE_WORKSPACE_ROOT_IN_CARD`: default `false`; controls whether the authenticated extended Agent Card includes the local `OPENCODE_WORKSPACE_ROOT` in the structured profile `runtime_context`. Keep disabled unless trusted callers explicitly need the host path.
 - `A2A_SANDBOX_MODE` / `A2A_SANDBOX_FILESYSTEM_SCOPE` / `A2A_SANDBOX_WRITABLE_ROOTS`: declarative execution-boundary metadata for sandbox mode, filesystem scope, and optional writable roots.
 - `A2A_NETWORK_ACCESS` / `A2A_NETWORK_ALLOWED_DOMAINS`: declarative execution-boundary metadata for network policy and optional allowlist disclosure.
 - `A2A_APPROVAL_POLICY` / `A2A_APPROVAL_ESCALATION_BEHAVIOR`: declarative execution-boundary metadata for approval workflow.
 - `A2A_WRITE_ACCESS_SCOPE` / `A2A_WRITE_ACCESS_OUTSIDE_WORKSPACE`: declarative execution-boundary metadata for write scope and whether writes may extend outside the primary workspace boundary.
 - `A2A_HOST` / `A2A_PORT`: runtime bind address. Defaults: `127.0.0.1:8000`.
 - `A2A_PUBLIC_URL`: public base URL advertised by the Agent Card. Default: `http://127.0.0.1:8000`.
+- `A2A_ALLOWED_ORIGINS`: comma-separated extra browser-origin allowlist for inbound requests. Requests carrying an `Origin` header must match the origin of `A2A_PUBLIC_URL` or an entry here; mismatches are rejected with `403` (CSRF guard). Requests without an `Origin` header (CLI/SDK clients) are unaffected.
+- `A2A_ALLOWED_HOSTS`: comma-separated `Host` header allowlist (exact names or `*.example.com` wildcards). When configured, every inbound request must present a matching `Host` header. Binding to a non-loopback address without this allowlist logs a startup warning (DNS rebinding risk).
 - `A2A_LOG_LEVEL`: runtime log level. Default: `WARNING`.
 - `A2A_LOG_PAYLOADS` / `A2A_LOG_BODY_LIMIT`: payload logging behavior and truncation. When `A2A_LOG_LEVEL=DEBUG`, upstream OpenCode stream events are also logged with preview truncation controlled by `A2A_LOG_BODY_LIMIT`.
 - The runtime accepts W3C `traceparent` / `tracestate` headers on inbound requests. When `traceparent` is missing or invalid, the runtime generates a fresh valid value and exposes it on the HTTP response header.
@@ -43,19 +48,24 @@ Key variables to understand protocol behavior:
 - Logs derive a stable `trace_id` from the active `traceparent` so request-scoped log lines can be correlated without introducing high-cardinality metric labels.
 - `A2A_HTTP_GZIP_MINIMUM_SIZE`: minimum eligible response-body size in bytes for global non-streaming HTTP gzip compression. Default: `8192`.
 - `A2A_MAX_REQUEST_BODY_BYTES`: runtime request-body limit. Oversized requests return HTTP `413`.
+- `A2A_RATE_LIMIT_ENABLED` / `A2A_RATE_LIMIT_WINDOW_SECONDS` / `A2A_RATE_LIMIT_MAX_REQUESTS`: per-credential sliding-window rate limiting (per-peer-IP for the unauthenticated Agent Card surface). Defaults: `true` / `60` seconds / `120` requests. Exceeding the window returns HTTP `429` with a `Retry-After` header; `A2A_RATE_LIMIT_ENABLED=false` disables the limiter.
+- `A2A_STREAM_MAX_BYTES` / `A2A_STREAM_MAX_DURATION_SECONDS` / `A2A_STREAM_IDLE_TIMEOUT_SECONDS`: streaming (SSE) response budgets for total bytes, total duration, and idle gap. Defaults: `67108864` bytes / `3600` seconds / `120` seconds; `0` disables the respective budget.
 - `A2A_PENDING_SESSION_CLAIM_TTL_SECONDS`: lease duration for pending preferred session claims before they expire and stop blocking other identities.
 - `A2A_INTERRUPT_REQUEST_TTL_SECONDS`: active retention window for the interrupt request binding registry used by `a2a.interrupt.*` callback methods. Default: `10800` seconds (`180` minutes).
 - `A2A_INTERRUPT_REQUEST_TOMBSTONE_TTL_SECONDS`: retention window for expired interrupt tombstones after active TTL has elapsed. During this window, repeated replies keep returning `INTERRUPT_REQUEST_EXPIRED` instead of falling through to `INTERRUPT_REQUEST_NOT_FOUND`. Default: `600` seconds (`10` minutes).
 - `A2A_CANCEL_ABORT_TIMEOUT_SECONDS`: best-effort timeout for upstream `session.abort` in cancel flow.
-- `OPENCODE_TIMEOUT` / `OPENCODE_TIMEOUT_STREAM`: upstream request timeout and optional stream timeout override.
-- `OPENCODE_MAX_CONCURRENT_REQUESTS`: optional fast-fail concurrency limit for unary/control upstream calls. `0` disables the limit.
-- `OPENCODE_MAX_CONCURRENT_STREAMS`: optional fast-fail concurrency limit for long-lived upstream `/event` streams. `0` disables the limit.
+- `OPENCODE_TIMEOUT` / `OPENCODE_TIMEOUT_STREAM`: upstream request timeout and stream timeout. Defaults: `120` and `900` seconds.
+- `OPENCODE_MAX_CONCURRENT_REQUESTS`: fast-fail concurrency limit for unary/control upstream calls. Default: `32`; `0` disables the limit explicitly.
+- `OPENCODE_MAX_CONCURRENT_STREAMS`: fast-fail concurrency limit for long-lived upstream `/event` streams. Default: `8`; `0` disables the limit explicitly.
+- `OPENCODE_AUTH_USERNAME` / `OPENCODE_AUTH_PASSWORD`: optional HTTP Basic credentials sent on every upstream OpenCode call. Set both when the upstream `opencode serve` is hardened with `OPENCODE_SERVER_PASSWORD`; the username defaults to `opencode` and must match `OPENCODE_SERVER_USERNAME` when that is overridden upstream. When unset, no `Authorization` header is sent.
 - `A2A_CLIENT_TIMEOUT_SECONDS`: outbound client timeout. Default: `30` seconds.
 - `A2A_CLIENT_CARD_FETCH_TIMEOUT_SECONDS`: outbound Agent Card fetch timeout. Default: `5` seconds.
 - `A2A_CLIENT_USE_CLIENT_PREFERENCE`: whether the outbound client prefers its own transport choices.
 - `A2A_CLIENT_BEARER_TOKEN`: optional bearer token attached to outbound peer calls made by the embedded A2A client and `a2a_call` tool path.
 - `A2A_CLIENT_BASIC_AUTH`: optional Basic auth credential attached to outbound peer calls made by the embedded A2A client and `a2a_call` tool path.
 - `A2A_CLIENT_SUPPORTED_TRANSPORTS`: ordered outbound transport preference list.
+- `A2A_CLIENT_ALLOWED_HOSTS`: comma-separated allowlist of outbound target hosts for the embedded A2A client and `a2a_call` tool path (exact names or `*.example.com` wildcards). When configured, outbound calls are restricted to matching hosts, and outbound credentials (`A2A_CLIENT_BEARER_TOKEN` / `A2A_CLIENT_BASIC_AUTH`) are only sent to allowlisted hosts.
+- `A2A_CLIENT_ALLOW_PRIVATE_HOSTS`: default `false`. When `false`, outbound `a2a_call(...)` targets that resolve to private, loopback, link-local, reserved, or multicast addresses are rejected (SSRF / DNS-rebinding guard). Set to `true` only when the deployment intentionally targets A2A peers on the local network.
 - `A2A_TASK_STORE_BACKEND`: unified lightweight persistence backend for SDK task rows plus adapter-managed session / interrupt state. Supported values: `database`, `memory`. Default: `database`.
 - `A2A_TASK_STORE_DATABASE_URL`: database URL used by the unified durable backend when `A2A_TASK_STORE_BACKEND=database`. Default: `sqlite+aiosqlite:///./opencode-a2a.db`.
 - On startup, the runtime only auto-migrates adapter-owned state tables; existing SDK-owned task tables must be upgraded explicitly with upstream `a2a-db`.
@@ -81,6 +91,20 @@ Key variables to understand protocol behavior:
   - `A2A_CLIENT_BASIC_AUTH`
   - `A2A_CLIENT_SUPPORTED_TRANSPORTS`
 
+## Inbound Origin and Host Boundary
+
+Browsers store and automatically attach Basic credentials, and they send an `Origin` header with every request. Without an origin boundary, a malicious web page could cross-site trigger `SendMessage`, `CancelTask`, or task subscription against a Basic-protected service. The runtime therefore enforces:
+
+- every request carrying an `Origin` header must match the origin of `A2A_PUBLIC_URL` (scheme, host, and non-default port) or an entry in `A2A_ALLOWED_ORIGINS`; mismatches return `403` before authentication. `Origin: null` (sandboxed iframes) is rejected unless explicitly allowlisted;
+- requests without an `Origin` header — normal CLI/SDK peers — are not subject to origin checks;
+- when `A2A_ALLOWED_HOSTS` is configured, every request must present a matching `Host` header (exact names, optional `host:port`, or `*.example.com` wildcards); mismatches return `403`. This also blocks DNS rebinding, where an attacker-controlled hostname resolves to the service address and the browser sends that hostname as `Host`;
+- binding to a non-loopback address (`0.0.0.0`, `::`, or a LAN/interface address) without `A2A_ALLOWED_HOSTS` logs a startup warning: the service is then exposed to DNS rebinding and should only run behind a trusted network boundary or a reverse proxy that validates `Host`.
+
+For browser-based clients, prefer the same origin as `A2A_PUBLIC_URL`, or explicitly allow the dashboard origin via `A2A_ALLOWED_ORIGINS` and treat `A2A_ALLOWED_HOSTS` as part of the deployment contract. Basic authentication should not be relied on as the sole browser-facing boundary: combine it with the origin/host checks above, short-lived credentials, and TLS at the public URL.
+
+The security surface mapping and residual-risk register live in
+[security-architecture.md](./security-architecture.md).
+
 ## Client Initialization Facade (Preview)
 
 `opencode-a2a` now includes a minimal client bootstrap module in `src/opencode_a2a/client/` to support downstream consumer usage while keeping server and client concerns separate.
@@ -100,6 +124,14 @@ Current client facade API:
 
 Server-side outbound peer calls read outbound credentials from environment variables. Configure `A2A_CLIENT_BEARER_TOKEN` or `A2A_CLIENT_BASIC_AUTH` when the remote agent protects its runtime surface. CLI outbound calls follow the same environment-only model.
 
+The embedded `a2a_call(...)` tool lets the upstream model choose the target URL, so the adapter applies a fail-closed network policy before opening any connection:
+
+- only `http`/`https` schemes are accepted, and URLs carrying userinfo credentials are rejected;
+- when `A2A_CLIENT_ALLOWED_HOSTS` is set, the target host must match the allowlist (exact or `*.example.com` wildcard);
+- unless `A2A_CLIENT_ALLOW_PRIVATE_HOSTS=true`, the resolved addresses must be public; private/loopback/link-local/reserved addresses are rejected even when the hostname matches the allowlist (DNS rebinding defense);
+- outbound credentials are only attached to allowlisted hosts. If credentials are configured without an allowlist, they are never sent and a warning is logged;
+- the `opencode-a2a call` CLI remains a manual operator action and is not subject to the allowlist, but still rejects non-http(s) schemes through the shared client URL handling.
+
 CLI outbound example:
 
 ```bash
@@ -174,11 +206,31 @@ With the default `database` backend, the unified lightweight persistence layer p
 - pending preferred-session claims
 - interrupt request bindings and tombstones
 
-This project is SQLite-first for local single-instance deployments. The runtime configures local durability-oriented SQLite connection settings (`WAL`, `busy_timeout`, `synchronous=NORMAL`) and creates missing parent directories for file-backed database paths.
+The supported persistence profile is one `opencode-a2a` application process using its own local SQLite database. Run Uvicorn with one worker and do not share the SQLite file between processes, containers, or replicas. Horizontal application scaling and PostgreSQL deployments are outside the supported deployment matrix. SQLAlchemy remains an internal implementation detail rather than a promise of dialect portability.
+
+The runtime configures local durability-oriented SQLite connection settings (`WAL`, `busy_timeout`, `synchronous=NORMAL`) and creates missing parent directories for file-backed database paths.
+
+### SQLite Persistence Hardening
+
+File-backed SQLite databases are hardened at startup and on every new connection on POSIX systems:
+
+- the database file must be a regular file; symlinks are rejected and fail startup;
+- the file must be owned by the user running `opencode-a2a`; a database owned by another user fails startup;
+- the database file is forced to mode `0600`, and existing SQLite sidecar files (`-wal`/`-shm`/`-journal`) are converged to the same mode;
+- the parent directory is created with mode `0700` when it does not exist; keep the database directory private (no group/world access);
+- if the database is replaced by a symlink, a special file, or a foreign-owned file while the service is running, the next connection fails closed.
+
+`A2A_TASK_STORE_DATABASE_URL` values that do not map to a plain file path are exempt: `:memory:` and `file:` URI-style database components (including in-memory shared-cache databases) are not hardened. Prefer a plain absolute file path for deployments that need the startup guarantees. Non-POSIX platforms rely on the user account ACLs of the hosting directory; the same private-directory requirement applies there.
+
+Deployment requirements:
+
+- run `opencode-a2a` as a dedicated user and keep the database directory outside world-readable workspace trees;
+- do not place the SQLite file on network-mounted or sync-managed directories;
+- when migrating an existing database, fix ownership and mode before startup: `chown <service-user> <db>` and `chmod 600 <db>`, and ensure the parent directory is not group/world accessible.
 
 The runtime automatically applies lightweight schema migrations for its custom state tables and records the applied version in `a2a_schema_version`. Schema-version writes are idempotent across concurrent first-start races, pending preferred-session claims now persist absolute `expires_at` timestamps, legacy rows without `expires_at` are pruned during migration instead of being reconstructed from historical TTL assumptions, and the built-in path currently targets the local SQLite deployment profile without requiring Alembic.
 
-Database-backed task persistence also keeps the existing first-terminal-state-wins contract while tightening the SQLite path with an atomic terminal-write guard instead of relying only on process-local read-before-write checks. Any wider SQLAlchemy dialect compatibility should be treated as incidental implementation latitude rather than a documented deployment target.
+Database-backed task persistence also keeps the existing first-terminal-state-wins contract while tightening the SQLite path with an atomic terminal-write guard instead of relying only on process-local read-before-write checks.
 
 At startup, the runtime logs a concise persistence summary covering the active backend, the redacted database URL when applicable, the shared persistence scope, and whether the SQLite local durability profile is active.
 
@@ -223,7 +275,7 @@ If one deployment works while another fails against the same upstream provider,
 ## Streaming Contract
 
 - Streaming is always enabled in this server profile; `message:stream` is part of the stable runtime baseline.
-- Streaming (`/v1/message:stream`) emits an initial working `Task`, then incremental `TaskArtifactUpdateEvent` / `TaskStatusUpdateEvent` updates, and finally a terminal `TaskStatusUpdateEvent(final=true)`.
+- Streaming (`/message:stream`) emits an initial working `Task`, then incremental `TaskArtifactUpdateEvent` / `TaskStatusUpdateEvent` updates, and finally a terminal `TaskStatusUpdateEvent(final=true)`.
 - Stream artifacts carry `artifact.metadata.shared.stream.block_type` with values `text` / `reasoning` / `tool_call`.
 - Stream artifacts are scoped to logical output lanes rather than one shared catch-all artifact:
   - text chunks use a stable text artifact ID
@@ -255,6 +307,8 @@ If one deployment works while another fails against the same upstream provider,
 
 - Requests require either `Authorization: Bearer <token>` or a configured `Authorization: Basic <base64(username:password)>`; otherwise `401` is returned. Agent Card endpoints are public.
 - Requests above `A2A_MAX_REQUEST_BODY_BYTES` are rejected with HTTP `413` before transport handling.
+- Inbound requests are rate limited with a sliding window keyed by `credential_id` when configured, otherwise by the authenticated principal; the public Agent Card surface is keyed by the direct peer IP (never `X-Forwarded-For`). Exceeding `A2A_RATE_LIMIT_MAX_REQUESTS` within `A2A_RATE_LIMIT_WINDOW_SECONDS` returns HTTP `429` with a `Retry-After` header. The limiter is process-local; multi-process deployments should place a shared gateway in front or rely on per-instance limits.
+- Streaming responses (JSON-RPC `SendStreamingMessage` / `SubscribeToTask` and REST `/message:stream` / `/tasks/{id}:subscribe`) are bounded by `A2A_STREAM_MAX_BYTES`, `A2A_STREAM_MAX_DURATION_SECONDS`, and `A2A_STREAM_IDLE_TIMEOUT_SECONDS`; when a budget is exceeded the server ends the stream with an SSE `event: error` frame. If the very first event already exceeds the budget, REST requests are rejected with HTTP `429` `RESOURCE_EXHAUSTED` before the SSE stream starts.
 - For validation failures, missing context (`task_id` / `context_id`), or internal errors, the service attempts to return standard A2A failure events via `event_queue`.
 - Failure events include concrete error details with `failed` state.
 
@@ -285,7 +339,7 @@ Current behavior:
 - Shared metadata extension URIs such as session binding and streaming are listed under `extensions.extension_uris`.
 - `all_jsonrpc_methods` is the runtime truth for the current deployment.
 - The current SDK-owned core JSON-RPC surface includes `GetExtendedAgentCard` and `tasks/pushNotificationConfig/*`.
-- The current SDK-owned REST surface also includes `GET /v1/tasks` and the task push notification config routes.
+- The current SDK-owned REST surface also includes `GET /tasks` and the task push notification config routes.
 - The SDK-owned core JSON-RPC method set follows the pinned `a2a-sdk` release and is locked by repository tests; review that surface deliberately when upgrading the SDK.
 - Push notification config routes/methods are currently exposed only because they are part of the SDK-owned core surface. This runtime does not configure a push config store or push sender, so push notification operations remain unsupported. REST routes currently return HTTP `501`, while JSON-RPC methods surface SDK-owned unsupported error envelopes.
 
@@ -483,7 +537,7 @@ Consumer guidance:
 Minimal example:
 
 ```bash
-curl -sS http://127.0.0.1:8000/v1/message:send \
+curl -sS http://127.0.0.1:8000/message:send \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer <your-token>' \
   -d '{
@@ -535,7 +589,7 @@ Consumer guidance:
 Minimal example:
 
 ```bash
-curl -sS http://127.0.0.1:8000/v1/message:send \
+curl -sS http://127.0.0.1:8000/message:send \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer <your-token>' \
   -d '{
@@ -1034,6 +1088,7 @@ Behavior notes:
 - `metadata.opencode.workspace.id` is declared consistently across the adapter, but current workspace-control methods do not use it to change the target project.
 - `opencode.workspaces.*` and `opencode.worktrees.*` currently wrap upstream `/experimental/workspace` and `/experimental/worktree` endpoints; treat them as experimental-upstream surfaces even when declared by the adapter.
 - Mutating methods should be treated as operator-only control-plane actions and are disabled by default.
+- Discovery responses are normalized provider-private summaries: upstream entries are filtered to stable fields only (`id`/`name`/`vcs` for projects, `id`/`type`/`name`/`branch` for workspaces, `name`/`branch` for worktrees) and never include upstream local paths (`directory`, `canonical`, worktree paths), raw entries, or credential-like fields.
 
 ### Project Discovery (`opencode.projects.list`, `opencode.projects.current`)
 
@@ -1051,8 +1106,8 @@ curl -sS http://127.0.0.1:8000/ \
 
 Response:
 
-- `opencode.projects.list` => `{"items": [...]}`
-- `opencode.projects.current` => `{"item": {...}}`
+- `opencode.projects.list` => `{"items": [{"id": "<id>", "name": "<name>", "vcs": "<vcs>"}]}` (normalized summaries; no local paths)
+- `opencode.projects.current` => `{"item": {"id": "<id>", "name": "<name>", "vcs": "<vcs>"}}` (normalized summary; no local paths)
 
 ### Workspace Discovery
 
@@ -1070,7 +1125,7 @@ curl -sS http://127.0.0.1:8000/ \
 
 Response:
 
-- `opencode.workspaces.list` => `{"items": [...]}`
+- `opencode.workspaces.list` => `{"items": [{"id": "<id>", "type": "<type>", "name": "<name>", "branch": "<branch>"}]}` (normalized summaries; no local paths)
 
 ### Workspace Mutation
 
@@ -1222,7 +1277,7 @@ curl -sS http://127.0.0.1:8000/ \
 ## Authentication Example (curl)
 
 ```bash
-curl -sS http://127.0.0.1:8000/v1/message:send \
+curl -sS http://127.0.0.1:8000/message:send \
   -H 'content-type: application/json' \
   -H 'Authorization: Bearer <your-token>' \
   -d '{
@@ -1256,7 +1311,7 @@ curl -sS http://127.0.0.1:8000/ \
 
 ## Streaming Re-Subscription (`SubscribeToTask`)
 
-If an SSE connection drops, use `GET /v1/tasks/{task_id}:subscribe` to re-subscribe while the task is still non-terminal.
+If an SSE connection drops, use `GET /tasks/{task_id}:subscribe` to re-subscribe while the task is still non-terminal.
 
 ## Cancellation Semantics (`CancelTask`)
 
@@ -1264,7 +1319,7 @@ If an SSE connection drops, use `GET /v1/tasks/{task_id}:subscribe` to re-subscr
 - For running tasks, the service attempts upstream OpenCode `POST /session/{sessionID}/abort` to stop generation.
 - Upstream interruption is best-effort: if upstream returns 404, network errors, or other HTTP errors, A2A cancellation still completes with `TaskState.TASK_STATE_CANCELED`.
 - Idempotency contract: repeated `CancelTask` on an already `canceled` task returns the current terminal task state without error.
-- Terminal subscribe contract: calling `SubscribeToTask` or `GET /v1/tasks/{task_id}:subscribe` on a terminal task replays one terminal `Task` snapshot and then closes the stream.
+- Terminal subscribe contract: calling `SubscribeToTask` or `GET /tasks/{task_id}:subscribe` on a terminal task replays one terminal `Task` snapshot and then closes the stream.
 - Terminal persistence contract: once a terminal task snapshot is persisted, this service treats it as immutable. Producers must emit final text and artifact updates before the terminal event, and any final usage or stream metadata must be attached to that terminal event itself. Late terminal-state mutations are rejected by the task-store write policy.
 - These two semantics are also declared as machine-readable `service_behaviors` in the compatibility profile and wire contract extensions.
 - At `A2A_LOG_LEVEL=DEBUG`, the service emits lightweight metric log records (`logger=opencode_a2a.execution.executor`):

{opencode_a2a-1.1.2 → opencode_a2a-1.3.0}/docs/maintainer-architecture.md

@@ -21,12 +21,11 @@ flowchart TD
 
     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"]
+        Contracts["contracts/extensions/"]
         Profile["profile/runtime.py"]
     end
 
@@ -61,7 +60,7 @@ flowchart TD
 
 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.
+3. `contracts/extensions/` 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
@@ -89,7 +88,7 @@ flowchart TD
 
 ### Extension and Contract Layer
 
-- `contracts/extensions.py`: SSOT for extension metadata, compatibility profile, and wire-contract payloads
+- `contracts/extensions/`: 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
@@ -128,5 +127,8 @@ For maintainers new to the codebase, this order usually gives the fastest payoff
 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`
+5. `src/opencode_a2a/contracts/extensions/`
+
+For security-focused contributors, `docs/security-architecture.md` additionally
+consolidates the security surface mapping and residual-risk register.
 6. `docs/guide.md`