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

{opencode_a2a_server-0.2.2/src/opencode_a2a_server.egg-info → opencode_a2a_server-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a-server
-Version: 0.2.2
+Version: 0.2.3
 Summary: A2A wrapper service for opencode
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -186,7 +186,10 @@ OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
 opencode serve
 
 A2A_BEARER_TOKEN=prod-token \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_MANAGED_SERVER=true \
 OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 opencode-a2a-server serve
 ```
@@ -196,12 +199,25 @@ exposes to OpenCode.
 
 Default address: `http://127.0.0.1:8000`
 
+OpenCode upstream modes:
+
+- Managed upstream: set `OPENCODE_MANAGED_SERVER=true` and
+  `opencode-a2a-server` will start a local `opencode serve`, capture its actual
+  listening URL, and stop it on shutdown.
+- External upstream: you start and manage `opencode serve` yourself, then point
+  `OPENCODE_BASE_URL` at that HTTP endpoint.
+
 Common runtime variables:
 
 | Variable | Required | Default | Purpose |
 | --- | --- | --- | --- |
 | `A2A_BEARER_TOKEN` | Yes | None | Bearer token required for authenticated runtime requests. |
-| `OPENCODE_BASE_URL` | No | `http://127.0.0.1:4096` | Upstream OpenCode HTTP endpoint. |
+| `OPENCODE_BASE_URL` | No | `http://127.0.0.1:4096` | Upstream OpenCode HTTP endpoint for externally managed upstream mode. |
+| `OPENCODE_MANAGED_SERVER` | No | `false` | Start and manage a local `opencode serve` child process. |
+| `OPENCODE_MANAGED_SERVER_HOST` | No | `127.0.0.1` | Bind host used when managed upstream mode is enabled. |
+| `OPENCODE_MANAGED_SERVER_PORT` | No | auto-pick | Bind port used when managed upstream mode is enabled. |
+| `OPENCODE_COMMAND` | No | `opencode` | OpenCode CLI executable used for managed upstream mode. |
+| `OPENCODE_STARTUP_TIMEOUT` | No | `20` | Seconds to wait for managed upstream startup. |
 | `OPENCODE_WORKSPACE_ROOT` | No | None | Default workspace root exposed to OpenCode. |
 | `OPENCODE_PROVIDER_ID` | No | None | Default provider for the upstream runtime. |
 | `OPENCODE_MODEL_ID` | No | None | Default model for the upstream runtime. Set together with `OPENCODE_PROVIDER_ID`. |
@@ -220,6 +236,9 @@ Common runtime variables:
 If you omit `OPENCODE_PROVIDER_ID` / `OPENCODE_MODEL_ID`, `opencode serve`
 uses your local OpenCode defaults (for example `~/.config/opencode/opencode.json`).
 
+When `OPENCODE_MANAGED_SERVER=true`, `OPENCODE_BASE_URL` is ignored and the
+runtime binds itself to the managed child process instead.
+
 For provider-specific auth, model IDs, and config details, use the OpenCode
 official docs and CLI:
 
@@ -240,7 +259,7 @@ Use any supervisor you prefer for long-running operation:
 The project no longer ships built-in host bootstrap or process-manager
 wrappers. The official product surface is the runtime entrypoint itself.
 
-Minimal `systemd` example:
+Minimal self-managed `systemd` example:
 
 1. Create an env file such as `/etc/opencode-a2a/alpha.env`:
 
@@ -249,7 +268,7 @@ A2A_BEARER_TOKEN=replace-me
 A2A_HOST=127.0.0.1
 A2A_PORT=8000
 A2A_PUBLIC_URL=https://a2a.example.com
-OPENCODE_BASE_URL=http://127.0.0.1:4096
+OPENCODE_MANAGED_SERVER=true
 OPENCODE_WORKSPACE_ROOT=/srv/my-workspace
 ```
 
@@ -275,6 +294,33 @@ WantedBy=multi-user.target
 
 Replace `ExecStart` with the absolute path returned by `command -v opencode-a2a-server`.
 
+Minimal managed-upstream foreground example:
+
+```bash
+A2A_BEARER_TOKEN=dev-token \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
+A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_MANAGED_SERVER=true \
+OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
+opencode-a2a-server serve
+```
+
+Advanced: externally managed upstream
+
+Use this mode when you intentionally want `opencode serve` and
+`opencode-a2a-server` to be supervised independently.
+
+```bash
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_BEARER_TOKEN=dev-token \
+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
+```
+
 Migration notes:
 
 - `OPENCODE_DIRECTORY` has been removed. Use `OPENCODE_WORKSPACE_ROOT`.
@@ -297,6 +343,9 @@ OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
 opencode serve
 
 A2A_BEARER_TOKEN=dev-token \
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
 OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 uv run opencode-a2a-server serve
 ```

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3}/README.md

