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

ksadk/harness/runtime.py

@@ -14,25 +14,16 @@ from ksadk.events.canonical import (
     ErrorInfo,
     ItemCompleted,
     ItemStarted,
-    ItemUpdated,
     OutputRef,
     RunCanceled,
     RunCompleted,
     RunFailed,
     RunStarted,
     SourceRef,
+    UsageReported,
 )
-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.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
@@ -109,6 +100,8 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         self._tool_lock = asyncio.Lock()
         self._mcp_toolsets: list[Any] = []
         self._sessions: dict[tuple[str, str, str], _HarnessSession] = {}
+        self._lifecycle_lock = asyncio.Lock()
+        self._closed = False
 
     @property
     def harness_config(self) -> HarnessConfig:
@@ -123,10 +116,13 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         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)
+        async with self._lifecycle_lock:
+            if self._closed:
+                raise RuntimeError("Harness runtime adapter is closed")
+            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,
@@ -174,28 +170,29 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         )
 
     async def close(self, handle: RunHandle) -> None:
-        run = self._runs.pop(handle.run_id, None)
+        async with self._lifecycle_lock:
+            run = self._runs.pop(handle.run_id, None)
+            has_runs = bool(self._runs)
         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:
+        if not has_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,
-                    },
-                )
-            )
+        async with self._lifecycle_lock:
+            self._closed = True
+            runs = tuple(self._runs.values())
+            self._runs.clear()
+            self._sessions.clear()
+        tasks = [run.task for run in runs if run.task is not None and not run.task.done()]
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        await self._close_tools()
 
     def is_handle_attached(self, handle: RunHandle) -> bool:
         return handle.run_id in self._runs
@@ -212,13 +209,28 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
     ) -> dict[str, Any]:
         tools = await self._ensure_tools()
         model, prompt = self._effective(request)
-        messages: list[dict[str, Any]] = [
-            {"role": "system", "content": prompt},
-            *[dict(message) for message in session.messages],
-        ]
-        user_message = {"role": "user", "content": str(request.input or "")}
-        messages.append(user_message)
+        conversation = request.conversation_preprocessing()
+        history = (
+            [dict(item) for item in conversation.messages]
+            if conversation is not None and conversation.messages
+            else [dict(item) for item in session.messages]
+        )
+        messages: list[dict[str, Any]] = [{"role": "system", "content": prompt}]
+        messages.extend(history)
+        current_input = str(request.input or "")
+        if not history or not (
+            str(history[-1].get("role") or "") == "user"
+            and str(history[-1].get("content") or "") == current_input
+        ):
+            messages.append({"role": "user", "content": current_input})
         execution_log: list[dict[str, Any]] = []
+        usage = {
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "cached_tokens": 0,
+            "reasoning_tokens": 0,
+        }
+        reasoning_parts: list[str] = []
 
         for _turn_number in range(_MAX_REASONING_TURNS):
             turn = await self._reasoner.complete(
@@ -227,6 +239,10 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
                 messages=tuple(messages),
                 tools=tools,
             )
+            for key in usage:
+                usage[key] += max(0, int((turn.usage or {}).get(key, 0)))
+            if turn.reasoning:
+                reasoning_parts.append(turn.reasoning)
             if turn.tool_calls:
                 messages.append(
                     {
@@ -288,6 +304,11 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
                 "prompt": prompt,
                 "tool_calls": execution_log,
                 "sandbox_read_only": self._config.sandbox.read_only,
+                "usage": {
+                    **usage,
+                    "total_tokens": usage["input_tokens"] + usage["output_tokens"],
+                },
+                "reasoning": "".join(reasoning_parts),
             }
         raise RuntimeError(f"Harness reasoning exceeded {_MAX_REASONING_TURNS} turns")
 
@@ -305,9 +326,7 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
 
     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()
+        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")
@@ -319,164 +338,180 @@ 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 next_seq() -> int:
+        framework = "ksadk"
+        scope_id = stable_scope_id(framework, handle.run_id)
+        run_item_id = stable_item_id(framework, handle.run_id, "$run")
+        request = run.request
+        source = SourceRef(
+            framework=framework,
+            native_run_id=handle.run_id,
+            metadata={
+                "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,
+            },
+        )
+
+        def envelope(event_type: str, item_id: str, part_id: str) -> dict[str, Any]:
             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
+                    framework,
+                    scope_id,
+                    item_id,
+                    event_type,
+                    part_id,
+                    handle.run_id,
+                    seq,
                 ),
