opencode-a2a-server 0.1.0__tar.gz → 0.2.1__tar.gz

{opencode_a2a_server-0.1.0 → opencode_a2a_server-0.2.1}/.gitignore

@@ -213,6 +213,9 @@ __marimo__/
 # GitHub CLI temporary body files (should not be committed)
 issue_*.md
 
+# Local session temp files
+temp_*.*
+
 # Local OpenCode OpenAPI snapshots (high-churn, local reference only)
 docs/operations/opencode/
 .swival/

{opencode_a2a_server-0.1.0 → opencode_a2a_server-0.2.1}/.secrets.baseline

@@ -133,9 +133,9 @@
         "filename": "scripts/init_system.sh",
         "hashed_secret": "96183ea4ff07d786ed3233777364ddbf14eb74cc",
         "is_verified": false,
-        "line_number": 23
+        "line_number": 25
       }
     ]
   },
-  "generated_at": "2026-03-13T14:03:33Z"
+  "generated_at": "2026-03-17T13:35:29Z"
 }

opencode_a2a_server-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+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.
+
+## Before You Start
+
+- Read [README.md](README.md) for project scope and user/operator paths.
+- Read [docs/guide.md](docs/guide.md) for runtime contracts and compatibility guidance.
+- Read [SECURITY.md](SECURITY.md) before changing auth, deployment, or secret handling.
+
+## Development Setup
+
+Requirements:
+
+- Python 3.11, 3.12, or 3.13
+- `uv`
+- A reachable OpenCode runtime if you need end-to-end manual checks
+
+Install dependencies:
+
+```bash
+uv sync --all-extras
+```
+
+Run the local development server:
+
+```bash
+A2A_BEARER_TOKEN=dev-token \
+OPENCODE_DIRECTORY=/abs/path/to/workspace \
+uv run opencode-a2a-server
+```
+
+## Validation
+
+Run the default validation baseline before opening a PR:
+
+```bash
+uv run pre-commit run --all-files
+uv run pytest
+```
+
+If you change shell or deployment scripts, also run:
+
+```bash
+bash -n scripts/deploy.sh
+bash -n scripts/deploy/setup_instance.sh
+```
+
+## Change Expectations
+
+- Keep code, comments, and docs in English.
+- Keep issue / PR discussion in Simplified Chinese when collaborating in this repository.
+- Do not drift Agent Card, OpenAPI examples, wire contract metadata, and runtime behavior.
+- Prefer additive, explicit compatibility changes over silent behavior changes.
+- Treat `opencode.*` surfaces as provider-private unless the repository already defines them as shared A2A contracts.
+
+## Git and PR Workflow
+
+- Branch from the latest `main`.
+- Use `git fetch` and `git merge --ff-only` to sync mainline.
+- Do not push directly to protected branches.
+- Link the relevant issue in commits and PR descriptions when applicable.
+- Open PRs as Draft by default when the change still needs review or iteration.
+
+## Documentation
+
+Update docs together with code whenever you change:
+
+- authentication or deployment behavior
+- extension contracts or compatibility expectations
+- 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.

