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

ksadk/runtime/_runner_adapter/stream_mapping.py

@@ -15,6 +15,7 @@ import logging
 import time
 from collections.abc import Mapping
 from contextlib import nullcontext
+from dataclasses import replace
 from typing import TYPE_CHECKING, Any, AsyncIterator, Optional, cast
 
 from pydantic import JsonValue
@@ -65,6 +66,38 @@ async def _anext_or_stop(gen: AsyncIterator[Any]) -> Any:
         return _STREAM_STOP
 
 
+async def _pump_stream_in_one_context(
+    gen: AsyncIterator[Any],
+    requests: asyncio.Queue[None],
+    results: asyncio.Queue[tuple[str, Any]],
+) -> None:
+    """Own one async generator in one Task without reading ahead."""
+    outcome: tuple[str, Any] = ("stop", _STREAM_STOP)
+    try:
+        while True:
+            await requests.get()
+            try:
+                chunk = await gen.__anext__()
+            except StopAsyncIteration:
+                break
+            await results.put(("chunk", chunk))
+    except asyncio.CancelledError:
+        raise
+    except BaseException as exc:
+        outcome = ("error", exc)
+    finally:
+        aclose = getattr(gen, "aclose", None)
+        if callable(aclose):
+            try:
+                await aclose()
+            except asyncio.CancelledError:
+                raise
+            except BaseException as exc:
+                if outcome[0] != "error":
+                    outcome = ("error", exc)
+    await results.put(outcome)
+
+
 def _a2ui_surface_event(
     self: Any,
     handle: RunHandle,
@@ -192,14 +225,27 @@ class _RunnerStreamMappingMixin:
     """``_map_runner_stream`` / ``_chunk_to_event`` 的实现载体(纯移动自 runner_adapter)。"""
 
     async def _map_runner_stream(
-        self, handle: RunHandle, runner_input: dict
+        self,
+        handle: RunHandle,
+        runner_input: dict,
+        *,
+        active_run: Optional[_ActiveRun] = None,
     ) -> AsyncIterator[RuntimeEvent]:
-        run: Optional[_ActiveRun] = self._active_runs.get(handle.run_id)  # type: ignore[attr-defined]
+        run: Optional[_ActiveRun] = active_run
+        if run is None:
+            run = self._active_runs.get(handle.run_id)  # type: ignore[attr-defined]
         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
         )