-                "seq": n,
+                "seq": seq,
                 "timestamp": time.time(),
-                "run_id": run_id,
+                "run_id": handle.run_id,
                 "scope_id": scope_id,
-                "source": make_source(),
+                "source": 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"),
+                **envelope("run.canceled", run_item_id, "run"),
                 status="canceled",
                 reason=CancelResult.PENDING_CANCEL_RECORDED.value,
             )
             return
         yield RunStarted(
-            **env_kwargs(run_item_id, "run.started", "run"),
+            **envelope("run.started", run_item_id, "run"),
             status="running",
         )
         run.task = asyncio.create_task(self.execute_request(run.request))
         try:
             result = await run.task
+            usage = result["usage"]
+            reasoning_text = str(result.get("reasoning") or "")
+            if reasoning_text:
+                reasoning_item_id = stable_item_id(
+                    framework, handle.run_id, "reasoning", "0"
+                )
+                reasoning_part_id = "reasoning-0"
+                reasoning_content = ContentSnapshot(
+                    parts=(TextContent(part_id=reasoning_part_id, text=reasoning_text),)
+                )
+                yield ItemStarted(
+                    **envelope("item.started", reasoning_item_id, reasoning_part_id),
+                    item_id=reasoning_item_id,
+                    item_kind="reasoning",
+                    phase="commentary",
+                    initial=reasoning_content,
+                )
+                yield ItemCompleted(
+                    **envelope("item.completed", reasoning_item_id, reasoning_part_id),
+                    item_id=reasoning_item_id,
+                    item_kind="reasoning",
+                    snapshot=reasoning_content,
+                )
+            yield UsageReported(
+                **envelope("usage.reported", run_item_id, "usage"),
+                input_tokens=usage["input_tokens"],
+                output_tokens=usage["output_tokens"],
+                total_tokens=usage["total_tokens"],
+                cached_tokens=usage["cached_tokens"],
+                reasoning_tokens=usage["reasoning_tokens"],
+            )
             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,
+                call_item_id = stable_item_id(
+                    framework, handle.run_id, "tool_call", call["call_id"]
+                )
+                call_part_id = "tool-call-0"
+                call_content = ToolCallContent(
+                    part_id=call_part_id,
+                    call_id=call["call_id"],
+                    name=call["name"],
+                    arguments=call["arguments"],
+                )
+                yield ItemStarted(
+                    **envelope("item.started", call_item_id, call_part_id),
+                    item_id=call_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
+                    phase="commentary",
+                    initial=ContentSnapshot(parts=(call_content,)),
+                )
                 yield ItemCompleted(
-                    **env_kwargs(tool_item_id, "item.completed", "tool-0"),
-                    item_id=tool_item_id,
+                    **envelope("item.completed", call_item_id, call_part_id),
+                    item_id=call_item_id,
                     item_kind="tool_call",
-                    snapshot=ContentSnapshot(
-                        parts=(
-                            ToolResultContent(
-                                part_id="tool-0",
-                                call_id=call_id,
-                                result=call["result"],
-                            ),
-                        )
-                    ),
+                    snapshot=ContentSnapshot(parts=(call_content,)),
+                )
+                result_item_id = stable_item_id(
+                    framework, handle.run_id, "tool_result", call["call_id"]
+                )
+                result_part_id = "tool-result-0"
+                result_content = ToolResultContent(
+                    part_id=result_part_id,
+                    call_id=call["call_id"],
+                    result=call["result"],
+                )
+                yield ItemStarted(
+                    **envelope("item.started", result_item_id, result_part_id),
+                    item_id=result_item_id,
+                    item_kind="tool_result",
+                    phase="commentary",
+                    initial=ContentSnapshot(parts=(result_content,)),
+                )
+                yield ItemCompleted(
+                    **envelope("item.completed", result_item_id, result_part_id),
+                    item_id=result_item_id,
+                    item_kind="tool_result",
+                    snapshot=ContentSnapshot(parts=(result_content,)),
                 )
             text = str(result["output"])
