davinci-resolve-mcp 2.205.2 → 2.206.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.206.0 — agent execution traces
+
+Adapted from the design contributed in PR #183.
+
+### Added
+
+- **Execution traces answer "why did the editor do this?"** v2.205.0's
+  `_operation` envelope describes one call; a real editorial pass is a loop of
+  them. When an agent removes 17 pauses, seventeen individual returns each show
+  one deletion. A trace correlates them into a single execution carrying the
+  request that started it, the tools invoked and how often, cumulative
+  `duration_ms`, the summed semantic deltas (`items_deleted: 17`), and a
+  verification rollup that keeps a contradiction distinct.
+- **Six actions on `resolve_control`** — `begin_execution`, `end_execution`,
+  `get_execution_trace`, `get_execution`, `list_recent_executions`,
+  `clear_executions` — with the compound tool count unchanged at 36. Any call
+  passing an explicit `execution_id` is correlated automatically; queries are
+  exempt from step recording, so observing a trace cannot alter it.
+- **`duration_ms` on the `_operation` envelope**, measured with
+  `time.perf_counter()` around the call.
+
+### Notes on the adaptation
+
+- **The trace log is anchored to the repo, not the working directory.** It was
+  derived from `os.getcwd()` and returned None when `./logs` did not exist —
+  and the generated client configs set no `cwd`, so on a standard install
+  persistence silently did nothing, with no signal either way. It now sits
+  beside `server.log`, the way `media-analysis-preferences.json` and
+  `server-preferences.json` already do, and the directory is created on first
+  write rather than being a precondition.
+- **`list_recent_executions` reports where the log is and whether it is
+  writable.** The append is best-effort and must never fail a real edit, which
+  means a broken destination is otherwise invisible — "the file is empty" and
+  "nothing is being written" looked identical from the caller's side.
+- **The log rotates at 8 MB, keeping one generation.** The in-memory ring was
+  capped at 100 executions; the file had no bound at all, at one append per
+  tool call, on machines that run for months.
+- **The persistence is described accurately.** It is a synchronous buffered
+  append on the calling thread — measured at ~0.07ms per call, immaterial
+  beside any Resolve round-trip, but "non-blocking" was the wrong word for it.
+  It runs outside the lock, so a slow filesystem cannot serialize concurrent
+  tool calls.
+- **What is recorded is now documented**: tool, action, timing, status,
+  semantic deltas, verification — no parameters, no file paths, no clip or
+  project names. The one free-text field is the `request` passed to
+  `begin_execution`, which on client work deserves the care of a commit
+  message.
+- Verified through the real stdio JSON-RPC tool layer: 36 tools register, a
+  begin/call/end cycle produces one correlated trace, and the reported
+  persistence path is the one actually written.
+
 ## What's New in v2.205.2 — #184: background analysis actually starts
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.205.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.206.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(353%20full)-blue.svg)](#server-modes)
@@ -266,6 +266,25 @@ confirm gate's `status: "confirmation_required"`. `setup(action="set_defaults",
 params={"result_envelope": "pure" | "legacy"})` changes the shape, per call via
 `params={"envelope": ...}`, per process via `RESOLVE_MCP_RESULT_ENVELOPE`.
 
+### Agent execution traces ("Why did the editor do this?")
+
+Multi-step AI operations correlate across tool calls into unified execution
+traces. Each trace aggregates tool durations (`duration_ms`), call counts, cumulative
+semantic deltas (`items_deleted`, `items_added`), and readback verifications.
+Agents and editors can inspect workflows via `resolve_control`:
+`get_execution_trace(execution_id?)`, `list_recent_executions()`, or open a
+scoped execution with `begin_execution(request="...")` / `end_execution()`.
+
+Traces live in a 100-entry in-memory ring and are appended to
+`logs/execution-traces.jsonl` beside `server.log` — `RESOLVE_MCP_TRACE_FILE`
+moves it. `list_recent_executions` reports that path and whether it is
+writable, so "the log is empty" and "nothing is being written" are
+distinguishable without reading the source. What is recorded is tool name,
+action, timing, status, semantic deltas and verification — no parameters and no
+file paths. The one free-text field is the `request` you pass to
+`begin_execution`, so treat it the way you would a commit message on a client
+project.
+
 ## Optional Extras
 
 The core install is deliberately small: Python, ffmpeg, and the Resolve scripting

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.205.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.206.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.205.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.206.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -166,6 +166,12 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 信封是带命名空间的，而不是平铺到顶层，因为 `status`、`operation`、`warnings`、`result` 和 `changes` 在这里本来就都是业务 key；平铺会改写后台任务的 `status: "done"` 和确认关卡的 `status: "confirmation_required"`。用 `setup(action="set_defaults", params={"result_envelope": "pure" | "legacy"})` 改变形态，单次调用用 `params={"envelope": ...}`，进程级用 `RESOLVE_MCP_RESULT_ENVELOPE`。
 
+### Agent 执行轨迹（"编辑器为什么这么做？"）
+
+多步 AI 操作会跨工具调用关联成统一的执行轨迹，聚合各工具耗时（`duration_ms`）、调用次数、累计语义增量（`items_deleted`、`items_added`）以及回读校验结果。通过 `resolve_control` 查看：`get_execution_trace(execution_id?)`、`list_recent_executions()`，或用 `begin_execution(request="...")` / `end_execution()` 圈定一段执行。
+
+轨迹保存在一个容量 100 条的内存环形缓冲里，并追加写入 `logs/execution-traces.jsonl`（就在 `server.log` 旁边，可用 `RESOLVE_MCP_TRACE_FILE` 改位置），文件到 8 MB 会轮转并保留一份上一代。`list_recent_executions` 会返回该路径以及是否可写，这样"日志是空的"和"根本没在写"就能区分开。记录的内容是工具名、动作、耗时、状态、语义增量和校验结果——不记录参数，也不记录文件路径。唯一的自由文本是你传给 `begin_execution` 的 `request`，在客户项目上请把它当成提交信息来写。
+
 ## 可选增强
 
 核心安装刻意保持精简：Python、ffmpeg 和 Resolve 脚本 API。有些功能需要更多依赖，且**每一项都会诚实拒绝并给出自己的安装命令，而不是退化成瞎猜**——编造的节拍或虚构的电平会产出自信但错误的结果，比没有这个功能更糟。

package/docs/SKILL.md

@@ -219,6 +219,80 @@ nested under `result`; `legacy` adds nothing.
 
 ---
 
+## Agent Observability: Execution Traces ("Why did the editor do this?")
+
+Multi-step AI operations (such as detecting pauses, deleting multiple timeline
+items, and verifying the result) correlate across calls into unified execution
+traces. Each trace captures the user request or prompt, tool execution timing,
+cumulative semantic deltas, and verification outcomes.
+
+Example trace shape returned by `resolve_control(action="get_execution_trace")`:
+
+```json
+{
+  "execution_id": "exec_8f91c7a210bc",
+  "request": "Remove all pauses longer than 800ms",
+  "status": "success",
+  "started_at": "2026-09-04T07:30:00Z",
+  "ended_at": "2026-09-04T07:30:02Z",
+  "duration_ms": 2845,
+  "tools": [
+    {
+      "tool": "media_analysis.analyze_timeline",
+      "count": 1,
+      "duration_ms": 821
+    },
+    {
+      "tool": "timeline.delete_item",
+      "count": 17,
+      "duration_ms": 1420
+    }
+  ],
+  "changes": {
+    "items_deleted": 17
+  },
+  "verification": {
+    "status": "passed",
+    "passed": true,
+    "checks": [{"check": "readback_verification", "passed": true}]
+  },
+  "warnings": []
+}
+```
+
+### Trace Actions on `resolve_control`
+
+- **`begin_execution(request?, execution_id?, initiator?)`**: Opens a scoped
+  multi-step execution. Subsequent tool calls in the session automatically thread
+  under this `execution_id` until ended.
+- **`end_execution(execution_id?, verification?, status?, notes?)`**: Closes the
+  active execution, finalizes timestamps and aggregated metrics.
+- **`get_execution_trace(execution_id?)`** / **`get_execution(execution_id)`**:
+  Fetches the trace for a specific ID, or the most recent execution if omitted.
+- **`list_recent_executions(limit?)`**: Returns the recent execution traces
+  (newest first, default limit 20).
+- **`clear_executions(dry_run?)`**: Clears the in-memory execution trace buffer.
+
+Explicit correlation is also supported per-call: pass `params={"execution_id": ...}`
+or `params={"trace_id": ...}` in any tool call to associate it with a specific trace.
+
+Two things to know when a trace is not where you expect it. The buffer holds the
+**100 most recent** executions and is in memory only — a server restart empties
+it, and the on-disk `logs/execution-traces.jsonl` is the durable record.
+`list_recent_executions` returns a `persistence` block naming that file and
+whether it is writable; check it before concluding that nothing was traced,
+since the append is best-effort and will never fail a real edit to report a
+logging problem.
+
+Recorded per step: tool, action, `duration_ms`, status, semantic deltas and
+verification. **Not** recorded: parameters, file paths, clip or project names.
+The only free text is the `request` string passed to `begin_execution`.
+
+The file rotates at 8 MB, keeping one previous generation as
+`execution-traces.jsonl.1`. Both are gitignored along with the rest of `logs/`.
+
+---
+
 ## Two Server Modes
 
 | Mode | Entry point | Tool count | Use when |

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.205.2"
+VERSION = "2.206.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.205.2",
+  "version": "2.206.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.205.2"
+VERSION = "2.206.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.205.2"
+VERSION = "2.206.0"
 
 import base64
 import os
@@ -66,6 +66,15 @@ from src.utils.operation_result import (
     get_envelope_mode as _get_envelope_mode,
     set_envelope_mode as _set_envelope_mode,
 )
+from src.utils import execution_trace as _execution_trace
+from src.utils.execution_trace import (
+    get_execution_trace,
+    get_execution,
+    list_recent_executions,
+    begin_execution,
+    end_execution,
+    clear_executions,
+)
 from src.utils.render_ids import (
     render_codec_id_from_codecs as _render_codec_id_from_codecs,
     render_format_id_from_formats as _render_format_id_from_formats,
@@ -1487,6 +1496,50 @@ def _guarded_params(args, kwargs) -> Optional[Dict[str, Any]]:
     return None
 
 
+_TRACE_OBSERVER_ACTIONS = {
+    "get_execution_trace", "get_execution", "list_recent_executions",
+    "clear_executions", "begin_execution", "end_execution",
+}
+
+
+def _record_execution_step(
+    tool_name: str,
+    action: str,
+    params: Optional[Dict[str, Any]],
+    raw_result: Any,
+    enveloped: Any,
+    duration_ms: int,
+) -> None:
+    if tool_name == "resolve_control" and action in _TRACE_OBSERVER_ACTIONS:
+        return
+    try:
+        env = None
+        if isinstance(enveloped, dict):
+            env = enveloped.get(_operation_result.ENVELOPE_KEY)
+            if not env and "execution_id" in enveloped:
+                env = enveloped
+        exec_id = env.get("execution_id") if isinstance(env, dict) else None
+        status = env.get("status") if isinstance(env, dict) else None
+        verification = env.get("verification") if isinstance(env, dict) else None
+        changes = env.get("changes") if isinstance(env, dict) else None
+        warnings = env.get("warnings") if isinstance(env, dict) else None
+
+        _execution_trace.record_step(
+            tool=tool_name,
+            action=action,
+            params=params if isinstance(params, dict) else None,
+            raw_result=raw_result,
+            duration_ms=duration_ms,
+            execution_id=exec_id,
+            status=status,
+            verification=verification,
+            changes=changes,
+            warnings=warnings,
+        )
+    except Exception as exc:  # pragma: no cover
+        logger.debug("Failed to record execution step: %s", exc)
+
+
 def _guard_missing_params(fn):
     """Tool decorator: report a missing parameter instead of leaking a KeyError.
 
@@ -1517,22 +1570,32 @@ def _guard_missing_params(fn):
         @functools.wraps(fn)
         async def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
+            params = _guarded_params(args, kwargs)
+            t0 = time.perf_counter()
             try:
                 result = await fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
-            return _build_operation_envelope(
-                tool_name, action, _guarded_params(args, kwargs), result)
+            duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+            enveloped = _build_operation_envelope(
+                tool_name, action, params, result, duration_ms=duration_ms)
+            _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
+            return enveloped
     else:
         @functools.wraps(fn)
         def wrapper(*args, **kwargs):
             action = _guarded_action_name(args, kwargs)
+            params = _guarded_params(args, kwargs)
+            t0 = time.perf_counter()
             try:
                 result = fn(*args, **kwargs)
             except _MissingParam as exc:
                 result = _missing_param_error(exc, action)
-            return _build_operation_envelope(
-                tool_name, action, _guarded_params(args, kwargs), result)
+            duration_ms = max(0, int((time.perf_counter() - t0) * 1000))
+            enveloped = _build_operation_envelope(
+                tool_name, action, params, result, duration_ms=duration_ms)
+            _record_execution_step(tool_name, action, params, result, enveloped, duration_ms)
+            return enveloped
 
     wrapper.__wrapped_by_missing_param_guard__ = True
     return wrapper
@@ -16047,6 +16110,18 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — Captures the current Resolve UI state so it can be restored after a preview.
       restore_state(state_token) -> {success, restored: {...}}
         — Returns Resolve to a previously-saved state.
+      get_execution_trace(execution_id?) -> {success, trace}
+        — Correlated agent execution trace by execution_id, or most recent if omitted (no connection needed).
+      get_execution(execution_id) -> {success, trace}
+        — Alias for get_execution_trace.
+      list_recent_executions(limit?) -> {success, executions, count}
+        — List recent execution traces with aggregated tool calls, durations, and verifications (no connection needed).
+      begin_execution(request?, execution_id?, initiator?) -> {success, execution_id, started_at, request}
+        — Open a multi-step execution trace so subsequent tool calls thread under this execution ID.
+      end_execution(execution_id?, verification?, status?, notes?) -> {success, trace}
+        — Conclude an execution trace and compute final rollups.
+      clear_executions(dry_run?) -> {success, cleared}
+        — Clear the in-memory execution trace buffer.
     """
     p = _params(params)
 
@@ -16134,6 +16209,53 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     if action == "list_jobs":
         return {"jobs": background_jobs.list_jobs()}
 
+    if action in {"get_execution_trace", "get_execution"}:
+        exec_id = p.get("execution_id") or p.get("id")
+        trace = _execution_trace.get_execution_trace(exec_id)
+        if not trace:
+            return _err(f"No execution trace found for id: {exec_id or 'latest'}", code="NOT_FOUND", category="state")
+        return {"success": True, "trace": trace}
+    if action == "list_recent_executions":
+        limit = _safe_int(p.get("limit"), 20, minimum=1, maximum=100)
+        executions = _execution_trace.list_recent_executions(limit=limit)
+        # Say where the on-disk log is and whether it is actually writable.
+        # The traces themselves live in a 100-entry in-memory ring, so "the
+        # list is short" and "the log is not being written" are different
+        # facts, and a caller should not have to guess which one they have.
+        return {
+            "success": True,
+            "executions": executions,
+            "count": len(executions),
+            "buffer_capacity": _execution_trace.MAX_RECENT_EXECUTIONS,
+            "persistence": _execution_trace.persistence_status(),
+        }
+    if action == "begin_execution":
+        req = p.get("request") or p.get("prompt") or p.get("reason")
+        exec_id = p.get("execution_id") or p.get("id")
+        res = _execution_trace.begin_execution(
+            request=req,
+            execution_id=exec_id,
+            initiator=p.get("initiator") or "agent",
+        )
+        return res
+    if action == "end_execution":
+        exec_id = p.get("execution_id") or p.get("id")
+        trace = _execution_trace.end_execution(
+            execution_id=exec_id,
+            verification=p.get("verification"),
+            status=p.get("status"),
+            notes=p.get("notes"),
+        )
+        if not trace:
+            return _err("No active or matching execution to end", code="NOT_FOUND", category="state")
+        return {"success": True, "trace": trace}
+    if action == "clear_executions":
+        dry_run = _setup_bool(p.get("dry_run", p.get("dryRun")), False)
+        if dry_run:
+            return {"success": True, "dry_run": True, "count": len(_execution_trace.list_recent_executions(100))}
+        res = _execution_trace.clear_executions()
+        return res
+
     # Control-panel actions don't require Resolve to be running.
     if action == "open_control_panel":
         return _open_control_panel(p)
@@ -16348,7 +16470,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if err:
             return _err(err)
         return {"success": bool(r.ExportUserPreferencesPreset(clean["name"], clean["path"]))}
-    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","clear_executions","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────

package/src/utils/execution_trace.py

@@ -0,0 +1,546 @@
+"""Agent execution tracing and observability ("Why did the editor do this?").
+
+Translates agent execution tracing concepts to DaVinci Resolve MCP.
+Connects multi-step tool calls, timing (duration_ms), semantic changes, and
+readback verifications under unified execution traces so human editors and AI
+agents can inspect, debug, and understand AI editorial workflows.
+
+Key capabilities:
+  1. Correlated execution traces across multi-step agent actions.
+  2. Per-tool timing (duration_ms) and invocation counts.
+  3. Semantic change aggregation (e.g. items_deleted, items_added).
+  4. Cumulative verification rollup (passed, checks, contradictions).
+  5. In-memory thread-safe ring buffer with fast queries:
+     - get_execution_trace(execution_id?) / get_execution(id)
+     - list_recent_executions(limit?)
+     - begin_execution(request?, execution_id?)
+     - end_execution(execution_id?, verification?)
+  6. Best-effort append-only persistence beside the server's own log.
+
+Adapted from the design contributed in PR #183.
+"""
+
+from __future__ import annotations
+
+import collections
+import json
+import logging
+import os
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Deque, Dict, List, Optional
+
+logger = logging.getLogger("resolve-mcp.execution-trace")
+
+MAX_RECENT_EXECUTIONS = 100
+
+#: Where traces are written, unless RESOLVE_MCP_TRACE_FILE overrides it.
+#:
+#: Anchored to the repository root, the way `server.log`,
+#: `media-analysis-preferences.json` and `server-preferences.json` all are.
+#: Deriving it from `os.getcwd()` instead put the file wherever the MCP client
+#: happened to launch the server from — and since the generated client configs
+#: set no `cwd`, that is usually a directory with no `logs/` in it, where the
+#: original code returned None and wrote nothing at all. Silently. A feature
+#: whose whole purpose is answering "why did the editor do this?" is worth
+#: rather more than a file that may or may not exist depending on the launcher.
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+#: Size at which the trace log is rotated, and how many old files are kept.
+#:
+#: The in-memory ring is capped at 100 executions; the file had no bound at all,
+#: and it takes one append per tool call. A default-on log that grows without
+#: limit on a working editorial machine is a slow leak, so it rolls over to
+#: `.1` and starts fresh — one generation back is enough for "what did the
+#: agent just do", which is the whole question this feature answers.
+MAX_TRACE_LOG_BYTES = 8 * 1024 * 1024
+TRACE_LOG_GENERATIONS = 1
+
+_LOCK = threading.Lock()
+_EXECUTIONS_BY_ID: Dict[str, Dict[str, Any]] = {}
+_RECENT_ORDER: Deque[str] = collections.deque(maxlen=MAX_RECENT_EXECUTIONS)
+_ACTIVE_EXECUTION_ID: Optional[str] = None
+
+
+def _now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def new_execution_id() -> str:
+    """Generate a correlated execution ID with prefix 'exec_'."""
+    return f"exec_{uuid.uuid4().hex[:12]}"
+
+
+def current_execution_id() -> Optional[str]:
+    """Return the active multi-turn execution ID for this session, if any."""
+    with _LOCK:
+        return _ACTIVE_EXECUTION_ID
+
+
+def _clean_trace_dict(trace: Dict[str, Any]) -> Dict[str, Any]:
+    """Return a deep copy of the execution trace for safe serialization."""
+    return json.loads(json.dumps(trace))
+
+
+def _aggregate_changes(
+    cumulative: Optional[Dict[str, Any]],
+    delta: Optional[Dict[str, Any]],
+) -> Optional[Dict[str, Any]]:
+    if not delta:
+        return cumulative
+    if cumulative is None:
+        return dict(delta)
+
+    out = dict(cumulative)
+    for k, v in delta.items():
+        if isinstance(v, (int, float)):
+            existing = out.get(k, 0)
+            if isinstance(existing, (int, float)):
+                out[k] = existing + v
+            else:
+                out[k] = v
+        else:
+            out[k] = v
+    return out
+
+
+def _merge_verification(
+    current: Dict[str, Any],
+    step_verif: Optional[Dict[str, Any]],
+) -> Dict[str, Any]:
+    if not isinstance(step_verif, dict):
+        return current
+
+    checks = list(current.get("checks", []))
+    new_checks = step_verif.get("checks", [])
+    if isinstance(new_checks, list):
+        checks.extend(new_checks)
+
+    contradiction = bool(current.get("contradiction")) or bool(step_verif.get("contradiction"))
+
+    # Determine status priority: contradiction > failed > partial > passed > unverified
+    statuses = {current.get("status", "unverified"), step_verif.get("status", "unverified")}
+    if contradiction or "contradiction" in statuses:
+        status = "contradiction"
+        passed = False
+    elif "failed" in statuses:
+        status = "failed"
+        passed = False
+    elif "partial" in statuses:
+        status = "partial"
+        passed = False
+    elif "passed" in statuses:
+        status = "passed"
+        passed = True
+    else:
+        status = "unverified"
+        passed = True
+
+    return {
+        "status": status,
+        "passed": passed,
+        "contradiction": contradiction,
+        "checks": checks,
+    }
+
+
+def begin_execution(
+    request: Optional[str] = None,
+    *,
+    execution_id: Optional[str] = None,
+    initiator: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Start an active multi-step execution trace for the session.
+
+    Subsequent tool calls will automatically thread under this execution ID
+    until end_execution() is called.
+    """
+    global _ACTIVE_EXECUTION_ID
+
+    exec_id = execution_id or new_execution_id()
+    now = _now_iso()
+
+    trace: Dict[str, Any] = {
+        "execution_id": exec_id,
+        "request": str(request).strip() if request else None,
+        "status": "running",
+        "started_at": now,
+        "ended_at": None,
+        "duration_ms": 0,
+        "tools": [],
+        "steps": [],
+        "changes": None,
+        "verification": {
+            "status": "unverified",
+            "passed": True,
+            "contradiction": False,
+            "checks": [],
+        },
+        "warnings": [],
+        "initiator": initiator or "agent",
+        "is_active": True,
+    }
+
+    with _LOCK:
+        _EXECUTIONS_BY_ID[exec_id] = trace
+        if exec_id in _RECENT_ORDER:
+            _RECENT_ORDER.remove(exec_id)
+        _RECENT_ORDER.appendleft(exec_id)
+        _ACTIVE_EXECUTION_ID = exec_id
+
+    _persist_trace_event("begin", trace)
+    return {
+        "success": True,
+        "execution_id": exec_id,
+        "started_at": now,
+        "request": trace["request"],
+    }
+
+
+def end_execution(
+    execution_id: Optional[str] = None,
+    *,
+    verification: Optional[Dict[str, Any]] = None,
+    status: Optional[str] = None,
+    notes: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """End an active execution trace and calculate final rollups."""
+    global _ACTIVE_EXECUTION_ID
+
+    target_id = execution_id or _ACTIVE_EXECUTION_ID
+    if not target_id:
+        return None
+
+    now = _now_iso()
+    with _LOCK:
+        trace = _EXECUTIONS_BY_ID.get(target_id)
+        if not trace:
+            return None
+
+        trace["ended_at"] = now
+        trace["is_active"] = False
+
+        if verification:
+            trace["verification"] = _merge_verification(trace["verification"], verification)
+
+        if notes:
+            trace["notes"] = str(notes).strip()
+
+        # Deduce overall status if not explicitly passed
+        if status:
+            trace["status"] = status
+        else:
+            if trace["verification"].get("contradiction"):
+                trace["status"] = "failed"
+            elif any(s.get("status") == "failed" for s in trace.get("steps", [])):
+                trace["status"] = "failed"
+            elif any(s.get("status") == "partial" for s in trace.get("steps", [])):
+                trace["status"] = "partial"
+            elif any(s.get("status") == "blocked" for s in trace.get("steps", [])):
+                trace["status"] = "blocked"
+            else:
+                trace["status"] = "success"
+
+        # If this was the active session execution, clear it
+        if _ACTIVE_EXECUTION_ID == target_id:
+            _ACTIVE_EXECUTION_ID = None
+
+        copy_trace = _clean_trace_dict(trace)
+
+    _persist_trace_event("end", copy_trace)
+    return copy_trace
+
+
+def record_step(
+    tool: str,
+    action: str,
+    params: Optional[Dict[str, Any]],
+    raw_result: Any,
+    duration_ms: int,
+    *,
+    execution_id: Optional[str] = None,
+    status: Optional[str] = None,
+    verification: Optional[Dict[str, Any]] = None,
+    changes: Optional[Dict[str, Any]] = None,
+    warnings: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Record a single tool call step into an execution trace.
+
+    If execution_id is provided or an active execution exists, appends to it.
+    Otherwise, creates a self-contained single-step execution trace.
+    """
+    op_name = f"{tool}.{action}"
+    step_status = status or ("failed" if isinstance(raw_result, dict) and raw_result.get("error") else "success")
+    now = _now_iso()
+
+    step_record: Dict[str, Any] = {
+        "seq": 1,
+        "tool": tool,
+        "action": action,
+        "operation": op_name,
+        "duration_ms": max(0, int(duration_ms)),
+        "status": step_status,
+        "timestamp": now,
+    }
+    if verification:
+        step_record["verification"] = verification
+    if changes:
+        step_record["changes"] = changes
+    if warnings:
+        step_record["warnings"] = warnings
+
+    with _LOCK:
+        target_id = execution_id or _ACTIVE_EXECUTION_ID
+        is_single_step = False
+
+        if not target_id:
+            target_id = new_execution_id()
+            is_single_step = True
+            request_text = None
+            if isinstance(params, dict):
+                request_text = params.get("request") or params.get("prompt") or params.get("reason")
+            trace: Dict[str, Any] = {
+                "execution_id": target_id,
+                "request": str(request_text).strip() if request_text else None,
+                "status": step_status,
+                "started_at": now,
+                "ended_at": now,
+                "duration_ms": 0,
+                "tools": [],
+                "steps": [],
+                "changes": None,
+                "verification": {
+                    "status": "unverified",
+                    "passed": True,
+                    "contradiction": False,
+                    "checks": [],
+                },
+                "warnings": [],
+                "initiator": "tool_call",
+                "is_active": False,
+            }
+            _EXECUTIONS_BY_ID[target_id] = trace
+            _RECENT_ORDER.appendleft(target_id)
+        else:
+            trace = _EXECUTIONS_BY_ID.get(target_id)
+            if not trace:
+                trace = {
+                    "execution_id": target_id,
+                    "request": None,
+                    "status": "running",
+                    "started_at": now,
+                    "ended_at": None,
+                    "duration_ms": 0,
+                    "tools": [],
+                    "steps": [],
+                    "changes": None,
+                    "verification": {
+                        "status": "unverified",
+                        "passed": True,
+                        "contradiction": False,
+                        "checks": [],
+                    },
+                    "warnings": [],
+                    "initiator": "agent",
+                    "is_active": True,
+                }
+                _EXECUTIONS_BY_ID[target_id] = trace
+                _RECENT_ORDER.appendleft(target_id)
+
+        # Update trace request if provided in params and currently empty
+        if not trace.get("request") and isinstance(params, dict):
+            req = params.get("request") or params.get("prompt") or params.get("reason")
+            if req:
+                trace["request"] = str(req).strip()
+
+        step_record["seq"] = len(trace["steps"]) + 1
+        trace["steps"].append(step_record)
+        trace["duration_ms"] = int(trace.get("duration_ms", 0)) + max(0, int(duration_ms))
+
+        # Update aggregated tools entry (matching user format)
+        found_tool = None
+        for t in trace["tools"]:
+            if t.get("tool") == op_name or t.get("tool") == action:
+                found_tool = t
+                break
+
+        if found_tool:
+            found_tool["count"] = int(found_tool.get("count", 1)) + 1
+            found_tool["duration_ms"] = int(found_tool.get("duration_ms", 0)) + max(0, int(duration_ms))
+        else:
+            trace["tools"].append({
+                "tool": op_name,
+                "count": 1,
+                "duration_ms": max(0, int(duration_ms)),
+            })
+
+        # Aggregate changes
+        if changes:
+            trace["changes"] = _aggregate_changes(trace.get("changes"), changes)
+
+        # Merge verification
+        if verification:
+            trace["verification"] = _merge_verification(trace["verification"], verification)
+
+        # Merge warnings
+        if warnings:
+            existing_warnings = set(trace.get("warnings", []))
+            for w in warnings:
+                w_str = str(w).strip()
+                if w_str and w_str not in existing_warnings:
+                    trace["warnings"].append(w_str)
+                    existing_warnings.add(w_str)
+
+        if is_single_step:
+            trace["status"] = step_status
+            trace["ended_at"] = now
+
+        result_copy = _clean_trace_dict(trace)
+
+    _persist_trace_event("step", {"execution_id": target_id, "step": step_record})
+    return result_copy
+
+
+def get_execution_trace(execution_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """Look up an execution trace by ID.
+
+    If execution_id is omitted, returns the most recent execution trace.
+    """
+    with _LOCK:
+        if not execution_id:
+            if not _RECENT_ORDER:
+                return None
+            target_id = _RECENT_ORDER[0]
+        else:
+            target_id = execution_id
+
+        trace = _EXECUTIONS_BY_ID.get(target_id)
+        if not trace:
+            return None
+        return _clean_trace_dict(trace)
+
+
+def get_execution(execution_id: str) -> Optional[Dict[str, Any]]:
+    """Alias for get_execution_trace(execution_id)."""
+    return get_execution_trace(execution_id)
+
+
+def list_recent_executions(limit: int = 20) -> List[Dict[str, Any]]:
+    """List recent executions (newest first) with summary information."""
+    max_count = max(1, min(int(limit), MAX_RECENT_EXECUTIONS))
+    out: List[Dict[str, Any]] = []
+
+    with _LOCK:
+        for exec_id in list(_RECENT_ORDER)[:max_count]:
+            trace = _EXECUTIONS_BY_ID.get(exec_id)
+            if not trace:
+                continue
+            summary = {
+                "execution_id": trace["execution_id"],
+                "request": trace.get("request"),
+                "status": trace.get("status"),
+                "started_at": trace.get("started_at"),
+                "ended_at": trace.get("ended_at"),
+                "duration_ms": trace.get("duration_ms", 0),
+                "tool_count": len(trace.get("tools", [])),
+                "step_count": len(trace.get("steps", [])),
+                "tools": trace.get("tools", []),
+                "verification": trace.get("verification", {}),
+                "changes": trace.get("changes"),
+            }
+            out.append(summary)
+
+    return out
+
+
+def clear_executions() -> Dict[str, Any]:
+    """Clear in-memory execution traces and active execution ID."""
+    global _ACTIVE_EXECUTION_ID
+    with _LOCK:
+        count = len(_EXECUTIONS_BY_ID)
+        _EXECUTIONS_BY_ID.clear()
+        _RECENT_ORDER.clear()
+        _ACTIVE_EXECUTION_ID = None
+    return {"success": True, "cleared": count}
+
+
+# ── Persistence (Best-Effort) ────────────────────────────────────────────────
+
+def trace_log_path() -> str:
+    """The file traces are appended to. Always a path, never None.
+
+    Returning None when a directory did not happen to exist made persistence
+    an invisible coin flip; the directory is created on first write instead.
+    """
+    override = os.environ.get("RESOLVE_MCP_TRACE_FILE")
+    if override:
+        return os.path.realpath(os.path.abspath(os.path.expanduser(override)))
+    return str(_REPO_ROOT / "logs" / "execution-traces.jsonl")
+
+
+def persistence_status() -> Dict[str, Any]:
+    """Whether traces are reaching disk, and where.
+
+    Reported alongside every query so "no traces in the file" is answerable
+    without reading this module: an unwritable path says so here rather than
+    being swallowed by the best-effort append.
+    """
+    path = trace_log_path()
+    status: Dict[str, Any] = {"path": path, "writable": False, "exists": False,
+                              "reason": None}
+    try:
+        status["exists"] = os.path.isfile(path)
+        directory = os.path.dirname(path)
+        os.makedirs(directory, exist_ok=True)
+        status["writable"] = os.access(directory, os.W_OK)
+        if not status["writable"]:
+            status["reason"] = f"{directory} is not writable"
+    except OSError as exc:
+        status["reason"] = str(exc)
+    return status
+
+
+# Kept for callers that used the private name; the public one is the path itself.
+_trace_log_path = trace_log_path
+
+
+def _rotate_if_oversized(path: str) -> None:
+    """Roll the trace log over once it passes the size cap. Never raises."""
+    try:
+        if os.path.getsize(path) < MAX_TRACE_LOG_BYTES:
+            return
+    except OSError:
+        return
+    try:
+        previous = f"{path}.{TRACE_LOG_GENERATIONS}"
+        if os.path.exists(previous):
+            os.remove(previous)
+        os.replace(path, previous)
+    except OSError as exc:
+        logger.debug("Could not rotate the execution trace log: %s", exc)
+
+
+def _persist_trace_event(event_type: str, data: Any) -> None:
+    """Best-effort append to the trace log. Never raises.
+
+    Synchronous, on the calling thread — not "non-blocking", as this was
+    originally described. It is a buffered append of a few hundred bytes and
+    measures at ~0.07ms per tool call on local disk, which is immaterial next
+    to any Resolve round-trip, but the accurate word for it is *cheap*. It runs
+    outside `_LOCK` so a slow filesystem cannot serialize concurrent tool calls.
+    """
+    try:
+        path = trace_log_path()
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        _rotate_if_oversized(path)
+        line = json.dumps({
+            "event": event_type,
+            "timestamp": _now_iso(),
+            "data": data,
+        }) + "\n"
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(line)
+    except Exception as exc:  # pragma: no cover
+        logger.debug("Failed to persist execution trace event: %s", exc)

package/src/utils/operation_result.py

@@ -337,6 +337,7 @@ def build_operation_envelope(
     *,
     execution_id: Optional[str] = None,
     mode: Optional[str] = None,
+    duration_ms: Optional[int] = None,
 ) -> Any:
     """Attach the operation envelope to one action's return value."""
     if is_passthrough(raw_result):
@@ -346,6 +347,20 @@ def build_operation_envelope(
     if selected == "legacy":
         return raw_result
 
+    if not execution_id and isinstance(params, dict):
+        candidate = params.get("execution_id") or params.get("_execution_id") or params.get("trace_id")
+        if isinstance(candidate, str) and candidate.strip():
+            execution_id = candidate.strip()
+
+    if not execution_id:
+        try:
+            from src.utils import execution_trace
+            active_id = execution_trace.current_execution_id()
+            if active_id:
+                execution_id = active_id
+        except ImportError:
+            pass
+
     envelope: Dict[str, Any] = {
         "status": normalize_status(raw_result),
         "operation": f"{tool_name}.{action}",
@@ -353,6 +368,9 @@ def build_operation_envelope(
         "verification": extract_verification(raw_result),
     }
 
+    if duration_ms is not None:
+        envelope["duration_ms"] = max(0, int(duration_ms))
+
     changes = extract_changes(raw_result)
     if changes is not None:
         envelope["changes"] = changes