opencode-a2a-server 0.2.3__tar.gz → 0.2.4__tar.gz

{opencode_a2a_server-0.2.3 → opencode_a2a_server-0.2.4}/CONTRIBUTING.md

@@ -2,9 +2,9 @@
 
 Thanks for contributing to `opencode-a2a-server`.
 
-This repository is maintained as a streaming-first A2A wrapper around OpenCode.
-Changes should keep runtime behavior, Agent Card declarations, OpenAPI examples,
-and machine-readable extension contracts aligned.
+This repository maintains an A2A adapter service around OpenCode. Changes
+should keep runtime behavior, Agent Card declarations, OpenAPI examples, and
+machine-readable extension contracts aligned.
 
 ## Before You Start
 
@@ -26,12 +26,19 @@ Install dependencies:
 uv sync --all-extras
 ```
 
-Run the local development server:
+Start OpenCode in one terminal:
+
+```bash
+opencode serve --hostname 127.0.0.1 --port 4096
+```
+
+Then start the A2A server in another terminal:
 
 ```bash
 A2A_BEARER_TOKEN=dev-token \
-OPENCODE_DIRECTORY=/abs/path/to/workspace \
-uv run opencode-a2a-server
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
+uv run opencode-a2a-server serve
 ```
 
 ## Validation
@@ -43,11 +50,20 @@ uv run pre-commit run --all-files
 uv run pytest
 ```
 
-If you change shell or deployment scripts, also run:
+If you change shell scripts, also run `bash -n` on each modified script, for
+example:
+
+```bash
+bash -n scripts/doctor.sh
+bash -n scripts/lint.sh
+```
+
+If you change extension methods, extension metadata, or Agent Card/OpenAPI
+contract surfaces, also run:
 
 ```bash
-bash -n scripts/deploy.sh
-bash -n scripts/deploy/setup_instance.sh
+uv run pytest tests/test_extension_contract_consistency.py
+uv run mypy src/opencode_a2a_server
 ```
 
 ## Change Expectations
@@ -77,3 +93,11 @@ Update docs together with code whenever you change:
 
 Keep compatibility guidance centralized in [docs/guide.md](docs/guide.md) unless a
 new standalone document is clearly necessary.
+
+When changing extension contracts, update
+[`src/opencode_a2a_server/extension_contracts.py`](src/opencode_a2a_server/extension_contracts.py)
+first and keep these generated/documented surfaces aligned:
+
+- Agent Card extension params
+- OpenAPI `POST /` extension metadata and examples
+- JSON-RPC notification behavior (`204 No Content`)

