uclone-x 0.1.0__py3-none-any.whl

uclone_x/__init__.py

@@ -0,0 +1,5 @@
+"""UClone-X: Next-Generation Event-Driven AI Agent Core & Collaboration Framework."""
+
+__version__ = "0.1.0"
+__author__ = "Kenny Lim <kennylim@uclone.net>"
+__all__ = ["__version__"]

uclone_x/a2a/__init__.py

@@ -0,0 +1,31 @@
+"""Google A2A v1.0.1 subsystem: Discovery, local fastpath, and remote REST/SSE wire protocol."""
+
+from uclone_x.a2a.discovery import A2ADiscoveryService
+from uclone_x.a2a.http_transport import A2AHttpTransport
+from uclone_x.a2a.in_memory import A2AInMemoryTransport
+from uclone_x.a2a.models import (
+    AgentCard,
+    TaskMessage,
+    TaskResult,
+    TaskStatus,
+    WireProtocolType,
+)
+from uclone_x.a2a.protocols import (
+    A2ADiscoveryProtocol,
+    A2ATransportProtocol,
+)
+from uclone_x.a2a.server import A2AServer
+
+__all__ = [
+    "A2ADiscoveryProtocol",
+    "A2ADiscoveryService",
+    "A2AHttpTransport",
+    "A2AInMemoryTransport",
+    "A2AServer",
+    "A2ATransportProtocol",
+    "AgentCard",
+    "TaskMessage",
+    "TaskResult",
+    "TaskStatus",
+    "WireProtocolType",
+]

uclone_x/a2a/discovery.py

