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

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
@@ -49,6 +72,19 @@ class _HarnessRun:
     done: bool = False
 
 
+@dataclass
+class _HarnessSession:
+    """Process-local transcript and serialization boundary for one Session.
+
+    The public capability matrix deliberately advertises process-scoped,
+    non-durable continuity.  Keeping this state on the adapter makes that
+    declaration true without pretending that a restart can recover it.
+    """
+
+    messages: list[dict[str, Any]]
+    lock: asyncio.Lock
+
+
 class HarnessRuntimeAdapter(RuntimeAdapter):
     """Execute a YAML Harness config directly as RuntimeEvent streams."""
 
@@ -72,6 +108,7 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         self._tools: tuple[HarnessTool, ...] | None = None
         self._tool_lock = asyncio.Lock()
         self._mcp_toolsets: list[Any] = []
+        self._sessions: dict[tuple[str, str, str], _HarnessSession] = {}
 
     @property
     def harness_config(self) -> HarnessConfig:
@@ -144,16 +181,43 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         if not self._runs:
             await self._close_tools()
 
+    async def close_all(self) -> None:
+        """Dispose every process-local run owned by this adapter instance."""
+
+        for run_id, run in list(self._runs.items()):
+            await self.close(
+                RunHandle(
+                    run_id=run_id,
+                    session_id=run.request.session_id,
+                    runtime_type="harness",
+                    native_ref={
+                        "user_id": run.request.user_id,
+                        "agent_id": run.request.agent_id,
+                    },
+                )
+            )
+
     def is_handle_attached(self, handle: RunHandle) -> bool:
         return handle.run_id in self._runs
 
     async def execute_request(self, request: StartRequest) -> dict[str, Any]:
+        session = self._session_for(request)
+        async with session.lock:
+            return await self._execute_session_request(request, session)
+
+    async def _execute_session_request(
+        self,
+        request: StartRequest,
+        session: _HarnessSession,
+    ) -> dict[str, Any]:
         tools = await self._ensure_tools()
         model, prompt = self._effective(request)
         messages: list[dict[str, Any]] = [
             {"role": "system", "content": prompt},
-            {"role": "user", "content": str(request.input or "")},
+            *[dict(message) for message in session.messages],
         ]
+        user_message = {"role": "user", "content": str(request.input or "")}
+        messages.append(user_message)
         execution_log: list[dict[str, Any]] = []
 
         for _turn_number in range(_MAX_REASONING_TURNS):
@@ -212,6 +276,12 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
                 raise RuntimeError(
                     "Harness reasoner returned neither a final response nor a tool call"
                 )
+            final_message = {"role": "assistant", "content": turn.final_text}
+            messages.append(final_message)
+            # Failed or cancelled turns never commit a partial transcript.
+            # A successful turn atomically replaces the process-local history
+            # while the per-session lock is still held.
+            session.messages[:] = [dict(message) for message in messages[1:]]
             return {
                 "output": turn.final_text,
                 "model": model,
@@ -221,6 +291,18 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
             }
         raise RuntimeError(f"Harness reasoning exceeded {_MAX_REASONING_TURNS} turns")
 
+    def _session_for(self, request: StartRequest) -> _HarnessSession:
+        key = (
+            str(request.agent_id or self._agent_name),
+            str(request.user_id),
+            str(request.session_id),
+        )
+        session = self._sessions.get(key)
+        if session is None:
+            session = _HarnessSession(messages=[], lock=asyncio.Lock())
+            self._sessions[key] = session
+        return session
+
     def _effective(self, request: StartRequest) -> tuple[str, str]:
         metadata = request.metadata or {}
         model = str(
@@ -237,86 +319,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",
+]

ksadk/interaction/contracts.py