{opencode_a2a_server-0.1.0/src/opencode_a2a_server.egg-info → opencode_a2a_server-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a-server
-Version: 0.1.0
+Version: 0.2.1
 Summary: A2A wrapper service for opencode
 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.24
+Requires-Dist: a2a-sdk==0.3.25
 Requires-Dist: fastapi>=0.110
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.6
@@ -52,7 +52,7 @@ need a stable service layer around it. This repository provides that layer by:
 
 - bridging A2A transport contracts to OpenCode session/message/event APIs
 - making session and interrupt behavior explicit and auditable
-- packaging deployment scripts and operational guidance for long-running use
+- packaging release-first deployment scripts and operational guidance for long-running use
 
 ## What It Already Provides
 
@@ -64,7 +64,7 @@ need a stable service layer around it. This repository provides that layer by:
 - session continuation via `metadata.shared.session.id`
 - request-scoped model selection via `metadata.shared.model`
 - OpenCode session query/control extensions and provider/model discovery
-- systemd multi-instance deployment and lightweight current-user deployment
+- released CLI install/upgrade flow and release-based systemd deployment
 
 ## Extension Capability Overview
 
@@ -88,6 +88,8 @@ Detailed consumption guidance:
 - Shared stream hints: [`docs/guide.md#shared-stream-hints-contract`](docs/guide.md#shared-stream-hints-contract)
 - OpenCode session query and provider discovery: [`docs/guide.md#opencode-session-query--provider-discovery-a2a-extensions`](docs/guide.md#opencode-session-query--provider-discovery-a2a-extensions)
 - Shared interrupt callback: [`docs/guide.md#shared-interrupt-callback-a2a-extension`](docs/guide.md#shared-interrupt-callback-a2a-extension)
+- Compatibility profile and retention guidance:
+  [`docs/guide.md#compatibility-profile`](docs/guide.md#compatibility-profile)
 
 ## Design Principle
 
@@ -113,7 +115,7 @@ flowchart TD
     Mapping --> Runtime["OpenCode HTTP runtime"]
 
     Api --> Auth["Bearer auth + request logging controls"]
-    Api --> Deploy["systemd and lightweight deployment scripts"]
+    Api --> Deploy["release-based deployment tooling"]
     Runtime --> Workspace["Shared workspace / environment boundary"]
 ```
 
@@ -145,30 +147,106 @@ hard multi-tenant isolation layer.
 Read before deployment:
 
 - [SECURITY.md](SECURITY.md)
-- [scripts/deploy_readme.md](scripts/deploy_readme.md)
+- [scripts/deploy_release_readme.md](scripts/deploy_release_readme.md)
+
+## User Paths
+
+Released versions are published to PyPI and mapped to Git tags / GitHub
+Releases. This is the recommended entry point for users.
 
-## Quick Start & Development
+### Path 1: Run a Released CLI in an Existing User Environment
 
-1. Start OpenCode:
+Install the latest release:
 
 ```bash
-opencode serve
+uv tool install opencode-a2a-server
 ```
 
-2. Install dependencies:
+Upgrade an existing installation:
 
 ```bash
-uv sync --all-extras
+uv tool upgrade opencode-a2a-server
 ```
 
-3. Start this service:
+Install an exact release:
 
 ```bash
-A2A_BEARER_TOKEN=dev-token uv run opencode-a2a-server
+uv tool install "opencode-a2a-server==<version>"
+```
+
+Run it against an existing project/workspace:
+
+```bash
+GOOGLE_GENERATIVE_AI_API_KEY=<your-key> \
+OPENCODE_PROVIDER_ID=google \
+OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
+opencode serve
+
+A2A_BEARER_TOKEN=prod-token \
+A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_DIRECTORY=/abs/path/to/workspace \
+opencode-a2a-server
 ```
 
 Default address: `http://127.0.0.1:8000`
 
+If you omit `OPENCODE_PROVIDER_ID` / `OPENCODE_MODEL_ID`, `opencode serve`
+uses your local OpenCode defaults (for example `~/.config/opencode/opencode.json`).
+
+For provider-specific auth, model IDs, and config details, use the OpenCode
+official docs and CLI:
+
+- Providers: <https://opencode.ai/docs/providers/>
+- Models: <https://opencode.ai/docs/models/>
+- Local checks: `opencode auth list`, `opencode models`, `opencode models <provider>`
+
+This path is for users who already manage their own shell, workspace, and
+process lifecycle. No host bootstrap script is required.
+
+### Path 2: Formal systemd Deploy From a Released Version
+
+For long-running systemd deployments, use the release-based scripts:
+
+```bash
+./scripts/init_release_system.sh
+./scripts/deploy_release.sh project=alpha a2a_port=8010 a2a_host=127.0.0.1
+```
+
+This path is for users who want:
+
+- isolated Linux users and per-project directories
+- systemd-managed restart behavior
+- root-only secret files
+- published package versions as the deployment boundary
+
+Primary operator docs:
+
+- [scripts/init_release_system.sh](scripts/init_release_system.sh)
+- [scripts/deploy_release.sh](scripts/deploy_release.sh)
+- [scripts/deploy_release_readme.md](scripts/deploy_release_readme.md)
+- [docs/release_deploy_smoke_test.md](docs/release_deploy_smoke_test.md)
+
+## Contributor Paths
+
+Use the repository checkout directly only for development, local debugging, or
+validation against unreleased changes. Source-based deploy/bootstrap docs are
+kept for contributors and internal debugging, not as the recommended user path.
+
+Quick source run:
+
+```bash
+uv sync --all-extras
+
+GOOGLE_GENERATIVE_AI_API_KEY=<your-key> \
+OPENCODE_PROVIDER_ID=google \
+OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
+opencode serve
+
+A2A_BEARER_TOKEN=dev-token \
+OPENCODE_DIRECTORY=/abs/path/to/workspace \
+uv run opencode-a2a-server
+```
+
 Baseline validation:
 
 ```bash
@@ -178,19 +256,32 @@ uv run pytest
 
 ## Documentation Map
 
+### User / Operator Docs
+
 - [docs/guide.md](docs/guide.md)
   Product behavior, API contracts, and detailed streaming/session/interrupt
   consumption guidance.
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+  Contributor workflow, validation baseline, and documentation expectations.
 - [docs/agent_deploy_sop.md](docs/agent_deploy_sop.md)
-  Operator-facing SOP for choosing, starting, verifying, and releasing
-  `deploy.sh` vs `deploy_light.sh`.
+  Operator-facing SOP for release-based deployment, verification, and uninstall.
+- [docs/release_deploy_smoke_test.md](docs/release_deploy_smoke_test.md)
+  Real-host smoke test checklist for release-based systemd deployment.
+- [scripts/deploy_release_readme.md](scripts/deploy_release_readme.md)
+  Release-based systemd deployment guide for published package versions.
+- [scripts/init_release_system_readme.md](scripts/init_release_system_readme.md)
+  Release-based host bootstrap guide that avoids source checkout.
+- [scripts/uninstall_readme.md](scripts/uninstall_readme.md)
+  Preview-first uninstall flow for deployed instances.
 - [scripts/README.md](scripts/README.md)
-  Entry points for init, deploy, lightweight deploy, local start, and
-  uninstall scripts.
+  Full script index, including contributor/internal paths.
+
+### Contributor / Internal Docs
+
 - [scripts/deploy_readme.md](scripts/deploy_readme.md)
-  systemd deployment, runtime secret strategy, and operations guidance.
-- [scripts/deploy_light_readme.md](scripts/deploy_light_readme.md)
-  current-user lightweight deployment without systemd.
+  Source-based systemd deployment for development/debugging only.
+- [scripts/init_system_readme.md](scripts/init_system_readme.md)
+  Source-based host bootstrap for contributor/internal workflows.
 - [SECURITY.md](SECURITY.md)
   threat model, deployment caveats, and vulnerability disclosure guidance.
 

{opencode_a2a_server-0.1.0 → opencode_a2a_server-0.2.1}/README.md

@@ -14,7 +14,7 @@ need a stable service layer around it. This repository provides that layer by:
 
 - bridging A2A transport contracts to OpenCode session/message/event APIs
 - making session and interrupt behavior explicit and auditable
-- packaging deployment scripts and operational guidance for long-running use
+- packaging release-first deployment scripts and operational guidance for long-running use
 
 ## What It Already Provides
 
@@ -26,7 +26,7 @@ need a stable service layer around it. This repository provides that layer by:
 - session continuation via `metadata.shared.session.id`
 - request-scoped model selection via `metadata.shared.model`
 - OpenCode session query/control extensions and provider/model discovery
-- systemd multi-instance deployment and lightweight current-user deployment
+- released CLI install/upgrade flow and release-based systemd deployment
 
 ## Extension Capability Overview
 
@@ -50,6 +50,8 @@ Detailed consumption guidance:
 - Shared stream hints: [`docs/guide.md#shared-stream-hints-contract`](docs/guide.md#shared-stream-hints-contract)
 - OpenCode session query and provider discovery: [`docs/guide.md#opencode-session-query--provider-discovery-a2a-extensions`](docs/guide.md#opencode-session-query--provider-discovery-a2a-extensions)
 - Shared interrupt callback: [`docs/guide.md#shared-interrupt-callback-a2a-extension`](docs/guide.md#shared-interrupt-callback-a2a-extension)
+- Compatibility profile and retention guidance:
+  [`docs/guide.md#compatibility-profile`](docs/guide.md#compatibility-profile)
 
 ## Design Principle
 
@@ -75,7 +77,7 @@ flowchart TD
     Mapping --> Runtime["OpenCode HTTP runtime"]
 
     Api --> Auth["Bearer auth + request logging controls"]
-    Api --> Deploy["systemd and lightweight deployment scripts"]
+    Api --> Deploy["release-based deployment tooling"]
     Runtime --> Workspace["Shared workspace / environment boundary"]
 ```
 
@@ -107,30 +109,106 @@ hard multi-tenant isolation layer.
 Read before deployment:
 
 - [SECURITY.md](SECURITY.md)
-- [scripts/deploy_readme.md](scripts/deploy_readme.md)
+- [scripts/deploy_release_readme.md](scripts/deploy_release_readme.md)
+
+## User Paths
+
+Released versions are published to PyPI and mapped to Git tags / GitHub
+Releases. This is the recommended entry point for users.
 
-## Quick Start & Development
+### Path 1: Run a Released CLI in an Existing User Environment
 
-1. Start OpenCode:
+Install the latest release:
 
 ```bash
-opencode serve
+uv tool install opencode-a2a-server
 ```
 
-2. Install dependencies:
+Upgrade an existing installation:
 
 ```bash
-uv sync --all-extras
+uv tool upgrade opencode-a2a-server
 ```
 
-3. Start this service:
+Install an exact release:
 
 ```bash
-A2A_BEARER_TOKEN=dev-token uv run opencode-a2a-server
+uv tool install "opencode-a2a-server==<version>"
+```
+
+Run it against an existing project/workspace:
+
+```bash
+GOOGLE_GENERATIVE_AI_API_KEY=<your-key> \
+OPENCODE_PROVIDER_ID=google \
+OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
+opencode serve
+
+A2A_BEARER_TOKEN=prod-token \
+A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_DIRECTORY=/abs/path/to/workspace \
+opencode-a2a-server
 ```
 
 Default address: `http://127.0.0.1:8000`
 
+If you omit `OPENCODE_PROVIDER_ID` / `OPENCODE_MODEL_ID`, `opencode serve`
+uses your local OpenCode defaults (for example `~/.config/opencode/opencode.json`).
+
+For provider-specific auth, model IDs, and config details, use the OpenCode
+official docs and CLI:
+
+- Providers: <https://opencode.ai/docs/providers/>
+- Models: <https://opencode.ai/docs/models/>
+- Local checks: `opencode auth list`, `opencode models`, `opencode models <provider>`
+
+This path is for users who already manage their own shell, workspace, and
+process lifecycle. No host bootstrap script is required.
+
+### Path 2: Formal systemd Deploy From a Released Version
+
+For long-running systemd deployments, use the release-based scripts:
+
+```bash
+./scripts/init_release_system.sh
+./scripts/deploy_release.sh project=alpha a2a_port=8010 a2a_host=127.0.0.1
+```
+
+This path is for users who want:
+
+- isolated Linux users and per-project directories
+- systemd-managed restart behavior
+- root-only secret files
+- published package versions as the deployment boundary
+
+Primary operator docs:
+
+- [scripts/init_release_system.sh](scripts/init_release_system.sh)
+- [scripts/deploy_release.sh](scripts/deploy_release.sh)
+- [scripts/deploy_release_readme.md](scripts/deploy_release_readme.md)
+- [docs/release_deploy_smoke_test.md](docs/release_deploy_smoke_test.md)
+
+## Contributor Paths
+
+Use the repository checkout directly only for development, local debugging, or
+validation against unreleased changes. Source-based deploy/bootstrap docs are
+kept for contributors and internal debugging, not as the recommended user path.
+
+Quick source run:
+
+```bash
+uv sync --all-extras
+
+GOOGLE_GENERATIVE_AI_API_KEY=<your-key> \
+OPENCODE_PROVIDER_ID=google \
+OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
+opencode serve
+
+A2A_BEARER_TOKEN=dev-token \
+OPENCODE_DIRECTORY=/abs/path/to/workspace \
+uv run opencode-a2a-server
+```
+
 Baseline validation:
 
 ```bash
@@ -140,19 +218,32 @@ uv run pytest
 
 ## Documentation Map
 
+### User / Operator Docs
+
 - [docs/guide.md](docs/guide.md)
   Product behavior, API contracts, and detailed streaming/session/interrupt
   consumption guidance.
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+  Contributor workflow, validation baseline, and documentation expectations.
 - [docs/agent_deploy_sop.md](docs/agent_deploy_sop.md)
-  Operator-facing SOP for choosing, starting, verifying, and releasing
-  `deploy.sh` vs `deploy_light.sh`.
+  Operator-facing SOP for release-based deployment, verification, and uninstall.
+- [docs/release_deploy_smoke_test.md](docs/release_deploy_smoke_test.md)
+  Real-host smoke test checklist for release-based systemd deployment.
+- [scripts/deploy_release_readme.md](scripts/deploy_release_readme.md)
+  Release-based systemd deployment guide for published package versions.
+- [scripts/init_release_system_readme.md](scripts/init_release_system_readme.md)
+  Release-based host bootstrap guide that avoids source checkout.
+- [scripts/uninstall_readme.md](scripts/uninstall_readme.md)
+  Preview-first uninstall flow for deployed instances.
 - [scripts/README.md](scripts/README.md)
-  Entry points for init, deploy, lightweight deploy, local start, and
-  uninstall scripts.
+  Full script index, including contributor/internal paths.
+
+### Contributor / Internal Docs
+
 - [scripts/deploy_readme.md](scripts/deploy_readme.md)
-  systemd deployment, runtime secret strategy, and operations guidance.
-- [scripts/deploy_light_readme.md](scripts/deploy_light_readme.md)
-  current-user lightweight deployment without systemd.
+  Source-based systemd deployment for development/debugging only.
+- [scripts/init_system_readme.md](scripts/init_system_readme.md)
+  Source-based host bootstrap for contributor/internal workflows.
 - [SECURITY.md](SECURITY.md)
   threat model, deployment caveats, and vulnerability disclosure guidance.