@@ -148,7 +148,10 @@ OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
 opencode serve
 
 A2A_BEARER_TOKEN=prod-token \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_MANAGED_SERVER=true \
 OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 opencode-a2a-server serve
 ```
@@ -158,12 +161,25 @@ exposes to OpenCode.
 
 Default address: `http://127.0.0.1:8000`
 
+OpenCode upstream modes:
+
+- Managed upstream: set `OPENCODE_MANAGED_SERVER=true` and
+  `opencode-a2a-server` will start a local `opencode serve`, capture its actual
+  listening URL, and stop it on shutdown.
+- External upstream: you start and manage `opencode serve` yourself, then point
+  `OPENCODE_BASE_URL` at that HTTP endpoint.
+
 Common runtime variables:
 
 | Variable | Required | Default | Purpose |
 | --- | --- | --- | --- |
 | `A2A_BEARER_TOKEN` | Yes | None | Bearer token required for authenticated runtime requests. |
-| `OPENCODE_BASE_URL` | No | `http://127.0.0.1:4096` | Upstream OpenCode HTTP endpoint. |
+| `OPENCODE_BASE_URL` | No | `http://127.0.0.1:4096` | Upstream OpenCode HTTP endpoint for externally managed upstream mode. |
+| `OPENCODE_MANAGED_SERVER` | No | `false` | Start and manage a local `opencode serve` child process. |
+| `OPENCODE_MANAGED_SERVER_HOST` | No | `127.0.0.1` | Bind host used when managed upstream mode is enabled. |
+| `OPENCODE_MANAGED_SERVER_PORT` | No | auto-pick | Bind port used when managed upstream mode is enabled. |
+| `OPENCODE_COMMAND` | No | `opencode` | OpenCode CLI executable used for managed upstream mode. |
+| `OPENCODE_STARTUP_TIMEOUT` | No | `20` | Seconds to wait for managed upstream startup. |
 | `OPENCODE_WORKSPACE_ROOT` | No | None | Default workspace root exposed to OpenCode. |
 | `OPENCODE_PROVIDER_ID` | No | None | Default provider for the upstream runtime. |
 | `OPENCODE_MODEL_ID` | No | None | Default model for the upstream runtime. Set together with `OPENCODE_PROVIDER_ID`. |
@@ -182,6 +198,9 @@ Common runtime variables:
 If you omit `OPENCODE_PROVIDER_ID` / `OPENCODE_MODEL_ID`, `opencode serve`
 uses your local OpenCode defaults (for example `~/.config/opencode/opencode.json`).
 
+When `OPENCODE_MANAGED_SERVER=true`, `OPENCODE_BASE_URL` is ignored and the
+runtime binds itself to the managed child process instead.
+
 For provider-specific auth, model IDs, and config details, use the OpenCode
 official docs and CLI:
 
@@ -202,7 +221,7 @@ Use any supervisor you prefer for long-running operation:
 The project no longer ships built-in host bootstrap or process-manager
 wrappers. The official product surface is the runtime entrypoint itself.
 
-Minimal `systemd` example:
+Minimal self-managed `systemd` example:
 
 1. Create an env file such as `/etc/opencode-a2a/alpha.env`:
 