@@ -0,0 +1,71 @@
+"""A2A discovery service for publishing and discovering Agent Cards per RFC 8615."""
+
+from __future__ import annotations
+
+import httpx
+
+from uclone_x.a2a.models import AgentCard
+from uclone_x.errors import (
+    InvalidAgentResponseError,
+    TaskNotFoundError,
+)
+
+
+class A2ADiscoveryService:
+    """Service for discovering and publishing Agent Cards per RFC 8615."""
+
+    def __init__(
+        self,
+        local_agent_card: AgentCard | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._local_card = local_agent_card or AgentCard(
+            name="uclone-x-agent",
+            description="UClone-X Default Agent",
+            version="1.0.1",
+        )
+        self._http_client = http_client
+
+    def get_local_agent_card(self) -> AgentCard:
+        """Export local agent capabilities."""
+        return self._local_card
+
+    def set_local_agent_card(self, card: AgentCard) -> None:
+        """Update the local agent card."""
+        self._local_card = card
+
+    async def fetch_remote_agent_card(self, endpoint_url: str) -> AgentCard:
+        """Fetch /.well-known/agent-card.json from remote peer per RFC 8615."""
+        url = endpoint_url.strip()
+        if not url.endswith("/.well-known/agent-card.json"):
+            url = f"{url.rstrip('/')}/.well-known/agent-card.json"
+
+        client = self._http_client or httpx.AsyncClient()
+        should_close = self._http_client is None
+        try:
+            resp = await client.get(
+                url,
+                headers={"A2A-Version": "1.0", "Accept": "application/json"},
+                timeout=10.0,
+            )
+            if resp.status_code == 404:
+                raise TaskNotFoundError(f"Agent card not found at {url}")
+            if resp.status_code != 200:
+                raise InvalidAgentResponseError(
+                    f"Failed to fetch agent card from {url}: HTTP {resp.status_code}"
+                )
+            try:
+                return AgentCard.model_validate_json(resp.text)
+            except Exception as exc:
+                raise InvalidAgentResponseError(
+                    f"Invalid AgentCard payload from {url}: {exc}"
+                ) from exc
+        except (TaskNotFoundError, InvalidAgentResponseError):
+            raise
+        except Exception as exc:
+            raise InvalidAgentResponseError(
+                f"Network error fetching agent card from {url}: {exc}"
+            ) from exc
+        finally:
+            if should_close:
+                await client.aclose()

uclone_x/a2a/http_transport.py

@@ -0,0 +1,204 @@
+"""A2A remote HTTP REST/SSE wire transport conforming to A2ATransportProtocol and A2ADiscoveryProtocol."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, cast
+
+import httpx
+
+from uclone_x.a2a.discovery import A2ADiscoveryService
+from uclone_x.a2a.models import (
+    AgentCard,
+    TaskMessage,
+    TaskResult,
+    WireProtocolType,
+)
+from uclone_x.a2a.wire import task_message_to_wire, task_result_from_wire_json
+from uclone_x.errors import (
+    A2AError,
+    InvalidAgentResponseError,
+    MissingProvenanceError,
+    TaskNotFoundError,
+    UnsupportedOperationError,
+    VersionNotSupportedError,
+)
+
+
+class A2AHttpTransport:
+    """Remote REST/SSE transport for distributed A2A communication."""
+
+    def __init__(
+        self,
+        http_client: httpx.AsyncClient | None = None,
+        default_agent_card: AgentCard | None = None,
+        discovery_service: A2ADiscoveryService | None = None,
+    ) -> None:
+        self._http_client = http_client
+        self._discovery = discovery_service or A2ADiscoveryService(
+            local_agent_card=default_agent_card,
+            http_client=http_client,
+        )
+
+    @property
+    def transport_type(self) -> WireProtocolType:
+        """Transport mechanism identifier."""
+        return WireProtocolType.REST_SSE
+
+    def get_local_agent_card(self) -> AgentCard:
+        """Export local agent capabilities."""
+        return self._discovery.get_local_agent_card()
+
+    def set_local_agent_card(self, card: AgentCard) -> None:
+        """Update local agent capabilities."""
+        self._discovery.set_local_agent_card(card)
+
+    async def fetch_remote_agent_card(self, endpoint_url: str) -> AgentCard:
+        """Fetch remote /.well-known/agent-card.json per RFC 8615."""
+        return await self._discovery.fetch_remote_agent_card(endpoint_url)
+
+    async def send_task(self, target_endpoint: str, message: TaskMessage) -> TaskResult:
+        """Dispatch task to remote agent over HTTP REST."""
+        url = target_endpoint.strip()
+        if not (
+            url.endswith("/message:send") or url.endswith("/tasks/send") or url.endswith("/tasks")
+        ):
+            url = f"{url.rstrip('/')}/message:send"
+
+        client = self._http_client or httpx.AsyncClient()
+        should_close = self._http_client is None
+        try:
+            resp = await client.post(
+                url,
+                headers={
+                    "A2A-Version": "1.0",
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
+                json=task_message_to_wire(message),
+                timeout=30.0,
+            )
+            if resp.status_code == 404:
+                err_msg = f"Endpoint or task not found at {url}"
+                try:
+                    raw_err = resp.json()
+                    if isinstance(raw_err, dict):
+                        raw_dict: dict[str, Any] = cast(dict[str, Any], raw_err)
+                        detail = raw_dict.get("detail")
+                        if isinstance(detail, dict) and "message" in detail:
+                            detail_dict: dict[str, Any] = cast(dict[str, Any], detail)
+                            err_msg = str(detail_dict["message"])
+                        elif isinstance(detail, str):
+                            err_msg = detail
+                        elif "message" in raw_dict:
+                            err_msg = str(raw_dict["message"])
+                except Exception:
+                    pass
+                raise TaskNotFoundError(err_msg)
+            if resp.status_code == 400:
+                try:
+                    err_obj = resp.json()
+                    if isinstance(err_obj, dict):
+                        err_dict: dict[str, Any] = cast(dict[str, Any], err_obj)
+                        detail_obj = err_dict.get("detail")
+                        detail_dict: dict[str, Any] = (
+                            cast(dict[str, Any], detail_obj) if isinstance(detail_obj, dict) else {}
+                        )
+                        err_name = err_dict.get("error") or detail_dict.get("error")
+                        err_type = str(err_name or "")
+                        if err_type == "VersionNotSupportedError":
+                            raise VersionNotSupportedError(
+                                f"A2A version not supported by {url}: {resp.text}"
+                            )
+                except (VersionNotSupportedError, TaskNotFoundError):
+                    raise
+                except Exception:
+                    pass
+                raise UnsupportedOperationError(f"Bad request sent to {url}: HTTP 400 {resp.text}")
+            if resp.status_code != 200:
+                raise InvalidAgentResponseError(
+                    f"Remote agent returned error {resp.status_code}: {resp.text}"
+                )
+
+            result = task_result_from_wire_json(resp.text)
+            if result.provenance is None:
+                raise MissingProvenanceError(
+                    f"Remote agent response from {url} is missing provenance (P6)"
+                )
+            return result
+        except (A2AError, MissingProvenanceError):
+            raise
+        except Exception as exc:
+            raise InvalidAgentResponseError(
+                f"Network or protocol error communicating with {url}: {exc}"
+            ) from exc
+        finally:
+            if should_close:
+                await client.aclose()
+
+    def stream_task(
+        self,
+        target_endpoint: str,
+        message: TaskMessage,
+    ) -> AsyncIterator[str]:
+        """Stream task results via remote SSE stream."""
+        url = target_endpoint.strip()
+        if not (url.endswith("/message:stream") or url.endswith("/tasks/stream")):
+            url = f"{url.rstrip('/')}/message:stream"
+
+        async def _stream_generator() -> AsyncIterator[str]:
+            client = self._http_client or httpx.AsyncClient()
+            should_close = self._http_client is None
+            try:
+                async with client.stream(
+                    "POST",
+                    url,
+                    headers={
+                        "A2A-Version": "1.0",
+                        "Content-Type": "application/json",
+                        "Accept": "text/event-stream",
+                    },
+                    json=task_message_to_wire(message),
+                    timeout=30.0,
+                ) as resp:
+                    if resp.status_code == 404:
+                        err_msg = f"Endpoint or task not found at {url}"
+                        try:
+                            body = await resp.aread()
+                            import json
+
+                            raw_err: object = json.loads(body)
+                            if isinstance(raw_err, dict):
+                                err_dict: dict[str, object] = cast(dict[str, object], raw_err)
+                                detail_val = err_dict.get("detail")
+                                if isinstance(detail_val, dict):
+                                    detail_d: dict[str, object] = cast(
+                                        dict[str, object], detail_val
+                                    )
+                                    if "message" in detail_d:
+                                        err_msg = str(detail_d["message"])
+                                elif isinstance(detail_val, str):
+                                    err_msg = detail_val
+                                elif "message" in err_dict:
+                                    err_msg = str(err_dict["message"])
+                        except Exception:
+                            pass
+                        raise TaskNotFoundError(err_msg)
+                    if resp.status_code != 200:
+                        raise InvalidAgentResponseError(
+                            f"Remote agent returned streaming error {resp.status_code}"
+                        )
+                    async for line in resp.aiter_lines():
+                        if line:
+                            yield line
+            except (A2AError, MissingProvenanceError):
+                raise
+            except Exception as exc:
+                raise InvalidAgentResponseError(
+                    f"Network error during stream from {url}: {exc}"
+                ) from exc
+            finally:
+                if should_close:
+                    await client.aclose()
+
+        return _stream_generator()

uclone_x/a2a/in_memory.py

@@ -0,0 +1,100 @@
+"""In-memory zero-copy fastpath transport for co-located A2A agents."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+
+from uclone_x.a2a.models import TaskMessage, TaskResult, WireProtocolType
+from uclone_x.a2a.wire import task_result_to_wire_json
+from uclone_x.errors import (
+    MissingProvenanceError,
+    TaskNotFoundError,
+)
+
+TaskHandler = Callable[[TaskMessage], Awaitable[TaskResult]]
+StreamHandler = Callable[[TaskMessage], AsyncIterator[str]]
+
+
+class A2AInMemoryTransport:
+    """Zero-copy in-memory transport for co-located agents within the same process."""
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, TaskHandler] = {}
+        self._stream_handlers: dict[str, StreamHandler] = {}
+
+    @property
+    def transport_type(self) -> WireProtocolType:
+        """Transport mechanism identifier."""
+        return WireProtocolType.LOCAL_IN_MEMORY
+
+    def register_handler(
+        self,
+        endpoint_or_agent_id: str,
+        handler: TaskHandler,
+    ) -> None:
+        """Register a direct async task handler for an endpoint or agent id."""
+        self._handlers[endpoint_or_agent_id] = handler
+
+    def register_stream_handler(
+        self,
+        endpoint_or_agent_id: str,
+        handler: StreamHandler,
+    ) -> None:
+        """Register a streaming task handler for an endpoint or agent id."""
+        self._stream_handlers[endpoint_or_agent_id] = handler
+
+    def unregister_handler(self, endpoint_or_agent_id: str) -> None:
+        """Unregister handlers associated with an endpoint or agent id."""
+        self._handlers.pop(endpoint_or_agent_id, None)
+        self._stream_handlers.pop(endpoint_or_agent_id, None)
+
+    async def send_task(self, target_endpoint: str, message: TaskMessage) -> TaskResult:
+        """Dispatch task directly to local in-process agent without network or serialization."""
+        handler = self._handlers.get(target_endpoint) or self._handlers.get(message.target_agent_id)
+        if handler is None:
+            raise TaskNotFoundError(
+                f"No in-memory handler registered for endpoint '{target_endpoint}' "
+                f"or agent '{message.target_agent_id}'"
+            )
+        result = await handler(message)
+        if result.provenance is None:
+            raise MissingProvenanceError(
+                "TaskResult returned by in-memory handler must contain in-band provenance (P6)"
+            )
+        return result
+
+    def stream_task(
+        self,
+        target_endpoint: str,
+        message: TaskMessage,
+    ) -> AsyncIterator[str]:
+        """Stream task results via in-memory generator."""
+        stream_handler = self._stream_handlers.get(target_endpoint) or self._stream_handlers.get(
+            message.target_agent_id
+        )
+        if stream_handler is not None:
+            return stream_handler(message)
+
+        handler = self._handlers.get(target_endpoint) or self._handlers.get(message.target_agent_id)
+        if handler is not None:
+
+            async def _fallback_stream() -> AsyncIterator[str]:
+                res = await handler(message)
+                if res.provenance is None:
+                    raise MissingProvenanceError(
+                        "TaskResult returned by in-memory handler must contain in-band provenance (P6)"
+                    )
+                yield task_result_to_wire_json(res)
+
+            return _fallback_stream()
+
+        async def _not_found_stream() -> AsyncIterator[str]:
+            raise TaskNotFoundError(
+                f"No in-memory handler registered for endpoint '{target_endpoint}' "
+                f"or agent '{message.target_agent_id}'"
+            )
+            # Make this an async generator function for type checkers
+            if False:  # pragma: no cover
+                yield ""
+
+        return _not_found_stream()

uclone_x/a2a/models.py

@@ -0,0 +1,76 @@
+"""Data models for Google Agent-to-Agent (A2A) protocol v1.0.1."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from uclone_x.core.immutable import ImmutableJsonMapping, ImmutableStrMapping
+from uclone_x.core.provenance import Provenance
+
+
+class WireProtocolType(StrEnum):
+    """Transport protocol type."""
+
+    LOCAL_IN_MEMORY = "local_in_memory"
+    REST_SSE = "rest_sse"
+
+
+class TaskStatus(StrEnum):
+    """Lifecycle and execution status of an A2A task per A2A v1.0.1 specification."""
+
+    SUBMITTED = "submitted"
+    WORKING = "working"
+    INPUT_REQUIRED = "input_required"
+    AUTH_REQUIRED = "auth_required"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELED = "canceled"
+    REJECTED = "rejected"
+
+
+class AgentCard(BaseModel):
+    """Agent discovery metadata exposed at /.well-known/agent-card.json per RFC 8615."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+
+    name: str
+    description: str
+    version: str = "1.0.1"
+    endpoints: ImmutableStrMapping = Field(default_factory=dict)
+    skills: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Declared skills and capabilities of the agent per A2A v1.0.1.",
+    )
+    input_schema: ImmutableJsonMapping = Field(default_factory=dict)
+    output_schema: ImmutableJsonMapping = Field(default_factory=dict)
+
+
+class TaskMessage(BaseModel):
+    """A2A task dispatch envelope."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+
+    task_id: str
+    session_id: str
+    input_data: ImmutableJsonMapping = Field(default_factory=dict)
+    sender_agent_id: str
+    target_agent_id: str
+    metadata: ImmutableStrMapping = Field(default_factory=dict)
+
+
+class TaskResult(BaseModel):
+    """A2A task response envelope."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", strict=True)
+
+    task_id: str
+    status: TaskStatus = TaskStatus.COMPLETED
+    output_data: ImmutableJsonMapping = Field(default_factory=dict)
+    error: str | None = None
+    provenance: Provenance | None = Field(
+        description="In-band attribution required by Principle 6. Explicit with no "
+        "default: `None` is representable so a non-conformant value can be rejected by "
+        "`require_provenance`, but it is never inherited silently.",
+    )