-            for ev in ensure_started(
+            message_item_id = stable_item_id(framework, handle.run_id, "message", "final_answer")
+            text_part_id = "text-0"
+            yield ItemStarted(
+                **envelope("item.started", message_item_id, text_part_id),
                 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),
+                initial=None,
             )
             yield ItemCompleted(
-                **env_kwargs(message_item_id, "item.completed", "text-0"),
+                **envelope("item.completed", message_item_id, text_part_id),
                 item_id=message_item_id,
                 item_kind="message",
-                snapshot=ContentSnapshot(
-                    parts=(TextContent(part_id="text-0", text=text),)
-                ),
+                snapshot=ContentSnapshot(parts=(TextContent(part_id=text_part_id, text=text),)),
             )
             run.done = True
             yield RunCompleted(
-                **env_kwargs(run_item_id, "run.completed", "run"),
+                **envelope("run.completed", run_item_id, "run"),
                 status="completed",
                 output_refs=(
                     OutputRef(
                         scope_id=scope_id,
                         item_id=message_item_id,
-                        part_id="text-0",
+                        part_id=text_part_id,
                     ),
                 ),
             )
         except asyncio.CancelledError:
             run.done = True
             yield RunCanceled(
-                **env_kwargs(run_item_id, "run.canceled", "run"),
+                **envelope("run.canceled", run_item_id, "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"),
+                **envelope("run.failed", run_item_id, "run"),
                 status="failed",
                 error=ErrorInfo(
-                    code="harness_failed",
+                    code="HARNESS_EXECUTION_FAILED",
                     message=str(exc),
-                    source=framework,
+                    source="ksadk.harness",
                     scope_id=scope_id,
                 ),
             )

ksadk/harness/runtime_capabilities.py

