agentengine-sdk-python 0.8.2__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,11 +66,43 @@ 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,
     chunk: Any,
-) -> RuntimeEvent | None:
+) -> 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
@@ -83,7 +116,7 @@ def _a2ui_surface_event(
     """
 
     if not isinstance(chunk, dict):
-        return None
+        return ()
     value = chunk.get("tool_output", chunk.get("output"))
     if value is not None and hasattr(value, "content"):
         value = value.content
@@ -91,15 +124,15 @@ def _a2ui_surface_event(
         try:
             value = json.loads(value)
         except (TypeError, ValueError):
-            return None
+            return ()
     if not isinstance(value, Mapping):
-        return None
+        return ()
     operations_raw = value.get("a2ui_operations")
     if not isinstance(operations_raw, list) or not operations_raw:
-        return None
+        return ()
     operations = [dict(operation) for operation in operations_raw if isinstance(operation, Mapping)]
     if not operations:
-        return None
+        return ()
 
     known: list[tuple[str, str]] = []  # (surface_id, lifecycle)
     for operation in operations:
@@ -116,71 +149,75 @@ def _a2ui_surface_event(
                     known.append((surface_id, lifecycle))
                     break
     if not known:
-        return None
+        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 None
+        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)
-    item_id = stable_item_id(framework, run_id, "a2ui", surface_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},
+        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 后清理
-    n = self._next_seq()
     timestamp = time.time()
-    if lifecycle == "begin":
-        return ItemStarted(
+    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, n
+                framework, scope_id, item_id, "item.started", "a2ui", run_id, start_seq
             ),
-            seq=n,
+            seq=start_seq,
             timestamp=timestamp,
             run_id=run_id,
             scope_id=scope_id,
             source=source,
             item_id=item_id,
             item_kind="data",
-            initial=ContentSnapshot(parts=(DataContent(part_id="a2ui-ops", data=operations),)),
-        )
-    if lifecycle == "update":
-        return ItemUpdated(
+            initial=snapshot,
+        ),
+        ItemCompleted(
             schema_version=2,
             event_id=stable_event_id(
-                framework, scope_id, item_id, "item.updated", "a2ui", run_id, n
+                framework, scope_id, item_id, "item.completed", "a2ui", run_id, completed_seq
             ),
-            seq=n,
+            seq=completed_seq,
             timestamp=timestamp,
             run_id=run_id,
             scope_id=scope_id,
             source=source,
             item_id=item_id,
             item_kind="data",
-            op="replace",
-            update=DataContent(part_id="a2ui-ops", data=operations),
-        )
-    # lifecycle == "end"
-    return ItemCompleted(
-        schema_version=2,
-        event_id=stable_event_id(framework, scope_id, item_id, "item.completed", "a2ui", run_id, n),
-        seq=n,
-        timestamp=timestamp,
-        run_id=run_id,
-        scope_id=scope_id,
-        source=source,
-        item_id=item_id,
-        item_kind="data",
-        snapshot=ContentSnapshot(parts=()),
+            snapshot=snapshot,
+        ),
     )
 
 
@@ -188,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
@@ -205,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
@@ -243,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 = (
@@ -265,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
@@ -323,14 +398,17 @@ class _RunnerStreamMappingMixin:
                                 usage.update(raw_usage)
                         for event in self._chunk_to_event(handle, run, chunk):  # type: ignore[attr-defined]
                             yield event
-                        a2ui_surface = _a2ui_surface_event(self, handle, chunk)
-                        if a2ui_surface is not None:
+                        for a2ui_surface in _a2ui_surface_event(self, handle, chunk):
                             yield a2ui_surface
             finally:
                 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:
@@ -338,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(
@@ -384,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 ----
@@ -446,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,
@@ -493,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 里;识别后转为
@@ -615,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 {}),
                     },
                 )
             ]
@@ -708,8 +835,10 @@ class _RunnerStreamMappingMixin:
             if run is not None:
                 run.final_answer_item_id = item_id
             text_content = TextContent(part_id="text-0", text=output)
-            # Auto-close any open commentary/reasoning item before emitting final_answer.
-            # Text/thinking deltas create items that are never ItemCompleted;
+            # Auto-close any open explicit commentary/reasoning item before completing
+            # final_answer. Text deltas already belong to the final-answer item and must
+            # keep that identity through completion.
+            # Commentary/thinking deltas create items that are never ItemCompleted;
             # without this, RunCompleted fails _ensure_no_open_items.
             #
             # Close them *before* allocating the final-answer item.  Event
@@ -764,9 +893,13 @@ class _RunnerStreamMappingMixin:
         text = self._coerce(chunk.get("delta") or chunk.get("output") or chunk.get("data"))  # type: ignore[attr-defined]
         if not text:
             return []
-        item_id = stable_item_id(framework, run_id, "message", "commentary")
+        is_commentary = chunk_type in {"commentary", "commentary_delta"}
+        phase = "commentary" if is_commentary else "final_answer"
+        item_id = stable_item_id(framework, run_id, "message", phase)
+        if run is not None and not is_commentary:
+            run.final_answer_item_id = item_id
         op: str = "replace" if chunk.get("replace") else "append"
-        events = ensure_started(item_id=item_id, item_kind="message", phase="commentary")
+        events = ensure_started(item_id=item_id, item_kind="message", phase=phase)
         events.append(
             ItemUpdated(
                 **self._canonical_kwargs(  # type: ignore[attr-defined]

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."""
 
 
 # ---------------------------------------------------------------------------
@@ -417,6 +419,7 @@ class RuntimeAdapter(ABC):
             inject=_unavailable("runtime_no_native_inject"),
             checkpoint=_unavailable(),
             durable_restore=_unavailable(),
+            interaction_mode="unavailable",
         )
 
     def native_capabilities(self) -> dict[str, object]:

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,