agentengine-sdk-python 0.8.1__py3-none-any.whl → 0.8.3__py3-none-any.whl

ksadk/_build_provenance.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"sourceCommit":"320b7f324966bd3aa8557a65cf592716699edb8c","sourceTree":"clean","version":"0.8.3"}

ksadk/a2a/_space_client_events.py

@@ -0,0 +1,381 @@
+"""A2ASpaceClient 的事件投影与持久化实现（纯移动自 ``ksadk.a2a.space_client``，行为不变）。
+
+以 mixin 形式被 :class:`A2ASpaceClient` 继承，依赖宿主提供 ``_event_adapter`` /
+``_event_dispatcher`` / ``_event_sink`` / ``_persisted_wire_events`` / ``_space_id`` /
+``_seq`` / ``_backend`` 及校验辅助方法。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from a2a.types import TaskState
+from google.protobuf.json_format import MessageToDict
+
+from ksadk.a2a.control_plane import DiscoveredAgent
+from ksadk.a2a.event_adapter import A2AEventAdapter
+from ksadk.events.runtime_event import RuntimeEvent
+
+if TYPE_CHECKING:
+    pass
+
+
+def _utc_now() -> str:
+    from ksadk.a2a.space_client import _utc_now as _impl
+
+    return _impl()
+
+
+def _canonical_proto(value: Any) -> dict[str, Any]:
+    from ksadk.a2a.space_client import _canonical_proto as _impl
+
+    return _impl(value)
+
+
+def _present_message_field(value: Any, field_name: str) -> Any | None:
+    from ksadk.a2a.space_client import _present_message_field as _impl
+
+    return _impl(value, field_name)
+
+
+class _SpaceClientEventMixin:
+    async def _project_stream_item(
+        self,
+        platform_task_id: str,
+        item: Any,
+        agent: DiscoveredAgent,
+        *,
+        wire_position: int,
+        operation_instance_id: str,
+    ) -> list[RuntimeEvent]:
+        runtime_events = self._stream_item_to_events(
+            item,
+            agent,
+            wire_position=wire_position,
+            invocation_id=platform_task_id,
+        )
+        platform_events = self._platform_events(
+            item,
+            platform_task_id,
+            operation_instance_id=operation_instance_id,
+            wire_position=wire_position,
+        )
+        if platform_events:
+            await self._event_dispatcher.enqueue(
+                platform_task_id=platform_task_id,
+                events=platform_events,
+            )
+        return await self._persist_events(runtime_events)
+
+    def _platform_events(
+        self,
+        item: Any,
+        platform_task_id: str,
+        *,
+        operation_instance_id: str,
+        wire_position: int,
+    ) -> list[dict[str, Any]]:
+        events: list[dict[str, Any]] = []
+
+        def append_event(
+            kind: str,
+            payload: dict[str, Any],
+            *,
+            status: str | None = None,
+            occurred_at: str | None = None,
+        ) -> None:
+            events.append(
+                self._platform_event(
+                    kind,
+                    payload,
+                    platform_task_id,
+                    operation_instance_id=operation_instance_id,
+                    wire_position=wire_position,
+                    event_ordinal=len(events),
+                    status=status,
+                    occurred_at=occurred_at,
+                )
+            )
+
+        task = _present_message_field(item, "task")
+        if task is None and hasattr(item, "status") and hasattr(item, "id"):
+            task = item
+        status_update = _present_message_field(item, "status_update")
+        artifact_update = _present_message_field(item, "artifact_update")
+        message = _present_message_field(item, "message")
+        if task is not None and getattr(task, "status", None) is not None:
+            payload = _canonical_proto(task.status)
+            state_name = TaskState.Name(task.status.state)
+            append_event(
+                "status",
+                payload,
+                status=state_name.removeprefix("TASK_STATE_").lower(),
+                occurred_at=str(payload.get("timestamp") or _utc_now()),
+            )
+            for artifact in getattr(task, "artifacts", None) or []:
+                append_event(
+                    "artifact",
+                    {
+                        "Artifact": _canonical_proto(artifact),
+                        "Append": False,
+                        "LastChunk": True,
+                    },
+                )
+        if status_update is not None and getattr(status_update, "status", None) is not None:
+            payload = _canonical_proto(status_update.status)
+            state_name = TaskState.Name(status_update.status.state)
+            append_event(
+                "status",
+                payload,
+                status=state_name.removeprefix("TASK_STATE_").lower(),
+                occurred_at=str(payload.get("timestamp") or _utc_now()),
+            )
+        if artifact_update is not None and getattr(artifact_update, "artifact", None) is not None:
+            append_event(
+                "artifact",
+                {
+                    "Artifact": _canonical_proto(artifact_update.artifact),
+                    "Append": bool(getattr(artifact_update, "append", False)),
+                    "LastChunk": bool(getattr(artifact_update, "last_chunk", False)),
+                },
+            )
+        if message is not None:
+            payload = _canonical_proto(message)
+            append_event("message", payload)
+            append_event(
+                "status",
+                {"state": "TASK_STATE_COMPLETED", "message": payload},
+                status="completed",
+            )
+        return events
+
+    @staticmethod
+    def _platform_event(
+        kind: str,
+        payload: dict[str, Any],
+        platform_task_id: str,
+        *,
+        operation_instance_id: str,
+        wire_position: int,
+        event_ordinal: int,
+        status: str | None = None,
+        occurred_at: str | None = None,
+    ) -> dict[str, Any]:
+        source_id = hashlib.sha256(
+            (
+                f"{platform_task_id}:{operation_instance_id}:{wire_position}:{event_ordinal}:{kind}"
+            ).encode("utf-8")
+        ).hexdigest()
+        event: dict[str, Any] = {
+            "SourceEventId": source_id,
+            "EventKind": kind,
+            "Payload": payload,
+            "OccurredAt": occurred_at or _utc_now(),
+        }
+        if status:
+            event["Status"] = status
+        return event
+
+    async def flush_pending_events(self) -> int:
+        """Deliver all currently queued platform event batches or raise on failure."""
+
+        return await self._event_dispatcher.drain(raise_on_error=True)
+
+    def _next_seq(self) -> int:
+        self._seq += 1
+        return self._seq
+
+    def _event_ctx(
+        self,
+        agent: DiscoveredAgent,
+        invocation_id: str,
+        *,
+        event_id: str | None = None,
+    ) -> dict[str, Any]:
+        return {
+            "agent_id": agent.agent_id,
+            "user_id": "a2a_space",
+            "session_id": self._space_id,
+            "invocation_id": invocation_id,
+            "seq_id": self._next_seq(),
+            "event_id": event_id,
+        }
+
+    def task_to_event(self, task: Any, agent: DiscoveredAgent) -> RuntimeEvent:
+        return self._event_adapter.task_status_to_event(
+            task.status, **self._event_ctx(agent, invocation_id=str(task.id))
+        )
+
+    def _stream_item_to_events(
+        self,
+        item: Any,
+        agent: DiscoveredAgent,
+        *,
+        wire_position: int = 0,
+        invocation_id: str | None = None,
+    ) -> list[RuntimeEvent]:
+        events: list[RuntimeEvent] = []
+        task = _present_message_field(item, "task")
+        if task is None and hasattr(item, "status") and hasattr(item, "id"):
+            task = item
+        status_update = _present_message_field(item, "status_update")
+        artifact_update = _present_message_field(item, "artifact_update")
+        message = _present_message_field(item, "message")
+        resolved_invocation_id = invocation_id or str(
+            getattr(item, "task_id", None)
+            or getattr(task, "id", "")
+            or getattr(status_update, "task_id", "")
+            or getattr(artifact_update, "task_id", "")
+            or getattr(message, "task_id", "")
+            or ""
+        )
+
+        def ctx(kind: str, value: Any) -> dict[str, Any]:
+            metadata = getattr(value, "metadata", None)
+            native_event_id = ""
+            if metadata is not None:
+                if isinstance(metadata, Mapping):
+                    metadata_dict = dict(metadata)
+                else:
+                    try:
+                        metadata_dict = MessageToDict(metadata, preserving_proto_field_name=True)
+                    except (AttributeError, TypeError, ValueError):
+                        metadata_dict = {}
+                native_event_id = str(
+                    metadata_dict.get("event_id") or metadata_dict.get("ksadk_event_id") or ""
+                )
+            message_id = str(getattr(value, "message_id", "") or "")
+            artifact = getattr(value, "artifact", None)
+            artifact_id = str(
+                getattr(value, "artifact_id", "") or getattr(artifact, "artifact_id", "") or ""
+            )
+            source_id = native_event_id or message_id or artifact_id
+            event_id = uuid.uuid5(
+                uuid.NAMESPACE_URL,
+                f"ksadk:a2a:{resolved_invocation_id}:{wire_position}:{kind}:{source_id}",
+            ).hex
+            return self._event_ctx(agent, invocation_id=resolved_invocation_id, event_id=event_id)
+
+        if task is not None and getattr(task, "status", None) is not None:
+            task_status_message = _present_message_field(task.status, "message")
+            task_status_text = A2AEventAdapter._parts_text(
+                getattr(task_status_message, "parts", None)
+            )
+            task_is_terminal = task.status.state in {
+                TaskState.TASK_STATE_COMPLETED,
+                TaskState.TASK_STATE_FAILED,
+                TaskState.TASK_STATE_CANCELED,
+                TaskState.TASK_STATE_REJECTED,
+            }
+            if not task_is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        task.status,
+                        **ctx("task", task),
+                    )
+                )
+            if task_status_text:
+                events.append(
+                    self._event_adapter.message_to_event(
+                        task_status_text,
+                        final=task_is_terminal,
+                        **ctx("task-status-message", task_status_message),
+                    )
+                )
+            if task_is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        task.status,
+                        **ctx("task", task),
+                    )
+                )
+        if status_update is not None and getattr(status_update, "status", None) is not None:
+            status_message = _present_message_field(status_update.status, "message")
+            text = A2AEventAdapter._parts_text(getattr(status_message, "parts", None))
+            terminal_states = {
+                TaskState.TASK_STATE_COMPLETED,
+                TaskState.TASK_STATE_FAILED,
+                TaskState.TASK_STATE_CANCELED,
+                TaskState.TASK_STATE_REJECTED,
+            }
+            is_terminal = status_update.status.state in terminal_states
+            if not is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        status_update.status, **ctx("status", status_update)
+                    )
+                )
+            if text:
+                events.append(
+                    self._event_adapter.message_to_event(
+                        text,
+                        final=is_terminal,
+                        **ctx("status-message", status_message),
+                    )
+                )
+            if is_terminal:
+                events.append(
+                    self._event_adapter.task_status_to_event(
+                        status_update.status, **ctx("status", status_update)
+                    )
+                )
+        if artifact_update is not None and getattr(artifact_update, "artifact", None) is not None:
+            artifact = artifact_update.artifact
+            events.append(
+                self._event_adapter.artifact_to_event(artifact, **ctx("artifact", artifact_update))
+            )
+            artifact_text = A2AEventAdapter._parts_text(getattr(artifact, "parts", None))
+            if artifact_text and str(getattr(artifact, "name", "") or "") == "response":
+                events.append(
+                    self._event_adapter.message_to_event(
+                        artifact_text,
+                        final=bool(getattr(artifact_update, "last_chunk", False)),
+                        **ctx("artifact-text", artifact_update),
+                    )
+                )
+        if message is not None:
+            text = A2AEventAdapter._parts_text(getattr(message, "parts", None))
+            if text:
+                events.append(
+                    self._event_adapter.message_to_event(
+                        text, final=True, **ctx("message", message)
+                    )
+                )
+        return events
+
+    async def _persist_events(self, events: list[RuntimeEvent]) -> list[RuntimeEvent]:
+        existing_ids = set(self._persisted_wire_events)
+        if self._event_sink is not None:
+            list_events = getattr(self._event_sink, "list", None)
+            if callable(list_events) and events:
+                session_id = str(events[0].source.metadata.get("session_id") or self._space_id)
+                persisted_before = await list_events(session_id)
+                existing_ids.update(event.event_id for event in persisted_before)
+        fresh = [event for event in events if event.event_id not in existing_ids]
+        if not fresh:
+            return []
+        if self._event_sink is not None:
+            append = getattr(self._event_sink, "append", None)
+            if append is None:
+                raise TypeError("event_sink must provide async append(events)")
+            # RuntimeEventStore.append(session_id, events) requires session_id;
+            # fall back to single-arg call for non-canonical sinks.
+            session_id_for_persist = (
+                str(events[0].source.metadata.get("session_id") or self._space_id)
+                if events
+                else self._space_id
+            )
+            try:
+                persisted = await append(session_id_for_persist, fresh)
+            except TypeError:
+                persisted = await append(fresh)
+            if persisted is not None:
+                fresh = list(persisted)
+        self._persisted_wire_events.update(event.event_id for event in fresh)
+        return fresh
+
+
+__all__ = ["_SpaceClientEventMixin"]

ksadk/a2a/event_adapter.py

@@ -5,31 +5,37 @@
 
 方向:
 - ``task_status_to_event``:A2A TaskStatus/TaskState → RuntimeEvent(run.*)。
-- ``artifact_to_event``:A2A Artifact → RuntimeEvent(artifact.*)。
-- ``message_to_event``:A2A Message → RuntimeEvent(text.*)。
-- ``event_to_text_part``:RuntimeEvent(text.*)→ A2A ``Part``(用于出站)。
+- ``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=...)``。
 """
 
 from __future__ import annotations
 
