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

ksadk/runtime/runner_adapter.py

@@ -13,24 +13,35 @@ from __future__ import annotations
 import asyncio
 import copy
 import inspect
-import json
 import logging
+import time
 from collections.abc import Mapping
-from contextlib import nullcontext
 from dataclasses import dataclass, field
 from typing import Any, AsyncIterator, Dict, Optional, cast
 
-from ksadk.conversations.runtime_input import _runner_name
-from ksadk.conversations.runtime_observability import (
-    _conversation_span_scope,
-    _set_conversation_input_attributes,
-    _set_conversation_output_attributes,
-    _set_conversation_span_attributes,
-    _set_conversation_usage_attributes,
+from pydantic import JsonValue
+
+from ksadk.events.canonical import (
+    ApprovalRequest,
+    InteractionRequested,
+    OutputRef,
+    RunCanceled,
+    RunCompleted,
+    RunInterrupted,
+    RunStarted,
+    RuntimeEvent,
+    SourceRef,
+)
+from ksadk.events.identity import (
+    stable_event_id,
+    stable_item_id,
+    stable_scope_id,
 )
-from ksadk.events.runtime_event import EventType, RuntimeEvent
+from ksadk.kernel.contracts import RuntimeCapability, RuntimeCapabilityMatrix
+from ksadk.kernel.errors import UnsupportedControlError
 from ksadk.runners.base_runner import BaseRunner
 from ksadk.runtime.adapter import (
+    RESUME_START_REQUEST_NATIVE_KEY,
     BaseRuntime,
     CancelResult,
     CheckpointCapability,
@@ -42,78 +53,22 @@ from ksadk.runtime.adapter import (
     StartRequest,
 )
 from ksadk.runtime.preprocessing import PreparedRuntimeStart, prepare_runtime_start
-from ksadk.runtime_context import platform_invocation_scope
+from ksadk.runtime.runner_loading import ensure_runner_loaded
 
 logger = logging.getLogger(__name__)
 
-_STREAM_STOP = object()
-_ResumeKey = tuple[str, str, str, str, str]
-
-
-async def _anext_or_stop(gen: AsyncIterator[Any]) -> Any:
-    """取下一个 chunk;流结束返回 _STREAM_STOP sentinel(便于竞速)。"""
-    try:
-        return await gen.__anext__()
-    except StopAsyncIteration:
-        return _STREAM_STOP
-
-
-def _a2ui_surface_event(chunk: Any) -> tuple[str, dict[str, Any]] | None:
-    """Recognize a validated A2UI tool envelope and make it a first-class event.
+# 保留既有 monkeypatch patch 点:stream_mapping 在调用时经本模块属性解析。
+from ksadk.conversations.runtime_observability import (  # noqa: E402,F401
+    _conversation_span_scope,
+)
 
-    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.
-    """
+# dict-chunk 退化路径的流竞速/事件映射实现拆至 _runner_adapter 子包(纯移动,行为不变)。
+from ksadk.runtime._runner_adapter.stream_mapping import (  # noqa: E402
+    _STREAM_STOP,
+    _RunnerStreamMappingMixin,
+)
 
-    if not isinstance(chunk, dict):
-        return None
-    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 None
-    if not isinstance(value, Mapping):
-        return None
-    operations_raw = value.get("a2ui_operations")
-    if not isinstance(operations_raw, list) or not operations_raw:
-        return None
-    operations = [dict(operation) for operation in operations_raw if isinstance(operation, Mapping)]
-    if not operations:
-        return None
-
-    known: list[tuple[str, str]] = []
-    for operation in operations:
-        for key, event_type in (
-            ("createSurface", EventType.A2UI_SURFACE_BEGIN),
-            ("updateComponents", EventType.A2UI_SURFACE_UPDATE),
-            ("updateDataModel", EventType.A2UI_SURFACE_UPDATE),
-            ("deleteSurface", EventType.A2UI_SURFACE_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, event_type))
-                    break
-    if not known:
-        return None
-    surface_ids = {surface_id for surface_id, _event_type in known}
-    if len(surface_ids) != 1:
-        logger.warning("ignoring A2UI tool result with multiple surfaces")
-        return None
-    surface_id = known[0][0]
-    event_type = (
-        EventType.A2UI_SURFACE_BEGIN
-        if any(kind == EventType.A2UI_SURFACE_BEGIN for _surface_id, kind in known)
-        else known[0][1]
-    )
-    return event_type, {"surface_id": surface_id, "operations": operations}
+_ResumeKey = tuple[str, str, str, str, str]
 
 
 def _coerce_literal(value: Any, allowed: tuple[str, ...], default: str) -> Any:
@@ -157,9 +112,14 @@ class _ActiveRun:
     resume_fingerprint: Any = None
     skip_runner: bool = False
     done: bool = False
+    completion_metrics: dict[str, Any] = field(default_factory=dict)
+    # dict-chunk 退化路径:追踪已 ItemStarted 的 item key,避免重复发 Started。
+    started_items: set[tuple[str, str]] = field(default_factory=set)
+    # dict-chunk 退化路径:final_answer message 的 item_id,供 RunCompleted.output_refs 引用。
+    final_answer_item_id: Optional[str] = None
 
 
-class RunnerRuntimeAdapter(RuntimeAdapter):
+class RunnerRuntimeAdapter(_RunnerStreamMappingMixin, RuntimeAdapter):
     """把 ``BaseRunner`` 映射为平台六动词的通用 adapter。"""
 
     def __init__(self, runner: BaseRunner, *, runtime_type: str) -> None:
@@ -178,6 +138,63 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
 
     # ---- 框架钩子(子类按需 override) ----
 
+    def capabilities(self) -> RuntimeCapabilityMatrix:
+        """诚实矩阵:cancel 经 asyncio 任务打断(emulated,过 conformance);
+        resume/checkpoint 依赖 runner 声明的原生 checkpoint;attach/durable_restore
+        依赖 ``attach_runtime_handle`` seam 与跨进程持久化,内存表不算数。
+        """
+
+        def _unavailable(reason: str) -> RuntimeCapability:
+            return RuntimeCapability(supported=False, mode="unavailable", reason=reason)
+
+        checkpoint_capability = self._checkpoint_capability()
+        attach_seam = callable(getattr(self._runner, "attach_runtime_handle", None))
+        checkpoint_supported = bool(checkpoint_capability.supported)
+        durable_supported = bool(
+            checkpoint_capability.durable
+            and checkpoint_capability.shared_across_pods
+            and attach_seam
+        )
+        return RuntimeCapabilityMatrix(
+            cancel=RuntimeCapability(
+                supported=True,
+                mode="emulated",
+                reason="runner_stream_task_interrupt",
+            ),
+            pause=_unavailable("runtime_no_native_pause"),
+            resume=(
+                RuntimeCapability(supported=True, mode="native")
+                if checkpoint_supported
+                else _unavailable("runtime_no_native_checkpoint")
+            ),
+            submit_interaction=_unavailable("runtime_no_live_interaction_channel"),
+            attach=(
+                RuntimeCapability(supported=True, mode="native")
+                if attach_seam
+                else _unavailable("runner_no_durable_attach_seam")
+            ),
+            steer=_unavailable("runtime_no_native_steer"),
+            inject=_unavailable("runtime_no_native_inject"),
+            checkpoint=(
+                RuntimeCapability(supported=True, mode="native")
+                if checkpoint_supported
+                else _unavailable("runtime_no_native_checkpoint")
+            ),
+            durable_restore=(
+                RuntimeCapability(supported=True, mode="native")
+                if durable_supported
+                else _unavailable("durable_restore_requires_cross_process_checkpoint")
+            ),
+        )
+
+    async def durable_restore(self, handle: RunHandle) -> RunHandle:
+        if not self.capabilities().durable_restore.supported:
+            raise UnsupportedControlError(
+                f"{self._runtime_type} has no cross-process checkpoint backend for run "
+                f"{handle.run_id!r}"
+            )
+        return await self.attach(handle)
+
     def _checkpoint_capability(self) -> CheckpointCapability:
         """诚实暴露 checkpoint 粒度。默认读 runner.describe_checkpoint_capability。"""
         raw = {}
@@ -230,7 +247,13 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
 
     # ---- 六动词 ----
 
+    async def preflight(self) -> None:
+        """Load the framework agent before a streaming HTTP response commits."""
+
+        ensure_runner_loaded(self._runner, runtime_type=self._runtime_type)
+
     async def start(self, request: StartRequest) -> RunHandle:
+        ensure_runner_loaded(self._runner, runtime_type=self._runtime_type)
         run_id = str(request.metadata.get("invocation_id") or self._next_invocation_id())
         prepared_start = await prepare_runtime_start(request, self._runner)
         handle = RunHandle(
@@ -275,7 +298,7 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
             )
         attach = getattr(self._runner, "attach_runtime_handle", None)
         if not callable(attach):
-            raise RuntimeError(
+            raise UnsupportedControlError(
                 f"runner for {self._runtime_type!r} has no durable "
                 "attach_runtime_handle capability"
             )
@@ -336,6 +359,12 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
             return handle
         self._require_native_checkpoint_capability()
         self._known_runs.add(handle.run_id)
+        prepared_start: PreparedRuntimeStart | None = None
+        raw_start_request = handle.native_ref.pop(RESUME_START_REQUEST_NATIVE_KEY, None)
+        if isinstance(raw_start_request, Mapping):
+            prepared_start = await prepare_runtime_start(
+                StartRequest.model_validate(raw_start_request), self._runner
+            )
         # _resume_native 返回的 runner_input 覆盖存到 run 上,下一次 stream() 经
         # _build_runner_input 消费,以框架原生方式真驱动恢复。
         override = await self._resume_native(handle, target, payload)
@@ -380,6 +409,8 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
             resume_key=resume_key,
             resume_fingerprint=resume_fingerprint,
         )
+        if prepared_start is not None:
+            run.__dict__["_prepared_start"] = prepared_start
         if override:
             run.__dict__["_resume_input_override"] = override
         self._resume_decisions[resume_key] = resume_fingerprint
@@ -390,7 +421,7 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
         capability = self._require_native_checkpoint_capability()
         checkpoint_id = str(handle.native_ref.get("checkpoint_id") or "").strip()
         if not checkpoint_id:
-            raise RuntimeError(
+            raise UnsupportedControlError(
                 f"{self._runtime_type} runner has no native checkpoint for run "
                 f"{handle.run_id!r}"
             )
@@ -407,7 +438,7 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
         if capability.supported:
             return capability
         detail = capability.reason or "runner does not expose framework checkpoints"
-        raise RuntimeError(
+        raise UnsupportedControlError(
             f"{self._runtime_type} native checkpoint capability is unavailable: {detail}"
         )
 
@@ -477,30 +508,19 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
         # 消费 pending cancel:start 时若已记 pending,立即中断该 turn。
         if handle.run_id in self._pending_cancels:
             self._pending_cancels.discard(handle.run_id)
-            yield self._event(
-                handle,
-                EventType.RUN_CANCELED,
-                {
-                    "status": "cancelled",
-                    "cancel_result": CancelResult.PENDING_CANCEL_RECORDED.value,
-                },
-            )
+            yield self._make_run_canceled(handle, reason=CancelResult.PENDING_CANCEL_RECORDED.value)
             return
 
         if run.skip_runner:
             run.done = True
             self._active_runs.pop(handle.run_id, None)
-            yield self._event(
-                handle,
-                EventType.RUN_COMPLETED,
-                {"status": "already_resumed"},
-            )
+            yield self._make_run_completed(handle)
             return
 
         if run.resume_key is not None:
             self._consumed_resumes.add(run.resume_key)
 
-        yield self._event(handle, EventType.RUN_STARTED, {"status": "in_progress"})
+        yield self._make_run_started(handle)
 
         request = run.__dict__.get("_start_request")
         runner_input = self._build_runner_input(handle, request)
@@ -512,35 +532,35 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
             run.stream = gen
             async for event in gen:
                 yield event
-                if event.event_type == EventType.APPROVAL_REQUESTED:
+                if event.event_type == "interaction.requested":
                     approval_interrupted = True
+                    # Track pending approval for canonical streams that bypass
+                    # _chunk_to_event (e.g. stream_canonical_events).
+                    if isinstance(event, InteractionRequested):
+                        call_id = str(event.interaction_id or "")
+                        if call_id:
+                            run.pending_approvals.add(call_id)
+                            pending_ids = handle.native_ref.setdefault("pending_approval_ids", [])
+                            if call_id not in pending_ids:
+                                pending_ids.append(call_id)
                 if event.event_type in {
-                    EventType.RUN_COMPLETED,
-                    EventType.RUN_FAILED,
-                    EventType.RUN_CANCELED,
-                    EventType.RUN_INTERRUPTED,
+                    "run.completed",
+                    "run.failed",
+                    "run.canceled",
+                    "run.interrupted",
                 }:
                     terminal_event_seen = True
-                if event.event_type in {EventType.RUN_FAILED, EventType.RUN_CANCELED}:
+                if event.event_type in {"run.failed", "run.canceled"}:
                     return
 
             if run.interrupt_event.is_set() and not terminal_event_seen:
-                yield self._event(
-                    handle,
-                    EventType.RUN_CANCELED,
-                    {
-                        "status": "cancelled",
-                        "cancel_result": CancelResult.INTERRUPTED_ACTIVE_TURN.value,
-                    },
+                yield self._make_run_canceled(
+                    handle, reason=CancelResult.INTERRUPTED_ACTIVE_TURN.value
                 )
             elif approval_interrupted and not terminal_event_seen:
-                yield self._event(
-                    handle,
-                    EventType.RUN_INTERRUPTED,
-                    {"status": "input_required"},
-                )
+                yield self._make_run_interrupted(handle, reason="input_required")
             elif not terminal_event_seen:
-                yield self._event(handle, EventType.RUN_COMPLETED, {"status": "completed"})
+                yield self._make_run_completed(handle, run=run, metrics=run.completion_metrics)
         finally:
             run.stream = None
             run.done = True
@@ -551,19 +571,30 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
         # 直接作为 runner 输入,驱动框架原生恢复。
         run = self._active_runs.get(handle.run_id)
         override = run.__dict__.get("_resume_input_override") if run is not None else None
+        prepared_start = run.__dict__.get("_prepared_start") if run is not None else None
         if override is not None:
-            merged = {
-                "input": override.get("input"),
-                "session_id": handle.session_id,
-                "invocation_id": handle.run_id,
-                "metadata": dict(override.get("metadata") or {}),
-            }
+            merged = (
+                dict(prepared_start.runner_input)
+                if isinstance(prepared_start, PreparedRuntimeStart)
+                else {}
+            )
+            base_metadata = merged.get("metadata")
+            merged.update(
+                {
+                    "input": override.get("input"),
+                    "session_id": handle.session_id,
+                    "invocation_id": handle.run_id,
+                    "metadata": {
+                        **(dict(base_metadata) if isinstance(base_metadata, Mapping) else {}),
+                        **dict(override.get("metadata") or {}),
+                    },
+                }
+            )
             for key, value in override.items():
                 if key not in ("input", "metadata"):
                     merged[key] = value
             return merged
 
-        prepared_start = run.__dict__.get("_prepared_start") if run is not None else None
         if isinstance(prepared_start, PreparedRuntimeStart):
             return dict(prepared_start.runner_input)
 
@@ -582,283 +613,191 @@ class RunnerRuntimeAdapter(RuntimeAdapter):
             "metadata": metadata,
         }
 
-    async def _map_runner_stream(
-        self, handle: RunHandle, runner_input: dict
-    ) -> AsyncIterator[RuntimeEvent]:
-        run = self._active_runs.get(handle.run_id)
-        interrupt = run.interrupt_event if run is not None else None
-        prepared_start = run.__dict__.get("_prepared_start") if run is not None else None
-        invocation_context = (
-            prepared_start.context if isinstance(prepared_start, PreparedRuntimeStart) else None
-        )
-        scope = (
-            platform_invocation_scope(invocation_context)
-            if invocation_context is not None
-            else nullcontext()
+    # ---- canonical event construction helpers ----
+
+    def _interaction_requested_from_approval(
+        self,
+        handle: RunHandle,
+        run: Optional[_ActiveRun],
+        *,
+        detail: Mapping[str, Any],
+        call_id: str,
+    ) -> list[RuntimeEvent]:
+        """把 ToolGateway 结果中携带的审批请求转为 canonical InteractionRequested。"""
+
+        approval_id = str(detail.get("approval_request_id") or detail.get("id") or call_id or "")
+        resolved_call_id = str(call_id or approval_id)
+        if run is not None and approval_id:
+            run.pending_approvals.add(approval_id)
+        if approval_id:
+            pending_approval_ids = handle.native_ref.setdefault("pending_approval_ids", [])
+            if approval_id not in pending_approval_ids:
+                pending_approval_ids.append(approval_id)
+        framework = self._runtime_type
+        run_id = handle.run_id
+        scope_id = stable_scope_id(framework, run_id)
+        interaction_id = resolved_call_id or stable_item_id(framework, run_id, "interaction")
+        item_id = stable_item_id(framework, run_id, "interaction")
+        detail_value: JsonValue = (
+            cast(JsonValue, dict(detail)) if isinstance(detail, Mapping) else None
         )
-        runner_name = _runner_name(self._runner)
-        accumulated_output: list[str] = []
-        usage: dict[str, Any] = {}
-        runner_gen: Optional[AsyncIterator[Any]] = None
-        async with _conversation_span_scope(runner_name) as span:
-            if isinstance(prepared_start, PreparedRuntimeStart):
-                _set_conversation_span_attributes(
-                    span,
-                    agent_id=str(handle.native_ref.get("agent_id") or "agent"),
-                    user_id=str(handle.native_ref.get("user_id") or "user"),
-                    session_id=handle.session_id,
-                    invocation_id=handle.run_id,
-                    runner_name=runner_name,
-                    model=prepared_start.context.model,
-                    response_id=prepared_start.response_id,
-                )
-                _set_conversation_input_attributes(span, prepared_start.input_text)
-            try:
-                with scope:
-                    stream_result = self._runner.stream(runner_input)
-                    if inspect.iscoroutine(stream_result):
-                        # runner.stream 若声明为 async def -> AsyncIterator(非 async generator),
-                        # 调用返回 coroutine,需 await 得到迭代器。
-                        stream_result = await stream_result
-                    runner_gen = cast(AsyncIterator[Any], stream_result)
-                    while True:
-                        # 竞速:下一个 runner chunk vs cancel 中断事件。
-                        chunk_task = asyncio.ensure_future(_anext_or_stop(runner_gen))
-                        if run is not None:
-                            run.chunk_task = chunk_task
-                        wait_set = {chunk_task}
-                        interrupt_task = (
-                            asyncio.ensure_future(interrupt.wait())
-                            if interrupt is not None
-                            else None
-                        )
-                        if interrupt_task is not None:
-                            wait_set.add(interrupt_task)
-                        done, pending = await asyncio.wait(
-                            wait_set, return_when=asyncio.FIRST_COMPLETED
-                        )
-                        for task in pending:
-                            task.cancel()
-                        if pending:
-                            await asyncio.gather(*pending, return_exceptions=True)
-                        if interrupt_task is not None and interrupt_task in done:
-                            # cancel 中断:安全关闭 runner 流(同一 task)并停止。
-                            chunk_task.cancel()
-                            await asyncio.gather(chunk_task, return_exceptions=True)
-                            return
-                        try:
-                            chunk = chunk_task.result()
-                        except asyncio.CancelledError:
-                            if interrupt is not None and interrupt.is_set():
-                                return
-                            raise
-                        finally:
-                            if run is not None:
-                                run.chunk_task = None
-                        if chunk is _STREAM_STOP:
-                            return
-                        if isinstance(chunk, dict):
-                            chunk_type = str(chunk.get("type") or "")
-                            if chunk_type in {"final", "text", "text_delta"}:
-                                text = self._coerce(
-                                    chunk.get("delta") or chunk.get("output") or chunk.get("data")
-                                )
-                                if text:
-                                    accumulated_output.append(text)
-                            raw_usage = chunk.get("usage")
-                            if isinstance(raw_usage, dict):
-                                usage.update(raw_usage)
-                        event = self._chunk_to_event(handle, run, chunk)
-                        if event is not None:
-                            yield event
-                        a2ui_surface = _a2ui_surface_event(chunk)
-                        if a2ui_surface is not None:
-                            event_type, payload = a2ui_surface
-                            yield self._event(handle, event_type, payload)
-            finally:
-                if accumulated_output:
-                    _set_conversation_output_attributes(span, "".join(accumulated_output))
-                _set_conversation_usage_attributes(span, usage)
-                if runner_gen is not None:
-                    aclose = getattr(runner_gen, "aclose", None)
-                    if callable(aclose):
-                        try:
-                            await aclose()
-                        except Exception:  # noqa: BLE001
-                            pass
-                if run is not None:
-                    run.cancellation_ack.set()
-
-    def _chunk_to_event(
-        self, handle: RunHandle, run: Optional[_ActiveRun], chunk: Any
-    ) -> Optional[RuntimeEvent]:
-        if not isinstance(chunk, dict):
-            return self._event(
-                handle, EventType.TEXT_DELTA, {"text": str(chunk)}, phase="commentary"
-            )
-        chunk_type = chunk.get("type")
-        if chunk_type in ("reasoning", "reasoning_delta", "thinking"):
-            text = self._coerce(
-                chunk.get("delta")
-                or chunk.get("content")
-                or chunk.get("output")
-                or chunk.get("data")
-            )
-            if not text:
-                return None
-            event_type = (
-                EventType.REASONING_COMPLETED
-                if chunk.get("status") in ("completed", "done")
-                else EventType.REASONING_DELTA
-            )
-            return self._event(
-                handle,
-                event_type,
-                {"text": text},
-                phase="commentary",
-            )
-        if chunk_type in ("tool_call", "tool_start"):
-            call_id = str(
-                chunk.get("tool_call_id")
-                or chunk.get("call_id")
-                or chunk.get("run_id")
-                or chunk.get("id")
-                or ""
-            )
-            name = str(chunk.get("tool_name") or chunk.get("name") or "tool")
-            return self._event(
-                handle,
-                EventType.TOOL_CALL_BEGIN,
-                {
-                    "call_id": call_id or name,
-                    "name": name,
-                    "args": chunk.get("tool_args", chunk.get("args")),
-                },
-            )
-        if chunk_type in ("tool_result", "tool_end"):
-            call_id = str(
-                chunk.get("tool_call_id")
-                or chunk.get("call_id")
-                or chunk.get("run_id")
-                or chunk.get("id")
-                or ""
-            )
-            name = str(chunk.get("tool_name") or chunk.get("name") or "tool")
-            return self._event(
-                handle,
-                EventType.TOOL_CALL_END,
-                {
-                    "call_id": call_id or name,
-                    "name": name,
-                    "result": chunk.get("tool_output", chunk.get("output")),
-                    "error": chunk.get("error"),
-                },
-            )
-        if chunk_type in ("interrupt", "approval", "approval_required"):
-            detail = chunk.get("interrupt_info") or chunk.get("detail") or {}
-            detail_id = detail.get("approval_request_id") if isinstance(detail, dict) else None
-            call_id = str(
-                chunk.get("call_id")
-                or chunk.get("approval_id")
-                or chunk.get("id")
-                or detail_id
-                or ""
-            )
-            if run is not None and call_id:
-                run.pending_approvals.add(call_id)
-            if call_id:
-                pending_approval_ids = handle.native_ref.setdefault("pending_approval_ids", [])
-                if call_id not in pending_approval_ids:
-                    pending_approval_ids.append(call_id)
-            return self._event(
-                handle,
-                EventType.APPROVAL_REQUESTED,
-                {
-                    "approval_id": call_id,
-                    "call_id": call_id,
-                    "kind": "tool",
-                    "detail": detail,
-                },
-            )
-        if chunk_type == "checkpoint":
-            metadata = chunk.get("metadata") or {}
-            agentengine = metadata.get("agentengine") if isinstance(metadata, dict) else {}
-            framework_ref = (
-                agentengine.get("framework_ref") if isinstance(agentengine, dict) else {}
-            ) or {}
-            runtime_ref = (
-                framework_ref.get(self._runtime_type) if isinstance(framework_ref, dict) else {}
-            ) or {}
-            checkpoint_id = str(
-                runtime_ref.get("checkpoint_id") if isinstance(runtime_ref, dict) else ""
-            )
-            if not checkpoint_id:
-                return None
-            handle.native_ref["checkpoint_id"] = checkpoint_id
-            known_checkpoint_ids = handle.native_ref.setdefault("known_checkpoint_ids", [])
-            if checkpoint_id not in known_checkpoint_ids:
-                known_checkpoint_ids.append(checkpoint_id)
-            handle.native_ref["framework_ref"] = framework_ref
-            if isinstance(runtime_ref, dict):
-                handle.native_ref.update(runtime_ref)
-            return self._event(
-                handle,
-                EventType.CHECKPOINT_CREATED,
-                {
-                    "checkpoint_id": checkpoint_id,
-                    "granularity": self._checkpoint_capability().granularity,
-                    "resume_target": framework_ref,
-                },
-            )
-        if chunk_type == "graph_update":
-            return self._event(
-                handle,
-                EventType.RUN_PROGRESS,
-                {
-                    "status": "in_progress",
-                    "node": str(chunk.get("node") or ""),
-                    "state_update": self._coerce(chunk.get("output")),
-                },
-            )
-        if chunk_type == "error":
-            error = self._coerce(chunk.get("message") or chunk.get("error"))
-            return self._event(
-                handle,
-                EventType.RUN_FAILED,
-                {
-                    "status": "failed",
-                    "error": error or "runner failed",
-                },
-            )
-        if chunk_type == "final":
-            return self._event(
-                handle,
-                EventType.TEXT_COMPLETED,
-                {"text": self._coerce(chunk.get("output"))},
-                phase="final_answer",
+        return [
+            InteractionRequested(
+                **self._canonical_kwargs(
+                    handle,
+                    scope_id=scope_id,
+                    item_id=item_id,
+                    event_type="interaction.requested",
+                    part_id="interaction",
+                ),
+                interaction_id=interaction_id,
+                interaction_kind="approval",
+                request=ApprovalRequest(
+                    call_id=resolved_call_id or None,
+                    kind="tool",
+                    detail=detail_value,
+                ),
             )
-        text = self._coerce(chunk.get("delta") or chunk.get("output") or chunk.get("data"))
-        if not text:
-            return None
-        return self._event(handle, EventType.TEXT_DELTA, {"text": text}, phase="commentary")
+        ]
+
+    def _make_source(self, handle: RunHandle, *, protocol: str | None = None) -> SourceRef:
+        # SourceRef.framework 是封闭枚举;测试 fixture 或自定义 runtime_type 落到
+        # 通用 "ksadk",原生框架名原样保留。
+        framework = self._runtime_type
+        if framework not in {"adk", "langgraph", "codex", "a2a", "ksadk"}:
+            framework = "ksadk"
+        return SourceRef(
+            framework=framework,
+            protocol=protocol,
+            native_run_id=handle.run_id,
+            metadata={
+                "agent_id": str(handle.native_ref.get("agent_id") or "agent"),
+                "user_id": str(handle.native_ref.get("user_id") or "user"),
+                "session_id": handle.session_id,
+                "invocation_id": handle.run_id,
+            },
+        )
 
-    def _event(
+    def _canonical_kwargs(
         self,
         handle: RunHandle,
+        *,
+        scope_id: str,
+        item_id: str,
         event_type: str,
-        payload: dict,
+        part_id: str,
+    ) -> dict[str, Any]:
+        """Build common EventEnvelope kwargs for the dict-chunk degraded path."""
+        framework = self._runtime_type
+        run_id = handle.run_id
+        # TODO(runtime-event-v2): dict chunk 退化路径,chunk_ordinal 用 seq counter;
+        # LangGraph/Codex 切 stream_canonical_events 后清理
+        n = self._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": self._make_source(handle),
+        }
+
+    def _make_run_started(self, handle: RunHandle) -> RunStarted:
+        framework = self._runtime_type
+        run_id = handle.run_id
+        scope_id = stable_scope_id(framework, run_id)
+        item_id = stable_item_id(framework, run_id, "$run")
+        return RunStarted(
+            schema_version=2,
+            event_id=stable_event_id(framework, scope_id, item_id, "run.started", "run", run_id, 0),
+            seq=self._next_seq(),
+            timestamp=time.time(),
+            run_id=run_id,
+            scope_id=scope_id,
+            source=self._make_source(handle),
+            status="running",
+        )
+
+    def _make_run_completed(
+        self,
+        handle: RunHandle,
         *,
-        phase: Optional[str] = None,
-    ) -> RuntimeEvent:
-        return RuntimeEvent.create(
-            event_type,
-            agent_id=str(handle.native_ref.get("agent_id") or "agent"),
-            user_id=str(handle.native_ref.get("user_id") or "user"),
-            session_id=handle.session_id,
-            invocation_id=handle.run_id,
-            seq_id=self._next_seq(),
-            phase=phase,
-            payload=payload,
+        run: Optional[_ActiveRun] = None,
+        metrics: Mapping[str, Any] | None = None,
+    ) -> RunCompleted:
+        framework = self._runtime_type
+        run_id = handle.run_id
+        scope_id = stable_scope_id(framework, run_id)
+        item_id = stable_item_id(framework, run_id, "$run")
+        output_refs: tuple[OutputRef, ...] = ()
+        if run is not None and run.final_answer_item_id:
+            output_refs = (
+                OutputRef(
+                    scope_id=scope_id,
+                    item_id=run.final_answer_item_id,
+                    part_id="text-0",
+                ),
+            )
+        source = self._make_source(handle)
+        if metrics:
+            source = source.model_copy(
+                update={"metadata": {**source.metadata, "metrics": dict(metrics)}}
+            )
+        return RunCompleted(
+            schema_version=2,
+            event_id=stable_event_id(
+                framework, scope_id, item_id, "run.completed", "run", run_id, 0
+            ),
+            seq=self._next_seq(),
+            timestamp=time.time(),
+            run_id=run_id,
+            scope_id=scope_id,
+            source=source,
+            status="completed",
+            output_refs=output_refs,
+        )
+
+    def _make_run_canceled(self, handle: RunHandle, *, reason: str | None = None) -> RunCanceled:
+        framework = self._runtime_type
+        run_id = handle.run_id
+        scope_id = stable_scope_id(framework, run_id)
+        item_id = stable_item_id(framework, run_id, "$run")
+        return RunCanceled(
+            schema_version=2,
+            event_id=stable_event_id(
+                framework, scope_id, item_id, "run.canceled", "run", run_id, 0
+            ),
+            seq=self._next_seq(),
+            timestamp=time.time(),
+            run_id=run_id,
+            scope_id=scope_id,
+            source=self._make_source(handle),
+            status="canceled",
+            reason=reason,
+        )
+
+    def _make_run_interrupted(
+        self, handle: RunHandle, *, reason: str | None = None
+    ) -> RunInterrupted:
+        framework = self._runtime_type
+        run_id = handle.run_id
+        scope_id = stable_scope_id(framework, run_id)
+        item_id = stable_item_id(framework, run_id, "$run")
+        return RunInterrupted(
+            schema_version=2,
+            event_id=stable_event_id(
+                framework, scope_id, item_id, "run.interrupted", "run", run_id, 0
+            ),
+            seq=self._next_seq(),
+            timestamp=time.time(),
+            run_id=run_id,
+            scope_id=scope_id,
+            source=self._make_source(handle),
+            status="interrupted",
+            reason=reason,
         )
 
     @staticmethod