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

ksadk/harness/runtime.py

@@ -0,0 +1,467 @@
+"""Native RuntimeAdapter for YAML Harness agents."""
+
+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.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
+from ksadk.harness.tools import HarnessTool, load_mcp_tools, sandbox_tools, tool_result_text
+from ksadk.runtime import (
+    BaseRuntime,
+    CancelResult,
+    CheckpointCapability,
+    CheckpointDescriptor,
+    ResumePayload,
+    ResumeTarget,
+    RunHandle,
+    RuntimeAdapter,
+    StartRequest,
+)
+
+_MAX_REASONING_TURNS = 8
+
+
+class HarnessRuntime(BaseRuntime):
+    runtime_type = "harness"
+
+    def native_capabilities(self) -> dict[str, Any]:
+        return {
+            "cancel": {"supported": True},
+            "resume": {"supported": False},
+            "checkpoint": {"supported": False, "granularity": "none"},
+            "session_continuity": {"durable": False, "scope": "process"},
+        }
+
+
+@dataclass
+class _HarnessRun:
+    request: StartRequest
+    task: asyncio.Task[dict[str, Any]] | None = None
+    pending_cancel: bool = False
+    done: bool = False
+
+
+class HarnessRuntimeAdapter(RuntimeAdapter):
+    """Execute a YAML Harness config directly as RuntimeEvent streams."""
+
+    def __init__(
+        self,
+        config: HarnessConfig,
+        *,
+        agent_name: str = "harness-agent",
+        reasoner: HarnessReasoner | None = None,
+        workspace_root: str | Path = ".",
+    ) -> None:
+        super().__init__(HarnessRuntime())
+        self._config = config
+        self._agent_name = agent_name
+        self._reasoner = reasoner or LiteLLMHarnessReasoner()
+        self._sandbox = HarnessSandboxExecutor(
+            workspace_root=workspace_root,
+            read_only=config.sandbox.read_only,
+        )
+        self._runs: dict[str, _HarnessRun] = {}
+        self._tools: tuple[HarnessTool, ...] | None = None
+        self._tool_lock = asyncio.Lock()
+        self._mcp_toolsets: list[Any] = []
+
+    @property
+    def harness_config(self) -> HarnessConfig:
+        return self._config
+
+    @property
+    def sandbox(self) -> HarnessSandboxExecutor:
+        return self._sandbox
+
+    @property
+    def workspace_root(self) -> Path:
+        return self._sandbox.workspace_root
+
+    async def start(self, request: StartRequest) -> RunHandle:
+        run_id = str(request.metadata.get("invocation_id") or f"harness_{uuid.uuid4().hex}")
+        if run_id in self._runs:
+            raise ValueError(f"duplicate Harness invocation: {run_id}")
+        self._runs[run_id] = _HarnessRun(request=request)
+        return RunHandle(
+            run_id=run_id,
+            session_id=request.session_id,
+            runtime_type="harness",
+            native_ref={"user_id": request.user_id, "agent_id": request.agent_id},
+        )
+
+    def stream(self, handle: RunHandle):
+        return self._stream(handle)
+
+    async def cancel(self, handle: RunHandle) -> CancelResult:
+        run = self._runs.get(handle.run_id)
+        if run is None or run.done:
+            return CancelResult.NOT_RUNNING
+        if run.task is None:
+            run.pending_cancel = True
+            return CancelResult.PENDING_CANCEL_RECORDED
+        if run.task.done():
+            return CancelResult.NOT_RUNNING
+        run.task.cancel()
+        return CancelResult.INTERRUPTED_ACTIVE_TURN
+
+    async def resume(
+        self,
+        handle: RunHandle,
+        target: ResumeTarget,
+        payload: ResumePayload | None,
+    ) -> RunHandle:
+        del handle, target, payload
+        raise RuntimeError("Harness runtime does not support resume")
+
+    async def checkpoint(self, handle: RunHandle) -> CheckpointDescriptor:
+        return CheckpointDescriptor(
+            checkpoint_id=f"unsupported:{handle.run_id}",
+            invocation_id=handle.run_id,
+            capability=CheckpointCapability(
+                supported=False,
+                granularity="none",
+                rollback_scope="none",
+                fork_supported=False,
+                durable=False,
+                shared_across_pods=False,
+                reason="Harness runtime has no checkpoint backend",
+            ),
+        )
+
+    async def close(self, handle: RunHandle) -> None:
+        run = self._runs.pop(handle.run_id, None)
+        if run is not None and run.task is not None and not run.task.done():
+            run.task.cancel()
+            await asyncio.gather(run.task, return_exceptions=True)
+        if not self._runs:
+            await self._close_tools()
+
+    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]:
+        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 "")},
+        ]
+        execution_log: list[dict[str, Any]] = []
+
+        for _turn_number in range(_MAX_REASONING_TURNS):
+            turn = await self._reasoner.complete(
+                model=model,
+                prompt=prompt,
+                messages=tuple(messages),
+                tools=tools,
+            )
+            if turn.tool_calls:
+                messages.append(
+                    {
+                        "role": "assistant",
+                        "content": turn.final_text,
+                        "tool_calls": [
+                            {
+                                "id": call.call_id,
+                                "type": "function",
+                                "function": {
+                                    "name": call.name,
+                                    "arguments": json.dumps(call.arguments, ensure_ascii=False),
+                                },
+                            }
+                            for call in turn.tool_calls
+                        ],
+                    }
+                )
+                for call in turn.tool_calls:
+                    tool = next((item for item in tools if item.name == call.name), None)
+                    if tool is None:
+                        raise RuntimeError(
+                            f"Harness tool {call.name!r} is not available; it may be filtered "
+                            "or was not exposed by its MCP server"
+                        )
+                    result = await tool.call(call.arguments, call_id=call.call_id)
+                    content = tool_result_text(result)
+                    execution_log.append(
+                        {
+                            "call_id": call.call_id,
+                            "name": call.name,
+                            "source": tool.source,
+                            "arguments": dict(call.arguments),
+                            "result": result,
+                        }
+                    )
+                    messages.append(
+                        {
+                            "role": "tool",
+                            "tool_call_id": call.call_id,
+                            "name": call.name,
+                            "content": content,
+                        }
+                    )
+                continue
+            if turn.final_text is None:
+                raise RuntimeError(
+                    "Harness reasoner returned neither a final response nor a tool call"
+                )
+            return {
+                "output": turn.final_text,
+                "model": model,
+                "prompt": prompt,
+                "tool_calls": execution_log,
+                "sandbox_read_only": self._config.sandbox.read_only,
+            }
+        raise RuntimeError(f"Harness reasoning exceeded {_MAX_REASONING_TURNS} turns")
+
+    def _effective(self, request: StartRequest) -> tuple[str, str]:
+        metadata = request.metadata or {}
+        model = str(
+            metadata.get("model_override") or request.model or self._config.model
+        ).strip()
+        prompt = str(
+            metadata.get("prompt_override")
+            or request.config.get("base_instructions")
+            or request.config.get("instructions")
+            or request.config.get("prompt")
+            or self._config.prompt
+        ).strip()
+        return model, prompt
+
+    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 next_seq() -> int:
+            nonlocal seq
+            seq += 1
+            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 RunCanceled(
+                **env_kwargs(run_item_id, "run.canceled", "run"),
+                status="canceled",
+                reason=CancelResult.PENDING_CANCEL_RECORDED.value,
+            )
+            return
+        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"]:
+                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"])
+            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 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 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 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 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:
+        if handle.runtime_type != "harness":
+            raise ValueError(f"Harness adapter cannot stream {handle.runtime_type!r}")
+        try:
+            return self._runs[handle.run_id]
+        except KeyError:
+            raise KeyError(f"unknown Harness run: {handle.run_id}") from None
+
+    async def _ensure_tools(self) -> tuple[HarnessTool, ...]:
+        if self._tools is not None:
+            return self._tools
+        async with self._tool_lock:
+            if self._tools is not None:
+                return self._tools
+            tools = sandbox_tools(self._sandbox)
+            try:
+                for spec in self._config.mcp_tools:
+                    toolset, discovered = await load_mcp_tools(spec)
+                    self._mcp_toolsets.append(toolset)
+                    tools.extend(discovered)
+                duplicates = sorted(
+                    {
+                        tool.name
+                        for tool in tools
+                        if sum(item.name == tool.name for item in tools) > 1
+                    }
+                )
+                if duplicates:
+                    raise RuntimeError(f"Harness tool names are not unique: {duplicates}")
+            except Exception:
+                await self._close_tools()
+                raise
+            self._tools = tuple(tools)
+            return self._tools
+
+    async def _close_tools(self) -> None:
+        toolsets, self._mcp_toolsets = self._mcp_toolsets, []
+        self._tools = None
+        if toolsets:
+            await asyncio.gather(*(toolset.close() for toolset in toolsets), return_exceptions=True)
+
+
+__all__ = ["HarnessRuntime", "HarnessRuntimeAdapter"]

ksadk/hermes_terminal.py

@@ -90,6 +90,7 @@ def build_start_frame(
     argv: Sequence[str],
     cols: int,
     rows: int,
+    session_id: str | None = None,
     cwd: str | None = None,
     options: Mapping[str, Any] | None = None,
 ) -> str:
@@ -106,6 +107,9 @@ def build_start_frame(
     normalized_cwd = str(cwd or "").strip()
     if normalized_cwd:
         payload["cwd"] = normalized_cwd
+    normalized_session_id = str(session_id or "").strip()
+    if normalized_session_id:
+        payload["session_id"] = normalized_session_id
     if options:
         payload["options"] = dict(options)
     return json.dumps(payload, ensure_ascii=False)
@@ -415,6 +419,7 @@ async def run_hermes_terminal_session(
                 argv=normalized_argv,
                 cols=size.cols,
                 rows=size.rows,
+                session_id=session_id,
                 cwd=cwd,
                 options=options,
             )

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",
+]