@@ -0,0 +1,158 @@
+"""Harness 跨 Runtime 的治理能力声明。
+
+控制动词能力仍由 ``RuntimeCapabilityMatrix`` 负责；本模块补充 Harness 关心的
+输入、上下文、能力调用与事件可观测语义，避免把“能启动”误报成“行为一致”。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, ClassVar
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ksadk.kernel.contracts import RuntimeCapabilityMatrix
+
+
+class CapabilitySupport(str, Enum):
+    SUPPORTED = "supported"
+    EMULATED = "emulated"
+    UNAVAILABLE = "unavailable"
+    OPAQUE = "opaque"
+
+
+class CapabilityOwner(str, Enum):
+    PLATFORM = "platform"
+    RUNTIME = "runtime"
+    PROVIDER = "provider"
+    SHARED = "shared"
+
+
+class HarnessCapability(BaseModel):
+    model_config = ConfigDict(extra="allow", frozen=True)
+
+    support: CapabilitySupport
+    owner: CapabilityOwner
+    reason: str = ""
+    evidence_refs: tuple[str, ...] = ()
+
+
+class RuntimeHarnessCapabilities(BaseModel):
+    """版本化、可序列化且可前向扩展的 Runtime Harness 声明。"""
+
+    model_config = ConfigDict(extra="allow", frozen=True)
+    schema_version: str = "harness.runtime-capabilities/v1"
+    runtime_type: str = Field(min_length=1)
+    capabilities: dict[str, HarnessCapability]
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    _REQUIRED: ClassVar[tuple[str, ...]] = (
+        "instructions",
+        "history",
+        "compaction",
+        "memory",
+        "tools",
+        "streaming",
+        "approval",
+        "checkpoint",
+        "recovery",
+        "events",
+    )
+
+    @classmethod
+    def required_capability_names(cls) -> tuple[str, ...]:
+        return cls._REQUIRED
+
+    @model_validator(mode="after")
+    def require_complete_declaration(self) -> "RuntimeHarnessCapabilities":
+        missing = set(self._REQUIRED) - set(self.capabilities)
+        if missing:
+            raise ValueError(f"runtime capability declaration missing: {sorted(missing)}")
+        return self
+
+
+def managed_langgraph_capabilities() -> RuntimeHarnessCapabilities:
+    evidence_by_capability = {
+        "instructions": ("tests/harness/test_prompt_contract.py",),
+        "history": ("tests/harness/test_context_pipeline.py",),
+        "compaction": ("tests/harness/test_context_pipeline.py",),
+        "memory": ("tests/memory",),
+        "tools": ("tests/harness/test_loop_tools.py",),
+        "streaming": ("tests/harness/test_harness_reasoner.py",),
+        "approval": ("tests/harness/test_engine_langgraph.py",),
+        "checkpoint": ("tests/harness/test_engine_langgraph.py",),
+        "recovery": ("tests/harness/test_runner_conformance_matrix.py",),
+        "events": ("tests/harness/test_event_v2_envelope.py",),
+    }
+    return RuntimeHarnessCapabilities(
+        runtime_type="managed-langgraph",
+        capabilities={
+            name: HarnessCapability(
+                support=CapabilitySupport.SUPPORTED,
+                owner=CapabilityOwner.PLATFORM,
+                evidence_refs=evidence_by_capability[name],
+            )
+            for name in RuntimeHarnessCapabilities._REQUIRED
+        },
+    )
+
+
+def _project_control(capability: Any, *, owner: CapabilityOwner) -> HarnessCapability:
+    if not bool(getattr(capability, "supported", False)):
+        return HarnessCapability(
+            support=CapabilitySupport.UNAVAILABLE,
+            owner=owner,
+            reason=str(getattr(capability, "reason", "") or "not_implemented"),
+        )
+    mode = str(getattr(capability, "mode", "native") or "native")
+    return HarnessCapability(
+        support=(
+            CapabilitySupport.EMULATED if mode == "emulated" else CapabilitySupport.SUPPORTED
+        ),
+        owner=owner,
+    )
+
+
+def project_adapter_capabilities(
+    runtime_type: str, matrix: RuntimeCapabilityMatrix
+) -> RuntimeHarnessCapabilities:
+    """从平台动词矩阵保守投影；不可观测的数据治理能力标记 opaque。"""
+    opaque = HarnessCapability(
+        support=CapabilitySupport.OPAQUE,
+        owner=CapabilityOwner.RUNTIME,
+        reason="runtime_private_state_unobservable",
+    )
+    capabilities = {
+        "instructions": opaque,
+        "history": opaque,
+        "compaction": opaque,
+        "memory": opaque,
+        "tools": opaque,
+        "streaming": HarnessCapability(
+            support=CapabilitySupport.SUPPORTED,
+            owner=CapabilityOwner.RUNTIME,
+            reason="RuntimeAdapter.stream",
+        ),
+        "approval": _project_control(matrix.resume, owner=CapabilityOwner.SHARED),
+        "checkpoint": _project_control(matrix.checkpoint, owner=CapabilityOwner.RUNTIME),
+        "recovery": _project_control(matrix.durable_restore, owner=CapabilityOwner.RUNTIME),
+        "events": HarnessCapability(
+            support=CapabilitySupport.EMULATED,
+            owner=CapabilityOwner.PLATFORM,
+            reason="adapter_event_projection",
+        ),
+    }
+    return RuntimeHarnessCapabilities(
+        runtime_type=runtime_type,
+        capabilities=capabilities,
+    )
+
+
+__all__ = [
+    "CapabilityOwner",
+    "CapabilitySupport",
+    "HarnessCapability",
+    "RuntimeHarnessCapabilities",
+    "managed_langgraph_capabilities",
+    "project_adapter_capabilities",
+]