agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/a2a/control_plane.py

@@ -21,13 +21,12 @@ from a2a.types import AgentCard
 from google.protobuf.json_format import ParseDict, ParseError
 
 from ksadk.a2a.ids import require_a2a_resource_id
+from ksadk.common.cloud_headers import build_cloud_headers
 from ksadk.common.kop_client import KOPClient, KOPError
 
-ENV_A2A_CONTROL_PLANE_URL = "KSADK_A2A_CONTROL_PLANE_URL"
-ENV_A2A_TOKEN_DIR = "KSADK_A2A_TOKEN_DIR"
-DEFAULT_A2A_TOKEN_DIR = "/var/run/secrets/agentengine/a2a"
-MAX_WORKLOAD_TOKEN_BYTES = 16 * 1024
+from ksadk.a2a.workload_tokens import ENV_A2A_TOKEN_DIR, DEFAULT_A2A_TOKEN_DIR, MAX_WORKLOAD_TOKEN_BYTES, WorkloadTokenProvider, FileWorkloadTokenProvider
 
+ENV_A2A_CONTROL_PLANE_URL = "KSADK_A2A_CONTROL_PLANE_URL"
 AUDIENCE_REGISTRY = "a2a-registry"
 AUDIENCE_TASK_SINK = "a2a-task-sink"
 AUDIENCE_CREDENTIAL_BROKER = "credential-broker"
@@ -44,9 +43,13 @@ A2A_OPERATIONS = frozenset(get_args(A2AOperation))
 A2AInternalAction = Literal[
     "ListA2ASpaceAgents",
     "PrepareA2ACall",
+    "SubmitA2AInboundMessage",
+    "CancelA2AInboundTask",
     "PrepareA2ATaskOperation",
     "BindA2ARemoteTask",
     "AppendA2ATaskEvents",
+    "AppendA2AProductKernelFacts",
+    "ListA2AProductKernelTasks",
     "ResolveA2ACredential",
 ]
 A2A_INTERNAL_ACTIONS = frozenset(get_args(A2AInternalAction))
@@ -87,95 +90,6 @@ class A2AControlPlaneError(RuntimeError):
         self.action = action
 
 