@@ -211,7 +230,7 @@ A2A_BEARER_TOKEN=replace-me
 A2A_HOST=127.0.0.1
 A2A_PORT=8000
 A2A_PUBLIC_URL=https://a2a.example.com
-OPENCODE_BASE_URL=http://127.0.0.1:4096
+OPENCODE_MANAGED_SERVER=true
 OPENCODE_WORKSPACE_ROOT=/srv/my-workspace
 ```
 
@@ -237,6 +256,33 @@ WantedBy=multi-user.target
 
 Replace `ExecStart` with the absolute path returned by `command -v opencode-a2a-server`.
 
+Minimal managed-upstream foreground example:
+
+```bash
+A2A_BEARER_TOKEN=dev-token \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
+A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_MANAGED_SERVER=true \
+OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
+opencode-a2a-server serve
+```
+
+Advanced: externally managed upstream
+
+Use this mode when you intentionally want `opencode serve` and
+`opencode-a2a-server` to be supervised independently.
+
+```bash
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_BEARER_TOKEN=dev-token \
+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
+```
+
 Migration notes:
 
 - `OPENCODE_DIRECTORY` has been removed. Use `OPENCODE_WORKSPACE_ROOT`.
@@ -259,6 +305,9 @@ OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
 opencode serve
 
 A2A_BEARER_TOKEN=dev-token \
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
 OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 uv run opencode-a2a-server serve
 ```

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3}/docs/guide.md

@@ -25,8 +25,16 @@ own process manager, container runtime, or host orchestration.
 Key variables to understand protocol behavior:
 
 - `A2A_BEARER_TOKEN`: required for all authenticated runtime requests.
-- `OPENCODE_BASE_URL`: upstream OpenCode HTTP endpoint. Default:
-  `http://127.0.0.1:4096`.
+- `OPENCODE_BASE_URL`: upstream OpenCode HTTP endpoint for externally managed
+  upstream mode. Default: `http://127.0.0.1:4096`.
+- `OPENCODE_MANAGED_SERVER`: when enabled, the service starts a local
+  `opencode serve`, captures its actual listening URL, and uses that as the
+  internal upstream endpoint.
+- `OPENCODE_MANAGED_SERVER_HOST` / `OPENCODE_MANAGED_SERVER_PORT`: bind address
+  for managed upstream mode. If the port is omitted, the service picks a free
+  localhost port before starting the child process.
+- `OPENCODE_COMMAND`: OpenCode CLI executable used for managed upstream mode.
+- `OPENCODE_STARTUP_TIMEOUT`: startup timeout for managed upstream mode.
 - `OPENCODE_WORKSPACE_ROOT`: service-level default workspace root exposed to
   OpenCode when clients do not request a narrower directory override.
 - `OPENCODE_PROVIDER_ID` / `OPENCODE_MODEL_ID`: default upstream model
@@ -54,14 +62,26 @@ Key variables to understand protocol behavior:
   optional stream timeout override.
 - Runtime authentication is bearer-token only via `A2A_BEARER_TOKEN`.
 
-Minimal runtime example:
+Minimal managed-upstream example:
 
 ```bash
 A2A_BEARER_TOKEN=dev-token \
 A2A_HOST=127.0.0.1 \
 A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_MANAGED_SERVER=true \
+OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
+opencode-a2a-server serve
+```
+
+Advanced externally managed upstream example:
+
+```bash
 OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_BEARER_TOKEN=dev-token \
+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
 ```

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3}/src/opencode_a2a_server/app.py

@@ -69,6 +69,7 @@ from .jsonrpc_ext import (
     OpencodeSessionQueryJSONRPCApplication,
 )
 from .opencode_client import OpencodeClient
+from .opencode_upstream import ManagedOpencodeServer, launch_managed_opencode_server
 
 logger = logging.getLogger(__name__)
 
@@ -993,8 +994,17 @@ def create_app(settings: Settings) -> FastAPI:
 
     @asynccontextmanager
     async def lifespan(_app: FastAPI):
-        yield
-        await client.close()
+        managed_upstream: ManagedOpencodeServer | None = None
+        try:
+            if settings.opencode_managed_server:
+                managed_upstream = await launch_managed_opencode_server(settings)
+                await client.rebind_base_url(managed_upstream.base_url)
+                _app.state.managed_opencode_upstream = managed_upstream
+            yield
+        finally:
+            if managed_upstream is not None:
+                await managed_upstream.close()
+            await client.close()
 
     agent_card = build_agent_card(settings)
     context_builder = IdentityAwareCallContextBuilder()

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3}/src/opencode_a2a_server/config.py

@@ -19,6 +19,23 @@ class Settings(BaseSettings):
 
     # OpenCode settings
     opencode_base_url: str = Field(default="http://127.0.0.1:4096", alias="OPENCODE_BASE_URL")
+    opencode_managed_server: bool = Field(default=False, alias="OPENCODE_MANAGED_SERVER")
+    opencode_managed_server_host: str = Field(
+        default="127.0.0.1",
+        alias="OPENCODE_MANAGED_SERVER_HOST",
+    )
+    opencode_managed_server_port: int | None = Field(
+        default=None,
+        ge=1,
+        le=65535,
+        alias="OPENCODE_MANAGED_SERVER_PORT",
+    )
+    opencode_command: str = Field(default="opencode", alias="OPENCODE_COMMAND")
+    opencode_startup_timeout: float = Field(
+        default=20.0,
+        gt=0.0,
+        alias="OPENCODE_STARTUP_TIMEOUT",
+    )
     opencode_workspace_root: str | None = Field(default=None, alias="OPENCODE_WORKSPACE_ROOT")
     opencode_provider_id: str | None = Field(default=None, alias="OPENCODE_PROVIDER_ID")
     opencode_model_id: str | None = Field(default=None, alias="OPENCODE_MODEL_ID")

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3}/src/opencode_a2a_server/opencode_client.py

@@ -54,15 +54,27 @@ class OpencodeClient:
         self._interrupt_request_ttl_seconds = 600.0
         self._interrupt_request_clock = time.monotonic
         self._interrupt_requests: dict[str, InterruptRequestBinding] = {}
-        self._client = httpx.AsyncClient(
-            base_url=self._base_url,
-            timeout=settings.opencode_timeout,
+        self._client = self._build_http_client(self._base_url)
+
+    def _build_http_client(self, base_url: str) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            base_url=base_url,
+            timeout=self._settings.opencode_timeout,
             headers={"Accept": "application/json"},
         )
 
     async def close(self) -> None:
         await self._client.aclose()
 
+    async def rebind_base_url(self, base_url: str) -> None:
+        normalized = base_url.rstrip("/")
+        if normalized == self._base_url:
+            return
+        previous_client = self._client
+        self._base_url = normalized
+        self._client = self._build_http_client(self._base_url)
+        await previous_client.aclose()
+
     @staticmethod
     def _response_body_preview(response: httpx.Response, *, limit: int = 200) -> str:
         body = response.text.strip()
@@ -177,6 +189,10 @@ class OpencodeClient:
     def settings(self) -> Settings:
         return self._settings
 
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
     def _query_params(self, directory: str | None = None) -> dict[str, str]:
         d = directory or self._directory
         if not d:

