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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opencode-a2a
-Version: 0.4.0
+Version: 0.4.1
 Summary: OpenCode A2A runtime
 Author: liujuanjuan1984@Intelligent-Internet
 License-Expression: Apache-2.0
@@ -115,7 +115,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.4.1}/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.4.1}/docs/guide.md

@@ -154,7 +154,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
 ```
 
 ## Troubleshooting Provider Auth State

{opencode_a2a-0.4.0 → opencode_a2a-0.4.1}/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.4.1}/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.4.1/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.4.1/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"]

opencode_a2a-0.4.1/src/opencode_a2a/client/error_mapping.py

@@ -0,0 +1,148 @@
+"""Centralized error mapping for outbound A2A client operations."""
+
+from __future__ import annotations
+
+import httpx
+from a2a.client.errors import A2AClientHTTPError, A2AClientJSONError, A2AClientJSONRPCError
+
+from .errors import (
+    A2AAgentUnavailableError,
+    A2AAuthenticationError,
+    A2AClientError,
+    A2AClientResetRequiredError,
+    A2APeerProtocolError,
+    A2APermissionDeniedError,
+    A2ATimeoutError,
+    A2AUnsupportedOperationError,
+)
+
+
+def _attach_http_status(error: A2AClientError, status: int | None) -> A2AClientError:
+    error.http_status = status
+    return error
+
+
+def _extract_jsonrpc_error_payload(
+    exc: A2AClientJSONRPCError,
+) -> tuple[str | None, int | None, object]:
+    error = getattr(exc, "error", None)
+    if error is None:
+        return None, None, None
+    return (
+        getattr(error, "message", None),
+        getattr(error, "code", None),
+        getattr(error, "data", None),
+    )
+
+
+def map_jsonrpc_error(exc: A2AClientJSONRPCError) -> A2AClientError:
+    _message, code, data = _extract_jsonrpc_error_payload(exc)
+    if code == -32601:
+        parsed_error = A2AUnsupportedOperationError(
+            "Remote A2A peer does not support the requested operation"
+        )
+        parsed_error.error_code = "method_not_supported"
+        parsed_error.code = code
+        parsed_error.data = data
+        return parsed_error
+    if code == -32602:
+        return A2APeerProtocolError(
+            "Remote A2A peer rejected the request payload",
+            error_code="invalid_params",
+            rpc_code=code,
+            data=data,
+        )
+    if code == -32603:
+        reset_required = A2AClientResetRequiredError(
+            "Remote A2A peer entered an unstable state and requires a fresh client session"
+        )
+        reset_required.code = code
+        reset_required.data = data
+        return reset_required
+    return A2APeerProtocolError(
+        "Remote A2A peer returned a protocol error",
+        error_code="peer_protocol_error",
+        rpc_code=code,
+        data=data,
+    )
+
+
+def map_http_error(operation: str, exc: A2AClientHTTPError) -> A2AClientError:
+    status = exc.status_code
+    if status == 401:
+        return _attach_http_status(
+            A2AAuthenticationError(
+                f"Remote A2A peer rejected {operation} due to authentication failure"
+            ),
+            status,
+        )
+    if status == 403:
+        return _attach_http_status(
+            A2APermissionDeniedError(
+                f"Remote A2A peer rejected {operation} due to insufficient permissions"
+            ),
+            status,
+        )
+    if status in {404, 405, 409, 501}:
+        return _attach_http_status(
+            A2AUnsupportedOperationError(f"Remote A2A peer does not support {operation}"),
+            status,
+        )
+    if status == 408:
+        return _attach_http_status(
+            A2ATimeoutError(f"Remote A2A peer timed out during {operation}"),
+            status,
+        )
+    if status in {429, 502, 503, 504}:
+        return _attach_http_status(
+            A2AClientResetRequiredError(
+                f"Remote A2A peer is temporarily unstable during {operation}"
+            ),
+            status,
+        )
+    return _attach_http_status(
+        A2AAgentUnavailableError(f"Remote A2A peer is unavailable for {operation}"),
+        status,
+    )
+
+
+def map_transport_error(
+    operation: str,
+    exc: httpx.TimeoutException | httpx.TransportError,
+) -> A2AClientError:
+    if isinstance(exc, httpx.TimeoutException):
+        return A2ATimeoutError(f"Remote A2A peer timed out during {operation}")
+    return A2AAgentUnavailableError(f"Remote A2A peer is unreachable for {operation}")
+
+
+def map_operation_error(
+    operation: str,
+    exc: A2AClientHTTPError | A2AClientJSONRPCError | httpx.TimeoutException | httpx.TransportError,
+) -> A2AClientError:
+    if isinstance(exc, A2AClientHTTPError):
+        return map_http_error(operation, exc)
+    if isinstance(exc, A2AClientJSONRPCError):
+        return map_jsonrpc_error(exc)
+    return map_transport_error(operation, exc)
+
+
+def map_agent_card_error(
+    exc: A2AClientHTTPError | A2AClientJSONError | httpx.TimeoutException | httpx.TransportError,
+) -> A2AClientError:
+    if isinstance(exc, A2AClientHTTPError):
+        return map_http_error("agent-card/fetch", exc)
+    if isinstance(exc, A2AClientJSONError):
+        return A2APeerProtocolError(
+            "Remote A2A peer returned an invalid agent card payload",
+            error_code="invalid_agent_card",
+        )
+    return map_transport_error("agent-card/fetch", exc)
+
+
+__all__ = [
+    "map_agent_card_error",
+    "map_http_error",
+    "map_jsonrpc_error",
+    "map_operation_error",
+    "map_transport_error",
+]

{opencode_a2a-0.4.0 → opencode_a2a-0.4.1}/src/opencode_a2a/client/errors.py

@@ -18,12 +18,30 @@ class A2AAgentUnavailableError(A2AClientError):
     error_code = "agent_unavailable"
 
 
+class A2AAuthenticationError(A2AClientError):
+    """Raised when a remote A2A peer rejects authentication."""
+
+    error_code = "authentication_failed"
+
+
+class A2APermissionDeniedError(A2AClientError):
+    """Raised when a remote A2A peer rejects authorization."""
+
+    error_code = "permission_denied"
+
+
 class A2AClientResetRequiredError(A2AAgentUnavailableError):
     """Raised when the cached transport should be rebuilt."""
 
     error_code = "reset_required"
 
 
+class A2ATimeoutError(A2AAgentUnavailableError):
+    """Raised when an outbound call to a remote A2A peer times out."""
+
+    error_code = "timeout"
+
+
 class A2AUnsupportedBindingError(A2AClientError):
     """Raised when local and remote transport configuration has no overlap."""
 
@@ -58,7 +76,10 @@ class A2APeerProtocolError(A2AClientError):
 __all__ = [
     "A2AClientError",
     "A2AAgentUnavailableError",
+    "A2AAuthenticationError",
+    "A2APermissionDeniedError",
     "A2AClientResetRequiredError",
+    "A2ATimeoutError",
     "A2AUnsupportedBindingError",
     "A2AUnsupportedOperationError",
     "A2APeerProtocolError",