-class WorkloadTokenProvider(ABC):
-    """Returns a short-lived workload token for one exact audience."""
-
-    @abstractmethod
-    def get_token(self, audience: str) -> str:
-        raise NotImplementedError
-
-
-class FileWorkloadTokenProvider(WorkloadTokenProvider):
-    """Reads audience-specific projected JWT files before every request."""
-
-    def __init__(self, token_dir: str | os.PathLike[str] | None = None) -> None:
-        configured = token_dir or os.getenv(ENV_A2A_TOKEN_DIR) or DEFAULT_A2A_TOKEN_DIR
-        self._token_dir = Path(configured)
-
-    def get_token(self, audience: str) -> str:
-        if not audience or "/" in audience or audience in {".", ".."}:
-            raise ValueError(f"invalid workload token audience: {audience!r}")
-        path = self._token_dir / f"{audience}.jwt"
-        if path.is_symlink():
-            raise RuntimeError(
-                f"workload token for audience {audience!r} must not be a symlink: {path}"
-            )
-        flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
-        try:
-            descriptor = os.open(path, flags)
-        except OSError as exc:
-            if exc.errno == errno.ELOOP:
-                raise RuntimeError(
-                    f"workload token for audience {audience!r} must not be a symlink: {path}"
-                ) from exc
-            raise RuntimeError(f"missing workload token for audience {audience!r}: {path}") from exc
-        try:
-            token_stat = os.fstat(descriptor)
-            if not stat.S_ISREG(token_stat.st_mode):
-                raise RuntimeError(
-                    f"workload token for audience {audience!r} is not a regular file: {path}"
-                )
-            if token_stat.st_size > MAX_WORKLOAD_TOKEN_BYTES:
-                raise RuntimeError(
-                    f"workload token for audience {audience!r} exceeds 16 KiB: {path}"
-                )
-            if stat.S_IMODE(token_stat.st_mode) != 0o400:
-                raise RuntimeError(
-                    f"workload token for audience {audience!r} must have mode 0400: {path}"
-                )
-            with os.fdopen(descriptor, "rb", closefd=False) as token_file:
-                raw_token = token_file.read(MAX_WORKLOAD_TOKEN_BYTES + 1)
-            if len(raw_token) > MAX_WORKLOAD_TOKEN_BYTES:
-                raise RuntimeError(
-                    f"workload token for audience {audience!r} exceeds 16 KiB: {path}"
-                )
-            token = raw_token.decode("ascii").strip()
-        except UnicodeError as exc:
-            raise RuntimeError(
-                f"workload token for audience {audience!r} must be ASCII: {path}"
-            ) from exc
-        finally:
-            os.close(descriptor)
-        if not token:
-            raise RuntimeError(f"empty workload token for audience {audience!r}: {path}")
-        self._validate_expiry(token, audience=audience, path=path)
-        return token
-
-    @staticmethod
-    def _validate_expiry(token: str, *, audience: str, path: Path) -> None:
-        parts = token.split(".")
-        if len(parts) != 3:
-            raise RuntimeError(f"workload token for audience {audience!r} is not a JWT: {path}")
-        try:
-            payload_segment = parts[1] + "=" * (-len(parts[1]) % 4)
-            payload = json.loads(base64.urlsafe_b64decode(payload_segment).decode("utf-8"))
-            expires_at = int(payload["exp"])
-        except (binascii.Error, KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
-            raise RuntimeError(
-                f"workload token for audience {audience!r} has no valid exp claim: {path}"
-            ) from exc
-        token_audience = payload.get("aud")
-        accepted_audiences = (
-            {str(item) for item in token_audience}
-            if isinstance(token_audience, list)
-            else {str(token_audience)}
-        )
-        if audience not in accepted_audiences:
-            raise RuntimeError(f"workload token audience mismatch for {audience!r}: {path}")
-        if expires_at <= int(time.time()):
-            raise RuntimeError(f"workload token for audience {audience!r} is expired: {path}")
-
-
 @dataclass(frozen=True)
 class A2ARouteInterface:
     url: str
@@ -187,14 +101,35 @@ class A2ARouteInterface:
 class A2ARoute:
     kind: str
     interface: A2ARouteInterface
+    streaming: bool = False
 
 
 @dataclass(frozen=True)
 class A2ATarget:
+    """Control-plane-owned target facts resolved for one authorized operation."""
+
     agent_id: str
     version_id: str
     card_sha256: str
 
+    def assert_matches(self, *, target_agent_id: str, expected_version_id: str) -> None:
+        """Reject target substitution or version drift before transport opens."""
+
+        require_a2a_resource_id(
+            target_agent_id,
+            "a2a-agent-",
+            field_name="target_agent_id",
+        )
+        require_a2a_resource_id(
+            expected_version_id,
+            "a2a-version-",
+            field_name="expected_version_id",
+        )
+        if self.agent_id != target_agent_id:
+            raise ValueError("A2A_TARGET_MISMATCH")
+        if self.version_id != expected_version_id:
+            raise ValueError("A2A_VERSION_DRIFT")
+
 
 @dataclass(frozen=True)
 class RemoteTaskReference:
@@ -244,6 +179,8 @@ class SpaceAgentPage:
 class A2AControlPlane(ABC):
     """Control-plane seam required by the product A2ASpaceClient."""
 
+    task_event_format = "legacy"
+
     @abstractmethod
     async def list_space_agents(
         self,
@@ -280,6 +217,7 @@ class A2AControlPlane(ABC):
         message_id: str | None = None,
         message_sha256: str | None = None,
         idempotency_token: str | None = None,
+        agent_id: str | None = None,
     ) -> PreparedA2AOperation:
         raise NotImplementedError
 
@@ -321,6 +259,8 @@ class A2AControlPlane(ABC):
 class InternalA2AControlPlaneClient(A2AControlPlane):
     """Workload-authenticated client for Runtime internal A2A Actions."""
 
+    task_event_format = "canonical_v2"
+
     def __init__(
         self,
         base_url: str,
@@ -328,11 +268,11 @@ class InternalA2AControlPlaneClient(A2AControlPlane):
         token_provider: WorkloadTokenProvider | None = None,
         httpx_client: httpx.AsyncClient | None = None,
         timeout: float = 15.0,
+        verify: Any = True,
     ) -> None:
         if not base_url:
-            raise ValueError(
-                f"InternalA2AControlPlaneClient requires {ENV_A2A_CONTROL_PLANE_URL}"
-            )
+            raise ValueError(f"InternalA2AControlPlaneClient requires {ENV_A2A_CONTROL_PLANE_URL}")
+        self._verify = verify
         self._base_url = base_url.rstrip("/")
         self._token_provider = token_provider or FileWorkloadTokenProvider()
         self._client = httpx_client
@@ -346,14 +286,14 @@ class InternalA2AControlPlaneClient(A2AControlPlane):
         payload: dict[str, Any],
     ) -> dict[str, Any]:
         token = self._token_provider.get_token(audience)