+import time
 from typing import Any, Optional
 
 from a2a.types import Part, TaskState, TaskStatus
 
-from ksadk.events.runtime_event import EventType, RuntimeEvent
-
-#: A2A TaskState → RuntimeEvent run.* 事件类型映射。
-_TASK_STATE_TO_RUN_EVENT = {
-    TaskState.TASK_STATE_SUBMITTED: EventType.RUN_STARTED,
-    TaskState.TASK_STATE_WORKING: EventType.RUN_PROGRESS,
-    TaskState.TASK_STATE_COMPLETED: EventType.RUN_COMPLETED,
-    TaskState.TASK_STATE_FAILED: EventType.RUN_FAILED,
-    TaskState.TASK_STATE_CANCELED: EventType.RUN_CANCELED,
-    TaskState.TASK_STATE_INPUT_REQUIRED: EventType.RUN_INTERRUPTED,
-    TaskState.TASK_STATE_REJECTED: EventType.RUN_FAILED,
-}
+from ksadk.events.canonical import (
+    ContentSnapshot,
+    ErrorInfo,
+    ItemCompleted,
+    ItemStarted,
+    ItemUpdated,
+    RunCanceled,
+    RunCompleted,
+    RunFailed,
+    RunInterrupted,
+    RunProgress,
+    RunStarted,
+    RuntimeEvent,
+    SourceRef,
+)
+from ksadk.events.content import TextContent
+from ksadk.events.identity import stable_event_id, stable_item_id, stable_scope_id
 
 
 class A2AEventAdapter:
