langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/task_runtime/tasks/trace_cleanup/scheduler.py

@@ -0,0 +1,169 @@
+"""
+trace_cleanup/scheduler.py — TraceCleanupScheduler
+
+职责：
+    定时触发 trace retention 清理（通过 registry 构造 TraceCleanupTask 并 await run）。
+
+链路位置：
+    由上层在 **已运行的 asyncio 事件循环** 内 ``asyncio.create_task(scheduler.start())`` 启动；
+    退出前须 ``scheduler.stop()`` 并 cancel 该 Task（OB-D10 §3.3）。
+
+当前裁剪范围：
+    不修改 BackgroundAiTaskScheduler 基类；可选 **非阻塞文件锁** + **marker 冷却**（多进程节流）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from pathlib import Path
+from typing import Any, IO
+
+import portalocker
+from portalocker.exceptions import BaseLockException
+
+from langchain_agentx.observability.evaluation.store import EvaluationStore
+from langchain_agentx.observability.trace.sqlite_store import SqliteTraceStore
+
+from ..ai_analysis.registry import BackgroundAiTaskRegistry
+from ..ai_analysis.scheduler import BackgroundAiTaskScheduler
+
+logger = logging.getLogger(__name__)
+
+_NO_LOCK = object()
+
+
+class TraceCleanupScheduler(BackgroundAiTaskScheduler):
+    """覆盖 ``_poll_once``：按配置触发 ``trace.cleanup`` 任务。"""
+
+    def __init__(
+        self,
+        trace_store: SqliteTraceStore,
+        evaluation_store: EvaluationStore,
+        registry: BackgroundAiTaskRegistry,
+        *,
+        poll_interval: float = 86400.0,
+        cleanup_config: dict[str, Any] | None = None,
+        enable_file_lock: bool = True,
+        lock_path: Path | str | None = None,
+        marker_path: Path | str | None = None,
+        marker_cooldown_seconds: float | None = None,
+        task_factory_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Args:
+            trace_store / evaluation_store: 注入 Store（测试须可传 tmp_path）。
+            registry: 须已注册 ``trace.cleanup``（通常随 ai_analysis 包 import 侧载）。
+            poll_interval: ``start()`` 循环中 ``asyncio.sleep`` 间隔（秒）。
+            cleanup_config: 传入 ``TraceCleanupTask.run`` 的 kwargs（如 failed_days / normal_days）。
+            enable_file_lock: 为 True 时用 ``portalocker`` 非阻塞独占锁，避免多进程同时跑 DELETE。
+            lock_path / marker_path: 默认与 ``trace_store.db_path`` 同目录派生文件名。
+            marker_cooldown_seconds: 非 None 时，marker 存在且距上次成功清理不足该秒数则跳过本轮（多进程节流）；**None** 表示不按 marker 跳过（§4.1 Q5 幂等每轮）。
+            task_factory_kwargs: 除 ``trace_store`` / ``evaluation_store`` 外传给 ``TraceCleanupTask`` 的 ``graph_factory`` / ``hook_engine`` 等。
+        """
+        db = Path(trace_store.db_path)
+        self._trace_store = trace_store
+        self._eval_store = evaluation_store
+        merged: dict[str, Any] = {
+            "failed_days": 180,
+            "normal_days": 30,
+            "cleanup_diagnostic_reports": False,
+        }
+        if cleanup_config:
+            merged.update(cleanup_config)
+        self._cleanup_config = merged
+        self._enable_file_lock = bool(enable_file_lock)
+        self._lock_path = Path(lock_path) if lock_path is not None else db.with_suffix(".cleanup.lock")
+        self._marker_path = Path(marker_path) if marker_path is not None else db.with_suffix(".cleanup.marker")
+        self._marker_cooldown_seconds = marker_cooldown_seconds
+
+        super().__init__(
+            evaluation_store=evaluation_store,
+            registry=registry,
+            task_factory_kwargs={
+                "trace_store": trace_store,
+                "evaluation_store": evaluation_store,
+                **(task_factory_kwargs or {}),
+            },
+            poll_interval=poll_interval,
+        )
+
+    def _should_skip_cleanup(self) -> bool:
+        """marker 冷却：在 ``marker_cooldown_seconds`` 非空且文件在冷却期内返回 True。"""
+        if self._marker_cooldown_seconds is None:
+            return False
+        path = self._marker_path
+        if not path.is_file():
+            return False
+        try:
+            last = float(path.read_text(encoding="utf-8").strip())
+        except (OSError, ValueError):
+            return False
+        return (time.time() - last) < float(self._marker_cooldown_seconds)
+
+    def _acquire_lock_nonblocking(self) -> Any:
+        """非阻塞获取清理锁；失败返回 ``None``。关闭文件锁时返回哨兵 ``_NO_LOCK``。"""
+        if not self._enable_file_lock:
+            return _NO_LOCK
+        self._lock_path.parent.mkdir(parents=True, exist_ok=True)
+        handle = open(self._lock_path, "a+b")  # noqa: SIM115 — 生命周期由 _release_lock 关闭
+        try:
+            portalocker.lock(handle, portalocker.LOCK_EX | portalocker.LOCK_NB)
+        except (OSError, BaseLockException):
+            handle.close()
+            return None
+        return handle
+
+    def _release_lock(self, lock_handle: Any) -> None:
+        if lock_handle is None or lock_handle is _NO_LOCK:
+            return
+        handle: IO[bytes] = lock_handle
+        try:
+            portalocker.unlock(handle)
+        except Exception:
+            logger.debug("portalocker.unlock 忽略异常", exc_info=True)
+        try:
+            handle.close()
+        except OSError:
+            pass
+
+    def _write_marker_now(self) -> None:
+        self._marker_path.parent.mkdir(parents=True, exist_ok=True)
+        self._marker_path.write_text(str(time.time()), encoding="utf-8")
+
+    async def _poll_once(self) -> None:
+        if self._should_skip_cleanup():
+            logger.debug("TraceCleanupScheduler 跳过本轮（marker 冷却中）")
+            return
+
+        lock_handle = self._acquire_lock_nonblocking()
+        if lock_handle is None:
+            logger.debug("TraceCleanupScheduler 跳过本轮（未获取到清理锁）")
+            return
+
+        try:
+            task_factory = self._registry.get("trace.cleanup")
+            if task_factory is None:
+                logger.warning("registry 未注册 trace.cleanup，跳过清理")
+                return
+            try:
+                # ``task_factory_kwargs`` 已在 ``__init__`` 中含 trace_store / evaluation_store
+                task = task_factory(**self._task_factory_kwargs)
+            except Exception:
+                logger.exception("TraceCleanupScheduler 构造 TraceCleanupTask 失败")
+                return
+
+            try:
+                await task.run(**self._cleanup_config)
+            except Exception:
+                logger.exception("TraceCleanupScheduler 执行 trace.cleanup 失败")
+                return
+
+            if self._marker_cooldown_seconds is not None:
+                self._write_marker_now()
+        finally:
+            self._release_lock(lock_handle)
+
+
+__all__ = ["TraceCleanupScheduler"]