@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+"""Interaction/v1 冻结合同（对齐 contracts/agent-kernel/v1/interaction.schema.json）。
+
+Wire 模型与 JSON Schema 一一对应；``InteractionRecord`` 是内核侧的完整
+durable 行（含内部 ``provider_id`` / ``native_target`` / 不透明的
+``continuation_metadata``），对外投影（SessionEvent payload、公共 API 返回）
+必须省略这三个字段。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Union
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+InteractionKind = Literal["approval", "structured_input", "plan_review", "custom"]
+InteractionStatus = Literal[
+    "pending", "resolving", "resolved", "cancelled", "expired"
+]
+InteractionAction = Literal["approve", "reject", "submit", "cancel"]
+InteractionOutcome = Literal[
+    "approved", "rejected", "submitted", "cancelled", "expired"
+]
+
+
+class _StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class A2UIPresentation(_StrictModel):
+    wire_version: Literal["0.9.1"] = "0.9.1"
+    catalog_digest: str
+    messages: list[dict[str, Any]]
+
+
+class InteractionPresentation(_StrictModel):
+    title: str
+    description: str | None = None
+    a2ui: A2UIPresentation | None = None
+
+
+class InteractionRecord(_StrictModel):
+    """一条 interaction 的 durable 状态行（内部权威形态）。
+
+    公开投影（``public_request()`` / interaction.requested 事件 payload）
+    省略 ``provider_id`` / ``native_target`` / ``continuation_metadata``。
+    """
+
+    schema_version: Literal[1] = 1
+    interaction_id: str
+    tenant_id: str
+    agent_instance_id: str
+    session_id: str
+    run_id: str
+    kind: InteractionKind
+    request_schema: dict[str, Any]
+    revision: int = 1
+    status: InteractionStatus = "pending"
+    created_at: str
+    expires_at: str | None = None
+    presentation: InteractionPresentation | None = None
+    # ---- 内部字段：绝不进入公共事件 / 公共 API 投影 ----
+    provider_id: str = ""
+    native_target: dict[str, Any] | None = None
+    continuation_metadata: dict[str, Any] | None = None
+
+    def public_request(self) -> dict[str, Any]:
+        """interactionRequest 投影（schema additionalProperties=false）。"""
+        payload: dict[str, Any] = {
+            "schema_version": self.schema_version,
+            "interaction_id": self.interaction_id,
+            "tenant_id": self.tenant_id,
+            "agent_instance_id": self.agent_instance_id,
+            "session_id": self.session_id,
+            "run_id": self.run_id,
+            "kind": self.kind,
+            "request_schema": self.request_schema,
+            "revision": self.revision,
+            "created_at": self.created_at,
+        }
+        if self.expires_at is not None:
+            payload["expires_at"] = self.expires_at
+        if self.presentation is not None:
+            payload["presentation"] = self.presentation.model_dump(mode="json")
+        return payload
+
+
+class InteractionSubmission(_StrictModel):
+    """用户对一条 pending interaction 的提交（submitInteractionRequest）。"""
+
+    schema_version: Literal[1] = 1
+    interaction_id: str
+    expected_revision: int
+    action: InteractionAction
+    response: Any = None
+    idempotency_key: str
+
+
+class InteractionReceipt(_StrictModel):
+    schema_version: Literal[1] = 1
+    interaction_id: str
+    revision: int
+    status: InteractionStatus
+    outcome: InteractionOutcome | None = None
+    event_id: UUID | str | None = None
+    accepted_seq: int | None = None
+
+
+RESOLVE_OUTCOMES: dict[str, InteractionOutcome] = {
+    "approve": "approved",
+    "reject": "rejected",
+    "submit": "submitted",
+}
+
+TERMINAL_STATUSES = frozenset({"resolved", "cancelled", "expired"})
+
+
+def is_terminal(status: str) -> bool:
+    return status in TERMINAL_STATUSES
+
+
+__all__ = [
+    "A2UIPresentation",
+    "InteractionAction",
+    "InteractionKind",
+    "InteractionOutcome",
+    "InteractionPresentation",
+    "InteractionRecord",
+    "InteractionReceipt",
+    "InteractionStatus",
+    "InteractionSubmission",
+    "RESOLVE_OUTCOMES",
+    "TERMINAL_STATUSES",
+    "is_terminal",
+]