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

ksadk/events/store.py

@@ -1,317 +1,4 @@
-"""RuntimeEventStore — 统一事件 store + 两类订阅 + projection (goal-10,H2 §4.3)。
+"""Public canonical RuntimeEvent storage implementation."""
 
-复用现有 ``SessionEvent(seq_id cursor)`` 持久化骨架(session service),**不另造存储、
-不改表**:RuntimeEvent 的 ``phase``/``payload``/``schema_version``/``user_id`` 打包进
-``SessionEvent.content``/``metadata``(均为自由 dict),并以 ``_RUNTIME_MARKER`` 标记区分
-legacy session 事件(assistant_message/run_status 等),读取时只还原 runtime 事件。
-
-- ``append`` / ``list``:RuntimeEvent ↔ SessionEvent 双向映射。
-- ``subscribe_run``:单 invocation,终态(completed/failed/canceled)后关闭(对齐现有
-  run 级 SSE 语义,新 schema)。
-- ``subscribe_session``:session 级 cursor stream,跨 invocation,支持 run 后 action 与
-  replay(A2UI 依赖)。
-- ``project``:replay / 增量 projection(fold)。
-- cursor 断线续传:订阅方持 ``last_seq_id``,断线后按 ``after_seq_id`` 重连,不丢不重。
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from typing import Any, AsyncIterator, Callable, Iterable, Optional
-
-from ksadk.events.runtime_event import EventType, RuntimeEvent
-from ksadk.sessions.base import SessionEvent
-
-logger = logging.getLogger(__name__)
-
-#: SessionEvent.metadata 中的标记:该条是由 RuntimeEvent 持久化来的(区分 legacy 事件)。
-_RUNTIME_MARKER = "ksadk_runtime_event"
-_A2A_TASK_AGENT_STATE_KEY = "__ksadk_a2a_task_agents"
-
-#: run 终态(subscribe_run 遇到即关闭;interrupted 是 input-required 暂停,非终态)。
-_RUN_TERMINAL_EVENT_TYPES = frozenset(
-    {
-        EventType.RUN_COMPLETED,
-        EventType.RUN_FAILED,
-        EventType.RUN_CANCELED,
-    }
-)
-
-#: 默认订阅轮询间隔(秒)与单条流上限(秒,防泄漏)。
-_DEFAULT_POLL_INTERVAL = 0.25
-_DEFAULT_STREAM_TIMEOUT = 5 * 60
-
-
-# ---------------------------------------------------------------------------
-# RuntimeEvent ↔ SessionEvent 映射
-# ---------------------------------------------------------------------------
-
-
-def runtime_event_to_session_event(event: RuntimeEvent) -> SessionEvent:
-    """把 RuntimeEvent 打包为 SessionEvent(content/metadata 承载新 schema 字段,不改表)。"""
-    event.validate_conformance()
-    return SessionEvent(
-        id=event.event_id,
-        session_id=event.session_id,
-        author=event.agent_id,
-        event_type=event.event_type,
-        content={"phase": event.phase, "payload": dict(event.payload)},
-        timestamp=event.timestamp,
-        seq_id=event.seq_id,
-        invocation_id=event.invocation_id,
-        metadata={
-            _RUNTIME_MARKER: True,
-            "user_id": event.user_id,
-            "schema_version": event.schema_version,
-        },
-    )
-
-
-def session_event_to_runtime_event(event: SessionEvent) -> Optional[RuntimeEvent]:
-    """把 SessionEvent 还原为 RuntimeEvent;非 runtime 事件(无标记)返回 None。"""
-    if not (event.metadata or {}).get(_RUNTIME_MARKER):
-        return None
-    content = event.content or {}
-    return RuntimeEvent.create(
-        event.event_type,
-        agent_id=event.author,
-        user_id=str(event.metadata.get("user_id") or ""),
-        session_id=event.session_id,
-        invocation_id=event.invocation_id or "",
-        seq_id=event.seq_id,
-        payload=dict(content.get("payload") or {}),
-        phase=content.get("phase"),
-        event_id=event.id,
-        timestamp=event.timestamp,
-    )
-
-
-# ---------------------------------------------------------------------------
-# RuntimeEventStore
-# ---------------------------------------------------------------------------
-
-
-class RuntimeEventStore:
-    """统一事件 store(复用 session service 的 seq_id cursor 持久化骨架)。"""
-
-    def __init__(self, session_service: Any) -> None:
-        self._service = session_service
-
-    # ---- append ----
-
-    async def append(self, events: Iterable[RuntimeEvent]) -> list[RuntimeEvent]:
-        """持久化一组 RuntimeEvent,返回存储层分配 cursor 后的事件。"""
-        appended: list[RuntimeEvent] = []
-        for event in events:
-            appended.append(await self.append_one(event))
-        return appended
-
-    async def append_one(self, event: RuntimeEvent) -> RuntimeEvent:
-        """Idempotently persist one event using its durable ``event_id``.
-
-        Replayed wire events return their original store-assigned cursor.  Reuse
-        of an ID for different content is rejected rather than silently losing a
-        legal event.
-        """
-        persisted, _created = await self.reserve_once(event)
-        return persisted
-
-    async def reserve_once(self, event: RuntimeEvent) -> tuple[RuntimeEvent, bool]:
-        """Durably claim ``event.event_id`` and report whether this caller won.
-
-        SQL backends enforce a unique event id, so this is also the command
-        reservation seam for side effects such as checkpoint resume.  A loser
-        receives the existing identical fact with ``created=False`` and must
-        not repeat the side effect.
-        """
-        existing = await self._event_by_id(event.session_id, event.event_id)
-        if existing is not None:
-            self._assert_same_event(existing, event)
-            return existing, False
-        try:
-            stored = await self._service.append_event(
-                event.session_id, runtime_event_to_session_event(event)
-            )
-        except Exception:
-            # Durable backends enforce a unique event id.  A concurrent writer
-            # may win between the read and append; resolve that race by reading
-            # the persisted fact and validating its content.
-            existing = await self._event_by_id(event.session_id, event.event_id)
-            if existing is None:
-                raise
-            self._assert_same_event(existing, event)
-            return existing, False
-        persisted = session_event_to_runtime_event(stored)
-        if persisted is None:  # pragma: no cover - marker is set above by construction
-            raise RuntimeError("RuntimeEvent 持久化后缺少 runtime marker")
-        return persisted, True
-
-    async def _event_by_id(self, session_id: str, event_id: str) -> RuntimeEvent | None:
-        raw = await self._service.get_events(session_id)
-        for stored in raw:
-            if stored.id != event_id:
-                continue
-            return session_event_to_runtime_event(stored)
-        return None
-
-    @staticmethod
-    def _assert_same_event(existing: RuntimeEvent, candidate: RuntimeEvent) -> None:
-        comparable = (
-            "event_type",
-            "agent_id",
-            "user_id",
-            "session_id",
-            "invocation_id",
-            "phase",
-            "payload",
-        )
-        if any(getattr(existing, field) != getattr(candidate, field) for field in comparable):
-            raise ValueError(f"RuntimeEvent id collision for {candidate.event_id!r}")
-
-    async def set_task_agent(self, session_id: str, task_id: str, agent_id: str) -> None:
-        """Persist the outbound A2A task locator in session state."""
-        session = await self._service.get_session_metadata(session_id)
-        if session is None:
-            raise ValueError(f"A2A space session {session_id!r} not found")
-        current = await self._service.get_state(
-            session.agent_id,
-            session.user_id,
-            session.id,
-            scope="session",
-        )
-        mapping = dict((current.state if current else {}).get(_A2A_TASK_AGENT_STATE_KEY) or {})
-        existing = mapping.get(task_id)
-        if existing and existing != agent_id:
-            raise ValueError(f"A2A task {task_id!r} is already bound to another agent")
-        mapping[task_id] = agent_id
-        await self._service.update_state(
-            agent_id=session.agent_id,
-            user_id=session.user_id,
-            session_id=session.id,
-            scope="session",
-            state_delta={_A2A_TASK_AGENT_STATE_KEY: mapping},
-        )
-
-    async def get_task_agent(self, session_id: str, task_id: str) -> str | None:
-        """Resolve a persisted outbound A2A task locator."""
-        session = await self._service.get_session_metadata(session_id)
-        if session is None:
-            return None
-        current = await self._service.get_state(
-            session.agent_id,
-            session.user_id,
-            session.id,
-            scope="session",
-        )
-        mapping = dict((current.state if current else {}).get(_A2A_TASK_AGENT_STATE_KEY) or {})
-        value = mapping.get(task_id)
-        return str(value) if value else None
-
-    # ---- list ----
-
-    async def list(
-        self,
-        session_id: str,
-        *,
-        after_seq_id: int = 0,
-        before_seq_id: Optional[int] = None,
-        invocation_id: Optional[str] = None,
-        limit: Optional[int] = None,
-    ) -> list[RuntimeEvent]:
-        """按 seq cursor 读 RuntimeEvent(升序;可按 invocation 过滤 / before 上界回放)。"""
-        raw = await self._service.get_events(
-            session_id,
-            after_seq_id=after_seq_id,
-            before_seq_id=before_seq_id,
-            limit=limit,
-        )
-        events = [e for e in (session_event_to_runtime_event(se) for se in raw) if e is not None]
-        if invocation_id is not None:
-            events = [e for e in events if e.invocation_id == invocation_id]
-        events.sort(key=lambda e: e.seq_id)
-        return events
-
-    # ---- 两类订阅 ----
-
-    async def subscribe_run(
-        self,
-        session_id: str,
-        invocation_id: str,
-        *,
-        after_seq_id: int = 0,
-        poll_interval: float = _DEFAULT_POLL_INTERVAL,
-        timeout: float = _DEFAULT_STREAM_TIMEOUT,
-    ) -> AsyncIterator[RuntimeEvent]:
-        """单 invocation 订阅:只产该 invocation 的 RuntimeEvent,终态后关闭。
-
-        断线续传:调用方持返回事件的 ``seq_id``,断线后以 ``after_seq_id`` 重连即可续传,
-        不丢(>after 的全部重发)、不重(<=after 的不重发)。
-        """
-        last = int(after_seq_id or 0)
-        deadline = asyncio.get_event_loop().time() + timeout
-        while True:
-            events = await self.list(session_id, after_seq_id=last, invocation_id=invocation_id)
-            for event in events:
-                last = max(last, event.seq_id)
-                yield event
-                if event.event_type in _RUN_TERMINAL_EVENT_TYPES:
-                    return
-            if asyncio.get_event_loop().time() > deadline:
-                return
-            await asyncio.sleep(poll_interval)
-
-    async def subscribe_session(
-        self,
-        session_id: str,
-        *,
-        after_seq_id: int = 0,
-        poll_interval: float = _DEFAULT_POLL_INTERVAL,
-        timeout: float = _DEFAULT_STREAM_TIMEOUT,
-    ) -> AsyncIterator[RuntimeEvent]:
-        """session 级 cursor stream:跨 invocation 产全部 RuntimeEvent(replay + live)。
-
-        支持 run 后 action 与跨 invocation replay(A2UI 依赖);断线续传同 subscribe_run。
-        """
-        last = int(after_seq_id or 0)
-        deadline = asyncio.get_event_loop().time() + timeout
-        while True:
-            events = await self.list(session_id, after_seq_id=last)
-            for event in events:
-                last = max(last, event.seq_id)
-                yield event
-            if asyncio.get_event_loop().time() > deadline:
-                return
-            await asyncio.sleep(poll_interval)
-
-    # ---- projection / replay ----
-
-    async def project(
-        self,
-        session_id: str,
-        projection: Optional[Callable[[Any, RuntimeEvent], Any]] = None,
-        *,
-        initial: Any = None,
-        after_seq_id: int = 0,
-        before_seq_id: Optional[int] = None,
-    ) -> Any:
-        """replay / projection。
-
-        默认(``projection=None``):返回按 seq 升序的 RuntimeEvent 序列(replay)。
-        给定 ``projection(acc, event) -> acc``:自 ``initial`` 起 fold 全部事件,支持
-        增量 projection(以 ``after_seq_id`` 从某个 checkpoint 续投影)。
-        """
-        events = await self.list(session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id)
-        if projection is None:
-            return events
-        acc = initial
-        for event in events:
-            acc = projection(acc, event)
-        return acc
-
-
-__all__ = [
-    "RuntimeEventStore",
-    "runtime_event_to_session_event",
-    "session_event_to_runtime_event",
-]
+from ksadk.events.canonical_store import *  # noqa: F403
+from ksadk.events.canonical_store import __all__

ksadk/events/v1_compat.py

@@ -0,0 +1,41 @@
+"""Read-only RuntimeEvent v1 wire compatibility.
+
+This module is the only owner of the legacy v1 envelope, parser, and the
+canonical-v2-to-v1 projection.  It is deliberately not a persistence or
+source-adapter boundary.
+
+Implementation lives in the :mod:`ksadk.events._v1_compat` subpackage
+(models / parser / projection); this module remains the stable import path.
+"""
+
+from __future__ import annotations
+
+from ksadk.events._v1_compat.models import (
+    ALL_V1_EVENT_TYPES,
+    V1_EVENT_PAYLOAD_REQUIRED_KEYS,
+    A2ATaskProjectionRef,
+    A2UIInteractionProjectionRef,
+    A2UISurfaceProjectionRef,
+    EventTypeV1,
+    RuntimeEventV1,
+    RuntimeEventV1ProjectionContext,
+    RuntimeEventV1ProjectionMode,
+    V1ProjectionContextRequiredError,
+)
+from ksadk.events._v1_compat.parser import RuntimeEventV1Parser
+from ksadk.events._v1_compat.projection import project_to_v1
+
+__all__ = [
+    "ALL_V1_EVENT_TYPES",
+    "A2ATaskProjectionRef",
+    "A2UIInteractionProjectionRef",
+    "A2UISurfaceProjectionRef",
+    "EventTypeV1",
+    "RuntimeEventV1",
+    "RuntimeEventV1Parser",
+    "RuntimeEventV1ProjectionContext",
+    "RuntimeEventV1ProjectionMode",
+    "V1ProjectionContextRequiredError",
+    "V1_EVENT_PAYLOAD_REQUIRED_KEYS",
+    "project_to_v1",
+]

ksadk/harness/runtime.py

@@ -4,12 +4,35 @@ from __future__ import annotations
 
 import asyncio
 import json
+import time
 import uuid
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from ksadk.events import EventPhase, EventType, RuntimeEvent
+from ksadk.events.canonical import (
+    ErrorInfo,
+    ItemCompleted,
+    ItemStarted,
+    ItemUpdated,
+    OutputRef,
+    RunCanceled,
+    RunCompleted,
+    RunFailed,
+    RunStarted,
+    SourceRef,
+)
+from ksadk.events.content import (
+    ContentSnapshot,
+    TextContent,
+    ToolCallContent,
+    ToolResultContent,
+)
+from ksadk.events.identity import (
+    stable_event_id,
+    stable_item_id,
+    stable_scope_id,
+)
 from ksadk.harness.config import HarnessConfig
 from ksadk.harness.reasoner import HarnessReasoner, LiteLLMHarnessReasoner
 from ksadk.harness.sandbox import HarnessSandboxExecutor
@@ -237,86 +260,166 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
 
     async def _stream(self, handle: RunHandle):
         run = self._require_run(handle)
+        framework = "ksadk"
+        run_id = handle.run_id
+        scope_id = stable_scope_id(framework, run_id)
+        message_item_id = stable_item_id(framework, run_id, "message", "final_answer")
+        run_item_id = stable_item_id(framework, run_id, "$run")
         seq = 0
+        started_items: set[tuple[str, str]] = set()
 
-        def event(
-            event_type: str,
-            payload: dict[str, Any],
-            *,
-            phase: str | None = None,
-        ) -> RuntimeEvent:
+        def next_seq() -> int:
             nonlocal seq
             seq += 1
-            request = run.request
-            return RuntimeEvent.create(
-                event_type,
-                agent_id=str(request.agent_id or self._agent_name),
-                user_id=request.user_id,
-                session_id=request.session_id,
-                invocation_id=handle.run_id,
-                seq_id=seq,
-                payload=payload,
-                phase=phase,
+            return seq
+
+        def make_source() -> SourceRef:
+            return SourceRef(
+                framework=framework,
+                native_run_id=run_id,
+                metadata={
+                    "agent_id": str(run.request.agent_id or self._agent_name),
+                    "user_id": run.request.user_id,
+                    "session_id": run.request.session_id,
+                    "invocation_id": run_id,
+                },
             )
 
+        def env_kwargs(
+            item_id: str, event_type: str, part_id: str
+        ) -> dict[str, Any]:
+            n = next_seq()
+            return {
+                "schema_version": 2,
+                "event_id": stable_event_id(
+                    framework, scope_id, item_id, event_type, part_id, run_id, n
+                ),
+                "seq": n,
+                "timestamp": time.time(),
+                "run_id": run_id,
+                "scope_id": scope_id,
+                "source": make_source(),
+            }
+
+        def ensure_started(
+            item_id: str,
+            item_kind: str,
+            phase: str | None = None,
+            initial: ContentSnapshot | None = None,
+        ) -> list[ItemStarted]:
+            key = (scope_id, item_id)
+            if key in started_items:
+                return []
+            started_items.add(key)
+            return [
+                ItemStarted(
+                    **env_kwargs(item_id, "item.started", "item"),
+                    item_id=item_id,
+                    item_kind=item_kind,
+                    phase=phase,
+                    initial=initial,
+                )
+            ]
+
         if run.pending_cancel:
             run.done = True
-            yield event(
-                EventType.RUN_CANCELED,
-                {
-                    "status": "cancelled",
-                    "cancel_result": CancelResult.PENDING_CANCEL_RECORDED.value,
-                },
+            yield RunCanceled(
+                **env_kwargs(run_item_id, "run.canceled", "run"),
+                status="canceled",
+                reason=CancelResult.PENDING_CANCEL_RECORDED.value,
             )
             return
-        yield event(EventType.RUN_STARTED, {"status": "in_progress"})
+        yield RunStarted(
+            **env_kwargs(run_item_id, "run.started", "run"),
+            status="running",
+        )
         run.task = asyncio.create_task(self.execute_request(run.request))
         try:
             result = await run.task
             for call in result["tool_calls"]:
-                yield event(
-                    EventType.TOOL_CALL_BEGIN,
-                    {
-                        "call_id": call["call_id"],
-                        "name": call["name"],
-                        "args": call["arguments"],
-                    },
-                )
-                yield event(
-                    EventType.TOOL_CALL_END,
-                    {
-                        "call_id": call["call_id"],
-                        "name": call["name"],
-                        "result": call["result"],
-                    },
+                call_id = call["call_id"]
+                tool_item_id = stable_item_id(framework, run_id, "tool_call", call_id)
+                for ev in ensure_started(
+                    item_id=tool_item_id,
+                    item_kind="tool_call",
+                    initial=ContentSnapshot(
+                        parts=(
+                            ToolCallContent(
+                                part_id="tool-0",
+                                call_id=call_id,
+                                name=call["name"],
+                                arguments=call["arguments"],
+                            ),
+                        )
+                    ),
+                ):
+                    yield ev
+                yield ItemCompleted(
+                    **env_kwargs(tool_item_id, "item.completed", "tool-0"),
+                    item_id=tool_item_id,
+                    item_kind="tool_call",
+                    snapshot=ContentSnapshot(
+                        parts=(
+                            ToolResultContent(
+                                part_id="tool-0",
+                                call_id=call_id,
+                                result=call["result"],
+                            ),
+                        )
+                    ),
                 )
             text = str(result["output"])
-            yield event(
-                EventType.TEXT_DELTA,
-                {"text": text},
-                phase=EventPhase.FINAL_ANSWER.value,
+            for ev in ensure_started(
+                item_id=message_item_id,
+                item_kind="message",
+                phase="final_answer",
+            ):
+                yield ev
+            yield ItemUpdated(
+                **env_kwargs(message_item_id, "item.updated", "text-0"),
+                item_id=message_item_id,
+                item_kind="message",
+                op="append",
+                update=TextContent(part_id="text-0", text=text),
             )
-            yield event(
-                EventType.TEXT_COMPLETED,
-                {"text": text},
-                phase=EventPhase.FINAL_ANSWER.value,
+            yield ItemCompleted(
+                **env_kwargs(message_item_id, "item.completed", "text-0"),
+                item_id=message_item_id,
+                item_kind="message",
+                snapshot=ContentSnapshot(
+                    parts=(TextContent(part_id="text-0", text=text),)
+                ),
             )
             run.done = True
-            yield event(EventType.RUN_COMPLETED, {"status": "completed"})
+            yield RunCompleted(
+                **env_kwargs(run_item_id, "run.completed", "run"),
+                status="completed",
+                output_refs=(
+                    OutputRef(
+                        scope_id=scope_id,
+                        item_id=message_item_id,
+                        part_id="text-0",
+                    ),
+                ),
+            )
         except asyncio.CancelledError:
             run.done = True
-            yield event(
-                EventType.RUN_CANCELED,
-                {
-                    "status": "cancelled",
-                    "cancel_result": CancelResult.INTERRUPTED_ACTIVE_TURN.value,
-                },
+            yield RunCanceled(
+                **env_kwargs(run_item_id, "run.canceled", "run"),
+                status="canceled",
+                reason=CancelResult.INTERRUPTED_ACTIVE_TURN.value,
             )
         except Exception as exc:  # noqa: BLE001
             run.done = True
-            yield event(
-                EventType.RUN_FAILED,
-                {"status": "failed", "error": str(exc)},
+            yield RunFailed(
+                **env_kwargs(run_item_id, "run.failed", "run"),
+                status="failed",
+                error=ErrorInfo(
+                    code="harness_failed",
+                    message=str(exc),
+                    source=framework,
+                    scope_id=scope_id,
+                ),
             )
 
     def _require_run(self, handle: RunHandle) -> _HarnessRun:

ksadk/identity/resolver.py

@@ -305,9 +305,10 @@ def resolve_identity(
             access_keys = _call_list_all_user_access_keys(client, sdk_parts)
             user_name = _find_username_by_ak(access_keys, access_key)
             if not user_name:
-                # AK 不在子用户列表（可能是主账号 AK），无法反查 user uuid
-                logger.warning(
-                    "AK 指纹 %s 未在 ListAllUserAccessKeys 找到匹配（可能是主账号 AK）",
+                # 主账号 AK 不会出现在子用户列表，属预期路径：无子账号 uuid 可反查，
+                # 调用方将只注入主账号维度 header（account_id）。
+                logger.info(
+                    "AK 为主账号密钥（指纹 %s），按主账号身份使用，不注入子账号 uuid",
                     fingerprint,
                 )
                 return None

ksadk/interaction/__init__.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+"""Durable Interaction ledger（Phase 1 Task 5，Interaction/v1）。"""
+
+from ksadk.interaction.contracts import (
+    InteractionRecord,
+    InteractionReceipt,
+    InteractionSubmission,
+)
+from ksadk.interaction.ledger import InteractionLedger
+from ksadk.interaction.provider import (
+    RUNTIME_INTERACTION_UNAVAILABLE,
+    InteractionProvider,
+    InteractionProviderMode,
+    InteractionResolveContext,
+    UnavailableInteractionProvider,
+)
+
+__all__ = [
+    "RUNTIME_INTERACTION_UNAVAILABLE",
+    "InteractionLedger",
+    "InteractionProvider",
+    "InteractionProviderMode",
+    "InteractionRecord",
+    "InteractionReceipt",
+    "InteractionResolveContext",
+    "InteractionSubmission",
+    "UnavailableInteractionProvider",
+]