agentengine-sdk-python 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

ksadk/a2ui/core.py

@@ -13,6 +13,7 @@ action ``a2ui.action``。均带 ``surface_id``(G0.2 必填键)。
 from __future__ import annotations
 
 import logging
+import time
 import uuid
 from typing import Any, Optional
 
@@ -22,7 +23,21 @@ from ksadk.a2ui.models import (
     PendingInteraction,
     Surface,
 )
-from ksadk.events.runtime_event import EventType, RuntimeEvent
+from ksadk.events.canonical import (
+    ContentSnapshot,
+    InteractionRequested,
+    ItemCompleted,
+    ItemStarted,
+    ItemUpdated,
+    RuntimeEvent,
+    SourceRef,
+)
+from ksadk.events.content import DataContent
+from ksadk.events.identity import (
+    stable_event_id,
+    stable_item_id,
+    stable_scope_id,
+)
 from ksadk.events.store import RuntimeEventStore
 
 logger = logging.getLogger(__name__)
@@ -33,6 +48,9 @@ class A2UICore:
 
     所有 A2UI 事件经 :class:`RuntimeEventStore` 持久化(**不另开通道、不经 A2A 绕过**),
     供 session 级订阅 / replay / 审计消费。
+
+    Canonical 映射:surface = ``item_kind=data`` + ``source.protocol="a2ui"``;
+    user action / input request = ``InteractionRequested``。
     """
 
     def __init__(
@@ -43,6 +61,9 @@ class A2UICore:
         user_id: str,
         session_id: str,
         catalog: dict[str, frozenset[str]] = BASIC_CATALOG,
+        interaction_ledger: Any | None = None,
+        interaction_guard: Any | None = None,
+        tenant_id: str = "default",
     ) -> None:
         self._store = store
         self._agent_id = agent_id
@@ -51,25 +72,59 @@ class A2UICore:
         self._catalog = catalog
         self._seq = 0
         self._seen_surfaces: set[str] = set()
+        # InteractionLedger 存在时它是 pending interaction 的唯一权威
+        # （Phase 1 Task 5 Step 6）；本地 dict 只作无 ledger 的降级路径。
+        self._ledger = interaction_ledger
+        self._guard = interaction_guard
+        self._tenant_id = tenant_id
         self._pending: dict[str, PendingInteraction] = {}
 
-    # ---- 内部:产出并持久化一个 A2UI RuntimeEvent ----
+    # ---- 内部:canonical 身份/信封 ----
 
-    async def _emit(
-        self, event_type: str, invocation_id: str, payload: dict[str, Any]
-    ) -> RuntimeEvent:
-        self._seq += 1
-        event = RuntimeEvent.create(
-            event_type,
-            agent_id=self._agent_id,
-            user_id=self._user_id,
-            session_id=self._session_id,
-            invocation_id=invocation_id,
-            seq_id=self._seq,
-            payload=payload,
+    def _scope_id(self, invocation_id: str) -> str:
+        return stable_scope_id("ksadk", self._session_id, invocation_id)
+
+    def _surface_item_id(self, invocation_id: str, surface_id: str) -> str:
+        return stable_item_id("ksadk", self._session_id, invocation_id, "a2ui", surface_id)
+
+    def _source(self, invocation_id: str, surface_id: str) -> SourceRef:
+        return SourceRef(
+            framework="ksadk",
+            protocol="a2ui",
+            native_run_id=invocation_id,
+            metadata={
+                "agent_id": self._agent_id,
+                "user_id": self._user_id,
+                "session_id": self._session_id,
+                "invocation_id": invocation_id,
+                "surface_id": surface_id,
+            },
         )
-        # 经 RuntimeEvent 持久化(A7 store)——canonical,不绕过。
-        await self._store.append_one(event)
+
+    def _envelope(
+        self,
+        invocation_id: str,
+        item_id: str,
+        event_type: str,
+        part_id: str,
+        surface_id: str = "",
+    ) -> dict[str, Any]:
+        self._seq += 1
+        return {
+            "schema_version": 2,
+            "event_id": stable_event_id(
+                "ksadk", self._scope_id(invocation_id), item_id, event_type, part_id,
+                invocation_id, self._seq,
+            ),
+            "seq": self._seq,
+            "timestamp": time.time(),
+            "run_id": invocation_id,
+            "scope_id": self._scope_id(invocation_id),
+            "source": self._source(invocation_id, surface_id or item_id.split(":")[-1]),
+        }
+
+    async def _append(self, event: RuntimeEvent) -> RuntimeEvent:
+        await self._store.append_one(self._session_id, event)
         return event
 
     # ---- 三种交互 ----
@@ -81,24 +136,31 @@ class A2UICore:
         invocation_id: str,
         origin: str = "local",
     ) -> str:
-        """展示 surface(不阻塞)。首显发 surface.begin,重复显发 surface.update。"""
+        """展示 surface(不阻塞)。首显发 item.started,重复显发 item.updated。"""
         surface.validate(self._catalog)
-        event_type = (
-            EventType.A2UI_SURFACE_BEGIN
-            if surface.surface_id not in self._seen_surfaces
-            else EventType.A2UI_SURFACE_UPDATE
-        )
+        item_id = self._surface_item_id(invocation_id, surface.surface_id)
+        part_id = "a2ui-surface"
+        surface_data = surface.to_dict()
+        is_new = surface.surface_id not in self._seen_surfaces
         self._seen_surfaces.add(surface.surface_id)
-        await self._emit(
-            event_type,
-            invocation_id,
-            {
-                "surface_id": surface.surface_id,
-                "catalog_id": surface.catalog_id,
-                "surface": surface.to_dict(),
-                "origin": origin,
-            },
-        )
+        if is_new:
+            event = ItemStarted(
+                **self._envelope(invocation_id, item_id, "item.started", part_id, surface_id=surface.surface_id),
+                item_id=item_id,
+                item_kind="data",
+                initial=ContentSnapshot(
+                    parts=(DataContent(part_id=part_id, data=surface_data),)
+                ),
+            )
+        else:
+            event = ItemUpdated(
+                **self._envelope(invocation_id, item_id, "item.updated", part_id, surface_id=surface.surface_id),
+                item_id=item_id,
+                item_kind="data",
+                op="replace",
+                update=DataContent(part_id=part_id, data=surface_data),
+            )
+        await self._append(event)
         return surface.surface_id
 
     async def request_ui_input(
@@ -117,23 +179,77 @@ class A2UICore:
         """
         # 先展示(确保 surface 已渲染),再请求输入。
         await self.display_ui(surface, invocation_id=invocation_id, origin=origin)