opencode_a2a_server-0.2.3/src/opencode_a2a_server/opencode_upstream.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import shutil
+import socket
+from collections import deque
+from dataclasses import dataclass
+
+from .config import Settings
+
+_LISTENING_PATTERN = re.compile(r"opencode server listening on (?P<url>https?://\S+)")
+_OUTPUT_BUFFER_LIMIT = 40
+
+
+def _pick_managed_server_port(host: str) -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind((host, 0))
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        return int(sock.getsockname()[1])
+
+
+def _resolve_opencode_command(command: str) -> str:
+    if os.path.sep in command:
+        if os.path.exists(command):
+            return command
+        raise RuntimeError(f"Managed upstream command not found: {command}")
+    resolved = shutil.which(command)
+    if resolved:
+        return resolved
+    raise RuntimeError(
+        f"Managed upstream command not found on PATH: {command}. "
+        "Install opencode or set OPENCODE_COMMAND."
+    )
+
+
+@dataclass
+class ManagedOpencodeServer:
+    process: asyncio.subprocess.Process
+    base_url: str
+    _output_task: asyncio.Task[None]
+
+    async def close(self) -> None:
+        if self.process.returncode is None:
+            self.process.terminate()
+            try:
+                await asyncio.wait_for(self.process.wait(), timeout=5.0)
+            except TimeoutError:
+                self.process.kill()
+                await self.process.wait()
+        await self._output_task
+
+
+async def _consume_process_output(
+    stream: asyncio.StreamReader | None,
+    *,
+    ready_future: asyncio.Future[str],
+    output_buffer: deque[str],
+) -> None:
+    if stream is None:
+        return
+    while True:
+        line = await stream.readline()
+        if not line:
+            return
+        text = line.decode("utf-8", errors="replace").rstrip()
+        if not text:
+            continue
+        output_buffer.append(text)
+        match = _LISTENING_PATTERN.search(text)
+        if match and not ready_future.done():
+            ready_future.set_result(match.group("url"))
+
+
+async def launch_managed_opencode_server(settings: Settings) -> ManagedOpencodeServer:
+    host = settings.opencode_managed_server_host
+    port = settings.opencode_managed_server_port or _pick_managed_server_port(host)
+    command = _resolve_opencode_command(settings.opencode_command)
+    cmd = [
+        command,
+        "serve",
+        "--hostname",
+        host,
+        "--port",
+        str(port),
+    ]
+    process = await asyncio.create_subprocess_exec(
+        *cmd,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+    )
+    ready_future: asyncio.Future[str] = asyncio.get_running_loop().create_future()
+    output_buffer: deque[str] = deque(maxlen=_OUTPUT_BUFFER_LIMIT)
+    output_task = asyncio.create_task(
+        _consume_process_output(
+            process.stdout,
+            ready_future=ready_future,
+            output_buffer=output_buffer,
+        )
+    )
+    try:
+        base_url = await asyncio.wait_for(ready_future, timeout=settings.opencode_startup_timeout)
+    except Exception as exc:
+        if process.returncode is None:
+            process.terminate()
+            try:
+                await asyncio.wait_for(process.wait(), timeout=5.0)
+            except TimeoutError:
+                process.kill()
+                await process.wait()
+        await output_task
+        buffered_output = "\n".join(output_buffer).strip() or "<no output>"
+        raise RuntimeError(
+            "Managed OpenCode upstream failed to become ready. "
+            f"command={' '.join(cmd)} output={buffered_output}"
+        ) from exc
+    return ManagedOpencodeServer(
+        process=process,
+        base_url=base_url.rstrip("/"),
+        _output_task=output_task,
+    )

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3/src/opencode_a2a_server.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a-server
-Version: 0.2.2
+Version: 0.2.3
 Summary: A2A wrapper service for opencode
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -186,7 +186,10 @@ OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
 opencode serve
 
 A2A_BEARER_TOKEN=prod-token \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
 A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_MANAGED_SERVER=true \
 OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 opencode-a2a-server serve
 ```
@@ -196,12 +199,25 @@ exposes to OpenCode.
 
 Default address: `http://127.0.0.1:8000`
 
+OpenCode upstream modes:
+
+- Managed upstream: set `OPENCODE_MANAGED_SERVER=true` and
+  `opencode-a2a-server` will start a local `opencode serve`, capture its actual
+  listening URL, and stop it on shutdown.
+- External upstream: you start and manage `opencode serve` yourself, then point
+  `OPENCODE_BASE_URL` at that HTTP endpoint.
+
 Common runtime variables:
 
 | Variable | Required | Default | Purpose |
 | --- | --- | --- | --- |
 | `A2A_BEARER_TOKEN` | Yes | None | Bearer token required for authenticated runtime requests. |