+        if run is not None and run.__dict__.get("_tag_context") is not None:
+            tag_context = run.__dict__["_tag_context"]
+            invocation_context = (
+                replace(invocation_context, session=tag_context.session)
+                if invocation_context is not None
+                else tag_context
+            )
         scope = (
             platform_invocation_scope(invocation_context)
             if invocation_context is not None
@@ -209,6 +255,9 @@ class _RunnerStreamMappingMixin:
         accumulated_output = ""
         usage: dict[str, Any] = {}
         runner_gen: Optional[AsyncIterator[Any]] = None
+        pump_requests: asyncio.Queue[None] | None = None
+        pump_queue: asyncio.Queue[tuple[str, Any]] | None = None
+        pump_task: asyncio.Task[None] | None = None
         # span scope 经 runner_adapter 模块属性间接解析,保持既有 monkeypatch
         # patch 点(tests/agui/test_runtime_preprocessing.py)继续生效。
         from ksadk.runtime import runner_adapter as _runner_adapter_module
@@ -247,10 +296,26 @@ class _RunnerStreamMappingMixin:
                         # 调用返回 coroutine,需 await 得到迭代器。
                         stream_result = await stream_result
                     runner_gen = cast(AsyncIterator[Any], stream_result)
+                    if self._requires_stable_stream_context():
+                        pump_requests = asyncio.Queue(maxsize=1)
+                        pump_queue = asyncio.Queue()
+                        pump_task = asyncio.create_task(
+                            _pump_stream_in_one_context(
+                                runner_gen, pump_requests, pump_queue
+                            )
+                        )
+                        if run is not None:
+                            run.chunk_task = pump_task
                     while True:
                         # 竞速:下一个 runner chunk vs cancel 中断事件。
-                        chunk_task = asyncio.ensure_future(_anext_or_stop(runner_gen))
-                        if run is not None:
+                        if pump_requests is not None:
+                            pump_requests.put_nowait(None)
+                        chunk_task = asyncio.ensure_future(
+                            pump_queue.get()
+                            if pump_queue is not None
+                            else _anext_or_stop(runner_gen)
+                        )
+                        if run is not None and pump_task is None:
                             run.chunk_task = chunk_task
                         wait_set = {chunk_task}
                         interrupt_task = (
@@ -269,17 +334,23 @@ class _RunnerStreamMappingMixin:
                             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)
+                            owner_task = pump_task or chunk_task
+                            owner_task.cancel()
+                            await asyncio.gather(owner_task, return_exceptions=True)
                             return
                         try:
                             chunk = chunk_task.result()
+                            if pump_task is not None:
+                                outcome, payload = cast(tuple[str, Any], chunk)
+                                if outcome == "error":
+                                    raise payload
+                                chunk = payload
                         except asyncio.CancelledError:
                             if interrupt is not None and interrupt.is_set():
                                 return
                             raise
                         finally:
-                            if run is not None:
+                            if run is not None and pump_task is None:
                                 run.chunk_task = None
                         if chunk is _STREAM_STOP:
                             return
@@ -333,7 +404,11 @@ class _RunnerStreamMappingMixin:
                 if accumulated_output:
                     _set_conversation_output_attributes(span, accumulated_output)
                 _set_conversation_usage_attributes(span, usage)
-                if runner_gen is not None:
+                if pump_task is not None:
+                    if not pump_task.done():
+                        pump_task.cancel()
+                    await asyncio.gather(pump_task, return_exceptions=True)
+                elif runner_gen is not None:
                     aclose = getattr(runner_gen, "aclose", None)
                     if callable(aclose):
                         try:
@@ -341,6 +416,8 @@ class _RunnerStreamMappingMixin:
                         except Exception:  # noqa: BLE001
                             pass
                 if run is not None:
+                    if pump_task is not None:
+                        run.chunk_task = None
                     run.cancellation_ack.set()
 
     def _chunk_to_event(
@@ -387,6 +464,24 @@ class _RunnerStreamMappingMixin:
                 )
             ]
 
+        def tool_item_id(effective_call_id: str, item_kind: str) -> str:
+            components = (effective_call_id, item_kind)
+            if run is None:
+                return stable_item_id(framework, run_id, *components)
+            occurrences = run.__dict__.setdefault("_tool_item_occurrences", {})
+            occurrence_key = (scope_id, item_kind, effective_call_id)
+            occurrence = int(occurrences.get(occurrence_key, 0))
+            occurrences[occurrence_key] = occurrence + 1
+            if occurrence == 0:
+                return stable_item_id(framework, run_id, *components)
+            return stable_item_id(
+                framework,
+                run_id,
+                *components,
+                "occurrence",
+                occurrence,
+            )
+
         chunk_type = chunk.get("type")
 
         # ---- reasoning ----
@@ -449,7 +544,7 @@ class _RunnerStreamMappingMixin:
             )
             name = str(chunk.get("tool_name") or chunk.get("name") or "tool")
             effective_call_id = call_id or name
-            item_id = stable_item_id(framework, run_id, effective_call_id, "tool_call")
+            item_id = tool_item_id(effective_call_id, "tool_call")
             part_id = "tool_call"
             tc_content = ToolCallContent(
                 part_id=part_id,
@@ -496,7 +591,7 @@ class _RunnerStreamMappingMixin:
             )
             name = str(chunk.get("tool_name") or chunk.get("name") or "tool")
             effective_call_id = call_id or name
-            item_id = stable_item_id(framework, run_id, effective_call_id, "tool_result")
+            item_id = tool_item_id(effective_call_id, "tool_result")
             part_id = "tool_result"
             result_data = chunk.get("tool_output", chunk.get("output"))
             # ToolGateway 审批可能出现在"本已终态"的 tool result 里;识别后转为
@@ -618,26 +713,55 @@ class _RunnerStreamMappingMixin:
             if isinstance(runtime_ref, dict):
                 handle.native_ref.update(runtime_ref)
             item_id = stable_item_id(framework, run_id, "$run")
+            # Extract checkpoint capability from agentengine metadata so the
+            # canonical event carries backend/scope/next_node facts that the
+            # projection layer (projection.py) needs for the REST payload.
+            capability: dict[str, Any] = {}
+            for cap_key in (
+                # Capability / resume fields
+                "backend", "scope", "durable", "next_node",
+                "is_terminal", "is_resumable", "resume_status",
+                "resume_disabled_reason",
+                # Checkpoint display fields
+                "phase", "stage", "stage_name", "stage_key",
+                "stage_index", "total_stages", "summary",
+                "next_action", "status", "artifact_preview",
+                "tool_name", "receipt_key", "artifact_path",
+            ):
+                cap_val = agentengine.get(cap_key)
+                if cap_val is not None:
+                    capability[cap_key] = cap_val
+            canonical_kwargs = self._canonical_kwargs(  # type: ignore[attr-defined]
+                handle,
+                scope_id=scope_id,
+                item_id=item_id,
+                event_type="continuation.created",
+                part_id="continuation",
+            )
+            if capability:
+                base_source = canonical_kwargs["source"]
+                canonical_kwargs["source"] = SourceRef(
+                    framework=base_source.framework,
+                    protocol=base_source.protocol,
+                    native_run_id=base_source.native_run_id,
+                    metadata={**base_source.metadata, "capability": capability},
+                )
             ref_value = cast(
                 JsonValue,
                 framework_ref if isinstance(framework_ref, dict) else {},
             )
+            next_node_val = agentengine.get("next_node")
             return [
                 ContinuationCreated(
-                    **self._canonical_kwargs(  # type: ignore[attr-defined]
-                        handle,
-                        scope_id=scope_id,
-                        item_id=item_id,
-                        event_type="continuation.created",
-                        part_id="continuation",
-                    ),
+                    **canonical_kwargs,
                     continuation_id=checkpoint_id,
                     continuation_kind="graph_checkpoint",
-                    resumable=True,
+                    resumable=bool(agentengine.get("is_resumable", True)),
                     ref={
                         "framework": ckpt_framework,
                         "framework_ref": ref_value,
                         "resume_target": ref_value,
+                        **({"next_node": str(next_node_val)} if next_node_val else {}),
                     },
                 )
             ]

ksadk/runtime/adapter.py

@@ -114,6 +114,8 @@ class ResumePayload(BaseModel):
     call_id: Optional[str] = None
     """对应的 ``approval.requested`` / ``tool.call`` 的 id(如有)。"""
     data: Any = None
+    session_context: dict[str, Any] | None = None
+    """Platform-owned snapshot for a new resume invocation; never model input."""
 
 
 # ---------------------------------------------------------------------------

ksadk/runtime/conversation_execution.py

