davinci-resolve-mcp 2.206.0 → 2.207.0

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 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.207.0 — execution audit report exports
+
+Contributed in PR #185.
+
+### Added
+
+- **Execution traces can now be exported as reviewable audit reports.**
+  `resolve_control(action="export_execution_report")` writes the latest trace,
+  or a named `execution_id`, as Markdown or JSON. The report carries the
+  request, status, start/end timestamps, duration, tool summary, semantic
+  deltas, verification rollup, warnings, notes, and optional per-step table.
+- **Reports default beside the trace log.** When no path is passed, reports are
+  written under `logs/execution-reports/<execution_id>.md` or `.json`.
+  `RESOLVE_MCP_TRACE_REPORT_DIR` can move that default destination without
+  changing where append-only trace events are logged.
+- **Exports are observer-safe.** Creating a report is exempt from execution-step
+  recording, just like querying traces, so inspecting or exporting a trace
+  cannot mutate the trace being reviewed.
+- **Existing files are protected by default.** A caller must pass
+  `overwrite=true` to replace a report at the chosen path.
+
+### Notes
+
+- The export is built from the existing trace summary fields, not raw tool
+  arguments or raw tool results. It is meant for review and audit, not a replay
+  script.
+- Added focused unit and server integration coverage for Markdown export, JSON
+  export, step omission, invalid formats, overwrite protection, observer
+  isolation, and `resolve_control` dispatch.
+
+### Fixed on the way in
+
+- **An unverified run no longer reports itself as passed.** The verification
+  rollup collapsed "nothing reported any evidence" into `passed: True`, and the
+  report printed it verbatim — so a workflow where nothing was checked produced
+  an audit document reading `Status: unverified` on one line and `Passed: yes`
+  on the next. Those sit inches apart and only one of them gets scanned. The
+  rollup now carries `None` for the unknown case and the Passed row renders
+  "not established — no checks recorded"; a real pass still says yes and a real
+  failure still says no. This is the same distinction v2.206.0 documented for
+  `verification.status`, and the export is exactly where it stops being a
+  nuance and starts being a claim on paper.
+- **The Simplified Chinese README was carrying a false version line.** Its
+  badge and "本翻译对应 vX.Y.Z 版 README" line were bumped to 2.207.0 without the
+  section itself, which is the specific failure the release process calls out —
+  a lagging translation whose version line asserts otherwise. Translated.
+- `path` is documented as honoured-as-given, creating directories to reach the
+  destination: deliberate, since a conform's paperwork belongs beside the
+  conform rather than in `logs/`, but worth stating next to a source-media
+  safety policy. The `execution_id` route is sanitised to a bare filename and
+  cannot escape the report directory — verified.
+
 ## What's New in v2.206.0 — agent execution traces
 
 Adapted from the design contributed in PR #183.

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.206.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.207.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)
@@ -274,6 +274,16 @@ 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()`.
+`export_execution_report(execution_id?, format="markdown"|"json")` writes a
+reviewable audit artifact with the same summary, defaulting to
+`logs/execution-reports/<execution_id>.md`. `path` writes it anywhere you want
+it instead — alongside a conform in a dated TransferFiles folder, say — and
+creates the directories to get there, so check the path before you send it.
+An existing file is never replaced without `overwrite: true`.
+
+A report for a run where nothing was verified says **"not established — no
+checks recorded"**, not "passed". Absence of evidence is a question still open,
+and an audit document is the last place to let a reader read it as an all-clear.
 
 Traces live in a 100-entry in-memory ring and are appended to
 `logs/execution-traces.jsonl` beside `server.log` — `RESOLVE_MCP_TRACE_FILE`

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.206.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.207.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.206.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.207.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -172,6 +172,12 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 轨迹保存在一个容量 100 条的内存环形缓冲里，并追加写入 `logs/execution-traces.jsonl`（就在 `server.log` 旁边，可用 `RESOLVE_MCP_TRACE_FILE` 改位置），文件到 8 MB 会轮转并保留一份上一代。`list_recent_executions` 会返回该路径以及是否可写，这样"日志是空的"和"根本没在写"就能区分开。记录的内容是工具名、动作、耗时、状态、语义增量和校验结果——不记录参数，也不记录文件路径。唯一的自由文本是你传给 `begin_execution` 的 `request`，在客户项目上请把它当成提交信息来写。
 
+### 导出执行审计报告
+
+`export_execution_report(execution_id?, format="markdown"|"json")` 会把一条轨迹写成可供审阅的审计文件，默认落在 `logs/execution-reports/<execution_id>.md`。传 `path` 可以写到任何你想要的位置——比如跟着某次套底放进当天的 TransferFiles 文件夹——并且会自动创建沿途的目录，所以发出去之前请先确认路径。已存在的文件不会被覆盖，除非显式传 `overwrite: true`。
+
+如果这次运行根本没有做过校验，报告里写的是**"not established — no checks recorded"（未确立——没有记录任何检查）**，而不是"通过"。没有证据是一个仍然悬而未决的问题；审计文件恰恰是最不该让读者把它读成"一切正常"的地方。
+
 ## 可选增强
 
 核心安装刻意保持精简：Python、ffmpeg 和 Resolve 脚本 API。有些功能需要更多依赖，且**每一项都会诚实拒绝并给出自己的安装命令，而不是退化成瞎猜**——编造的节拍或虚构的电平会产出自信但错误的结果，比没有这个功能更糟。

package/docs/SKILL.md

@@ -271,6 +271,11 @@ Example trace shape returned by `resolve_control(action="get_execution_trace")`:
   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).
+- **`export_execution_report(execution_id?, format?, path?, overwrite?, include_steps?)`**:
+  Writes a Markdown or JSON audit report for a trace. The default destination is
+  `logs/execution-reports/<execution_id>.md`; pass `format: "json"` for
+  structured output, `include_steps: false` for a shorter summary, or
+  `overwrite: true` to replace an existing report.
 - **`clear_executions(dry_run?)`**: Clears the in-memory execution trace buffer.
 
 Explicit correlation is also supported per-call: pass `params={"execution_id": ...}`
@@ -290,6 +295,20 @@ 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/`.
+Audit reports are separate point-in-time exports; `RESOLVE_MCP_TRACE_REPORT_DIR`
+moves their default directory without moving the append-only trace log.
+
+`path` is honoured as given — the report can be written anywhere, and the
+directories are created to reach it. That is deliberate (a conform's paperwork
+belongs beside the conform, not in `logs/`), so treat it the way you would any
+other export destination and do not invent a path near source media. The
+`execution_id` route cannot escape the report directory: it is sanitised to a
+filename.
+
+A report whose run recorded no verification checks renders **"not established
+— no checks recorded"** in the Passed row, never "yes" — the same rule as
+`verification.status: "unverified"` in the envelope. Do not report such a run
+to the user as verified.
 
 ---
 

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.206.0"
+VERSION = "2.207.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.206.0",
+  "version": "2.207.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.206.0"
+VERSION = "2.207.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.206.0"
+VERSION = "2.207.0"
 
 import base64
 import os