@@ -48,25 +54,57 @@ class A2AEventAdapter:
         seq_id: int,
         event_id: Optional[str] = None,
     ) -> RuntimeEvent:
-        """A2A TaskStatus → RuntimeEvent(run.*)。"""
-        event_type = _TASK_STATE_TO_RUN_EVENT.get(status.state, EventType.RUN_PROGRESS)
-        state_name = TaskState.Name(status.state) if status.state is not None else "unknown"
-        payload: dict[str, Any] = {"status": state_name}
-        if event_type == EventType.RUN_CANCELED:
-            payload["cancel_result"] = "interrupted_active_turn"
-        elif event_type == EventType.RUN_FAILED:
-            message = getattr(status, "message", None)
-            payload["error"] = self._parts_text(getattr(message, "parts", None)) or state_name
-        return RuntimeEvent.create(
-            event_type,
-            agent_id=agent_id,
-            user_id=user_id,
-            session_id=session_id,
-            invocation_id=invocation_id,
-            seq_id=seq_id,
-            payload=payload,
-            event_id=event_id,
+        """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,
@@ -79,23 +117,40 @@ class A2AEventAdapter:
         seq_id: int,
         event_id: Optional[str] = None,
     ) -> RuntimeEvent:
-        """A2A Artifact → RuntimeEvent(artifact.*)。"""
+        """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))
-        return RuntimeEvent.create(
-            EventType.ARTIFACT_CREATED,
-            agent_id=agent_id,
-            user_id=user_id,
-            session_id=session_id,
-            invocation_id=invocation_id,
-            seq_id=seq_id,
-            payload={
-                "artifact_id": str(getattr(artifact, "artifact_id", None) or ""),
-                "name": name,
-                "version": 1,
-                "text": text,
-            },
-            event_id=event_id,
+        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 message_to_event(
@@ -110,29 +165,66 @@ class A2AEventAdapter:
         seq_id: int,
         event_id: Optional[str] = None,
     ) -> RuntimeEvent:
-        """A2A Message 文本 → RuntimeEvent(text.*,带相位)。"""
-        return RuntimeEvent.create(
-            EventType.TEXT_COMPLETED if final else EventType.TEXT_DELTA,
-            agent_id=agent_id,
-            user_id=user_id,
-            session_id=session_id,
-            invocation_id=invocation_id,
-            seq_id=seq_id,
-            phase="final_answer" if final else "commentary",
-            payload={"text": text},
-            event_id=event_id,
+        """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},
+        )
+        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
+        )
+        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),
         )
 
     # ---- RuntimeEvent → A2A ----
 
     @staticmethod
     def event_to_text_part(event: RuntimeEvent) -> Optional[Part]:
-        """RuntimeEvent(text.*)→ A2A ``Part``(用于出站 message/artifact)。"""
-        event.validate_conformance()
-        if event.event_type not in (EventType.TEXT_DELTA, EventType.TEXT_COMPLETED):
+        """RuntimeEvent(item.*,item_kind="message")→ A2A ``Part``(用于出站 message/artifact)。"""
+        if isinstance(event, ItemUpdated) and event.item_kind == "message":
+            if isinstance(event.update, TextContent):
+                text = event.update.text
+                return Part(text=text) if text else None
+            return None
+        if isinstance(event, ItemCompleted) and event.item_kind == "message":
+            if event.snapshot.parts and isinstance(event.snapshot.parts[0], TextContent):
+                text = event.snapshot.parts[0].text
+                return Part(text=text) if text else None
             return None
-        text = str(event.payload.get("text") or "")
-        return Part(text=text) if text else None
+        return None
 
     @staticmethod
     def _parts_text(parts: Any) -> str: