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

ksadk/plugins/teams/workspaces.py

@@ -0,0 +1,255 @@
+"""Frozen inputs and per-attempt working trees inside an execution node.
+
+The authority stores an intent only. This module resolves filesystem paths on
+the actual execution node, within roots explicitly granted by its owner.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+from collections.abc import Sequence
+from pathlib import Path
+
+from .artifacts import read_workspace_artifact
+from .errors import TeamsError
+from .store import digest, encode
+
+
+def validate_workspace_plan(plan: dict | None, *, require_pinned_git: bool = False) -> None:
+    if (
+        plan
+        and require_pinned_git
+        and plan.get("mode", "auto") != "directory"
+        and not re.fullmatch(r"(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})", str(plan.get("baseRef") or ""))
+    ):
+        raise TeamsError(
+            "workspace_commit_required",
+            "服务端 Git 任务需要完整提交哈希；非 Git 文件请选择目录模式",
+            status=422,
+        )
+
+
+def _component(value: str) -> str:
+    if re.fullmatch(r"[a-zA-Z0-9_-]{1,160}", value):
+        return value
+    return hashlib.sha256(value.encode()).hexdigest()
+
+
+def _git(source: Path, *arguments: str, required: bool = True) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-c", "core.hooksPath=/dev/null", "-C", str(source), *arguments],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+            env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise TeamsError(
+            "workspace_git_unavailable", "Git 工作区准备失败，请检查节点环境", status=422
+        ) from error
+    if result.returncode:
+        if not required:
+            return None
+        raise TeamsError(
+            "workspace_git_failed", "无法准备所选 Git 基线，请检查提交与仓库", status=422
+        )
+    return result.stdout.strip()
+
+
+def _relative_input(value: str) -> Path:
+    path = Path(value)
+    if (
+        not path.parts
+        or path.is_absolute()
+        or ".." in path.parts
+        or ".git" in path.parts
+        or "\x00" in value
+    ):
+        raise TeamsError(
+            "workspace_input_forbidden", "输入必须是源目录内的普通相对文件", status=422
+        )
+    return path
+
+
+def _mkdir(path: Path, root: Path) -> None:
+    relative = path.relative_to(root)
+    current = root
+    for part in relative.parts:
+        current = current / part
+        if current.is_symlink():
+            raise TeamsError("workspace_path_forbidden", "工作区路径不能包含符号链接", status=403)
+        current.mkdir(exist_ok=True)
+
+
+def prepare_workspace(
+    output_root: Path,
+    *,
+    group_id: str,
+    team_run_id: str,
+    member_id: str,
+    attempt_id: str,
+    plan: dict | None,
+    allowed_roots: Sequence[Path],
+    require_pinned_git: bool = False,
+) -> Path:
+    """Return the real cwd; each run resolves its baseline exactly once per node.
+
+    Git HEAD/ref includes committed content. Explicit input files are frozen
+    separately, allowing a user to intentionally supply an untracked file.
+    Existing attempt directories are reused without resetting their changes.
+    """
+    validate_workspace_plan(plan, require_pinned_git=require_pinned_git)
+    output_root = output_root.resolve()
+    output_root.mkdir(parents=True, exist_ok=True)
+    run_root = output_root / _component(group_id) / _component(team_run_id)
+    target = run_root / _component(member_id) / _component(attempt_id)
+    _mkdir(target.parent, output_root)
+    if not plan:
+        _mkdir(target, output_root)
+        return target
+    source = Path(plan["sourcePath"]).expanduser().resolve()
+    if not any(source.is_relative_to(Path(root).resolve()) for root in allowed_roots):
+        raise TeamsError(
+            "workspace_source_forbidden", "所选目录不在该执行节点允许的工作目录内", status=403
+        )
+    if not source.is_dir():
+        raise TeamsError("workspace_source_missing", "所选源目录在执行节点上不存在", status=422)
+    # A filesystem lock coordinates simultaneous members and multiple node
+    # workers. Keep the lock file outside their writable attempt directories.
+    try:
+        import fcntl
+    except ImportError as error:
+        raise TeamsError(
+            "workspace_platform_unsupported", "当前节点不支持隔离工作区锁", status=422
+        ) from error
+    lock = run_root / ".workspace.lock"
+    fd = os.open(lock, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise TeamsError(
+                "workspace_busy", "任务基线正在由另一个执行准备，请稍后重试", status=409
+            ) from error
+        manifest_path = run_root / ".workspace.json"
+        if manifest_path.is_symlink():
+            raise TeamsError("workspace_manifest_invalid", "任务基线文件不可用", status=409)
+        plan_digest = digest(plan)
+        if manifest_path.exists():
+            manifest = json.loads(manifest_path.read_text())
+            if manifest["planDigest"] != plan_digest:
+                raise TeamsError(
+                    "workspace_plan_changed", "任务基线已经冻结，不能在执行中修改", status=409
+                )
+        else:
+            git_root = None
+            if plan.get("mode", "auto") == "auto":
+                git_root = _git(source, "rev-parse", "--show-toplevel", required=False)
+            if git_root:
+                repository = Path(git_root).resolve()
+                if not any(
+                    repository.is_relative_to(Path(root).resolve()) for root in allowed_roots
+                ):
+                    raise TeamsError(
+                        "workspace_source_forbidden", "Git 仓库根目录超出节点授权范围", status=403
+                    )
+                commit = _git(
+                    repository,
+                    "rev-parse",
+                    "--verify",
+                    "--end-of-options",
+                    str(plan.get("baseRef") or "HEAD") + "^{commit}",
+                )
+                if require_pinned_git and commit.lower() != plan["baseRef"].lower():
+                    raise TeamsError(
+                        "workspace_commit_mismatch", "节点仓库与任务冻结提交不一致", status=409
+                    )
+            else:
+                repository, commit = None, None
+                if plan.get("baseRef"):
+                    raise TeamsError(
+                        "workspace_base_ref_invalid", "只有 Git 工作区可以选择提交基线", status=422
+                    )
+            manifest = {
+                "planDigest": plan_digest,
+                "sourcePath": str(source),
+                "repository": str(repository) if repository else None,
+                "commit": commit,
+                "inputs": {},
+            }
+            frozen = run_root / ".inputs"
+            _mkdir(frozen, output_root)
+            total = 0
+            # Validate all files before publishing the run baseline.
+            supplied = []
+            for value in dict.fromkeys(plan.get("inputs", [])):
+                relative = _relative_input(value)
+                _, content = read_workspace_artifact(source, str(relative))
+                total += len(content)
+                if total > 64 * 1024 * 1024:
+                    raise TeamsError(
+                        "workspace_inputs_too_large", "单任务输入文件总计不能超过64MiB", status=422
+                    )
+                supplied.append((relative, content))
+            for relative, content in supplied:
+                input_target = frozen / relative
+                _mkdir(input_target.parent, output_root)
+                if input_target.is_symlink():
+                    raise TeamsError(
+                        "workspace_input_forbidden", "输入快照不能包含符号链接", status=403
+                    )
+                input_target.write_bytes(content)
+                manifest["inputs"][str(relative)] = hashlib.sha256(content).hexdigest()
+            temporary = manifest_path.with_suffix(".tmp")
+            with temporary.open("w", encoding="utf-8") as stream:
+                stream.write(encode(manifest))
+            temporary.replace(manifest_path)
+        marker = target.parent / (target.name + ".prepared.json")
+        if marker.exists():
+            if (
+                marker.is_symlink()
+                or json.loads(marker.read_text()).get("planDigest") != plan_digest
+            ):
+                raise TeamsError("workspace_manifest_invalid", "执行工作区标识不一致", status=409)
+            if target.is_symlink() or not target.is_dir():
+                raise TeamsError("workspace_path_forbidden", "执行工作区不可用", status=409)
+            return target
+        if target.exists():
+            # Never reset or delete partially prepared / user-edited files.
+            raise TeamsError(
+                "workspace_preparation_incomplete",
+                "工作区准备未完成，请检查该次尝试的目录后重试",
+                status=409,
+            )
+        if manifest["repository"]:
+            _git(
+                Path(manifest["repository"]),
+                "worktree",
+                "add",
+                "--detach",
+                str(target),
+                manifest["commit"],
+            )
+        else:
+            _mkdir(target, output_root)
+        for value, checksum in manifest["inputs"].items():
+            relative = _relative_input(value)
+            _, content = read_workspace_artifact(run_root / ".inputs", value)
+            if hashlib.sha256(content).hexdigest() != checksum:
+                raise TeamsError("workspace_input_changed", "冻结输入文件摘要已改变", status=409)
+            destination = target / relative
+            _mkdir(destination.parent, output_root)
+            if destination.is_symlink():
+                raise TeamsError("workspace_input_forbidden", "输入目标不能是符号链接", status=403)
+            destination.write_bytes(content)
+        with marker.open("x", encoding="utf-8") as stream:
+            stream.write(encode({"planDigest": plan_digest, "commit": manifest["commit"]}))
+        return target
+    finally:
+        os.close(fd)

ksadk/runners/_langgraph_runner_streams.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-import inspect
+import logging
 import time
 import uuid
 from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, Mapping
@@ -15,6 +15,10 @@ from langgraph.types import Command
 from ksadk.conversations.reasoning_markup import ReasoningMarkupParser, strip_reasoning_markup
 from ksadk.events.runtime_event import RuntimeEvent
 from ksadk.runners.usage_accumulator import accumulate_usage
+from ksadk.runtime.skill_eval_result import skill_eval_response_fields
+from ksadk.runtime.timing import extract_timing
+
+logger = logging.getLogger(__name__)
 
 if TYPE_CHECKING:
     pass
@@ -57,12 +61,13 @@ class _LangGraphStreamMixin:
             invoke_payload["resume_payload_provided"] = resume_payload_provided
             invoke_payload["resume_interrupt_id"] = resume_interrupt_id
 
-        config = self._get_config(session_id)
+        config = await self._get_session_config(session_id)
         if is_checkpoint_resume:
             config = self._apply_checkpoint_resume_config(
                 config,
                 session_id=session_id,
                 checkpoint_ref=checkpoint_ref,
+                enforce_bound_thread=bool(self._invocation_identity_scope_ref()),
             )
 
         if is_checkpoint_resume:
@@ -86,6 +91,8 @@ class _LangGraphStreamMixin:
         inline_reasoning_parser = ReasoningMarkupParser()
         emitted_non_text_event = False
         final_output_text = ""
+        final_output_timing: dict[str, Any] = {}
+        final_result_fields: dict[str, Any] = {}
         final_output_usage: dict[str, Any] = {}
         final_output_last_usage: dict[str, Any] = {}
         model_run_usages: dict[str, dict[str, Any]] = {}
@@ -96,6 +103,7 @@ class _LangGraphStreamMixin:
         model_step_indexes: dict[str, int] = {}
         first_token_seen: set[str] = set()
         next_step_index = 0
+        internal_model_runs: set[str] = set()
 
         def model_run_key(
             event: Mapping[str, Any],
@@ -168,6 +176,8 @@ class _LangGraphStreamMixin:
             last_usage = self._extract_last_usage(result)
             if last_usage:
                 final_chunk.setdefault("metadata", {})["last_usage"] = last_usage
+            if timing := extract_timing(result):
+                final_chunk["timing"] = timing
             yield final_chunk
             return
 
@@ -195,6 +205,19 @@ class _LangGraphStreamMixin:
             async for event in self._agent.astream_events(stream_input, **stream_kwargs):
                 event_kind = event.get("event", "")
 
+                # This metadata is scoped to a model call, not the whole graph.
+                # Remember it because subsequent chunks may omit metadata.
+                event_run_id = str(event.get("run_id") or "")
+                event_metadata = event.get("metadata") or {}
+                internal_output = (
+                    isinstance(event_metadata, Mapping)
+                    and event_metadata.get("ksadk_output_visibility") == "internal"
+                )
+                if event_kind.startswith("on_chat_model_"):
+                    if internal_output and event_run_id:
+                        internal_model_runs.add(event_run_id)
+                    internal_output = internal_output or event_run_id in internal_model_runs
+
                 if event_kind == "on_chat_model_start":
                     model_call_id = str(event.get("run_id") or "")
                     if model_call_id:
@@ -219,15 +242,10 @@ class _LangGraphStreamMixin:
                     if not chunk:
                         continue
                     model_call_id = str(event.get("run_id") or "")
-                    if (
-                        model_call_id in model_started_at
-                        and model_call_id not in first_token_seen
-                    ):
+                    if model_call_id in model_started_at and model_call_id not in first_token_seen:
                         reasoning_content = getattr(chunk, "reasoning_content", None)
                         if not reasoning_content and hasattr(chunk, "additional_kwargs"):
-                            reasoning_content = chunk.additional_kwargs.get(
-                                "reasoning_content"
-                            )
+                            reasoning_content = chunk.additional_kwargs.get("reasoning_content")
                         if getattr(chunk, "content", None) or reasoning_content:
                             first_token_seen.add(model_call_id)
                             yield {
@@ -235,8 +253,7 @@ class _LangGraphStreamMixin:
                                 "step_id": f"step_{model_call_id}",
                                 "model_call_id": model_call_id,
                                 "ttft_ms": int(
-                                    (time.monotonic() - model_started_at[model_call_id])
-                                    * 1000
+                                    (time.monotonic() - model_started_at[model_call_id]) * 1000
                                 ),
                             }
                     chunk_usage = self._extract_usage(chunk)
@@ -253,6 +270,11 @@ class _LangGraphStreamMixin:
                             stream_usage_run_keys.add(run_key)
                             record_model_usage(event, latest_stream_usage)
 
+                    # Collect usage/lifecycle above even for internal calls, but
+                    # never feed their text into the shared reasoning parser.
+                    if internal_output:
+                        continue
+
                     # 推理内容
                     reasoning = getattr(chunk, "reasoning_content", None)
                     if not reasoning and hasattr(chunk, "additional_kwargs"):
@@ -392,26 +414,23 @@ class _LangGraphStreamMixin:
 
                 elif event_kind == "on_chain_end":
                     output = event.get("data", {}).get("output", {})
+                    if not event.get("parent_ids"):
+                        final_output_timing = extract_timing(output)
+                        final_result_fields = skill_eval_response_fields(output)
                     if isinstance(output, dict) and "__interrupt__" in output:
                         emitted_non_text_event = True
                         # __interrupt__ 是 LangGraph 原始 Interrupt 对象列表，
                         # 直接 yield 会导致下游拿不到 tool_name/description（非 Mapping）。
                         # 用 _get_interrupt_info 从 state 提取结构化 interrupt_info，
                         # 与 406-412 的异常路径和 419-436 的 pending_approval 兜底一致。
-                        _interrupt_info = {}
-                        try:
-                            _get_state = getattr(self._agent, "aget_state", None) or getattr(
-                                self._agent, "get_state", None
-                            )
-                            if _get_state is not None:
-                                _maybe_state = _get_state(config)
-                                if inspect.isawaitable(_maybe_state):
-                                    _maybe_state = await _maybe_state
-                                _interrupt_info = self._get_interrupt_info(_maybe_state)
-                        except Exception:
-                            _interrupt_info = {}
+                        state, _error = await self._read_graph_state(
+                            config, include_subgraphs=True
+                        )
+                        _interrupt_info = (
+                            self._get_interrupt_info(state) if state is not None else {}
+                        )
                         if not _interrupt_info:
-                            # 取不到 state 时 fallback 到原始 __interrupt__（兼容旧行为）。
+                            # state 里读不到结构化信息时，退回原始 __interrupt__。
                             _interrupt_info = output["__interrupt__"]
                         yield {
                             "type": "interrupt",
@@ -427,9 +446,15 @@ class _LangGraphStreamMixin:
 
         except Exception as e:
             if "Interrupt" in type(e).__name__:
+                state, error = await self._read_graph_state(config, include_subgraphs=True)
+                if state is None:
+                    # 图已经抛出 interrupt 但状态读不回来：显性失败，不返回空信息。
+                    raise RuntimeError(
+                        "graph interrupted but its checkpoint state could not be read"
+                    ) from error
                 yield {
                     "type": "interrupt",
-                    "interrupt_info": self._get_interrupt_info(self._agent.get_state(config)),
+                    "interrupt_info": self._get_interrupt_info(state),
                     "session_id": session_id,
                 }
                 return
@@ -437,20 +462,26 @@ class _LangGraphStreamMixin:
 
         # goal-18(ksadk-web 人机交互):图因审批门(HITL)在流式中静默暂停时,
         # 这里把审批详情(action_requests)作为 approval 事件冒出,供 UI 渲染审批卡。
-        # 此前流式路径只在 checkpoint 标 resumable,UI 拿不到"该批哪个工具/什么参数/允许哪些决定"。
-        # 注:get_state 在部分 agent 上是 async,统一按 awaitable 处理;取不到则跳过,不破坏事件流。
+        # 失败语义(0.8.5 契约):interrupt 依赖 checkpointer——
+        # - 配了 checkpointer 的图(含内存版),状态读不出来必须显性失败——绝不能把
+        #   "读不到"当成"没有待审批"继续走 completed(审批卡会无声消失)。
+        # - 没配 checkpointer 的图不可能有 interrupt,读不到属于正常情况。
         pending_approval = None
-        try:
-            _get_state = getattr(self._agent, "aget_state", None) or getattr(
-                self._agent, "get_state", None
+        state, error = await self._read_graph_state(config, include_subgraphs=True)
+        if state is None:
+            agent = getattr(self, "_agent", None)
+            has_checkpointer = (
+                getattr(agent, "checkpointer", None) is not None
+                or getattr(agent, "_checkpointer", None) is not None
             )
-            if _get_state is not None:
-                _maybe_state = _get_state(config)
-                if inspect.isawaitable(_maybe_state):
-                    _maybe_state = await _maybe_state
-                pending_approval = self._get_interrupt_info(_maybe_state)
-        except Exception:
-            pending_approval = None
+            if has_checkpointer:
+                raise RuntimeError(
+                    "stream ended without a terminal event and the checkpoint "
+                    "state could not be read; refusing to report the run as completed"
+                ) from error
+            logger.debug("graph has no checkpointer; skipping pending-approval probe")
+        else:
+            pending_approval = self._get_interrupt_info(state)
         if pending_approval:
             yield {
                 "type": "approval",
@@ -474,7 +505,7 @@ class _LangGraphStreamMixin:
 
         if not accumulated_text:
             if final_output_text:
-                final_chunk = {"output": final_output_text, "type": "final"}
+                final_chunk = {"output": final_output_text, "type": "final", **final_result_fields}
                 usage = accumulated_model_usage() or final_output_usage or latest_stream_usage
                 last_usage = (
                     latest_model_usage() or final_output_last_usage or latest_stream_usage or usage
@@ -483,11 +514,14 @@ class _LangGraphStreamMixin:
                     final_chunk["usage"] = usage
                 if last_usage:
                     final_chunk.setdefault("metadata", {})["last_usage"] = last_usage
+                if final_output_timing:
+                    final_chunk["timing"] = final_output_timing
                 yield final_chunk
             elif not emitted_non_text_event:
                 result = await self.invoke({**invoke_payload, "_ksadk_force_graph_invoke": True})
                 fallback_chunk: dict[str, Any] = {
                     "output": result.get("output", ""),
+                    **skill_eval_response_fields(result),
                     "type": "final",
                 }
                 usage = self._extract_usage(result)
@@ -496,13 +530,15 @@ class _LangGraphStreamMixin:
                 last_usage = self._extract_last_usage(result)
                 if last_usage:
                     fallback_chunk.setdefault("metadata", {})["last_usage"] = last_usage
+                if timing := extract_timing(result):
+                    fallback_chunk["timing"] = timing
                 yield fallback_chunk
                 checkpoint_metadata = result.get("metadata") if isinstance(result, dict) else None
                 if isinstance(checkpoint_metadata, dict) and checkpoint_metadata.get("agentengine"):
                     yield {"type": "checkpoint", "metadata": checkpoint_metadata}
                     return
         else:
-            final_chunk = {"output": accumulated_text, "type": "final"}
+            final_chunk = {"output": accumulated_text, "type": "final", **final_result_fields}
             state_usage = await self._latest_state_usage(config)
             usage = (
                 accumulated_model_usage()
@@ -520,6 +556,8 @@ class _LangGraphStreamMixin:
                     or usage
                 )
                 final_chunk.setdefault("metadata", {})["last_usage"] = last_usage
+            if final_output_timing:
+                final_chunk["timing"] = final_output_timing
             yield final_chunk
 
         metadata = await self._latest_checkpoint_metadata(config)
@@ -554,6 +592,7 @@ class _LangGraphStreamMixin:
             RunInterrupted,
             RunStarted,
             SourceRef,
+            UsageReported,
         )
         from ksadk.events.identity import stable_event_id, stable_item_id, stable_scope_id
         from ksadk.events.reducer import StreamReducer
@@ -581,12 +620,13 @@ class _LangGraphStreamMixin:
             context_schema=getattr(self._agent, "context_schema", None),
         )
 
-        config = self._get_config(session_id)
+        config = await self._get_session_config(session_id)
         if is_checkpoint_resume:
             config = self._apply_checkpoint_resume_config(
                 config,
                 session_id=session_id,
                 checkpoint_ref=checkpoint_ref,
+                enforce_bound_thread=bool(self._invocation_identity_scope_ref()),
             )
 
         # --- build state (same logic as stream()) ---
@@ -694,6 +734,8 @@ class _LangGraphStreamMixin:
         )
         adapter = LangGraphEventAdapter()
         reducer = StreamReducer()
+        accumulated_usage: dict[str, Any] = {}
+        final_result_fields: dict[str, Any] = {}
 
         # --- build stream kwargs (v3 rejects stream_mode/subgraphs) ---
         stream_kwargs: dict[str, Any] = {"version": "v3", "config": config}
@@ -706,6 +748,18 @@ class _LangGraphStreamMixin:
         try:
             run_stream = await self._agent.astream_events(stream_input, **stream_kwargs)
             async for event in adapter.stream_run(run_stream, adapter_context):
+                if isinstance(event, UsageReported):
+                    accumulated_usage = accumulate_usage(
+                        accumulated_usage,
+                        {
+                            "input_tokens": event.input_tokens,
+                            "output_tokens": event.output_tokens,
+                            "total_tokens": event.total_tokens,
+                            "cached_tokens": event.cached_tokens,
+                            "reasoning_tokens": event.reasoning_tokens,
+                        },
+                    )
+                    event = event.model_copy(update=accumulated_usage)
                 if isinstance(event, RunInterrupted):
                     was_interrupted = True
                     # Extract checkpoint from graph state and emit
@@ -713,7 +767,9 @@ class _LangGraphStreamMixin:
                     # consumers (agui agent) can resolve the resumable
                     # checkpoint_id before processing the terminal interrupt.
                     try:
-                        ckpt_state = self._agent.get_state(config)
+                        # 统一异步状态读取入口：managed 模式挂 AsyncPostgresSaver，
+                        # 在事件循环里同步 get_state 会直接报错。
+                        ckpt_state, ckpt_read_error = await self._read_graph_state(config)
                         ckpt_config = getattr(ckpt_state, "config", {}) or {}
                         ckpt_id = str(
                             (ckpt_config.get("configurable") or {}).get("checkpoint_id", "") or ""
@@ -766,7 +822,14 @@ class _LangGraphStreamMixin:
                                         "thread_id", session_id
                                     )
                                 ),
-                                "checkpoint_ns": "",
+                                # 保留状态自报的真实寻址（子图 ns 带任务路径），
+                                # 根 checkpoint 时为空串。恢复按原地址定位。
+                                "checkpoint_ns": str(
+                                    (ckpt_config.get("configurable") or {}).get(
+                                        "checkpoint_ns", ""
+                                    )
+                                    or ""
+                                ),
                                 "checkpoint_id": ckpt_id,
                                 **({"next_node": ckpt_next_node} if ckpt_next_node else {}),
                             }
@@ -806,8 +869,15 @@ class _LangGraphStreamMixin:
                             )
                             reducer.apply(cont_event)
                             yield cont_event
-                    except Exception:
-                        pass
+                    except Exception as ckpt_error:
+                        # 恢复指针丢失会让这次 interrupt 无法恢复——绝不能静默：
+                        # RunInterrupted 仍然发出（下游知道 run 已暂停），但必须
+                        # 留下显性告警指向根因。
+                        logger.warning(
+                            "LangGraph resume checkpoint 读取失败，ContinuationCreated "
+                            "未发出（run 可标记为 interrupted 但不可恢复）: %s",
+                            ckpt_error,
+                        )
                     reducer.apply(event)
                     last_timestamp = float(getattr(event, "timestamp", 0.0) or last_timestamp)
                     yield event
@@ -815,6 +885,9 @@ class _LangGraphStreamMixin:
                 reducer.apply(event)
                 last_timestamp = float(getattr(event, "timestamp", 0.0) or last_timestamp)
                 yield event
+            # v3 exposes the final graph state after the event stream completes.
+            final_state = await run_stream.output()
+            final_result_fields = skill_eval_response_fields(final_state)
         except Exception as exc:
             error_source = SourceRef(
                 framework="langgraph",
@@ -864,7 +937,10 @@ class _LangGraphStreamMixin:
         terminal_source = SourceRef(
             framework="langgraph",
             native_run_id=run_id,
-            metadata=dict(source_metadata),
+            metadata={
+                **source_metadata,
+                **({"metrics": final_result_fields} if final_result_fields else {}),
+            },
         )
         yield RunCompleted(
             schema_version=2,