opencode_a2a_server-0.2.4/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: opencode-a2a-server
+Version: 0.2.4
+Summary: A2A wrapper service for opencode
+Author: liujuanjuan1984@Intelligent-Internet
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Intelligent-Internet/opencode-a2a-server
+Project-URL: Repository, https://github.com/Intelligent-Internet/opencode-a2a-server
+Project-URL: Issues, https://github.com/Intelligent-Internet/opencode-a2a-server/issues
+Keywords: a2a,opencode,fastapi,json-rpc,sse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: FastAPI
+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: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: sse-starlette>=2.1
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: dev
+Requires-Dist: mypy>=1.19.1; extra == "dev"
+Requires-Dist: pip-audit>=2.9; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# opencode-a2a-server
+
+> Expose OpenCode through A2A.
+
+`opencode-a2a-server` adds an A2A service layer to `opencode serve`, with
+auth, streaming, session continuity, interrupt handling, and a clear
+deployment boundary.
+
+## What This Is
+
+- An A2A adapter service for `opencode serve`.
+- Use it when you need a stable A2A endpoint for apps, gateways, or A2A
+  clients.
+
+```mermaid
+flowchart TD
+    Client["a2a-client-hub / any A2A client"]
+
+    subgraph ServerSide["Server-side"]
+        Adapter["opencode-a2a-server\nA2A adapter service"]
+        Runtime["opencode serve\nOpenCode runtime"]
+
+        Adapter <--> Runtime
+    end
+
+    Client <--> Adapter
+```
+
+## Quick Start
+
+Install the released CLI with `uv tool`:
+
+```bash
+uv tool install opencode-a2a-server
+```
+
+Upgrade later with:
+
+```bash
+uv tool upgrade opencode-a2a-server
+```
+
+Make sure provider credentials and a default model are configured on the
+OpenCode side, then start OpenCode:
+
+```bash
+opencode auth login
+opencode models
+opencode serve --hostname 127.0.0.1 --port 4096
+```
+
+Then start `opencode-a2a-server` against that upstream:
+
+```bash
+A2A_BEARER_TOKEN=dev-token \
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
+A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
+opencode-a2a-server serve
+```
+
+Verify that the service is up:
+
+```bash
+curl http://127.0.0.1:8000/.well-known/agent-card.json
+```
+
+Default local address: `http://127.0.0.1:8000`
+
+## What You Get
+
+- A2A HTTP+JSON endpoints such as `/v1/message:send` and
+  `/v1/message:stream`
+- A2A JSON-RPC support on `POST /`
+- SSE streaming with normalized `text`, `reasoning`, and `tool_call` blocks
+- Session continuity through `metadata.shared.session.id`
+- Request-scoped model selection through `metadata.shared.model`
+- OpenCode-oriented JSON-RPC extensions for session and model/provider queries
+
+Detailed protocol contracts, examples, and extension docs live in
+[`docs/guide.md`](docs/guide.md).
+
+## When To Use It
+
+Use this project when:
+
+- you want to keep OpenCode as the runtime
+- you need A2A transports and Agent Card discovery
+- you want a thin service boundary instead of building your own adapter
+
+Look elsewhere if:
+
+- you need hard multi-tenant isolation inside one shared runtime
+- you want this project to manage your process supervisor or host bootstrap
+- you want a general client integration layer rather than a server wrapper
+
+For client-side integration, prefer
+[a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub).
+
+## Deployment Boundary
+
+This repository improves the service boundary around OpenCode, but it does not
+turn OpenCode into a hardened multi-tenant platform.
+
+- `A2A_BEARER_TOKEN` protects the A2A surface.
+- Provider auth and default model configuration remain on the OpenCode side.
+- Deployment supervision is intentionally BYO. Use `systemd`, Docker,
+  Kubernetes, or another supervisor if you need long-running operation.
+- For mutually untrusted tenants, run separate instance pairs with isolated
+  users, containers, workspaces, credentials, and ports.
+
+Read before deployment:
+
+- [SECURITY.md](SECURITY.md)
+- [docs/guide.md](docs/guide.md)
+
+## Further Reading
+
+- [docs/guide.md](docs/guide.md)
+  Usage guide, transport details, streaming behavior, extensions, and examples.
+- [SECURITY.md](SECURITY.md)
+  Threat model, deployment caveats, and vulnerability disclosure guidance.
+
+## Development
+
+For contributor workflow, local validation, and helper scripts, see
+[CONTRIBUTING.md](CONTRIBUTING.md) and [scripts/README.md](scripts/README.md).
+
+## License
+
+Apache-2.0. See [`LICENSE`](LICENSE).

opencode_a2a_server-0.2.4/README.md