+        interaction_id = f"int_{uuid.uuid4().hex[:12]}"
+        if self._ledger is not None and self._guard is not None:
+            # Phase 1 Task 5 Step 6:durable ledger 是 pending interaction 的
+            # 唯一权威;持久化身份与 interaction.requested 事实由 ledger 落盘。
+            from datetime import datetime, timezone
+
+            from ksadk.interaction.contracts import InteractionRecord
+
+            record = InteractionRecord(
+                interaction_id=interaction_id,
+                tenant_id=self._tenant_id,
+                agent_instance_id=self._agent_id,
+                session_id=self._session_id,
+                run_id=invocation_id,
+                kind="structured_input",
+                request_schema=dict(schema),
+                created_at=datetime.now(timezone.utc).isoformat(),
+            )
+            stored = await self._ledger.request(record, guard=self._guard)
+            interaction = PendingInteraction(
+                interaction_id=stored.interaction_id,
+                surface_id=surface.surface_id,
+                kind=kind,
+                input_schema=dict(schema),
+                status=stored.status,
+            )
+            self._pending[interaction.interaction_id] = interaction
+            # canonical A2UI wire 事实照常产出(durable 权威在 ledger)。
+            item_id = stable_item_id(
+                "ksadk", self._session_id, invocation_id,
+                "a2ui-interaction", interaction.interaction_id,
+            )
+            from ksadk.events.canonical import StructuredInputRequest
+
+            request = StructuredInputRequest(prompt=None, schema=dict(schema))
+            event = InteractionRequested(
+                **self._envelope(
+                    invocation_id, item_id, "interaction.requested", "a2ui-interaction"
+                ),
+                interaction_id=interaction.interaction_id,
+                interaction_kind="structured_input",
+                request=request,
+            )
+            event.source.metadata["surface_id"] = surface.surface_id
+            event.source.metadata["kind"] = kind
+            await self._append(event)
+            return interaction
         interaction = PendingInteraction(
-            interaction_id=f"int_{uuid.uuid4().hex[:12]}",
+            interaction_id=interaction_id,
             surface_id=surface.surface_id,
             kind=kind,
             input_schema=dict(schema),
         )
         self._pending[interaction.interaction_id] = interaction