-        client = self._client or httpx.AsyncClient(timeout=self._timeout)
+        client = self._client or httpx.AsyncClient(timeout=self._timeout, verify=self._verify, trust_env=False)
         owns_client = self._client is None
         try:
             try:
                 response = await client.post(
                     f"{self._base_url}{build_a2a_internal_action_path(action)}",
                     json=payload,
-                    headers={"Authorization": f"Bearer {token}"},
+                    headers=build_cloud_headers({"Authorization": f"Bearer {token}"}),
                 )
             except httpx.HTTPError as exc:
                 raise A2AControlPlaneError(
@@ -412,6 +352,41 @@ class InternalA2AControlPlaneClient(A2AControlPlane):
             if owns_client:
                 await client.aclose()
 
+    async def submit_inbound_message(
+        self, *, platform_task_id: str, target_version_id: str,
+        remote_task_id: str, remote_context_id: str, message: dict[str, Any],
+        continuation: dict[str, Any] | None = None,
+    ):
+        from ksadk.a2a.inbound_kernel import InboundKernelSubmission
+
+        data = await self._post(
+            "SubmitA2AInboundMessage", audience=AUDIENCE_REGISTRY,
+            payload={"A2ATaskId": platform_task_id, "TargetVersionId": target_version_id,
+                     "RemoteTaskId": remote_task_id, "RemoteContextId": remote_context_id,
+                     "Message": message, **({"Continuation": continuation} if continuation is not None else {})},
+        )
+        try:
+            return InboundKernelSubmission.from_wire(data)
+        except (TypeError, ValueError, AttributeError) as exc:
+            raise A2AControlPlaneError(
+                code=502, message="invalid Server Kernel admission response",
+                error_code="A2A_CONTROL_PLANE_INVALID_RESPONSE",
+                action="SubmitA2AInboundMessage",
+            ) from exc
+
+    async def cancel_inbound_task(self, *, platform_task_id: str, target_version_id: str,
+                                  remote_task_id: str, remote_context_id: str, run_id: str):
+        from ksadk.a2a.inbound_kernel import InboundKernelSubmission
+        data = await self._post("CancelA2AInboundTask", audience=AUDIENCE_REGISTRY, payload={
+            "A2ATaskId": platform_task_id, "TargetVersionId": target_version_id,
+            "RemoteTaskId": remote_task_id, "RemoteContextId": remote_context_id, "RunId": run_id,
+        })
+        try:
+            return InboundKernelSubmission.from_wire(data)
+        except (TypeError, ValueError, AttributeError) as exc:
+            raise A2AControlPlaneError(code=502, message="invalid Server Kernel cancellation response",
+                error_code="A2A_CONTROL_PLANE_INVALID_RESPONSE", action="CancelA2AInboundTask") from exc
+
     @staticmethod
     def _raise_action_error(
         response: httpx.Response,
@@ -497,6 +472,7 @@ class InternalA2AControlPlaneClient(A2AControlPlane):
         message_id: str | None = None,
         message_sha256: str | None = None,
         idempotency_token: str | None = None,
+        agent_id: str | None = None,
     ) -> PreparedA2AOperation:
         _validate_task_operation_request(
             operation=operation,
@@ -551,6 +527,23 @@ class InternalA2AControlPlaneClient(A2AControlPlane):
             payload={"A2ATaskId": platform_task_id, "Events": events},
         )
 
+    async def list_product_kernel_tasks(self, *, after_task_id: str = "", limit: int = 25):
+        return await self._post(
+            "ListA2AProductKernelTasks", audience=AUDIENCE_TASK_SINK,
+            payload={"AfterTaskId": after_task_id, "Limit": limit},
+        )
+
+    async def append_product_kernel_facts(
+        self, *, platform_task_id: str, target_version_id: str,
+        remote_task_id: str, remote_context_id: str, events: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        return await self._post(
+            "AppendA2AProductKernelFacts", audience=AUDIENCE_TASK_SINK,
+            payload={"A2ATaskId": platform_task_id, "TargetVersionId": target_version_id,
+                     "RemoteTaskId": remote_task_id, "RemoteContextId": remote_context_id,
+                     "Events": events},
+        )
+
     async def resolve_credential(
         self,
         *,
@@ -653,9 +646,7 @@ class A2AAgentCardClient(A2AControlPlane):
             a2a_agent_id = str(item.get("A2AAgentId") or "").strip()
             if not a2a_agent_id:
                 continue
-            # server 用纯 uuid,ksadk 内部要求 a2a-agent- 前缀;补前缀适配契约。
-            if not a2a_agent_id.startswith("a2a-agent-"):
-                a2a_agent_id = f"a2a-agent-{a2a_agent_id}"
+            # Registry identity is opaque; do not invent a different lookup key.
             invocation_status = str(item.get("InvocationStatus") or "")
             if invocation_status and invocation_status != "available":
                 continue
@@ -886,11 +877,13 @@ def _agent_card_from_wire(payload: Any) -> AgentCard:
     # 兼容 0.3 card：顶层 url/preferredTransport 折叠进 supportedInterfaces[0]。
     if not payload.get("supportedInterfaces") and payload.get("url"):
         payload = dict(payload)
-        payload["supportedInterfaces"] = [{
-            "url": payload["url"],
-            "protocolBinding": payload.get("preferredTransport", "JSONRPC"),
-            "protocolVersion": payload.get("protocolVersion", "0.3"),
-        }]
+        payload["supportedInterfaces"] = [
+            {
+                "url": payload["url"],
+                "protocolBinding": payload.get("preferredTransport", "JSONRPC"),
+                "protocolVersion": payload.get("protocolVersion", "0.3"),
+            }
+        ]
     try:
         return ParseDict(payload, AgentCard(), ignore_unknown_fields=True)
     except (ParseError, TypeError, ValueError) as exc:
@@ -947,6 +940,14 @@ def _prepared_operation_from_wire(data: dict[str, Any]) -> PreparedA2AOperation:
     target: dict[str, Any] = raw_target if isinstance(raw_target, dict) else {}
     raw_route = data.get("Route")
     route: dict[str, Any] = raw_route if isinstance(raw_route, dict) else {}
+    capabilities = route.get("Capabilities", {})
+    if not isinstance(capabilities, dict) or type(capabilities.get("Streaming", False)) is not bool:
+        raise A2AControlPlaneError(
+            code=502,
+            message="prepared route streaming capability must be a boolean",
+            error_code="A2A_CONTROL_PLANE_INVALID_RESPONSE",
+            field="Route.Capabilities.Streaming",
+        )
     raw_interface = route.get("Interface")
     interface: dict[str, Any] = raw_interface if isinstance(raw_interface, dict) else {}
     raw_remote_task = data.get("RemoteTask")
@@ -1007,6 +1008,7 @@ def _prepared_operation_from_wire(data: dict[str, Any]) -> PreparedA2AOperation:
         ),
         route=A2ARoute(
             kind=route_kind,
+            streaming=capabilities.get("Streaming", False),
             interface=A2ARouteInterface(
                 url=_required_str(interface.get("Url"), field_name="Route.Interface.Url"),
                 protocol_binding=protocol_binding,

ksadk/a2a/event_adapter.py

@@ -1,15 +1,7 @@
-"""A2AEventAdapter — A2A Message/Task/Artifact 与 RuntimeEvent 的双向转换 (goal-05)。
+"""Deprecated stateless facade over the sole canonical A2A mapper.
 
-契约 §3.2:``A2AEventAdapter`` 负责 A2A wire 对象与 G0.2 RuntimeEvent 的双向转换;
-§7.2:artifact/message ↔ RuntimeEvent artifact/text/data。
-
-方向:
-- ``task_status_to_event``:A2A TaskStatus/TaskState → RuntimeEvent(run.*)。
-- ``artifact_to_event``:A2A Artifact → RuntimeEvent(item.*,item_kind="artifact")。
-- ``message_to_event``:A2A Message → RuntimeEvent(item.*,item_kind="message")。
-- ``event_to_text_part``:RuntimeEvent(item.*,item_kind="message")→ A2A ``Part``(用于出站)。
-
-wire 对象是 protobuf(``a2a_pb2``);文本用 ``Part(text=...)``。
+Managed invocations use events.adapters.a2a directly, retaining one adapter
+per local handle. This facade only preserves older scalar helper signatures.
 """
 
 from __future__ import annotations
@@ -17,197 +9,104 @@ from __future__ import annotations
 import time
 from typing import Any, Optional
 
-from a2a.types import Part, TaskState, TaskStatus
-
-from ksadk.events.canonical import (
-    ContentSnapshot,
-    ErrorInfo,
-    ItemCompleted,
-    ItemStarted,
-    ItemUpdated,
-    RunCanceled,
-    RunCompleted,
-    RunFailed,
-    RunInterrupted,
-    RunProgress,
-    RunStarted,
-    RuntimeEvent,
-    SourceRef,
-)
+from a2a.types import Message, Part, Role, Task, TaskArtifactUpdateEvent, TaskState
+
+from ksadk.events.adapters.a2a import A2AAdapterContext
+from ksadk.events.adapters.a2a import A2AEventAdapter as CanonicalA2AEventAdapter
+from ksadk.events.canonical import ItemCompleted, ItemUpdated, RunStarted, RuntimeEvent
 from ksadk.events.content import TextContent
-from ksadk.events.identity import stable_event_id, stable_item_id, stable_scope_id
 
 
 class A2AEventAdapter:
-    """A2A wire 对象 ↔ RuntimeEvent 双向转换器。"""
-
-    # ---- A2A → RuntimeEvent ----
-
-    def task_status_to_event(
-        self,
-        status: TaskStatus,
-        *,
-        agent_id: str,
-        user_id: str,
-        session_id: str,
-        invocation_id: str,
-        seq_id: int,
-        event_id: Optional[str] = None,
-    ) -> RuntimeEvent:
-        """A2A TaskStatus → canonical RuntimeEvent(run.*)。"""
-        state = status.state
-        state_name = TaskState.Name(state) if state is not None else "unknown"
-        scope_id = stable_scope_id("a2a", session_id, invocation_id)
-        run_id = invocation_id
-        source = SourceRef(
-            framework="a2a",
-            native_run_id=invocation_id,
-            metadata={"agent_id": agent_id, "user_id": user_id, "status": state_name},
-        )
-        timestamp = time.time()
-        eid = event_id or stable_event_id(
-            "a2a", scope_id, run_id, "run", "run", invocation_id, seq_id
-        )
-        common: dict[str, Any] = {
-            "schema_version": 2,
-            "event_id": eid,
-            "seq": seq_id,
-            "timestamp": timestamp,
-            "run_id": run_id,
-            "scope_id": scope_id,
-            "source": source,
-        }
-        if state == TaskState.TASK_STATE_SUBMITTED:
-            return RunStarted(**common, status="running")
-        if state == TaskState.TASK_STATE_WORKING:
-            return RunProgress(**common, status="running", message=state_name)
-        if state == TaskState.TASK_STATE_COMPLETED:
-            return RunCompleted(**common, status="completed", output_refs=())
-        if state in {TaskState.TASK_STATE_FAILED, TaskState.TASK_STATE_REJECTED}:
-            message = getattr(status, "message", None)
-            error_text = self._parts_text(getattr(message, "parts", None)) or state_name
-            return RunFailed(
-                **common,
-                status="failed",
-                error=ErrorInfo(
-                    code=(
-                        "a2a_task_rejected"
-                        if state == TaskState.TASK_STATE_REJECTED
-                        else "a2a_task_failed"
-                    ),
-                    message=error_text,
-                    source="a2a",
-                    scope_id=scope_id,
-                ),
-            )
-        if state == TaskState.TASK_STATE_CANCELED:
-            return RunCanceled(**common, status="canceled", reason="interrupted_active_turn")
-        if state == TaskState.TASK_STATE_INPUT_REQUIRED:
-            return RunInterrupted(**common, status="interrupted", reason=state_name)
-        return RunProgress(**common, status="running", message=state_name)
-
-    def artifact_to_event(
-        self,
-        artifact: Any,
-        *,
-        agent_id: str,
-        user_id: str,
-        session_id: str,
-        invocation_id: str,
-        seq_id: int,
-        event_id: Optional[str] = None,
-    ) -> RuntimeEvent:
-        """A2A Artifact → canonical RuntimeEvent(item.started,item_kind="artifact")。"""
-        artifact_id = str(getattr(artifact, "artifact_id", None) or "")
-        name = getattr(artifact, "name", None) or "artifact"
-        text = self._parts_text(getattr(artifact, "parts", None))
-        scope_id = stable_scope_id("a2a", session_id, invocation_id)
-        item_id = stable_item_id(
-            "a2a", session_id, invocation_id, "artifact", artifact_id or name
-        )
-        source = SourceRef(
-            framework="a2a",
-            native_run_id=invocation_id,
-            native_item_id=artifact_id or None,
-            metadata={"agent_id": agent_id, "user_id": user_id, "artifact_name": name},
-        )
-        eid = event_id or stable_event_id(
-            "a2a", scope_id, item_id, "item.started", "artifact", invocation_id, seq_id
-        )
-        initial = (
-            ContentSnapshot(parts=(TextContent(part_id="text", text=text),))
-            if text
-            else None
-        )
-        return ItemStarted(
-            schema_version=2,
-            event_id=eid,
-            seq=seq_id,
-            timestamp=time.time(),
-            run_id=invocation_id,
-            scope_id=scope_id,
-            source=source,
-            item_id=item_id,
-            item_kind="artifact",
-            phase="final_answer",
-            initial=initial,
+    def __init__(self) -> None:
+        self._canonical = CanonicalA2AEventAdapter()
+
+    @staticmethod
+    def _context(kwargs):
+        return A2AAdapterContext(
+            run_id=kwargs["invocation_id"],
+            context_id=kwargs["session_id"],
+            task_id=kwargs["invocation_id"],
+            initial_seq=kwargs["seq_id"],
         )
 
-    def message_to_event(
-        self,
-        text: str,
-        *,
-        final: bool,
-        agent_id: str,
-        user_id: str,
-        session_id: str,
-        invocation_id: str,
-        seq_id: int,
-        event_id: Optional[str] = None,
-    ) -> RuntimeEvent:
-        """A2A Message 文本 → canonical RuntimeEvent(item.*,item_kind="message")。"""
-        scope_id = stable_scope_id("a2a", session_id, invocation_id)
-        item_id = stable_item_id("a2a", session_id, invocation_id, "message", "response")
-        source = SourceRef(
-            framework="a2a",
-            native_run_id=invocation_id,
-            metadata={"agent_id": agent_id, "user_id": user_id},
+    @staticmethod
+    def _decorate(event, kwargs):
+        updates = {"seq": kwargs["seq_id"]}
+        if kwargs.get("event_id"):
+            updates["event_id"] = kwargs["event_id"]
+        return event.model_copy(update=updates)
+
+    def task_status_to_events(self, status, **kwargs):
+        # A terminal task may be the only frame delivered by a legacy peer.
+        # That path historically represents a completed item and must not
+        # manufacture a lifecycle start after its terminal status message.
+        # Streaming peers still receive RunStarted from their first
+        # non-terminal snapshot, which keeps the canonical lifecycle intact.
+        was_started = self._canonical._run_started
+        context = self._context(kwargs)
+        # The legacy scalar callback has no outer Task context. Project its
+        # interaction message onto the local platform task identity; the
+        # canonical mapper needs that message to identify input/approval waits.
+        # Other status messages are projected separately by
+        # _SpaceClientEventMixin.
+        scalar_status = type(status)()
+        scalar_status.CopyFrom(status)
+        if scalar_status.HasField("message"):
+            if status.state in {
+                TaskState.TASK_STATE_INPUT_REQUIRED,
+                TaskState.TASK_STATE_AUTH_REQUIRED,
+            }:
+                scalar_status.message.context_id = context.context_id
+                scalar_status.message.task_id = context.task_id
+            else:
+                scalar_status.ClearField("message")
+        task = Task(id=context.task_id, context_id=context.context_id, status=scalar_status)
+        events = self._canonical._map_task_snapshot(
+            task, context, "subscription_rebuild", "legacy", time.time()
         )
-        timestamp = time.time()
-        if final:
-            eid = event_id or stable_event_id(
-                "a2a", scope_id, item_id, "item.completed", "snapshot", invocation_id, seq_id
-            )
-            return ItemCompleted(
-                schema_version=2,
-                event_id=eid,
-                seq=seq_id,
-                timestamp=timestamp,
-                run_id=invocation_id,
-                scope_id=scope_id,
-                source=source,
-                item_id=item_id,
-                item_kind="message",
-                snapshot=ContentSnapshot(
-                    parts=(TextContent(part_id="text-0", text=text),)
-                ),
-            )
-        eid = event_id or stable_event_id(
-            "a2a", scope_id, item_id, "item.updated", "text-0", invocation_id, seq_id
+        terminal_states = {
+            TaskState.TASK_STATE_COMPLETED,
+            TaskState.TASK_STATE_CANCELED,
+            TaskState.TASK_STATE_FAILED,
+            TaskState.TASK_STATE_REJECTED,
+        }
+        if status.state in terminal_states and not was_started:
+            return [event for event in events if not isinstance(event, RunStarted)]
+        return events
+
+    def task_status_to_event(self, status, **kwargs):
+        return self._decorate(self.task_status_to_events(status, **kwargs)[-1], kwargs)
+
+    def artifact_to_events(self, artifact, **kwargs):
+        context = self._context(kwargs)
+        native = TaskArtifactUpdateEvent(
+            task_id=context.task_id,
+            context_id=context.context_id,
+            artifact=artifact,
+            append=False,
+            last_chunk=False,
         )
-        return ItemUpdated(
-            schema_version=2,
-            event_id=eid,
-            seq=seq_id,
-            timestamp=timestamp,
-            run_id=invocation_id,
-            scope_id=scope_id,
-            source=source,
-            item_id=item_id,
-            item_kind="message",
-            op="append",
-            update=TextContent(part_id="text-0", text=text),
+        return self._canonical.map_event(native, context, timestamp=time.time())
+
+    def artifact_to_event(self, artifact, **kwargs):
+        events = self.artifact_to_events(artifact, **kwargs)
+        return self._decorate(events[-1], kwargs)
+
+    def message_to_event(self, text, *, final, **kwargs):
+        adapter, context = CanonicalA2AEventAdapter(), self._context(kwargs)
+        native = Message(
+            message_id=kwargs.get("event_id") or "legacy-response",
+            task_id=context.task_id,
+            context_id=context.context_id,
+            role=Role.ROLE_AGENT,
+            parts=[Part(text=text)],
         )
+        events = adapter.map_event(native, context, timestamp=time.time())
+        message_events = [
+            event for event in events if getattr(event, "item_kind", None) == "message"
+        ]
+        return self._decorate(message_events[-1], kwargs)
 
     # ---- RuntimeEvent → A2A ----