-| `OPENCODE_BASE_URL` | No | `http://127.0.0.1:4096` | Upstream OpenCode HTTP endpoint. |
+| `OPENCODE_BASE_URL` | No | `http://127.0.0.1:4096` | Upstream OpenCode HTTP endpoint for externally managed upstream mode. |
+| `OPENCODE_MANAGED_SERVER` | No | `false` | Start and manage a local `opencode serve` child process. |
+| `OPENCODE_MANAGED_SERVER_HOST` | No | `127.0.0.1` | Bind host used when managed upstream mode is enabled. |
+| `OPENCODE_MANAGED_SERVER_PORT` | No | auto-pick | Bind port used when managed upstream mode is enabled. |
+| `OPENCODE_COMMAND` | No | `opencode` | OpenCode CLI executable used for managed upstream mode. |
+| `OPENCODE_STARTUP_TIMEOUT` | No | `20` | Seconds to wait for managed upstream startup. |
 | `OPENCODE_WORKSPACE_ROOT` | No | None | Default workspace root exposed to OpenCode. |
 | `OPENCODE_PROVIDER_ID` | No | None | Default provider for the upstream runtime. |
 | `OPENCODE_MODEL_ID` | No | None | Default model for the upstream runtime. Set together with `OPENCODE_PROVIDER_ID`. |
@@ -220,6 +236,9 @@ Common runtime variables:
 If you omit `OPENCODE_PROVIDER_ID` / `OPENCODE_MODEL_ID`, `opencode serve`
 uses your local OpenCode defaults (for example `~/.config/opencode/opencode.json`).
 
+When `OPENCODE_MANAGED_SERVER=true`, `OPENCODE_BASE_URL` is ignored and the
+runtime binds itself to the managed child process instead.
+
 For provider-specific auth, model IDs, and config details, use the OpenCode
 official docs and CLI:
 
@@ -240,7 +259,7 @@ Use any supervisor you prefer for long-running operation:
 The project no longer ships built-in host bootstrap or process-manager
 wrappers. The official product surface is the runtime entrypoint itself.
 
-Minimal `systemd` example:
+Minimal self-managed `systemd` example:
 
 1. Create an env file such as `/etc/opencode-a2a/alpha.env`:
 
@@ -249,7 +268,7 @@ A2A_BEARER_TOKEN=replace-me
 A2A_HOST=127.0.0.1
 A2A_PORT=8000
 A2A_PUBLIC_URL=https://a2a.example.com
-OPENCODE_BASE_URL=http://127.0.0.1:4096
+OPENCODE_MANAGED_SERVER=true
 OPENCODE_WORKSPACE_ROOT=/srv/my-workspace
 ```
 
@@ -275,6 +294,33 @@ WantedBy=multi-user.target
 
 Replace `ExecStart` with the absolute path returned by `command -v opencode-a2a-server`.
 
+Minimal managed-upstream foreground example:
+
+```bash
+A2A_BEARER_TOKEN=dev-token \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
+A2A_PUBLIC_URL=http://127.0.0.1:8000 \
+OPENCODE_MANAGED_SERVER=true \
+OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
+opencode-a2a-server serve
+```
+
+Advanced: externally managed upstream
+
+Use this mode when you intentionally want `opencode serve` and
+`opencode-a2a-server` to be supervised independently.
+
+```bash
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_BEARER_TOKEN=dev-token \
+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
+```
+
 Migration notes:
 
 - `OPENCODE_DIRECTORY` has been removed. Use `OPENCODE_WORKSPACE_ROOT`.
@@ -297,6 +343,9 @@ OPENCODE_MODEL_ID=gemini-3.1-pro-preview \
 opencode serve
 
 A2A_BEARER_TOKEN=dev-token \
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_HOST=127.0.0.1 \
+A2A_PORT=8000 \
 OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 uv run opencode-a2a-server serve
 ```

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3}/src/opencode_a2a_server.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ src/opencode_a2a_server/extension_contracts.py
 src/opencode_a2a_server/jsonrpc_ext.py
 src/opencode_a2a_server/jsonrpc_models.py
 src/opencode_a2a_server/opencode_client.py