@@ -0,0 +1,133 @@
+# opencode-a2a-server
+
+> Expose OpenCode through A2A.
+
+`opencode-a2a-server` adds an A2A service layer to `opencode serve`, with
+auth, streaming, session continuity, interrupt handling, and a clear
+deployment boundary.
+
+## What This Is
+
+- An A2A adapter service for `opencode serve`.
+- Use it when you need a stable A2A endpoint for apps, gateways, or A2A
+  clients.
+
+```mermaid
+flowchart TD
+    Client["a2a-client-hub / any A2A client"]
+
+    subgraph ServerSide["Server-side"]
+        Adapter["opencode-a2a-server\nA2A adapter service"]
+        Runtime["opencode serve\nOpenCode runtime"]
+
+        Adapter <--> Runtime
+    end
+
+    Client <--> Adapter
+```
+
+## Quick Start
+
+Install the released CLI with `uv tool`:
+
+```bash
+uv tool install opencode-a2a-server
+```
+
+Upgrade later with:
+
+```bash
+uv tool upgrade opencode-a2a-server
+```
+
+Make sure provider credentials and a default model are configured on the
+OpenCode side, then start OpenCode:
+
+```bash
+opencode auth login
+opencode models
+opencode serve --hostname 127.0.0.1 --port 4096
+```
+
+Then start `opencode-a2a-server` against that upstream:
+
+```bash
+A2A_BEARER_TOKEN=dev-token \
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
+A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
+opencode-a2a-server serve
+```
+
+Verify that the service is up:
+
+```bash
+curl http://127.0.0.1:8000/.well-known/agent-card.json
+```
+
+Default local address: `http://127.0.0.1:8000`
+
+## What You Get
+
+- A2A HTTP+JSON endpoints such as `/v1/message:send` and
+  `/v1/message:stream`
+- A2A JSON-RPC support on `POST /`
+- SSE streaming with normalized `text`, `reasoning`, and `tool_call` blocks
+- Session continuity through `metadata.shared.session.id`
+- Request-scoped model selection through `metadata.shared.model`
+- OpenCode-oriented JSON-RPC extensions for session and model/provider queries
+
+Detailed protocol contracts, examples, and extension docs live in
+[`docs/guide.md`](docs/guide.md).
+
+## When To Use It
+
+Use this project when:
+
+- you want to keep OpenCode as the runtime
+- you need A2A transports and Agent Card discovery
+- you want a thin service boundary instead of building your own adapter
+
+Look elsewhere if:
+
+- you need hard multi-tenant isolation inside one shared runtime
+- you want this project to manage your process supervisor or host bootstrap
+- you want a general client integration layer rather than a server wrapper
+
+For client-side integration, prefer
+[a2a-client-hub](https://github.com/liujuanjuan1984/a2a-client-hub).
+
+## Deployment Boundary
+
+This repository improves the service boundary around OpenCode, but it does not
+turn OpenCode into a hardened multi-tenant platform.
+
+- `A2A_BEARER_TOKEN` protects the A2A surface.
+- Provider auth and default model configuration remain on the OpenCode side.
+- Deployment supervision is intentionally BYO. Use `systemd`, Docker,
+  Kubernetes, or another supervisor if you need long-running operation.
+- For mutually untrusted tenants, run separate instance pairs with isolated
+  users, containers, workspaces, credentials, and ports.
+
+Read before deployment:
+
+- [SECURITY.md](SECURITY.md)
+- [docs/guide.md](docs/guide.md)
+
+## Further Reading
+
+- [docs/guide.md](docs/guide.md)
+  Usage guide, transport details, streaming behavior, extensions, and examples.
+- [SECURITY.md](SECURITY.md)
+  Threat model, deployment caveats, and vulnerability disclosure guidance.
+
+## Development
+
+For contributor workflow, local validation, and helper scripts, see
+[CONTRIBUTING.md](CONTRIBUTING.md) and [scripts/README.md](scripts/README.md).
+
+## License
+
+Apache-2.0. See [`LICENSE`](LICENSE).

{opencode_a2a_server-0.2.3 → opencode_a2a_server-0.2.4}/SECURITY.md

@@ -2,10 +2,10 @@
 
 ## Scope
 
-This repository is an adapter layer that exposes OpenCode through A2A
-HTTP+JSON and JSON-RPC interfaces. It adds authentication, task/session
-contracts, streaming, interrupt handling, and runtime guidance, but it does
-not fully isolate upstream model credentials from OpenCode runtime behavior.
+This repository wraps OpenCode as an A2A adapter service. It exposes A2A
+HTTP+JSON and JSON-RPC interfaces, and adds authentication, task/session
+contracts, streaming, interrupt handling, and runtime guidance. It does not
+fully isolate upstream model credentials from OpenCode runtime behavior.
 
 ## Security Boundary
 
@@ -13,7 +13,10 @@ not fully isolate upstream model credentials from OpenCode runtime behavior.
   tenant-isolation boundary inside one deployed instance.
 - One `OpenCode + opencode-a2a-server` instance pair is treated as a
   single-tenant trust boundary by design.
-- Tenant isolation across consumers is expected to come from parameterized self-deployment of separate instance pairs with distinct Linux users, workspace roots, credentials, and runtime ports.
+- Tenant isolation across consumers is expected to come from parameterized
+  self-deployment.
+- For mutually untrusted tenants, use separate instance pairs with distinct
+  Linux users, workspace roots, credentials, and runtime ports.
 - Within one instance, consumers share the same underlying OpenCode
   workspace/environment by default.
 - LLM provider keys are consumed by the `opencode` process. Prompt injection or