langchain_agentx/tool_runtime/__init__.py

@@ -0,0 +1,90 @@
+"""
+tool_runtime/ — 工具运行时框架核心包
+
+对外暴露框架的稳定公共接口，外部代码只需从此处导入，
+不需要直接依赖子模块路径。
+"""
+
+from .adapter import LangChainAdapter
+from .base import RuntimeTool
+from .errors import (
+    ToolInputSchemaError,
+    ToolNotFoundError,
+    ToolRegistrationError,
+    ToolRuntimeError,
+    blocked_envelope,
+    exception_to_envelope,
+    validation_error_envelope,
+)
+from .models import (
+    AuthorizationDecision,
+    ToolArtifact,
+    ToolErrorInfo,
+    ToolExecutionContext,
+    ToolHint,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+from .identical_call_cache import IdenticalCallMemo
+from .loader import ToolRuntimeLoader
+from .pipeline import PermissionAskInterrupt, ToolExecutorPipeline, ToolOutputManager
+from .policy import DefaultPolicyEngine, PolicyEngine, ToolPolicyConfig
+from .registry import RuntimeToolRegistry
+from .resolvers import (
+    AgentSessionPermissionResolver,
+    BackgroundPermissionResolver,
+    ConversationPermissionResolver,
+    PermissionRequest,
+    PermissionResolver,
+    WorkflowPermissionResolver,
+)
+from .session_store import AgentSessionStore, FileReadRecord, FileWriteRecord
+from .state_bridge import ToolStateBridge
+
+__all__ = [
+    # models
+    "ToolExecutionContext",
+    "ToolResultEnvelope",
+    "ValidationResult",
+    "AuthorizationDecision",
+    "ToolErrorInfo",
+    "ToolHint",
+    "ToolArtifact",
+    # base
+    "RuntimeTool",
+    # errors
+    "ToolRuntimeError",
+    "ToolRegistrationError",
+    "ToolNotFoundError",
+    "ToolInputSchemaError",
+    "exception_to_envelope",
+    "blocked_envelope",
+    "validation_error_envelope",
+    # policy
+    "ToolPolicyConfig",
+    "PolicyEngine",
+    "DefaultPolicyEngine",
+    # state
+    "ToolStateBridge",
+    # session
+    "AgentSessionStore",
+    "FileReadRecord",
+    "FileWriteRecord",
+    # pipeline
+    "ToolOutputManager",
+    "ToolExecutorPipeline",
+    "PermissionAskInterrupt",
+    "IdenticalCallMemo",
+    "PermissionResolver",
+    "PermissionRequest",
+    "AgentSessionPermissionResolver",
+    "ConversationPermissionResolver",
+    "BackgroundPermissionResolver",
+    "WorkflowPermissionResolver",
+    # adapter
+    "LangChainAdapter",
+    # registry
+    "RuntimeToolRegistry",
+    # loader
+    "ToolRuntimeLoader",
+]

langchain_agentx/tool_runtime/adapter.py

@@ -0,0 +1,365 @@
+"""
+runtime/adapter.py — LangChain 集成适配器
+
+职责：
+    框架内部 RuntimeTool 与 LangChain 生态之间的唯一边界层，负责：
+    1. 从 RunnableConfig 构造 ToolExecutionContext（隔离 LangGraph 底层依赖）
+       - 同时将 RuntimeTool 的 is_read_only / is_destructive 注入 ctx.tool_flags
+       - 允许通过 configurable 透传 permission_mode、sandbox 相关运行时标志
+       - PolicyEngine 从 ctx.tool_flags 读取，不污染 input_data
+    2. 将 RuntimeTool 导出为 LangChain StructuredTool（保持模型可见 schema 稳定）
+    3. 将内部 ToolResultEnvelope 映射为 ToolMessage.content 字符串
+
+    LangChain 工具执行路径：
+        ToolNode → StructuredTool.func(**kwargs) → str → ToolMessage.content
+
+    同参重复调用短路在 ``ToolExecutorPipeline``（``RuntimeTool.dedupe_identical_calls`` +
+    ``IdenticalCallMemo``）完成；本适配器仍只负责 ``pipeline.run/arun`` → 字符串，不单独做去重。
+
+与 CC 对比：
+    CC 中工具直接实现 TypeScript 函数，由 ToolNode 调用，没有显式 adapter 层。
+    本框架引入 LangChainAdapter 作为边界，将 LangGraph 底层对象（RunnableConfig、
+    state）的消费集中在此处，工具内部只依赖 ToolExecutionContext。
+
+    envelope_to_tool_output 的输出格式对应 CC 工具返回的 ToolResult.content，
+    模型只收到紧凑文本，meta 不进入模型上下文。
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable, Literal, MutableMapping
+
+from langgraph.prebuilt.tool_node import ToolRuntime
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import StructuredTool
+
+from .models import ToolExecutionContext, ToolResultEnvelope
+from langchain_agentx.observability.replay.store import (
+    OBS_SCHEMA_VERSION,
+    get_global_trace_store,
+    sample_events,
+    sanitize_value,
+)
+from .pipeline import ToolExecutorPipeline
+
+
+class LangChainAdapter:
+    """
+    LangChain 集成适配器。
+
+    职责边界：
+        负责：上下文构造（含 tool_flags 注入）、StructuredTool 导出、envelope → str 映射
+        不负责：业务执行、policy 规则决策、graph 路由
+    """
+
+    def build_tool_execution_context(
+        self,
+        *,
+        tool_name: str,
+        raw_input: dict[str, Any],
+        state: MutableMapping[str, Any],
+        config: RunnableConfig | None = None,
+        tool_call_id: str | None = None,
+        actor: Literal["agent", "human", "system"] = "agent",
+        tool_flags: dict[str, Any] | None = None,
+    ) -> ToolExecutionContext:
+        """
+        从 RunnableConfig.configurable 构造 ToolExecutionContext。
+
+        LangGraph 在调用工具时通过 RunnableConfig 传递 thread_id、run_id、
+        tool_call_id 等元数据。本方法将这些字段提取并归一化，
+        隔离工具内部对 LangGraph 底层对象的直接依赖。
+
+        tool_flags：由 build_structured_tool 从 RuntimeTool 类属性提取后传入，
+            {"is_read_only": bool, "is_destructive": bool}
+            PolicyEngine.authorize() 从 ctx.tool_flags 读取工具读写属性，
+            不污染 input_data。
+
+        config 参数接受 RunnableConfig 或 None。
+        """
+        configurable: dict = {}
+        if config is not None:
+            configurable = config.get("configurable", {}) or {}
+
+        loop_config = configurable.get("loop_config")
+
+        model = getattr(loop_config, "model", None)
+        available_tools = list(getattr(loop_config, "available_tools", None) or [])
+        session_id = getattr(loop_config, "session_id", None)
+        conversation_session_id = getattr(loop_config, "conversation_session_id", None) or session_id
+        workspace_root = getattr(loop_config, "workspace_root", None)
+        agent_home = getattr(loop_config, "agent_home", ".langchain_agentx")
+        # cwd 优先级：loop_config.cwd > loop_config.workspace_root > get_cwd()
+        # CC 对照：getCwd() = AsyncLocalStorage.getStore() ?? getCwdState()
+        from langchain_agentx.utils.cwd import get_cwd
+        cwd = getattr(loop_config, "cwd", None) or workspace_root or get_cwd()
+        trace_enabled = bool(getattr(loop_config, "trace_enabled", True))
+
+        _depth_from_loop = getattr(loop_config, "agent_depth", None)
+        if _depth_from_loop is not None:
+            agent_depth = int(_depth_from_loop)
+        elif isinstance(state, dict):
+            agent_depth = int(state.get("agent_depth") or 0)
+        else:
+            agent_depth = 0
+
+        _agent_id_from_state = state.get("agent_id") if isinstance(state, dict) else None
+        agent_id = getattr(loop_config, "agent_id", None) or _agent_id_from_state
+
+        resolved_tool_call_id = tool_call_id
+        if not isinstance(resolved_tool_call_id, str) or not resolved_tool_call_id:
+            resolved_tool_call_id = configurable.get("tool_call_id")
+        if not isinstance(resolved_tool_call_id, str) or not resolved_tool_call_id:
+            raw_tool_call_id = raw_input.get("tool_call_id") or raw_input.get("id")
+            if isinstance(raw_tool_call_id, str) and raw_tool_call_id:
+                resolved_tool_call_id = raw_tool_call_id
+            else:
+                resolved_tool_call_id = configurable.get("run_id")
+
+        cancel_ev = configurable.get("cancel_event")
+        if not isinstance(cancel_ev, threading.Event):
+            cancel_ev = None
+
+        return ToolExecutionContext(
+            tool_name=tool_name,
+            # 回退顺序：显式 tool_call_id -> config.tool_call_id -> input.tool_call_id -> input.id -> run_id
+            # 用于尽量保留上游真实 tool_call 语义，避免子 run 关联键缺失。
+            tool_call_id=resolved_tool_call_id,
+            input_args=raw_input,
+            state=state,
+            model=model,
+            available_tools=available_tools,
+            agent_id=agent_id,
+            agent_depth=agent_depth,
+            now_ts=time.time(),
+            thread_id=configurable.get("thread_id"),
+            run_id=configurable.get("run_id") or session_id,
+            session_id=session_id,
+            conversation_session_id=conversation_session_id,
+            actor=actor,
+            session_store=configurable.get("session_store"),
+            tool_loader=configurable.get("tool_loader"),
+            tool_registry=configurable.get("tool_registry"),
+            tool_flags=tool_flags or {},
+            workspace_root=workspace_root,
+            agent_home=agent_home,
+            cwd=cwd,
+            trace_enabled=trace_enabled,
+            cancel_event=cancel_ev,
+        )
+
+    def build_structured_tool(
+        self,
+        *,
+        tool: Any,  # RuntimeTool，避免循环导入用 Any
+        pipeline: ToolExecutorPipeline,
+        state_getter: Callable[[], MutableMapping[str, Any]] | None = None,
+    ) -> StructuredTool:
+        """
+        将 RuntimeTool 导出为 LangChain StructuredTool。
+
+        args_schema 直接使用 tool.input_model，保证模型可见 schema 稳定。
+        内部 func / coroutine 调用 pipeline.run / arun，
+        通过 LangChain 的 config 参数获取 RunnableConfig。
+
+        从 tool 类属性提取 tool_flags，在每次调用时注入 ctx，
+        使 PolicyEngine 可以获取工具的读写属性。
+
+        state_getter：历史参数，已忽略；LangGraph state 不再注入 ctx.state，
+        控制面请使用 ``config["configurable"]["loop_config"]``（见 ``build_tool_execution_context``）。
+        """
+        adapter = self
+        # 在 StructuredTool 构造时从类属性提取，避免每次调用重复读取
+        _tool_flags: dict[str, Any] = {
+            "is_read_only": getattr(tool, "is_read_only", False),
+            "is_destructive": getattr(tool, "is_destructive", False),
+        }
+
+        def _func(
+            config: RunnableConfig,
+            tool_runtime: ToolRuntime | None = None,
+            **kwargs: Any,
+        ) -> str:
+            state: MutableMapping[str, Any] = {}
+            effective_tool_flags = dict(_tool_flags)
+            configurable = config.get("configurable", {}) or {}
+            if "permission_mode" in configurable:
+                effective_tool_flags["permission_mode"] = configurable["permission_mode"]
+            if "allow_dangerously_disable_sandbox" in configurable:
+                effective_tool_flags["allow_dangerously_disable_sandbox"] = configurable["allow_dangerously_disable_sandbox"]
+            if "sandbox_excluded_commands" in configurable:
+                effective_tool_flags["sandbox_excluded_commands"] = configurable["sandbox_excluded_commands"]
+            ctx = adapter.build_tool_execution_context(
+                tool_name=tool.name,
+                raw_input=kwargs,
+                state=state,
+                config=config,
+                tool_call_id=getattr(tool_runtime, "tool_call_id", None),
+                tool_flags=effective_tool_flags,
+            )
+            envelope = pipeline.run(tool=tool, raw_input=kwargs, ctx=ctx)
+            return adapter.envelope_to_tool_output(envelope)
+
+        async def _afunc(
+            config: RunnableConfig,
+            tool_runtime: ToolRuntime | None = None,
+            **kwargs: Any,
+        ) -> str:
+            state: MutableMapping[str, Any] = {}
+            effective_tool_flags = dict(_tool_flags)
+            configurable = config.get("configurable", {}) or {}
+            if "permission_mode" in configurable:
+                effective_tool_flags["permission_mode"] = configurable["permission_mode"]
+            if "allow_dangerously_disable_sandbox" in configurable:
+                effective_tool_flags["allow_dangerously_disable_sandbox"] = configurable["allow_dangerously_disable_sandbox"]
+            if "sandbox_excluded_commands" in configurable:
+                effective_tool_flags["sandbox_excluded_commands"] = configurable["sandbox_excluded_commands"]
+            ctx = adapter.build_tool_execution_context(
+                tool_name=tool.name,
+                raw_input=kwargs,
+                state=state,
+                config=config,
+                tool_call_id=getattr(tool_runtime, "tool_call_id", None),
+                tool_flags=effective_tool_flags,
+            )
+            envelope = await pipeline.arun(tool=tool, raw_input=kwargs, ctx=ctx)
+            return adapter.envelope_to_tool_output(envelope)
+
+        return StructuredTool(
+            name=tool.name,
+            description=tool.description,
+            args_schema=tool.input_model,
+            func=_func,
+            coroutine=_afunc,
+        )
+
+    def envelope_to_tool_output(self, env: ToolResultEnvelope) -> str:
+        """
+        将内部 ToolResultEnvelope 映射为 LangChain ToolMessage.content 字符串。
+
+        输出格式：
+            ok:      summary + payload 紧凑文本 + artifacts/hints（若有）
+            blocked: "Permission denied: <message>"
+            error:   summary + payload（若有）
+            truncated 时：summary 已包含 overflow_file 提示（由 ToolOutputManager 注入）
+
+        meta 默认不进入输出（面向系统，不面向模型）。
+        """
+        self._capture_observability(env)
+
+        if env.status == "blocked":
+            return env.summary  # "Permission denied: ..."
+
+        parts: list[str] = [env.summary]
+        payload_text = self._render_payload(env.payload)
+        if payload_text:
+            parts.append(payload_text)
+
+        if env.blocks:
+            parts.extend(self._render_blocks(env))
+
+        if env.artifacts:
+            parts.extend(self._render_artifacts(env))
+
+        if env.hints:
+            hint_lines = [f"[Hint: {h.message}]" for h in env.hints]
+            parts.extend(hint_lines)
+
+        meta_lines = self._render_selected_meta(env)
+        if meta_lines:
+            parts.extend(meta_lines)
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def _render_payload(payload: dict[str, Any] | str | None) -> str | None:
+        if payload is None:
+            return None
+        if isinstance(payload, str):
+            return payload
+
+        import json
+
+        try:
+            return json.dumps(payload, ensure_ascii=False)
+        except Exception:
+            return str(payload)
+
+    @staticmethod
+    def _render_artifacts(env: ToolResultEnvelope) -> list[str]:
+        lines: list[str] = []
+        for artifact in env.artifacts or ():
+            label = artifact.description or artifact.media_type
+            lines.append(f"[Artifact: {label} ({artifact.media_type})]")
+        return lines
+
+    @staticmethod
+    def _render_blocks(env: ToolResultEnvelope) -> list[str]:
+        lines: list[str] = []
+        for block in env.blocks or ():
+            if block.type == "text" and block.text:
+                lines.append(block.text)
+            elif block.type == "status" and block.text:
+                lines.append(f"[Status] {block.text}")
+            elif block.type == "reference":
+                ref = block.uri or ""
+                label = block.text or "reference"
+                lines.append(f"[Reference: {label}] {ref}")
+            elif block.type == "image":
+                label = block.media_type or "image/*"
+                lines.append(f"[Image block: {label}]")
+        return lines
+
+    @staticmethod
+    def _render_selected_meta(env: ToolResultEnvelope) -> list[str]:
+        if not env.meta:
+            return []
+        keys = (
+            "task_id",
+            "task_mode",
+            "task_status",
+            "task_exit_code",
+            "auto_backgrounded",
+        )
+        lines: list[str] = []
+        for key in keys:
+            if key in env.meta and env.meta[key] is not None:
+                lines.append(f"[Meta: {key}={env.meta[key]}]")
+        obs = env.meta.get("observability")
+        if isinstance(obs, dict):
+            events = obs.get("events", [])
+            lines.append(f"[Meta: observability_schema={obs.get('schema_version', OBS_SCHEMA_VERSION)}]")
+            lines.append(f"[Meta: observability_events={len(events) if isinstance(events, list) else 0}]")
+        return lines
+
+    @staticmethod
+    def _capture_observability(env: ToolResultEnvelope) -> None:
+        if not env.meta:
+            return
+        obs = env.meta.get("observability")
+        cleaned: dict[str, Any] | None = None
+        if isinstance(obs, dict):
+            cleaned = sanitize_value(obs)
+            events = cleaned.get("events")
+            if isinstance(events, list):
+                cleaned["events"] = sample_events(events, limit=200)
+        trace_ctx = (
+            cleaned.get("trace_context")
+            if isinstance(cleaned, dict) and isinstance(cleaned.get("trace_context"), dict)
+            else {}
+        )
+        tool_call_id = trace_ctx.get("tool_call_id") or env.meta.get("tool_call_id")
+        decision_trace = env.meta.get("decision_trace") if isinstance(env.meta.get("decision_trace"), list) else []
+        if cleaned is None and not decision_trace:
+            return
+        record = {
+            "schema_version": (cleaned or {}).get("schema_version", OBS_SCHEMA_VERSION),
+            "tool_name": env.tool_name,
+            "status": env.status,
+            "summary": env.summary,
+            "observability": cleaned or {},
+            "decision_trace": sanitize_value(decision_trace),
+        }
+        get_global_trace_store().put(tool_call_id, record)