agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/runtime.py

@@ -14,27 +14,18 @@ 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.reasoner import HarnessReasoner, ModelGatewayHarnessReasoner
 from ksadk.harness.sandbox import HarnessSandboxExecutor
 from ksadk.harness.tools import HarnessTool, load_mcp_tools, sandbox_tools, tool_result_text
 from ksadk.runtime import (
@@ -61,6 +52,7 @@ class HarnessRuntime(BaseRuntime):
             "resume": {"supported": False},
             "checkpoint": {"supported": False, "granularity": "none"},
             "session_continuity": {"durable": False, "scope": "process"},
+            "steering": {"supported": False},
         }
 
 
@@ -99,7 +91,7 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
         super().__init__(HarnessRuntime())
         self._config = config
         self._agent_name = agent_name
-        self._reasoner = reasoner or LiteLLMHarnessReasoner()
+        self._reasoner = reasoner or ModelGatewayHarnessReasoner()
         self._sandbox = HarnessSandboxExecutor(
             workspace_root=workspace_root,
             read_only=config.sandbox.read_only,
@@ -218,13 +210,31 @@ 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] = []
+        reasoning_effort = (
+            str(request.config.get("effort") or "").strip().lower() or None
+        )
 
         for _turn_number in range(_MAX_REASONING_TURNS):
             turn = await self._reasoner.complete(
@@ -232,7 +242,16 @@ class HarnessRuntimeAdapter(RuntimeAdapter):
                 prompt=prompt,
                 messages=tuple(messages),
                 tools=tools,
+                **(
+                    {"reasoning_effort": reasoning_effort}
+                    if reasoning_effort
+                    else {}
+                ),
             )
+            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(
                     {
@@ -294,6 +313,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")
 
@@ -323,160 +347,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,228 @@
+"""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 RuntimeCapability, RuntimeCapabilityMatrix
+
+
+def managed_harness_native_capabilities(*, durable: bool = False) -> dict[str, Any]:
+    """Declare the Managed assembly without importing its execution engine.
+
+    Metadata readers and the Managed adapter share this one declaration. A
+    declaration does not install the optional framework or select an engine.
+    """
+    return {
+        "cancel": {"supported": True},
+        "resume": {"supported": True},
+        "checkpoint": {"supported": True, "granularity": "snapshot"},
+        "session_continuity": {
+            "durable": durable,
+            "scope": "workspace" if durable else "process",
+        },
+        "progressive_disclosure": {"skill": True, "mcp": True},
+        "steering": {"supported": True, "mode": "native", "follow_up": True},
+    }
+
+
+def managed_harness_capabilities(
+    *, durable: bool, execution_policy: bool = False
+) -> RuntimeCapabilityMatrix:
+    """Return the canonical control declaration for one Managed assembly tier."""
+    def available() -> RuntimeCapability:
+        return RuntimeCapability(supported=True, mode="native")
+
+    def unavailable(reason: str) -> RuntimeCapability:
+        return RuntimeCapability(supported=False, mode="unavailable", reason=reason)
+
+    durable_capability = (
+        available() if durable else unavailable("managed_harness_checkpoint_is_process_local")
+    )
+    return RuntimeCapabilityMatrix(
+        cancel=available(),
+        pause=unavailable("managed_harness_pause_not_implemented"),
+        resume=available(),
+        submit_interaction=durable_capability,
+        attach=durable_capability,
+        steer=available(),
+        inject=unavailable("runtime_no_native_inject"),
+        checkpoint=available(),
+        durable_restore=durable_capability,
+        interaction_mode="durable_resume" if durable else "unavailable",
+        execution_policy=(
+            available() if execution_policy else unavailable("managed_harness_no_host_resolver")
+        ),
+    )
+
+
+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",),
+        "steering": ("tests/harness/test_steering.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
+        }
+        | {
+            # steering（steer/follow_up）是可选扩展能力，不进 _REQUIRED，
+            # 避免旧 runtime 报缺声明；托管引擎原生支持（G1）。
+            "steering": HarnessCapability(
+                support=CapabilitySupport.SUPPORTED,
+                owner=CapabilityOwner.PLATFORM,
+                evidence_refs=evidence_by_capability["steering"],
+            ),
+        },
+        metadata={
+            "skill_standard": "agentskills-v1-compatible",
+            # G5 §5.2 Provider 钩子纪律声明：顺序 await、异常可见降级、钩子不获得
+            # approval 绕过权与沙箱豁免、不可改模型路由（引擎强制回写）。
+            "provider_hooks_discipline": (
+                "ordered-await; visible-degradation; no-approval-bypass; "
+                "no-sandbox-exemption; model-immutable"
+            ),
+        },
+    )
+
+
+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_harness_capabilities",
+    "managed_harness_native_capabilities",
+    "managed_langgraph_capabilities",
+    "project_adapter_capabilities",
+]