+src/opencode_a2a_server/opencode_upstream.py
 src/opencode_a2a_server/parts_mapper.py
 src/opencode_a2a_server/text_parts.py
 src/opencode_a2a_server.egg-info/PKG-INFO
@@ -52,6 +53,7 @@ tests/test_multipart_input.py
 tests/test_opencode_agent_session_binding.py
 tests/test_opencode_client_params.py
 tests/test_opencode_session_extension.py
+tests/test_opencode_upstream.py
 tests/test_script_health_contract.py
 tests/test_session_ownership.py
 tests/test_settings.py

opencode_a2a_server-0.2.3/tests/test_opencode_upstream.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from fastapi.testclient import TestClient
+
+from opencode_a2a_server.app import create_app
+from opencode_a2a_server.opencode_upstream import (
+    ManagedOpencodeServer,
+    _resolve_opencode_command,
+    launch_managed_opencode_server,
+)
+from tests.helpers import make_settings
+
+
+class _DummyProcess:
+    def __init__(self, lines: list[str], *, returncode: int | None = None) -> None:
+        self.stdout = asyncio.StreamReader()
+        for line in lines:
+            self.stdout.feed_data(line.encode("utf-8"))
+        self.stdout.feed_eof()
+        self.returncode = returncode
+        self.terminated = False
+        self.killed = False
+
+    def terminate(self) -> None:
+        self.terminated = True
+        self.returncode = 0
+
+    def kill(self) -> None:
+        self.killed = True
+        self.returncode = -9
+
+    async def wait(self) -> int:
+        if self.returncode is None:
+            self.returncode = 0
+        return self.returncode
+
+
+def test_resolve_opencode_command_errors_when_not_found(monkeypatch) -> None:
+    monkeypatch.setattr("opencode_a2a_server.opencode_upstream.shutil.which", lambda _: None)
+
+    with pytest.raises(RuntimeError) as excinfo:
+        _resolve_opencode_command("opencode")
+
+    assert "OPENCODE_COMMAND" in str(excinfo.value)
+
+
+@pytest.mark.asyncio
+async def test_launch_managed_opencode_server_uses_listening_url(monkeypatch) -> None:
+    dummy = _DummyProcess(
+        [
+            "Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.\n",
+            "opencode server listening on http://127.0.0.1:40419\n",
+        ]
+    )
+    captured: list[str] = []
+
+    async def _fake_create_subprocess_exec(*cmd, **kwargs):  # noqa: ANN001
+        del kwargs
+        captured.extend(cmd)
+        return dummy
+
+    monkeypatch.setattr(
+        "opencode_a2a_server.opencode_upstream._resolve_opencode_command",
+        lambda command: command,
+    )
+    monkeypatch.setattr(
+        "opencode_a2a_server.opencode_upstream._pick_managed_server_port",
+        lambda host: 40419,
+    )
+    monkeypatch.setattr(
+        "opencode_a2a_server.opencode_upstream.asyncio.create_subprocess_exec",
+        _fake_create_subprocess_exec,
+    )
+    settings = make_settings(
+        opencode_managed_server=True,
+        opencode_command="opencode",
+        opencode_startup_timeout=1.0,
+    )
+
+    handle = await launch_managed_opencode_server(settings)
+
+    assert captured == ["opencode", "serve", "--hostname", "127.0.0.1", "--port", "40419"]
+    assert handle.base_url == "http://127.0.0.1:40419"
+    await handle.close()
+    assert dummy.terminated is True
+
+
+@pytest.mark.asyncio
+async def test_launch_managed_opencode_server_surfaces_startup_failure(monkeypatch) -> None:
+    dummy = _DummyProcess(["fatal: boom\n"], returncode=1)
+
+    async def _fake_create_subprocess_exec(*_cmd, **_kwargs):  # noqa: ANN001
+        return dummy
+
+    monkeypatch.setattr(
+        "opencode_a2a_server.opencode_upstream._resolve_opencode_command",
+        lambda command: command,
+    )
+    monkeypatch.setattr(
+        "opencode_a2a_server.opencode_upstream._pick_managed_server_port",
+        lambda host: 40420,
+    )
+    monkeypatch.setattr(
+        "opencode_a2a_server.opencode_upstream.asyncio.create_subprocess_exec",
+        _fake_create_subprocess_exec,
+    )
+    settings = make_settings(
+        opencode_managed_server=True,
+        opencode_command="opencode",
+        opencode_startup_timeout=0.01,
+    )
+
+    with pytest.raises(RuntimeError) as excinfo:
+        await launch_managed_opencode_server(settings)
+
+    assert "failed to become ready" in str(excinfo.value)
+    assert "fatal: boom" in str(excinfo.value)
+
+
+def test_create_app_manages_upstream_lifecycle(monkeypatch) -> None:
+    import opencode_a2a_server.app as app_module
+
+    calls: list[str] = []
+
+    class _DummyHandle(ManagedOpencodeServer):
+        def __init__(self) -> None:
+            self.process = _DummyProcess([])
+            self.base_url = "http://127.0.0.1:40421"
+            self._output_task = asyncio.get_event_loop().create_task(asyncio.sleep(0))
+
+        async def close(self) -> None:  # type: ignore[override]
+            calls.append("managed_close")
+
+    async def _fake_launch(settings):  # noqa: ANN001
+        assert settings.opencode_managed_server is True
+        calls.append("launch")
+        return _DummyHandle()
+
+    async def _fake_rebind(self, base_url: str) -> None:  # noqa: ANN001
+        calls.append(f"rebind:{base_url}")
+
+    async def _fake_close(self) -> None:  # noqa: ANN001
+        calls.append("client_close")
+
+    monkeypatch.setattr(app_module, "launch_managed_opencode_server", _fake_launch)
+    monkeypatch.setattr(app_module.OpencodeClient, "rebind_base_url", _fake_rebind)
+    monkeypatch.setattr(app_module.OpencodeClient, "close", _fake_close)
+
+    app = create_app(
+        make_settings(
+            a2a_bearer_token="test-token",
+            opencode_managed_server=True,
+        )
+    )
+
+    with TestClient(app):
+        assert calls[:2] == ["launch", "rebind:http://127.0.0.1:40421"]
+
+    assert calls == ["launch", "rebind:http://127.0.0.1:40421", "managed_close", "client_close"]