@@ -194,12 +194,21 @@ async def iter_runtime_conversation_events(
             for persisted in await pipeline.ingest(context_event):
                 yield persisted
         async for event in executor.stream(handle):
-            _validate_event_scope(event, request)
+            _validate_event_scope(
+                event,
+                request,
+                alternate_run_id=(
+                    prepared.invocation_id if checkpoint_resume is not None else None
+                ),
+            )
             for persisted in await pipeline.ingest(event):
                 await _project_runtime_run_status(
                     persisted,
                     session_id=prepared.session_id,
                     author=agent_id,
+                    invocation_id=(
+                        prepared.invocation_id if checkpoint_resume is not None else None
+                    ),
                     run_mode=prepared.run_mode,
                     run_trigger=prepared.run_trigger,
                     session_service_provider=provider,
@@ -223,13 +232,16 @@ async def iter_runtime_conversation_events(
             raise RuntimeError("runtime stream ended without a terminal or interrupted event")
     except asyncio.CancelledError:
         cancel_result = await executor.cancel(handle)
+        cancel_run_id = (
+            prepared.invocation_id if checkpoint_resume is not None else handle.run_id
+        )
         cancelled_event = RunCanceled(
             schema_version=2,
-            event_id=f"cancel:{handle.run_id}:{cancel_result.value}",
+            event_id=f"cancel:{cancel_run_id}:{cancel_result.value}",
             seq=0,
             timestamp=time.time(),
-            run_id=handle.run_id,
-            scope_id=handle.run_id,
+            run_id=cancel_run_id,
+            scope_id=cancel_run_id,
             source=SourceRef(
                 framework="ksadk", metadata={"cancel_result": cancel_result.value}
             ),
@@ -241,6 +253,9 @@ async def iter_runtime_conversation_events(
             persisted_cancelled,
             session_id=prepared.session_id,
             author=agent_id,
+            invocation_id=(
+                prepared.invocation_id if checkpoint_resume is not None else None
+            ),
             run_mode=prepared.run_mode,
             run_trigger=prepared.run_trigger,
             session_service_provider=provider,
@@ -375,6 +390,7 @@ async def _project_runtime_run_status(
     *,
     session_id: str,
     author: str,
+    invocation_id: str | None = None,
     run_mode: str,
     run_trigger: str,
     session_service_provider: Callable[[], Any],
@@ -389,7 +405,7 @@ async def _project_runtime_run_status(
         session_id=session_id,
         author=author,
         status=status,
-        invocation_id=event.run_id,
+        invocation_id=str(invocation_id or event.run_id),
         detail=str(detail) if detail else None,
         metadata={
             "runtime_event_id": event.event_id,
@@ -450,10 +466,7 @@ async def _resume_runtime_handle(
 def _resume_target(resume_input: Mapping[str, Any]) -> ResumeTarget:
     framework = str(resume_input.get("framework") or "").strip().lower()
     framework_ref = resume_input.get("framework_ref")
-    raw_runtime_ref = framework_ref.get(framework) if isinstance(framework_ref, Mapping) else None
-    runtime_ref: Mapping[str, Any] = (
-        raw_runtime_ref if isinstance(raw_runtime_ref, Mapping) else {}
-    )
+    runtime_ref = _runtime_ref_from_projection(framework, framework_ref)
     checkpoint_id = str(resume_input.get("checkpoint_id") or "").strip()
     run_id = str(resume_input.get("run_id") or "").strip()
     if framework == "langgraph":
@@ -470,8 +483,7 @@ def _persisted_resume_native_ref(resume_input: Mapping[str, Any]) -> dict[str, A
     checkpoint_id = str(resume_input.get("checkpoint_id") or "").strip()
     framework_ref = resume_input.get("framework_ref")
     normalized_ref = dict(framework_ref) if isinstance(framework_ref, Mapping) else {}
-    runtime_ref = normalized_ref.get(framework)
-    native_ref = dict(runtime_ref) if isinstance(runtime_ref, Mapping) else {}
+    native_ref = _runtime_ref_from_projection(framework, normalized_ref)
     native_ref["framework_ref"] = normalized_ref
     if checkpoint_id:
         native_ref.setdefault("checkpoint_id", checkpoint_id)
@@ -479,12 +491,45 @@ def _persisted_resume_native_ref(resume_input: Mapping[str, Any]) -> dict[str, A
     return native_ref
 
 
-def _validate_event_scope(event: RuntimeEvent, request: StartRequest) -> None:
+def _runtime_ref_from_projection(framework: str, framework_ref: Any) -> dict[str, Any]:
+    """Flatten native refs wrapped by checkpoint REST/session projections."""
+
+    if not framework or not isinstance(framework_ref, Mapping):
+        return {}
+    raw = framework_ref.get(framework)
+    if not isinstance(raw, Mapping):
+        return {}
+    resolved = dict(raw)
+    current = raw
+    for _ in range(4):
+        nested_ref: Mapping[str, Any] | None = None
+        for key in ("framework_ref", "resume_target"):
+            container = current.get(key)
+            candidate = container.get(framework) if isinstance(container, Mapping) else None
+            if isinstance(candidate, Mapping):
+                nested_ref = candidate
+                break
+        if nested_ref is None:
+            break
+        resolved.update(nested_ref)
+        current = nested_ref
+    return resolved
+
+
+def _validate_event_scope(
+    event: RuntimeEvent,
+    request: StartRequest,
+    *,
+    alternate_run_id: str | None = None,
+) -> None:
     expected_run_id = str(request.metadata["invocation_id"])
-    if event.schema_version != 2 or event.run_id != expected_run_id:
+    expected_run_ids = {expected_run_id}
+    if alternate_run_id:
+        expected_run_ids.add(str(alternate_run_id))
+    if event.schema_version != 2 or event.run_id not in expected_run_ids:
         raise ValueError(
             "runtime event scope does not match request: "
-            f"expected run_id={expected_run_id!r}, got {event.run_id!r}"
+            f"expected run_id in {sorted(expected_run_ids)!r}, got {event.run_id!r}"
         )
 
 
@@ -496,6 +541,14 @@ async def iter_runtime_conversation_semantic_events(
     reducer = StreamReducer()
     approval: dict[str, Any] | None = None
     execution_context: dict[str, str] = {}
+    # (scope_id, call_id) → tool_name：不同子运行可复用原生 call_id。
+    # （ToolResultContent 不带 name，前端靠 name 关联 call/result）。
+    _tool_name_by_call_id: dict[tuple[str, str], str] = {}
+    # 按 scope 和 call_id 跨 ItemStarted/ItemCompleted 去重，保留其他子运行的调用。
+    # 各 adapter 产生 ToolCallContent 的位置不一致：Codex 在 ItemStarted.initial 和
+    # ItemCompleted.snapshot 都带（需去重）；LangGraph/ADK 的 ItemStarted.initial=None，
+    # ToolCallContent 只出现在 ItemCompleted.snapshot（需在 Completed 补发，不能跳过）。
+    _emitted_tool_call_ids: set[tuple[str, str]] = set()
     async for event in iter_runtime_conversation_events(
         **kwargs, _execution_context=execution_context
     ):
@@ -543,15 +596,34 @@ async def iter_runtime_conversation_semantic_events(
         elif isinstance(event, ItemStarted) and event.initial is not None:
             for part in event.initial.parts:
                 if isinstance(part, ToolCallContent):
+                    # 记录 call_id → name，供后续 tool_result 反查 name
+                    # （ToolResultContent 不带 name，否则前端渲染成 "tool"）。
+                    if part.call_id and part.name:
+                        _tool_name_by_call_id[(event.scope_id, part.call_id)] = part.name
+                    if (event.scope_id, part.call_id) in _emitted_tool_call_ids:
+                        continue
+                    if part.call_id:
+                        _emitted_tool_call_ids.add((event.scope_id, part.call_id))
                     yield _tool_call_semantic(part)
         elif isinstance(event, ItemCompleted):
             for part in event.snapshot.parts:
                 if isinstance(part, ToolCallContent):
+                    # Codex 的 ItemStarted.initial 已发过 tool_call → 去重跳过；
+                    # LangGraph/ADK 的 ItemStarted.initial=None 没发过 → 在这里补发，
+                    # 否则 tool_call 事件会丢失、tool_result 也反查不到 name。
+                    if part.call_id and part.name:
+                        _tool_name_by_call_id[(event.scope_id, part.call_id)] = part.name
+                    if (event.scope_id, part.call_id) in _emitted_tool_call_ids:
+                        continue
+                    if part.call_id:
+                        _emitted_tool_call_ids.add((event.scope_id, part.call_id))
                     yield _tool_call_semantic(part)
                 elif isinstance(part, ToolResultContent):
+                    # ToolResultContent 不带 name，用 call_id 反查 tool_call 的 name。
+                    tool_name = _tool_name_by_call_id.get((event.scope_id, part.call_id), "")
                     yield {
                         "type": "tool_result",
-                        "name": "",
+                        "name": tool_name,
                         "output": part.result,
                         "run_id": part.call_id,
                     }
@@ -596,7 +668,11 @@ async def iter_runtime_conversation_semantic_events(
                 else None
             )
             if isinstance(requested_agentengine, Mapping):
-                completion_metadata["agentengine"] = dict(requested_agentengine)
+                completion_metadata["agentengine"] = {
+                    key: value
+                    for key, value in requested_agentengine.items()
+                    if key != "session_context"
+                }
             completion_metadata["runtime"] = {
                 "duration_ms": event.source.metadata.get("duration_ms"),
                 "runtime_type": kwargs["launch_context"].runtime_type,

ksadk/runtime/executor.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import hashlib
+import inspect
 import json
 from contextlib import suppress
 from dataclasses import dataclass
@@ -75,6 +76,7 @@ class RuntimeExecutor:
         self._registry = registry
         self._kernel_store = kernel_store
         self._runs: dict[_HandleKey, _OwnedRun] = {}
+        self._capability_adapters: dict[int, tuple[RuntimeLaunchContext, RuntimeAdapter]] = {}
 
     def create_adapter(self, context: RuntimeLaunchContext) -> RuntimeAdapter:
         """从本 executor 的 registry 创建一个 adapter。
@@ -225,6 +227,18 @@ class RuntimeExecutor:
                     first_error = exc
             finally:
                 self._runs.pop(key, None)
+        for key, (_context, adapter) in list(self._capability_adapters.items()):
+            runner = getattr(adapter, "_runner", None)
+            close_runner = getattr(runner, "close", None)
+            if callable(close_runner):
+                try:
+                    result = close_runner()
+                    if inspect.isawaitable(result):
+                        await result
+                except BaseException as exc:
+                    if first_error is None:
+                        first_error = exc
+            self._capability_adapters.pop(key, None)
         if first_error is not None:
             raise first_error
 
@@ -295,7 +309,7 @@ class RuntimeExecutor:
     def native_capabilities(self, context: RuntimeLaunchContext) -> dict[str, object]:
         """Read the capability declaration from the registered Runtime implementation."""
 
-        adapter = self._registry.create(context)
+        adapter = self.capability_adapter(context)
         return dict(adapter.runtime.native_capabilities())
 
     def capability_matrix(self, context: RuntimeLaunchContext) -> dict[str, object]:
@@ -306,9 +320,25 @@ class RuntimeExecutor:
         modes can be exposed only when the selected runtime declares support.
         """
 
-        adapter = self._registry.create(context)
+        adapter = self.capability_adapter(context)
         return adapter.capabilities().model_dump(mode="json")
 
+    def capability_adapter(self, context: RuntimeLaunchContext) -> RuntimeAdapter:
+        """Return one stable, non-executing adapter for capability discovery."""
+
+        key = id(context)
+        cached = self._capability_adapters.get(key)
+        if cached is None or cached[0] is not context:
+            adapter = self._registry.create(context)
+            self._capability_adapters[key] = (context, adapter)
+            return adapter
+        return cached[1]
+
+    def capability_subject(self, context: RuntimeLaunchContext) -> object | None:
+        """Expose the runner whose async capability hooks feed persistence gating."""
+
+        return getattr(self.capability_adapter(context), "_runner", None)
+
     def registered_runtime_types(self) -> list[str]:
         """Expose Registry membership without leaking or duplicating the Registry."""
 
@@ -375,6 +405,51 @@ def _normalize_runtime_type(runtime_type: str) -> str:
     return runtime_type.strip().lower()
 
 
+def project_legacy_runtime_capabilities(
+    native: dict[str, object],
+    matrix: dict[str, object],
+) -> dict[str, object]:
+    """Fill the legacy PascalCase UI contract from the typed v1 matrix."""
+
+    projected = dict(native)
+
+    def capability(name: str) -> dict[str, object]:
+        value = matrix.get(name)
+        return dict(value) if isinstance(value, dict) else {}
+
+    cancel = capability("cancel")
+    checkpoint = capability("checkpoint")
+    resume = capability("resume")
+    projected.setdefault(
+        "CancelRun",
+        {
+            "Supported": cancel.get("supported") is True,
+            "Reason": str(cancel.get("reason") or ""),
+        },
+    )
+    projected.setdefault(
+        "Checkpoint",
+        {
+            "Supported": checkpoint.get("supported") is True,
+            "Backend": "native" if checkpoint.get("supported") is True else "none",
+            "Scope": "runtime",
+            "Durable": capability("durable_restore").get("supported") is True,
+            "SharedAcrossPods": False,
+            "ResumeMode": str(resume.get("mode") or "none"),
+            "Reason": str(checkpoint.get("reason") or ""),
+        },
+    )
+    projected.setdefault(
+        "ResumeRun",
+        {
+            "Supported": resume.get("supported") is True,
+            "ResumeMode": str(resume.get("mode") or "none"),
+            "Reason": str(resume.get("reason") or ""),
+        },
+    )
+    return projected
+
+
 def _handle_key(handle: RunHandle) -> _HandleKey:
     return (
         _normalize_runtime_type(handle.runtime_type),
@@ -389,4 +464,5 @@ __all__ = [
     "DurableRun",
     "RunNotFoundError",
     "handle_digest",
+    "project_legacy_runtime_capabilities",
 ]