-        await self._emit(
-            EventType.A2UI_INTERACTION,
-            invocation_id,
-            {
-                "surface_id": surface.surface_id,
-                "interaction_id": interaction.interaction_id,
-                "kind": kind,
-                "input_schema": dict(schema),
-            },
+        item_id = stable_item_id(
+            "ksadk", self._session_id, invocation_id, "a2ui-interaction", interaction.interaction_id
         )
+        from ksadk.events.canonical import StructuredInputRequest
+
+        request = StructuredInputRequest(prompt=None, schema=dict(schema))
+        event = InteractionRequested(
+            **self._envelope(
+                invocation_id, item_id, "interaction.requested", "a2ui-interaction"
+            ),
+            interaction_id=interaction.interaction_id,
+            interaction_kind="structured_input",
+            request=request,
+        )
+        event.source.metadata["surface_id"] = surface.surface_id
+        event.source.metadata["kind"] = kind
+        await self._append(event)
         return interaction
 
     async def submit_action(
@@ -145,7 +261,10 @@ class A2UICore:
     ) -> ActionReceipt:
         """非阻塞 action(原 run 可已结束):登记 action.received,返回幂等回执。
 
-        ``action``: ``{"action_id","surface_id","name","actor"?,"component_id"?}``。
+        ``action``: ``{"action_id","surface_id","name","actor"?,"component_id"?}``;
+        携带 ``interaction_id`` 且配置了 InteractionLedger 时,对原 ID 建
+        InteractionSubmission 走 durable resolve,不再发第二个
+        InteractionRequested(Phase 1 Task 5 Step 6)。
         """
         receipt = ActionReceipt(
             action_id=str(action.get("action_id") or f"act_{uuid.uuid4().hex[:12]}"),
@@ -154,33 +273,83 @@ class A2UICore:
             actor=str(action.get("actor") or "user"),
             status="received",
         )
-        await self._emit(
-            EventType.A2UI_ACTION,
-            invocation_id,
-            {
-                "surface_id": receipt.surface_id,
+        if (
+            self._ledger is not None
+            and self._guard is not None
+            and action.get("interaction_id")
+        ):
+            # durable 路径:对原 interaction 建 submission(first-wins),
+            # 不再产出第二个 interaction.requested 事实。
+            from ksadk.interaction.contracts import InteractionSubmission
+
+            submission = InteractionSubmission(
+                interaction_id=str(action["interaction_id"]),
+                expected_revision=int(action.get("expected_revision") or 1),
+                action="submit",
+                response=dict(action),
+                idempotency_key=f"a2ui-action:{receipt.action_id}",
+            )
+            resolved = await self._ledger.resolve(submission, guard=self._guard)
+            receipt.status = resolved.status
+            pending = self._pending.get(submission.interaction_id)
+            if pending is not None:
+                pending.status = resolved.status
+            return receipt
+        item_id = stable_item_id(
+            "ksadk", self._session_id, invocation_id, "a2ui-action", receipt.action_id
+        )
+        from ksadk.events.canonical import ApprovalRequest
+
+        request = ApprovalRequest(
+            call_id=None,
+            kind="a2ui_action",
+            detail={
                 "action_id": receipt.action_id,
+                "surface_id": receipt.surface_id,
                 "name": receipt.name,
                 "actor": receipt.actor,
                 "component_id": action.get("component_id"),
                 "origin": origin,
             },
         )
+        event = InteractionRequested(
+            **self._envelope(
+                invocation_id, item_id, "interaction.requested", "a2ui-action"
+            ),
+            interaction_id=receipt.action_id,
+            interaction_kind="approval",
+            request=request,
+        )
+        await self._append(event)
         return receipt
 
     async def end_surface(self, surface_id: str, *, invocation_id: str) -> None:
-        """结束 surface(surface.end)。"""
-        await self._emit(
-            EventType.A2UI_SURFACE_END,
-            invocation_id,
-            {"surface_id": surface_id},
+        """结束 surface(item.completed)。"""
+        item_id = self._surface_item_id(invocation_id, surface_id)
+        event = ItemCompleted(
+            **self._envelope(invocation_id, item_id, "item.completed", "a2ui-surface", surface_id=surface_id),
+            item_id=item_id,
+            item_kind="data",
+            snapshot=ContentSnapshot(parts=()),
         )
+        await self._append(event)
         self._seen_surfaces.discard(surface_id)
 
     # ---- 查询 ----
 
     def pending_interaction(self, interaction_id: str) -> Optional[PendingInteraction]:
+        """查询 pending interaction。
+
+        配置了 ledger 时,durable 台账是权威;本地缓存条目由
+        request_ui_input / submit_action 随 durable 事实同步更新。
+        """
         return self._pending.get(interaction_id)
 
+    async def pending_interaction_record(self, interaction_id: str):
+        """durable 视角:从 InteractionLedger 读取 InteractionRecord。"""
+        if self._ledger is None:
+            return None
+        return await self._ledger.get(interaction_id)
+
 
 __all__ = ["A2UICore"]

ksadk/agui/_agent_helpers.py

@@ -0,0 +1,243 @@
+"""KsadkAGUIAgent 的静态辅助函数（纯移动自 ``ksadk.agui.agent``，行为不变）。
+
+类内保留同名 staticmethod 委托，对外 ``KsadkAGUIAgent._x`` 调用面不变。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any, Mapping
+
+from ag_ui.core import Interrupt, RunAgentInput
+
+from ksadk.agui.a2ui_projection import project_a2ui_operations
+from ksadk.events.canonical import (
+    ContentSnapshot,
+    InteractionRequested,
+    ItemCompleted,
+    ItemStarted,
+    ItemUpdated,
+)
+from ksadk.events.content import DataContent, TextContent
+from ksadk.runtime.adapter import RunHandle
+
+if TYPE_CHECKING:
+    from ksadk.agui.agent import _ThreadRun
+
+
+def approval_decision_for_audit(status: str, payload: Any) -> str:
+    """Persist a stable decision value while accepting official AG-UI envelopes."""
+
+    if status != "resolved":
+        return "rejected"
+    if payload is True:
+        return "approved"
+    if isinstance(payload, Mapping):
+        for key in ("approve", "approved"):
+            if key in payload:
+                return "approved" if bool(payload[key]) else "rejected"
+        for key in ("decision", "type"):
+            if key in payload:
+                return approval_decision_for_audit(status, payload[key])
+        return "rejected"
+    if isinstance(payload, str) and payload.strip().lower() in {"approve", "approved"}:
+        return "approved"
+    return "rejected"
+
+
+def durable_handle(handle: RunHandle) -> dict[str, Any]:
+    allowed = {
+        "agent_id",
+        "user_id",
+        "checkpoint_id",
+        "known_checkpoint_ids",
+        "pending_approval_ids",
+        "framework_ref",
+        "thread_id",
+        "checkpoint_ns",
+        "resume_thread_id",
+    }
+    native_ref = {key: value for key, value in handle.native_ref.items() if key in allowed}
+    return {
+        "run_id": handle.run_id,
+        "session_id": handle.session_id,
+        "runtime_type": handle.runtime_type,
+        "native_ref": json_safe(native_ref),
+    }
+
+
+def interrupt_from_payload(payload: Mapping[str, Any]) -> Interrupt:
+    interrupt_id = str(payload.get("approval_id") or payload.get("call_id") or "")
+    raw_detail = payload.get("detail")
+    detail = raw_detail if isinstance(raw_detail, dict) else {}
+    return Interrupt(
+        id=interrupt_id,
+        reason=str(detail.get("reason") or payload.get("kind") or "approval"),
+        message=approval_message(detail, payload),
+        tool_call_id=str(payload.get("call_id") or "") or None,
+        response_schema=detail.get("response_schema"),
+        metadata=approval_metadata(detail, payload),
+    )
+
+
+def interrupt_from_interaction(event: InteractionRequested) -> Interrupt:
+    detail = event.request.detail if isinstance(event.request.detail, dict) else {}
+    payload = {
+        "approval_id": event.interaction_id,
+        "call_id": event.request.call_id or "",
+        "kind": event.request.kind,
+        "detail": detail,
+    }
+    return interrupt_from_payload(payload)
+
+
+def extract_text(snapshot: ContentSnapshot | None) -> str:
+    if snapshot is None:
+        return ""
+    for part in snapshot.parts:
+        if isinstance(part, TextContent):
+            return part.text
+    return ""
+
+
+def first_part(snapshot: ContentSnapshot | None) -> Any:
+    if snapshot is None or not snapshot.parts:
+        return None
+    return snapshot.parts[0]
+
+
+def a2ui_operations(
+    event: ItemStarted | ItemUpdated | ItemCompleted,
+    surface_id: str,
+) -> list[dict[str, Any]]:
+    if isinstance(event, ItemStarted):
+        part = first_part(event.initial)
+        if isinstance(part, DataContent):
+            if isinstance(part.data, list):
+                return [dict(op) for op in part.data if isinstance(op, Mapping)]
+            if isinstance(part.data, Mapping):
+                # Surface data dict (surface_id, catalog_id, components, etc.)
+                # Use project_a2ui_operations to extract canonical operations.
+                return project_a2ui_operations("a2ui.surface.begin", dict(part.data))
+        return []
+    if isinstance(event, ItemUpdated):
+        if isinstance(event.update, DataContent):
+            if isinstance(event.update.data, list):
+                return [dict(op) for op in event.update.data if isinstance(op, Mapping)]
+            if isinstance(event.update.data, Mapping):
+                return project_a2ui_operations("a2ui.surface.update", dict(event.update.data))
+        return []
+    # ItemCompleted (end): produce deleteSurface to preserve AG-UI wire
+    if surface_id:
+        return [{"version": "v0.9", "deleteSurface": {"surfaceId": surface_id}}]
+    return []
+
+
+def duplicate_run(input: RunAgentInput) -> "_ThreadRun":
+    from ksadk.agui.agent import _ThreadRun
+
+    return _ThreadRun(
+        handle=RunHandle(
+            run_id=input.run_id,
+            session_id=input.thread_id,
+            runtime_type="ag-ui-duplicate",
+        )
+    )
+
+
+def json_safe(value: Any) -> Any:
+    return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+
+
+def latest_user_input(input: RunAgentInput) -> Any:
+    for message in reversed(input.messages):
+        if getattr(message, "role", None) == "user":
+            return getattr(message, "content", "")
+    return ""
+
+
+def input_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, Mapping):
+        return str(value.get("text") or value.get("content") or "").strip()
+    return str(value or "").strip()
+
+
+def approval_action(detail: Mapping[str, Any]) -> Mapping[str, Any]:
+    nested_request = detail.get("approval_requests")
+    actions = (
+        nested_request.get("action_requests")
+        if isinstance(nested_request, Mapping)
+        else detail.get("action_requests")
+    )
+    if isinstance(actions, list):
+        for action in actions:
+            if isinstance(action, Mapping):
+                return action
+    return {}
+
+
+def approval_metadata(
+    detail: Mapping[str, Any],
+    payload: Mapping[str, Any],
+) -> dict[str, Any]:
+    action = approval_action(detail)
+    arguments = (
+        action.get("args")
+        or action.get("arguments")
+        or detail.get("arguments")
+        or detail.get("args")
+        or payload.get("args")
+    )
+    metadata: dict[str, Any] = {
+        "tool_name": str(
+            action.get("name")
+            or detail.get("tool_name")
+            or payload.get("name")
+            or payload.get("kind")
+            or "approval"
+        ),
+        "arguments": arguments if arguments is not None else {},
+    }
+    approval_level = (
+        action.get("approval_level")
+        or detail.get("approval_level")
+        or payload.get("approval_level")
+    )
+    if approval_level:
+        metadata["approval_level"] = str(approval_level)
+    return metadata
+
+
+def approval_message(detail: Mapping[str, Any], payload: Mapping[str, Any]) -> str:
+    action = approval_action(detail)
+    return str(
+        action.get("description")
+        or detail.get("message")
+        or payload.get("message")
+        or "Approval required"
+    )
+
+
+def resume_fingerprint(status: str, payload: Any) -> Any:
+    return json.dumps([status, payload], sort_keys=True, ensure_ascii=False, default=str)
+
+
+__all__ = [
+    "a2ui_operations",
+    "approval_action",
+    "approval_decision_for_audit",
+    "approval_message",
+    "approval_metadata",
+    "durable_handle",
+    "duplicate_run",
+    "extract_text",
+    "first_part",
+    "input_text",
+    "interrupt_from_interaction",
+    "interrupt_from_payload",
+    "json_safe",
+    "latest_user_input",
+    "resume_fingerprint",
+]

ksadk/agui/a2ui_projection.py

@@ -5,11 +5,18 @@ from __future__ import annotations
 from collections.abc import Mapping
 from typing import Any
 
-from ksadk.events.runtime_event import EventType
-
 
 def project_a2ui_operations(event_type: str, payload: Mapping[str, Any]) -> list[dict[str, Any]]:
-    """Return A2UI v0.9 operations carried by an AG-UI activity event."""
+    """Return A2UI v0.9 operations carried by an AG-UI activity event.
+
+    公开承诺字段（契约声明见 ``ksadk/events/projections.py``）：
+    - 操作列表，每条形如 ``{"version": "v0.9", createSurface|updateComponents|
+      updateDataModel|deleteSurface: {...}}``，内层必含 ``surfaceId``；
+    - 无 surface 信息时返回空列表。
+
+    内部不保证字段：操作的构造来源（显式 operations vs 从 surface 推导）、
+    catalogId 缺省值之外的字段顺序与附加键。
+    """
 
     explicit = payload.get("operations", payload.get("a2ui_operations"))
     if isinstance(explicit, list):
@@ -18,7 +25,7 @@ def project_a2ui_operations(event_type: str, payload: Mapping[str, Any]) -> list
     surface_id = str(payload.get("surface_id") or payload.get("surfaceId") or "")
     if not surface_id:
         return []
-    if event_type == EventType.A2UI_SURFACE_END:
+    if event_type == "a2ui.surface.end":
         return [{"version": "v0.9", "deleteSurface": {"surfaceId": surface_id}}]
 
     surface = payload.get("surface")
@@ -26,7 +33,7 @@ def project_a2ui_operations(event_type: str, payload: Mapping[str, Any]) -> list
     components = _flatten_components(surface_data.get("components"))
     data_model = surface_data.get("data_model", surface_data.get("dataModel"))
     operations: list[dict[str, Any]] = []
-    if event_type == EventType.A2UI_SURFACE_BEGIN:
+    if event_type == "a2ui.surface.begin":
         catalog_id = str(
             surface_data.get("catalog_id")
             or surface_data.get("catalogId")