{opencode_a2a_server-0.2.2 → opencode_a2a_server-0.2.3}/tests/test_settings.py

@@ -22,6 +22,11 @@ def test_settings_valid():
     env = {
         "A2A_BEARER_TOKEN": "test-token",
         "OPENCODE_TIMEOUT": "300",
+        "OPENCODE_MANAGED_SERVER": "true",
+        "OPENCODE_MANAGED_SERVER_HOST": "127.0.0.1",
+        "OPENCODE_MANAGED_SERVER_PORT": "42111",
+        "OPENCODE_COMMAND": "/usr/local/bin/opencode",
+        "OPENCODE_STARTUP_TIMEOUT": "9.5",
         "OPENCODE_WORKSPACE_ROOT": "/srv/workspaces/alpha",
         "A2A_MAX_REQUEST_BODY_BYTES": "2048",
         "A2A_CANCEL_ABORT_TIMEOUT_SECONDS": "0.75",
@@ -31,6 +36,11 @@ def test_settings_valid():
         settings = Settings.from_env()
         assert settings.a2a_bearer_token == "test-token"
         assert settings.opencode_timeout == 300.0
+        assert settings.opencode_managed_server is True
+        assert settings.opencode_managed_server_host == "127.0.0.1"
+        assert settings.opencode_managed_server_port == 42111
+        assert settings.opencode_command == "/usr/local/bin/opencode"
+        assert settings.opencode_startup_timeout == 9.5
         assert settings.opencode_workspace_root == "/srv/workspaces/alpha"
         assert settings.a2a_max_request_body_bytes == 2048
         assert settings.a2a_cancel_abort_timeout_seconds == 0.75