opencode-a2a 0.4.0__tar.gz → 0.5.0__tar.gz

{opencode_a2a-0.4.0/src/opencode_a2a.egg-info → opencode_a2a-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a
-Version: 0.4.0
+Version: 0.5.0
 Summary: OpenCode A2A runtime
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -20,10 +20,12 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: a2a-sdk==0.3.25
+Requires-Dist: aiosqlite<1.0,>=0.20
 Requires-Dist: fastapi<1.0,>=0.110
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic<3.0,>=2.6
 Requires-Dist: pydantic-settings<3.0,>=2.2
+Requires-Dist: sqlalchemy<3.0,>=2.0
 Requires-Dist: sse-starlette<4.0,>=2.1
 Requires-Dist: uvicorn<1.0,>=0.29
 Provides-Extra: dev
@@ -115,7 +117,7 @@ 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 serve
+opencode-a2a
 ```
 
 Verify that the service is up:

{opencode_a2a-0.4.0 → opencode_a2a-0.5.0}/README.md

@@ -77,7 +77,7 @@ 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 serve
+opencode-a2a
 ```
 
 Verify that the service is up:

{opencode_a2a-0.4.0 → opencode_a2a-0.5.0}/docs/guide.md

@@ -55,10 +55,10 @@ Key variables to understand protocol behavior:
   also logged with preview truncation controlled by `A2A_LOG_BODY_LIMIT`.
 - `A2A_MAX_REQUEST_BODY_BYTES`: runtime request-body limit. Oversized requests
   return HTTP `413`.
-- `A2A_SESSION_CACHE_TTL_SECONDS` / `A2A_SESSION_CACHE_MAXSIZE`: session cache
-  behavior for `(identity, contextId) -> session_id`.
+- `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
-  in-memory interrupt request binding cache used by `a2a.interrupt.*`
+  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,
@@ -76,6 +76,12 @@ Key variables to understand protocol behavior:
 - `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_SUPPORTED_TRANSPORTS`: ordered outbound transport preference list.
+- `A2A_TASK_STORE_BACKEND`: runtime state backend. Supported values: `database`,
+  `memory`. Default: `database`.
+- `A2A_TASK_STORE_DATABASE_URL`: database URL used by the default durable
+  backend. Default: `sqlite+aiosqlite:///./opencode-a2a.db`.
+- `A2A_TASK_STORE_TABLE_NAME` / `A2A_TASK_STORE_CREATE_TABLE`: database task
+  store table name and whether to auto-create database tables on startup.
 - Runtime authentication is bearer-token only via `A2A_BEARER_TOKEN`.
 - The same outbound client flags are also honored by the server-side embedded
   A2A client used for peer calls and `a2a_call` tool execution:
@@ -154,7 +160,31 @@ 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 serve
+opencode-a2a
+```
+
+By default, the service uses a SQLite-backed durable state store:
+
+```bash
+OPENCODE_BASE_URL=http://127.0.0.1:4096 \
+A2A_BEARER_TOKEN=dev-token \
+A2A_TASK_STORE_DATABASE_URL=sqlite+aiosqlite:///./opencode-a2a.db \
+opencode-a2a
+```
+
+With the default `database` backend, the service persists:
+
+- task records
+- session binding / ownership state
+- interrupt request bindings and tombstones
+
+In-flight asyncio locks, outbound A2A client caches, and stream-local
+aggregation buffers remain process-local runtime state.
+
+To opt into an ephemeral development profile, set:
+
+```bash
+A2A_TASK_STORE_BACKEND=memory
 ```
 
 ## Troubleshooting Provider Auth State
@@ -825,8 +855,8 @@ Notes:
 
 - `request_id` must be a live interrupt request observed from stream metadata
   (`metadata.shared.interrupt.request_id`).
-- The server keeps an in-memory interrupt binding cache; callbacks with unknown
-  or expired `request_id` are rejected.
+- The server keeps an interrupt binding registry; callbacks with unknown or
+  expired `request_id` are rejected.
 - The cache retention windows are controlled by
   `A2A_INTERRUPT_REQUEST_TTL_SECONDS` (default: `10800` seconds / `180`
   minutes) and `A2A_INTERRUPT_REQUEST_TOMBSTONE_TTL_SECONDS` (default: `600`

{opencode_a2a-0.4.0 → opencode_a2a-0.5.0}/pyproject.toml

@@ -25,10 +25,12 @@ classifiers = [
 ]
 dependencies = [
     "a2a-sdk==0.3.25",
+    "aiosqlite>=0.20,<1.0",
     "fastapi>=0.110,<1.0",
     "httpx>=0.27,<1.0",
     "pydantic>=2.6,<3.0",
     "pydantic-settings>=2.2,<3.0",
+    "sqlalchemy>=2.0,<3.0",
     "sse-starlette>=2.1,<4.0",
     "uvicorn>=0.29,<1.0",
 ]

{opencode_a2a-0.4.0 → opencode_a2a-0.5.0}/src/opencode_a2a/cli.py

@@ -53,7 +53,8 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="opencode-a2a",
         description=(
-            "OpenCode A2A runtime. Deployment supervision is intentionally left to the operator."
+            "OpenCode A2A runtime. Run without a subcommand to start the service."
+            " Deployment supervision is intentionally left to the operator."
         ),
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
@@ -64,11 +65,6 @@ def build_parser() -> argparse.ArgumentParser:
     )
 
     subparsers = parser.add_subparsers(dest="command")
-    subparsers.add_parser(
-        "serve",
-        help="Start the OpenCode A2A runtime using environment-based settings.",
-        description="Start the OpenCode A2A runtime using environment-based settings.",
-    )
 
     call_parser = subparsers.add_parser(
         "call",
@@ -95,10 +91,6 @@ def main(argv: Sequence[str] | None = None) -> int:
         return 0
 
     namespace = parser.parse_args(args)
-    if namespace.command == "serve":
-        serve_main()
-        return 0
-
     if namespace.command == "call":
         return asyncio.run(run_call(namespace.agent_url, namespace.text, namespace.token))
 

{opencode_a2a-0.4.0 → opencode_a2a-0.5.0}/src/opencode_a2a/client/__init__.py

@@ -10,7 +10,6 @@ from .errors import (
     A2AUnsupportedBindingError,
     A2AUnsupportedOperationError,
 )
-from .types import A2AClientEvent, A2AClientEventStream, A2AClientMetadata
 
 __all__ = [
     "A2AClient",
@@ -21,8 +20,5 @@ __all__ = [
     "A2AUnsupportedBindingError",
     "A2AUnsupportedOperationError",
     "A2AClientSettings",
-    "A2AClientEvent",
-    "A2AClientEventStream",
-    "A2AClientMetadata",
     "load_settings",
 ]

opencode_a2a-0.5.0/src/opencode_a2a/client/agent_card.py

@@ -0,0 +1,81 @@
+"""Helpers for agent-card URL normalization and resolver bootstrap."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx
+from a2a.client.card_resolver import A2ACardResolver
+from a2a.utils.constants import (
+    AGENT_CARD_WELL_KNOWN_PATH,
+    EXTENDED_AGENT_CARD_PATH,
+    PREV_AGENT_CARD_WELL_KNOWN_PATH,
+)
+
+from .request_context import build_default_headers
+
+
+def normalize_agent_card_endpoint(agent_url: str) -> tuple[str, str]:
+    parsed_url = urlsplit(agent_url)
+    if not parsed_url.scheme or not parsed_url.netloc:
+        raise ValueError(f"agent_url must be absolute URL: {agent_url}")
+
+    path = parsed_url.path or ""
+    normalized_no_leading = path.rstrip("/").lstrip("/")
+    candidate_paths = (
+        AGENT_CARD_WELL_KNOWN_PATH,
+        PREV_AGENT_CARD_WELL_KNOWN_PATH,
+        EXTENDED_AGENT_CARD_PATH,
+    )
+
+    base_path = normalized_no_leading
+    agent_card_path = AGENT_CARD_WELL_KNOWN_PATH
+    for candidate_path in candidate_paths:
+        card_suffix = candidate_path.lstrip("/")
+        if normalized_no_leading.endswith(card_suffix):
+            base_path = normalized_no_leading[: -len(card_suffix)].rstrip("/")
+            agent_card_path = candidate_path
+            break
+
+    base_url = urlunsplit(
+        (
+            parsed_url.scheme,
+            parsed_url.netloc,
+            f"/{base_path}" if base_path else "",
+            "",
+            "",
+        )
+    ).rstrip("/")
+    return base_url, agent_card_path
+
+
+def build_agent_card_resolver(
+    agent_url: str,
+    httpx_client: httpx.AsyncClient,
+) -> A2ACardResolver:
+    base_url, agent_card_path = normalize_agent_card_endpoint(agent_url)
+    return A2ACardResolver(
+        httpx_client=httpx_client,
+        base_url=base_url,
+        agent_card_path=agent_card_path,
+    )
+
+
+def build_resolver_http_kwargs(
+    *,
+    bearer_token: str | None,
+    timeout: float,
+) -> dict[str, Any]:
+    http_kwargs: dict[str, Any] = {"timeout": timeout}
+    default_headers = build_default_headers(bearer_token)
+    if default_headers:
+        http_kwargs["headers"] = default_headers
+    return http_kwargs
+
+
+__all__ = [
+    "build_agent_card_resolver",
+    "build_resolver_http_kwargs",
+    "normalize_agent_card_endpoint",
+]

opencode_a2a-0.5.0/src/opencode_a2a/client/client.py

@@ -0,0 +1,317 @@
+"""A2A client facade for opencode-a2a consumers."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Mapping
+from typing import Any, cast
+from uuid import uuid4
+
+import httpx
+from a2a.client import Client, ClientConfig, ClientFactory
+from a2a.client.errors import (
+    A2AClientHTTPError,
+    A2AClientJSONError,
+    A2AClientJSONRPCError,
+)
+from a2a.types import (
+    Message,
+    Part,
+    Role,
+    Task,
+    TaskArtifactUpdateEvent,
+    TaskIdParams,
+    TaskQueryParams,
+    TaskStatusUpdateEvent,
+    TextPart,
+)
+
+from .agent_card import build_agent_card_resolver, build_resolver_http_kwargs
+from .config import A2AClientSettings, load_settings
+from .error_mapping import (
+    map_agent_card_error,
+    map_operation_error,
+)
+from .errors import A2AUnsupportedBindingError
+from .payload_text import extract_text as extract_text_from_payload
+from .request_context import build_call_context, build_client_interceptors, split_request_metadata
+
+
+class A2AClient:
+    """Factory-style facade for lightweight A2A client bootstrap and calls."""
+
+    def __init__(
+        self,
+        agent_url: str,
+        *,
+        settings: A2AClientSettings | None = None,
+        httpx_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not agent_url or not agent_url.strip():
+            raise ValueError("agent_url must be non-empty")
+        self.agent_url = agent_url.rstrip("/")
+        self._settings = settings or load_settings({})
+        self._owns_httpx_client = httpx_client is None
+        self._httpx_client = httpx_client
+        self._client: Client | None = None
+        self._agent_card: object | None = None
+        self._lock = asyncio.Lock()
+        self._request_lock = asyncio.Lock()
+        self._active_requests = 0
+
+    async def close(self) -> None:
+        """Close cached client resources and owned HTTP transport."""
+        self._client = None
+        if self._httpx_client is not None and self._owns_httpx_client:
+            await self._httpx_client.aclose()
+
+    def is_busy(self) -> bool:
+        """Report whether this facade currently has in-flight work."""
+        return self._active_requests > 0
+
+    async def get_agent_card(self) -> Any:
+        """Fetch and cache peer Agent Card."""
+        if self._agent_card is not None:
+            return self._agent_card
+
+        resolver = build_agent_card_resolver(
+            self.agent_url,
+            await self._get_httpx_client(),
+        )
+        try:
+            card = await resolver.get_agent_card(
+                http_kwargs=build_resolver_http_kwargs(
+                    bearer_token=self._settings.bearer_token,
+                    timeout=self._settings.card_fetch_timeout,
+                )
+            )
+        except (
+            A2AClientHTTPError,
+            A2AClientJSONError,
+            httpx.TimeoutException,
+            httpx.TransportError,
+        ) as exc:
+            raise map_agent_card_error(exc) from exc
+        self._agent_card = card
+        return card
+
+    async def send_message(
+        self,
+        text: str,
+        *,
+        context_id: str | None = None,
+        task_id: str | None = None,
+        message_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        extensions: list[str] | None = None,
+    ) -> AsyncIterator[
+        Message | tuple[Task, TaskStatusUpdateEvent | TaskArtifactUpdateEvent | None] | None
+    ]:
+        """Send one user message and stream protocol events."""
+        await self._acquire_operation()
+        try:
+            client = await self._ensure_client()
+            request_metadata, extra_headers = split_request_metadata(metadata)
+            request = self._build_user_message(
+                text=text,
+                context_id=context_id,
+                task_id=task_id,
+                message_id=message_id,
+            )
+            try:
+                async for event in client.send_message(
+                    request,
+                    context=build_call_context(self._settings.bearer_token, extra_headers),
+                    request_metadata=request_metadata,
+                    extensions=extensions,
+                ):
+                    yield event
+            except (
+                A2AClientHTTPError,
+                A2AClientJSONRPCError,
+                httpx.TimeoutException,
+                httpx.TransportError,
+            ) as exc:
+                raise map_operation_error("message/send", exc) from exc
+        finally:
+            await self._release_operation()
+
+    async def send(
+        self,
+        text: str,
+        *,
+        context_id: str | None = None,
+        task_id: str | None = None,
+        message_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        extensions: list[str] | None = None,
+    ) -> Message | tuple[Task, TaskStatusUpdateEvent | TaskArtifactUpdateEvent | None] | None:
+        """Send a message and return the terminal response/event."""
+        last_event: (
+            Message | tuple[Task, TaskStatusUpdateEvent | TaskArtifactUpdateEvent | None] | None
+        ) = None
+        async for event in self.send_message(
+            text,
+            context_id=context_id,
+            task_id=task_id,
+            message_id=message_id,
+            metadata=metadata,
+            extensions=extensions,
+        ):
+            last_event = event
+        return last_event
+
+    async def get_task(
+        self,
+        task_id: str,
+        *,
+        history_length: int | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Task:
+        """Fetch one task by id."""
+        await self._acquire_operation()
+        try:
+            client = await self._ensure_client()
+            request_metadata, extra_headers = split_request_metadata(metadata)
+            try:
+                return await client.get_task(
+                    TaskQueryParams(
+                        id=task_id,
+                        history_length=history_length,
+                        metadata=request_metadata or {},
+                    ),
+                    context=build_call_context(self._settings.bearer_token, extra_headers),
+                )
+            except (
+                A2AClientHTTPError,
+                A2AClientJSONRPCError,
+                httpx.TimeoutException,
+                httpx.TransportError,
+            ) as exc:
+                raise map_operation_error("tasks/get", exc) from exc
+        finally:
+            await self._release_operation()
+
+    async def cancel_task(
+        self,
+        task_id: str,
+        *,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Task:
+        """Cancel one task by id."""
+        await self._acquire_operation()
+        try:
+            client = await self._ensure_client()
+            request_metadata, extra_headers = split_request_metadata(metadata)
+            try:
+                return await client.cancel_task(
+                    TaskIdParams(id=task_id, metadata=request_metadata or {}),
+                    context=build_call_context(self._settings.bearer_token, extra_headers),
+                )
+            except (
+                A2AClientHTTPError,
+                A2AClientJSONRPCError,
+                httpx.TimeoutException,
+                httpx.TransportError,
+            ) as exc:
+                raise map_operation_error("tasks/cancel", exc) from exc
+        finally:
+            await self._release_operation()
+
+    async def resubscribe_task(
+        self,
+        task_id: str,
+        *,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> AsyncIterator[tuple[Task, TaskStatusUpdateEvent | TaskArtifactUpdateEvent | None]]:
+        """Resubscribe to task updates."""
+        await self._acquire_operation()
+        try:
+            client = await self._ensure_client()
+            request_metadata, extra_headers = split_request_metadata(metadata)
+            try:
+                async for event in client.resubscribe(
+                    TaskIdParams(id=task_id, metadata=request_metadata or {}),
+                    context=build_call_context(self._settings.bearer_token, extra_headers),
+                ):
+                    yield event
+            except (
+                A2AClientHTTPError,
+                A2AClientJSONRPCError,
+                httpx.TimeoutException,
+                httpx.TransportError,
+            ) as exc:
+                raise map_operation_error("tasks/resubscribe", exc) from exc
+        finally:
+            await self._release_operation()
+
+    async def _ensure_client(self) -> Client:
+        async with self._lock:
+            if self._client is not None:
+                return self._client
+            return await self._build_client()
+
+    async def _build_client(self) -> Client:
+        card = await self.get_agent_card()
+        config = ClientConfig(
+            streaming=True,
+            polling=False,
+            httpx_client=await self._get_httpx_client(),
+            supported_transports=list(self._settings.supported_transports),
+            use_client_preference=self._settings.use_client_preference,
+        )
+        try:
+            factory = ClientFactory(config, consumers=None)
+            client = factory.create(
+                card,
+                interceptors=build_client_interceptors(self._settings.bearer_token),
+            )
+        except ValueError as exc:
+            raise A2AUnsupportedBindingError(
+                f"No supported transport found for {self.agent_url}"
+            ) from exc
+        self._client = client
+        return client
+
+    async def _get_httpx_client(self) -> httpx.AsyncClient:
+        if self._httpx_client is not None:
+            return self._httpx_client
+        self._httpx_client = httpx.AsyncClient(timeout=self._settings.default_timeout)
+        return self._httpx_client
+
+    async def _acquire_operation(self) -> None:
+        async with self._request_lock:
+            self._active_requests += 1
+
+    async def _release_operation(self) -> None:
+        async with self._request_lock:
+            if self._active_requests > 0:
+                self._active_requests -= 1
+
+    def _build_user_message(
+        self,
+        *,
+        text: str,
+        context_id: str | None,
+        task_id: str | None,
+        message_id: str | None,
+    ) -> Message:
+        return Message(
+            role=Role.user,
+            message_id=message_id or str(uuid4()),
+            context_id=context_id,
+            task_id=task_id,
+            parts=self._normalize_parts(text),
+            metadata=None,
+        )
+
+    @classmethod
+    def extract_text(cls, payload: Any) -> str | None:
+        return extract_text_from_payload(payload)
+
+    # keep parts construction explicitly typed for mypy compatibility in older stubs
+    def _normalize_parts(self, text: str) -> list[Part]:
+        return [cast(Part, TextPart(text=text))]
+
+
+__all__ = ["A2AClient"]