uclone_x/a2a/protocols.py

@@ -0,0 +1,62 @@
+"""Protocols for A2A dual-transport and discovery.
+
+`@runtime_checkable` is applied only where a runtime `isinstance` check is actually
+performed. On a protocol with a `@property`, `issubclass()` raises `TypeError` and
+`isinstance()` calls the object's getters as a side effect of the type test, and neither
+form checks a signature — which is what actually drifted in issue 2026-09-02-035.
+Conformance is enforced statically instead, by the bindings in
+`tests/unit/test_protocol_conformance.py`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Protocol, runtime_checkable
+
+from uclone_x.a2a.models import (
+    AgentCard,
+    TaskMessage,
+    TaskResult,
+    WireProtocolType,
+)
+
+
+@runtime_checkable
+class A2ADiscoveryProtocol(Protocol):
+    """Protocol for discovering and publishing Agent Cards."""
+
+    def get_local_agent_card(self) -> AgentCard:
+        """Export local agent capabilities."""
+        ...
+
+    async def fetch_remote_agent_card(self, endpoint_url: str) -> AgentCard:
+        """Fetch /.well-known/agent-card.json from remote peer."""
+        ...
+
+
+class A2ATransportProtocol(Protocol):
+    """Protocol for sending tasks across local zero-copy or remote REST/SSE transport."""
+
+    @property
+    def transport_type(self) -> WireProtocolType:
+        """Transport mechanism (local vs remote)."""
+        ...
+
+    async def send_task(self, target_endpoint: str, message: TaskMessage) -> TaskResult:
+        """Dispatch task to local or remote agent."""
+        ...
+
+    def stream_task(
+        self,
+        target_endpoint: str,
+        message: TaskMessage,
+    ) -> AsyncIterator[str]:
+        """Stream task results via SSE or in-memory generator.
+
+        Declared `def`, not `async def`: an async generator function *is* a plain
+        function returning an `AsyncIterator`. As `async def ... -> AsyncIterator` the
+        caller had to await the call to obtain the iterator and then iterate it, which
+        no async generator can satisfy — caught by the conformance stub in
+        `tests/unit/test_protocol_conformance.py` (issue 2026-09-02-035).
+        """
+        ...