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

ksadk/runtime/_runner_adapter/stream_mapping.py

@@ -20,12 +20,14 @@ from typing import TYPE_CHECKING, Any, AsyncIterator, Optional, cast
 
 from pydantic import JsonValue
 
+from ksadk.common.diagnostics import safe_exception_detail
 from ksadk.conversations.runtime_input import _runner_name
 from ksadk.conversations.runtime_observability import (
     _set_conversation_input_attributes,
     _set_conversation_output_attributes,
     _set_conversation_span_attributes,
     _set_conversation_usage_attributes,
+    _set_skill_eval_result_attributes,
 )
 from ksadk.events.canonical import (
     ApprovalRequest,
@@ -37,6 +39,7 @@ from ksadk.events.canonical import (
     ItemCompleted,
     ItemStarted,
     ItemUpdated,
+    RunCompleted,
     RunFailed,
     RunProgress,
     RuntimeEvent,
@@ -47,9 +50,15 @@ from ksadk.events.content import DataContent, TextContent, ToolCallContent, Tool
 from ksadk.events.identity import stable_event_id, stable_item_id, stable_scope_id
 from ksadk.runtime.adapter import RunHandle
 from ksadk.runtime.preprocessing import PreparedRuntimeStart
+from ksadk.runtime.skill_eval_result import extract_skill_eval_result
+from ksadk.runtime.timing import extract_timing
+from ksadk.runtime.usage import canonical_usage_payload
 from ksadk.runtime_context import platform_invocation_scope
 from ksadk.tools.gateway import approval_interrupt_info_from_result
 
+from ksadk.runtime._runner_adapter.a2ui_surface import _a2ui_surface_event
+from ksadk.runtime._runner_adapter.gateway_approvals import _canonical_gateway_approvals
+
 if TYPE_CHECKING:
     from ksadk.runtime.runner_adapter import _ActiveRun
 
@@ -98,129 +107,6 @@ async def _pump_stream_in_one_context(
     await results.put(outcome)
 
 
-def _a2ui_surface_event(
-    self: Any,
-    handle: RunHandle,
-    chunk: Any,
-) -> tuple[RuntimeEvent, ...]:
-    """Recognize a validated A2UI tool envelope and emit a canonical data-item event.
-
-    The dynamic ``generate_a2ui`` tool returns official v0.9 operations as a
-    JSON tool result. Tool results are otherwise opaque to the runtime, which
-    would leave AG-UI with nothing to project until a page reload reconstructs
-    history. Convert exactly that envelope at the runtime boundary so it is
-    streamed, persisted, and replayed like every other A2UI surface.
-
-    In the canonical schema, A2UI surfaces are modeled as ``item_kind="data"``
-    items with ``source.protocol="a2ui"``.
-    """
-
-    if not isinstance(chunk, dict):
-        return ()
-    value = chunk.get("tool_output", chunk.get("output"))
-    if value is not None and hasattr(value, "content"):
-        value = value.content
-    if isinstance(value, str):
-        try:
-            value = json.loads(value)
-        except (TypeError, ValueError):
-            return ()
-    if not isinstance(value, Mapping):
-        return ()
-    operations_raw = value.get("a2ui_operations")
-    if not isinstance(operations_raw, list) or not operations_raw:
-        return ()
-    operations = [dict(operation) for operation in operations_raw if isinstance(operation, Mapping)]
-    if not operations:
-        return ()
-
-    known: list[tuple[str, str]] = []  # (surface_id, lifecycle)
-    for operation in operations:
-        for key, lifecycle in (
-            ("createSurface", "begin"),
-            ("updateComponents", "update"),
-            ("updateDataModel", "update"),
-            ("deleteSurface", "end"),
-        ):
-            detail = operation.get(key)
-            if isinstance(detail, Mapping) and isinstance(detail.get("surfaceId"), str):
-                surface_id = detail["surfaceId"].strip()
-                if surface_id:
-                    known.append((surface_id, lifecycle))
-                    break
-    if not known:
-        return ()
-    surface_ids = {surface_id for surface_id, _lifecycle in known}
-    if len(surface_ids) != 1:
-        logger.warning("ignoring A2UI tool result with multiple surfaces")
-        return ()
-    surface_id = known[0][0]
-    lifecycle = "begin" if any(lc == "begin" for _, lc in known) else known[0][1]
-
-    framework = self._runtime_type
-    run_id = handle.run_id
-    scope_id = stable_scope_id(framework, run_id)
-    # A dynamic A2UI tool result is a complete, immutable operation batch.  It
-    # must therefore be represented by a closed canonical item.  Reusing one
-    # long-lived item per surface leaves a create/update-only batch open at the
-    # run terminal and makes strict reducers reject the stream.
-    start_seq = self._next_seq()
-    batch_ref = str(chunk.get("call_id") or chunk.get("run_id") or chunk.get("id") or "")
-    if not batch_ref:
-        batch_ref = json.dumps(
-            operations,
-            ensure_ascii=False,
-            sort_keys=True,
-            separators=(",", ":"),
-        )
-    item_id = stable_item_id(framework, run_id, "a2ui-batch", surface_id, batch_ref)
-    source = SourceRef(
-        framework=framework,
-        protocol="a2ui",
-        native_run_id=run_id,
-        metadata={
-            "surface_id": surface_id,
-            "operation_batch": True,
-            "surface_lifecycle": lifecycle,
-        },
-    )
-    # TODO(runtime-event-v2): dict chunk 退化路径,chunk_ordinal 用 seq counter;
-    # LangGraph/Codex 切 stream_canonical_events 后清理
-    timestamp = time.time()
-    snapshot = ContentSnapshot(parts=(DataContent(part_id="a2ui-ops", data=operations),))
-    completed_seq = self._next_seq()
-    return (
-        ItemStarted(
-            schema_version=2,
-            event_id=stable_event_id(
-                framework, scope_id, item_id, "item.started", "a2ui", run_id, start_seq
-            ),
-            seq=start_seq,
-            timestamp=timestamp,
-            run_id=run_id,
-            scope_id=scope_id,
-            source=source,
-            item_id=item_id,
-            item_kind="data",
-            initial=snapshot,
-        ),
-        ItemCompleted(
-            schema_version=2,
-            event_id=stable_event_id(
-                framework, scope_id, item_id, "item.completed", "a2ui", run_id, completed_seq
-            ),
-            seq=completed_seq,
-            timestamp=timestamp,
-            run_id=run_id,
-            scope_id=scope_id,
-            source=source,
-            item_id=item_id,
-            item_kind="data",
-            snapshot=snapshot,
-        ),
-    )
-
-
 class _RunnerStreamMappingMixin:
     """``_map_runner_stream`` / ``_chunk_to_event`` 的实现载体(纯移动自 runner_adapter)。"""
 
@@ -258,6 +144,7 @@ class _RunnerStreamMappingMixin:
         pump_requests: asyncio.Queue[None] | None = None
         pump_queue: asyncio.Queue[tuple[str, Any]] | None = None
         pump_task: asyncio.Task[None] | None = None
+        saw_terminal_event = False
         # span scope 经 runner_adapter 模块属性间接解析,保持既有 monkeypatch
         # patch 点(tests/agui/test_runtime_preprocessing.py)继续生效。
         from ksadk.runtime import runner_adapter as _runner_adapter_module
@@ -278,12 +165,16 @@ class _RunnerStreamMappingMixin:
             try:
                 with scope:
                     canonical_stream = getattr(self._runner, "stream_canonical_events", None)  # type: ignore[attr-defined]
-                    # ToolGateway 语义续跑 runner(gateway approval 可能出现在终态
-                    # tool result 之后)仍走 chunk 路径:approval 识别逻辑在
-                    # _chunk_to_events 的 tool_result 分支,canonical 快速路径
-                    # (stream_canonical_events)不覆盖该语义。
+                    # Keep legacy semantic-resume runners on their chunk path.
+                    # Managed LangGraph requires canonical identity; its local
+                    # gateway results are handled by _canonical_gateway_approvals.
                     if getattr(
-                        self._runner, "supports_gateway_approval_semantic_resume", False  # type: ignore[attr-defined]
+                        self._runner,
+                        "supports_gateway_approval_semantic_resume",
+                        False,  # type: ignore[attr-defined]
+                    ) and not (
+                        self._runtime_type == "langgraph"
+                        and getattr(self._runner, "_managed_a2a_bootstrap", None) is not None
                     ):
                         canonical_stream = None
                     stream_result = (
@@ -357,6 +248,12 @@ class _RunnerStreamMappingMixin:
                         if isinstance(chunk, EventEnvelope):
                             # canonical 事件(来自 stream_canonical_events):直接转发,
                             # 追踪 output/usage 供 span 属性。
+                            if isinstance(chunk, RunCompleted):
+                                evidence = extract_skill_eval_result(
+                                    chunk.source.metadata.get("metrics")
+                                )
+                                if evidence:
+                                    _set_skill_eval_result_attributes(span, evidence)
                             if isinstance(chunk, ItemCompleted) and chunk.item_kind == "message":
                                 accumulated_output = "".join(
                                     part.text
@@ -376,6 +273,11 @@ class _RunnerStreamMappingMixin:
                         if isinstance(chunk, dict):
                             chunk_type = str(chunk.get("type") or "")
                             if chunk_type == "final" and run is not None:
+                                if evidence := extract_skill_eval_result(chunk):
+                                    run.completion_metrics["skill_eval_result"] = evidence
+                                    _set_skill_eval_result_attributes(span, evidence)
+                                if timing := extract_timing(chunk):
+                                    run.completion_metrics["timing"] = timing
                                 for source_key, target_key in (
                                     ("duration_ms", "duration_ms"),
                                     ("started_at", "started_at"),
@@ -397,9 +299,43 @@ class _RunnerStreamMappingMixin:
                             if isinstance(raw_usage, dict):
                                 usage.update(raw_usage)
                         for event in self._chunk_to_event(handle, run, chunk):  # type: ignore[attr-defined]
+                            if getattr(event, "event_type", "") in {
+                                "run.completed",
+                                "run.failed",
+                                "run.canceled",
+                                "run.interrupted",
+                            }:
+                                saw_terminal_event = True
                             yield event
                         for a2ui_surface in _a2ui_surface_event(self, handle, chunk):
                             yield a2ui_surface
+            except Exception as exc:
+                # 原始 runner 异常(如 GraphRecursionError)不走 "error" chunk 路径。
+                # 不转换则 canonical 事件流没有 run.failed 终态：下游按"流结束无终态"
+                # 报错，会话 run 状态缺失 canonical failed，前端只见干净收尾。这里
+                # 把异常转成 canonical RunFailed 后正常终止；runner 已自行发过终态
+                # 时不重复。CancelledError 是 BaseException，不经此处，保持取消语义。
+                if not saw_terminal_event:
+                    framework = self._runtime_type  # type: ignore[attr-defined]
+                    run_id = handle.run_id
+                    scope_id = stable_scope_id(framework, run_id)
+                    yield RunFailed(
+                        **self._canonical_kwargs(  # type: ignore[attr-defined]
+                            handle,
+                            scope_id=scope_id,
+                            item_id=stable_item_id(framework, run_id, "$run"),
+                            event_type="run.failed",
+                            part_id="run",
+                        ),
+                        status="failed",
+                        error=ErrorInfo(
+                            code="runner_failed",
+                            message=safe_exception_detail(exc),
+                            source=framework,
+                            scope_id=scope_id,
+                        ),
+                    )
+                return
             finally:
                 if accumulated_output:
                     _set_conversation_output_attributes(span, accumulated_output)
@@ -420,6 +356,8 @@ class _RunnerStreamMappingMixin:
                         run.chunk_task = None
                     run.cancellation_ack.set()
 
+    _canonical_gateway_approvals = _canonical_gateway_approvals
+
     def _chunk_to_event(
         self, handle: RunHandle, run: Optional[_ActiveRun], chunk: Any
     ) -> list[RuntimeEvent]:
@@ -428,6 +366,39 @@ class _RunnerStreamMappingMixin:
             # 抑制 runner 自己的 run.started(adapter 已发自己的)。
             if chunk.event_type == "run.started":
                 return []
+            if (
+                self._runtime_type == "langgraph"
+                and chunk.source.framework == "langgraph"
+                and isinstance(chunk, ContinuationCreated)
+                and chunk.continuation_kind == "graph_checkpoint"
+            ):
+                # The canonical continuation arrives before its interaction.
+                # Retain its native target just as the legacy checkpoint path
+                # does, so Kernel records and resumes the original interrupt.
+                checkpoint_id = chunk.ref.get("checkpoint_id")
+                thread_id = chunk.ref.get("thread_id")
+                if (
+                    isinstance(checkpoint_id, str)
+                    and checkpoint_id
+                    and isinstance(thread_id, str)
+                    and thread_id
+                ):
+                    native_ref = {key: chunk.ref[key] for key in (
+                        "checkpoint_id", "thread_id", "checkpoint_ns"
+                    ) if key in chunk.ref}
+                    handle.native_ref.update(native_ref)
+                    handle.native_ref["framework_ref"] = {"langgraph": native_ref}
+                    known = handle.native_ref.setdefault("known_checkpoint_ids", [])
+                    if checkpoint_id not in known:
+                        known.append(checkpoint_id)
+            if (
+                self._runtime_type == "langgraph"
+                and chunk.source.framework == "langgraph"
+                and isinstance(chunk, ItemCompleted)
+            ):
+                approvals = self._canonical_gateway_approvals(handle, run, chunk)
+                if approvals:
+                    return [chunk, *approvals]
             return [chunk]
         if not isinstance(chunk, dict):
             chunk = {"type": "text", "delta": str(chunk)}
@@ -786,7 +757,11 @@ class _RunnerStreamMappingMixin:
         # ---- usage ----
         if chunk_type == "usage":
             raw_usage = chunk.get("usage")
-            usage_dict: dict[str, Any] = raw_usage if isinstance(raw_usage, dict) else {}
+            usage_dict = (
+                canonical_usage_payload(raw_usage, runtime_type=framework)
+                if isinstance(raw_usage, Mapping)
+                else {}
+            )
             item_id = stable_item_id(framework, run_id, "$run")
             return [
                 UsageReported(
@@ -873,6 +848,36 @@ class _RunnerStreamMappingMixin:
             events.extend(
                 ensure_started(item_id=item_id, item_kind="message", phase="final_answer")
             )
+            # The dict-chunk path is still required for gateway approval flows.
+            # It must project runner-final usage into the canonical stream too;
+            # otherwise non-streaming Runs aggregate zero even when the runner
+            # returned provider token accounting.
+            raw_usage = chunk.get("usage")
+            if isinstance(raw_usage, Mapping):
+                usage_dict = canonical_usage_payload(
+                    raw_usage,
+                    runtime_type=framework,
+                )
+                input_tokens = usage_dict["input_tokens"]
+                output_tokens = usage_dict["output_tokens"]
+                total_tokens = usage_dict["total_tokens"]
+                if input_tokens or output_tokens or total_tokens:
+                    events.append(
+                        UsageReported(
+                            **self._canonical_kwargs(  # type: ignore[attr-defined]
+                                handle,
+                                scope_id=scope_id,
+                                item_id=stable_item_id(framework, run_id, "$run"),
+                                event_type="usage.reported",
+                                part_id="usage",
+                            ),
+                            input_tokens=input_tokens,
+                            output_tokens=output_tokens,
+                            total_tokens=total_tokens,
+                            cached_tokens=usage_dict["cached_tokens"],
+                            reasoning_tokens=usage_dict["reasoning_tokens"],
+                        )
+                    )
             events.append(
                 ItemCompleted(
                     **self._canonical_kwargs(  # type: ignore[attr-defined]

ksadk/runtime/adapter.py

@@ -363,8 +363,11 @@ class RuntimeAdapter(ABC):
     async def steer(self, handle: RunHandle, payload: SteerPayload) -> None:
         """Mid-turn steering: adjust an in-flight run without ending the turn.
 
-        No runtime exposes a native steer channel today; start/stream never
-        implies steer.  Fails closed until a real implementation overrides it.
+        Native implementations exist on managed harness runtimes:
+        ``ManagedHarnessRuntimeAdapter`` (see ``managed_runtime.py``, delegating
+        to ``ManagedLangGraphEngine.steer``) exposes a real mid-turn steer /
+        follow-up channel.  The default below stays fail-closed for runtimes
+        without such a channel; start/stream never implies steer.
         """
 
         raise UnsupportedControlError(
@@ -372,6 +375,35 @@ class RuntimeAdapter(ABC):
             "runtime has no native mid-turn steering channel"
         )
 
+    async def guide(self, handle: RunHandle, payload: SteerPayload) -> object | None:
+        """Continue the current task at a sealed boundary without replacing it."""
+        raise UnsupportedControlError(
+            f"{type(self).__name__} does not support current-turn guidance"
+        )
+
+    async def child_tasks(self, handle: RunHandle) -> tuple[dict[str, Any], ...]:
+        """List authorized children of this attached Run when supported."""
+        raise UnsupportedControlError(f"{type(self).__name__} does not support child task control")
+
+    async def child_execution_view(self, handle: RunHandle, child_run_id: str) -> dict[str, Any]:
+        """Read a scoped child's public canonical execution view, when available."""
+        raise UnsupportedControlError(f"{type(self).__name__} does not support child execution views")
+
+    async def cancel_child(self, handle: RunHandle, *, child_run_id: str, command_id: str):
+        """Request cancellation of one original owned child, without stopping its parent."""
+        raise UnsupportedControlError(f"{type(self).__name__} does not support child cancellation")
+
+    async def promote_child(
+        self, handle: RunHandle, *, child_run_id: str, command_id: str,
+    ) -> object:
+        """Queue delivery control of the same child; do not launch a new child."""
+        raise UnsupportedControlError(f"{type(self).__name__} does not support child promotion")
+
+    async def send_child_input(self, handle: RunHandle, *, child_run_id: str, text: str,
+                               command_id: str, expected_goal_revision: int) -> object:
+        """Queue user guidance on an existing child without restarting it."""
+        raise UnsupportedControlError(f"{type(self).__name__} does not support child input")
+
     async def inject(self, handle: RunHandle, payload: InjectPayload) -> None:
         """Inject ambient context into an in-flight run without a user turn."""
 
@@ -442,7 +474,12 @@ class RuntimeAdapter(ABC):
             "checkpoint",
             "durable_restore",
         )
-        return {name: getattr(matrix, name).supported for name in names}
+        mirrored = {name: getattr(matrix, name).supported for name in names}
+        if matrix.guide is not None:
+            mirrored["guide"] = matrix.guide.supported
+        if matrix.child_input is not None:
+            mirrored["child_input"] = matrix.child_input.supported
+        return mirrored
 
     def is_handle_attached(self, handle: RunHandle) -> bool:
         """Return whether ``handle`` is already attached to this adapter process."""

ksadk/runtime/conversation_execution.py

@@ -48,6 +48,8 @@ from ksadk.runtime.adapter import (
 from ksadk.runtime.executor import RuntimeExecutor, RuntimeStartPreparation
 from ksadk.runtime.factory import apply_runtime_start_request_defaults
 from ksadk.runtime.launch import RuntimeLaunchContext
+from ksadk.runtime.skill_eval_result import skill_eval_response_fields
+from ksadk.runtime.timing import normalize_timing
 from ksadk.sessions import resolve_session_service
 
 _TERMINAL_EVENTS = frozenset(
@@ -631,8 +633,10 @@ async def iter_runtime_conversation_semantic_events(
             if event.interaction_kind == "approval" and event.request.request_type == "approval":
                 detail = event.request.detail
                 approval = dict(detail) if isinstance(detail, Mapping) else {}
-                approval.setdefault("approval_request_id", event.interaction_id)
-                approval.setdefault("id", event.interaction_id)
+                # Live controls must use the same public identity as durable
+                # resume; the detail may still contain a provider-native ID.
+                approval["approval_request_id"] = event.interaction_id
+                approval["id"] = event.interaction_id
                 approval.setdefault("call_id", event.request.call_id)
                 approval.setdefault("kind", event.request.kind)
         elif isinstance(event, RunInterrupted):
@@ -647,20 +651,31 @@ async def iter_runtime_conversation_semantic_events(
                 "session_id": execution_context.get("session_id", ""),
             }
         elif isinstance(event, RunFailed):
+            metrics = event.source.metadata.get("metrics")
+            timing = normalize_timing(metrics.get("timing")) if isinstance(metrics, Mapping) else {}
             yield {
                 "type": "error",
                 "message": event.error.message or "Agent 运行失败",
                 "session_id": execution_context.get("session_id", ""),
                 "usage": projection.usage.model_dump(),
+                **({"timing": timing} if timing else {}),
+                **skill_eval_response_fields(metrics),
             }
         elif isinstance(event, RunCanceled):
+            metrics = event.source.metadata.get("metrics")
+            timing = normalize_timing(metrics.get("timing")) if isinstance(metrics, Mapping) else {}
             yield {
                 "type": "cancelled",
                 "session_id": execution_context.get("session_id", ""),
                 "usage": projection.usage.model_dump(),
+                **({"timing": timing} if timing else {}),
+                **skill_eval_response_fields(metrics),
             }
         elif isinstance(event, RunCompleted):
             completion_metadata = dict(event.source.metadata)
+            metrics = completion_metadata.get("metrics")
+            metrics = metrics if isinstance(metrics, Mapping) else {}
+            timing = normalize_timing(metrics.get("timing"))
             request_metadata = kwargs.get("request_metadata")
             requested_agentengine = (
                 request_metadata.get("agentengine")
@@ -674,7 +689,10 @@ async def iter_runtime_conversation_semantic_events(
                     if key != "session_context"
                 }
             completion_metadata["runtime"] = {
-                "duration_ms": event.source.metadata.get("duration_ms"),
+                "duration_ms": timing.get(
+                    "agent_duration_ms",
+                    metrics.get("duration_ms", event.source.metadata.get("duration_ms")),
+                ),
                 "runtime_type": kwargs["launch_context"].runtime_type,
             }
             yield {
@@ -683,6 +701,8 @@ async def iter_runtime_conversation_semantic_events(
                 "session_id": execution_context.get("session_id", ""),
                 "usage": projection.usage.model_dump(),
                 "metadata": completion_metadata,
+                **({"timing": timing} if timing else {}),
+                **skill_eval_response_fields(metrics),
             }
 
 
@@ -728,6 +748,8 @@ async def invoke_runtime_conversation_once(
     usage: dict[str, Any] = {}
     metadata: dict[str, Any] = {}
     completed = False
+    timing: dict[str, Any] = {}
+    result_fields: dict[str, Any] = {}
     async for event in iter_runtime_conversation_semantic_events(**kwargs):
         event_type = event.get("type")
         if event_type == "started":
@@ -741,6 +763,8 @@ async def invoke_runtime_conversation_once(
             output_text = str(event.get("output_text") or output_text)
             usage = dict(event.get("usage") or {})
             metadata = dict(event.get("metadata") or {})
+            timing = normalize_timing(event.get("timing"))
+            result_fields = skill_eval_response_fields(event)
         elif event_type == "error":
             raise RuntimeError(str(event.get("message") or "Agent 运行失败"))
         elif event_type == "cancelled":
@@ -751,8 +775,10 @@ async def invoke_runtime_conversation_once(
         raise RuntimeError("runtime did not produce a completed result")
     return session_id, {
         "output_text": output_text,
+        **result_fields,
         "usage": usage,
         "metadata": metadata,
+        **({"timing": timing} if timing else {}),
     }