@@ -74,6 +74,7 @@ from src.utils.execution_trace import (
     begin_execution,
     end_execution,
     clear_executions,
+    export_execution_report,
 )
 from src.utils.render_ids import (
     render_codec_id_from_codecs as _render_codec_id_from_codecs,
@@ -1499,6 +1500,7 @@ def _guarded_params(args, kwargs) -> Optional[Dict[str, Any]]:
 _TRACE_OBSERVER_ACTIONS = {
     "get_execution_trace", "get_execution", "list_recent_executions",
     "clear_executions", "begin_execution", "end_execution",
+    "export_execution_report",
 }
 
 
@@ -16120,6 +16122,8 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         — 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.
+      export_execution_report(execution_id?, format?, path?, overwrite?, include_steps?) -> {success, path, bytes}
+        — Write a Markdown or JSON audit report for an execution trace (no connection needed).
       clear_executions(dry_run?) -> {success, cleared}
         — Clear the in-memory execution trace buffer.
     """
@@ -16249,6 +16253,33 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if not trace:
             return _err("No active or matching execution to end", code="NOT_FOUND", category="state")
         return {"success": True, "trace": trace}
+    if action == "export_execution_report":
+        exec_id = p.get("execution_id") or p.get("id")
+        report_format = p.get("format") or p.get("report_format") or "markdown"
+        include_steps = _setup_bool(p.get("include_steps", p.get("includeSteps")), True)
+        overwrite = _setup_bool(p.get("overwrite"), False)
+        try:
+            res = _execution_trace.export_execution_report(
+                execution_id=exec_id,
+                report_format=report_format,
+                output_path=p.get("path") or p.get("output_path") or p.get("outputPath"),
+                overwrite=overwrite,
+                include_steps=include_steps,
+            )
+        except FileExistsError as exc:
+            return _err(str(exc), code="REPORT_EXISTS", category="invalid_input")
+        except ValueError as exc:
+            return _err(str(exc), code="INVALID_REPORT_FORMAT", category="invalid_input")
+        except OSError as exc:
+            return _err(
+                "Could not write execution report",
+                code="REPORT_WRITE_FAILED",
+                category="io",
+                reason=str(exc),
+            )
+        if not res:
+            return _err(f"No execution trace found for id: {exec_id or 'latest'}", code="NOT_FOUND", category="state")
+        return res
     if action == "clear_executions":
         dry_run = _setup_bool(p.get("dry_run", p.get("dryRun")), False)
         if dry_run:
@@ -16470,7 +16501,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","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"])
+    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","export_execution_report","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

@@ -26,11 +26,12 @@ import collections
 import json
 import logging
 import os
+import re
 import threading
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Deque, Dict, List, Optional
+from typing import Any, Deque, Dict, List, Optional, Union
 
 logger = logging.getLogger("resolve-mcp.execution-trace")
 
@@ -135,8 +136,12 @@ def _merge_verification(
         status = "passed"
         passed = True
     else:
+        # None, not True. Nothing reported any evidence either way, and
+        # collapsing that into a boolean makes the rollup assert a pass it
+        # never observed — which then reaches a human as "Passed: yes" in an
+        # exported audit report.
         status = "unverified"
-        passed = True
+        passed = None
 
     return {
         "status": status,
@@ -174,7 +179,10 @@ def begin_execution(
         "changes": None,
         "verification": {
             "status": "unverified",
-            "passed": True,
+            # None, not True. "Nothing was checked" is not "everything passed",
+            # and the difference reaches a human in an exported audit report —
+            # see _execution_report_markdown.
+            "passed": None,
             "contradiction": False,
             "checks": [],
         },
@@ -313,7 +321,7 @@ def record_step(
                 "changes": None,
                 "verification": {
                     "status": "unverified",
-                    "passed": True,
+                    "passed": None,  # see above: unknown, not passed
                     "contradiction": False,
                     "checks": [],
                 },
@@ -338,7 +346,7 @@ def record_step(
                     "changes": None,
                     "verification": {
                         "status": "unverified",
-                        "passed": True,
+                        "passed": None,  # see above: unknown, not passed
                         "contradiction": False,
                         "checks": [],
                     },
@@ -466,6 +474,247 @@ def clear_executions() -> Dict[str, Any]:
     return {"success": True, "cleared": count}
 
 
+# ── Audit Reports ───────────────────────────────────────────────────────────
+
+def _report_format(report_format: str) -> str:
+    fmt = str(report_format or "markdown").strip().lower()
+    if fmt in {"md", "markdown"}:
+        return "markdown"
+    if fmt == "json":
+        return "json"
+    raise ValueError("format must be markdown or json")
+
+
+def _report_extension(report_format: str) -> str:
+    return ".md" if _report_format(report_format) == "markdown" else ".json"
+
+
+def _report_filename(execution_id: str, report_format: str) -> str:
+    safe_id = re.sub(r"[^A-Za-z0-9_.-]+", "_", str(execution_id or "execution")).strip("._")
+    if not safe_id:
+        safe_id = "execution"
+    return f"{safe_id}{_report_extension(report_format)}"
+
+
+def execution_report_dir() -> str:
+    """Directory used for generated execution audit reports."""
+    override = os.environ.get("RESOLVE_MCP_TRACE_REPORT_DIR")
+    if override:
+        return os.path.realpath(os.path.abspath(os.path.expanduser(override)))
+    return str(_REPO_ROOT / "logs" / "execution-reports")
+
+
+def _default_report_path(trace: Dict[str, Any], report_format: str) -> str:
+    return str(Path(execution_report_dir()) / _report_filename(trace["execution_id"], report_format))
+
+
+def _format_ms(value: Any) -> str:
+    try:
+        return f"{max(0, int(value))} ms"
+    except (TypeError, ValueError):
+        return "0 ms"
+
+
+def _scalar(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, sort_keys=True, ensure_ascii=False)
+    return str(value)
+
+
+def _markdown_row(*cells: Any) -> str:
+    escaped = []
+    for cell in cells:
+        text = _scalar(cell).replace("\n", " ").replace("|", "\\|")
+        escaped.append(text)
+    return "| " + " | ".join(escaped) + " |"
+
+
+def _execution_report_json(trace: Dict[str, Any], *, include_steps: bool = True) -> Dict[str, Any]:
+    """Return a stable, compact report object derived from safe trace summaries."""
+    out = {
+        "execution_id": trace.get("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),
+        "initiator": trace.get("initiator"),
+        "is_active": trace.get("is_active", False),
+        "tools": trace.get("tools", []),
+        "changes": trace.get("changes"),
+        "verification": trace.get("verification", {}),
+        "warnings": trace.get("warnings", []),
+    }
+    if trace.get("notes"):
+        out["notes"] = trace.get("notes")
+    if include_steps:
+        out["steps"] = trace.get("steps", [])
+    return out
+
+
+def _execution_report_markdown(trace: Dict[str, Any], *, include_steps: bool = True) -> str:
+    report = _execution_report_json(trace, include_steps=include_steps)
+    lines = [
+        "# Execution Audit Report",
+        "",
+        _markdown_row("Field", "Value"),
+        _markdown_row("---", "---"),
+        _markdown_row("Execution ID", report.get("execution_id")),
+        _markdown_row("Request", report.get("request")),
+        _markdown_row("Status", report.get("status")),
+        _markdown_row("Started", report.get("started_at")),
+        _markdown_row("Ended", report.get("ended_at")),
+        _markdown_row("Duration", _format_ms(report.get("duration_ms"))),
+        _markdown_row("Initiator", report.get("initiator")),
+        "",
+        "## Tool Summary",
+        "",
+    ]
+
+    tools = report.get("tools") or []
+    if tools:
+        lines.extend([
+            _markdown_row("Tool", "Calls", "Duration"),
+            _markdown_row("---", "---:", "---:"),
+        ])
+        for tool in tools:
+            lines.append(_markdown_row(tool.get("tool"), tool.get("count", 0), _format_ms(tool.get("duration_ms"))))
+    else:
+        lines.append("No tool calls recorded.")
+
+    lines.extend(["", "## Changes", ""])
+    changes = report.get("changes")
+    if isinstance(changes, dict) and changes:
+        lines.extend([
+            _markdown_row("Change", "Value"),
+            _markdown_row("---", "---"),
+        ])
+        for key in sorted(changes):
+            lines.append(_markdown_row(key, changes[key]))
+    else:
+        lines.append("No semantic changes recorded.")
+
+    verification = report.get("verification") or {}
+    lines.extend([
+        "",
+        "## Verification",
+        "",
+        _markdown_row("Field", "Value"),
+        _markdown_row("---", "---"),
+        _markdown_row("Status", verification.get("status")),
+        _markdown_row("Passed", _verification_passed_label(verification)),
+        _markdown_row("Contradiction", verification.get("contradiction")),
+        _markdown_row("Checks", len(verification.get("checks") or [])),
+    ])
+
+    warnings = report.get("warnings") or []
+    lines.extend(["", "## Warnings", ""])
+    if warnings:
+        lines.extend(f"- {_scalar(w)}" for w in warnings)
+    else:
+        lines.append("No warnings recorded.")
+
+    if report.get("notes"):
+        lines.extend(["", "## Notes", "", _scalar(report["notes"])])
+
+    if include_steps:
+        lines.extend(["", "## Steps", ""])
+        steps = report.get("steps") or []
+        if steps:
+            lines.extend([
+                _markdown_row("#", "Timestamp", "Operation", "Status", "Duration"),
+                _markdown_row("---:", "---", "---", "---", "---:"),
+            ])
+            for step in steps:
+                lines.append(_markdown_row(
+                    step.get("seq"),
+                    step.get("timestamp"),
+                    step.get("operation"),
+                    step.get("status"),
+                    _format_ms(step.get("duration_ms")),
+                ))
+        else:
+            lines.append("No steps recorded.")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _verification_passed_label(verification: Dict[str, Any]) -> str:
+    """How the Passed row reads when nothing was actually verified.
+
+    A report that prints `Status: unverified` beside `Passed: yes` is read by a
+    human as "it passed" — the two lines are inches apart and only one of them
+    is scanned. Unverified means no evidence was reported, which is a question
+    still open, not a clean bill of health; an audit document is the last place
+    that distinction should be left to the reader.
+    """
+    passed = verification.get("passed")
+    if passed is None:
+        return "not established — no checks recorded"
+    return "yes" if passed else "no"
+
+
+def render_execution_report(
+    trace: Dict[str, Any],
+    *,
+    report_format: str = "markdown",
+    include_steps: bool = True,
+) -> Union[str, Dict[str, Any]]:
+    """Render an execution trace as a Markdown or JSON audit report."""
+    fmt = _report_format(report_format)
+    if fmt == "json":
+        return _execution_report_json(trace, include_steps=include_steps)
+    return _execution_report_markdown(trace, include_steps=include_steps)
+
+
+def export_execution_report(
+    execution_id: Optional[str] = None,
+    *,
+    report_format: str = "markdown",
+    output_path: Optional[str] = None,
+    overwrite: bool = False,
+    include_steps: bool = True,
+) -> Optional[Dict[str, Any]]:
+    """Write an execution audit report to disk.
+
+    The export is built from trace summaries, not raw tool arguments/results.
+    """
+    trace = get_execution_trace(execution_id)
+    if not trace:
+        return None
+
+    fmt = _report_format(report_format)
+    path = output_path or _default_report_path(trace, fmt)
+    real_path = os.path.realpath(os.path.abspath(os.path.expanduser(path)))
+    if os.path.exists(real_path) and not overwrite:
+        raise FileExistsError(f"Report already exists: {real_path}")
+
+    rendered = render_execution_report(trace, report_format=fmt, include_steps=include_steps)
+    os.makedirs(os.path.dirname(real_path), exist_ok=True)
+    if fmt == "json":
+        payload = json.dumps(rendered, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+    else:
+        payload = str(rendered)
+    with open(real_path, "w", encoding="utf-8") as fh:
+        fh.write(payload)
+
+    return {
+        "success": True,
+        "execution_id": trace["execution_id"],
+        "format": fmt,
+        "path": real_path,
+        "bytes": len(payload.encode("utf-8")),
+        "included_steps": bool(include_steps),
+    }
+
+
 # ── Persistence (Best-Effort) ────────────────────────────────────────────────
 
 def trace_log_path() -> str: