davinci-resolve-mcp 2.29.0 → 2.30.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 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.30.0
+
+Adds the **Resolve 21 AI-ops ledger** — usage/time/file accounting for the
+Resolve-local AI operations added in v2.29.0 (audio classification, IntelliSearch,
+slate, motion-deblur, speech generation). These run on Resolve's own GPU/AI engine
+and do **not** consume the Claude-side analysis token budget, so they get their
+own ledger instead of being metered by the analysis-caps layer.
+
+**What's tracked.** Every run of the five 21.0 ops records: op name, op class
+(`analysis` vs `render`), clip id, success/failure, wall-clock time, and — for the
+two media-creating ops (`remove_motion_blur`, `generate_speech`) — the output
+file path and byte size. The reliable signal is invocation counts + the
+file/disk accounting for the creators; durations for the bool-returning analysis
+ops reflect the script-call time (some queue work inside Resolve).
+
+- **New table** `resolve_ai_op_usage` (timeline_brain DB schema v7).
+- **New module** `src/utils/resolve_ai_ledger.py` — `timed()` context manager +
+  `record_op` / `get_usage` / `get_summary`. All writes are best-effort and never
+  block or mask the underlying Resolve op.
+- **Instrumentation** wraps the consolidated `folder` / `media_pool_item`
+  `perform_audio_classification` / `clear_audio_classification` /
+  `analyze_for_intellisearch` / `analyze_for_slate` / `remove_motion_blur`
+  handlers and `project_settings.generate_speech`.
+- **New MCP action** `media_analysis(action="get_resolve_ai_usage", session_only?, op?, limit?)`
+  returns the per-op summary + recent runs.
+- **Control panel**: a read-only "Resolve 21 AI ops" card (`/api/resolve_ai_usage`)
+  shows runs, success/fail, total time, and files/bytes created.
+
+Phase 1 of a staged build (ledger → interactive console → governance). Granular
+`--full` server instrumentation is deferred — the ledger covers the consolidated
+server, which is the default surface. Validated live against Resolve Studio 21.0.0.47.
+
 ## What's New in v2.29.0
 
 Adds the **DaVinci Resolve 21.0** scripting-API additions. Every new method is

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.29.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.30.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-32%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -668,6 +668,15 @@ effective values + a usage rollup (clip / job / day) with percent-consumed.
 counts for one scope. Usage is tracked in
 `<project>/_soul/timeline_brain.sqlite` (`analysis_token_usage` table).
 
+Resolve 21's local AI ops (audio classification, IntelliSearch, slate,
+motion-deblur, speech generation) run on Resolve's own GPU/AI engine and do NOT
+spend the Claude analysis token budget — they are tracked separately in the
+`resolve_ai_op_usage` table. Inspect with
+`media_analysis(action="get_resolve_ai_usage", session_only?, op?, limit?)` →
+`{summary, recent}` (invocation counts, wall-clock, and files/bytes created by
+`remove_motion_blur` / `generate_speech`). The control panel shows the same as a
+read-only "Resolve 21 AI ops" card.
+
 The caps layer:
 - Slices `frame_paths` to `frames_per_clip` before the host LLM sees them.
 - Downscales each sampled frame in place to `max_frame_dim_pixels` (Pillow;

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.29.0"
+VERSION = "2.30.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.29.0",
+  "version": "2.30.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -4370,6 +4370,24 @@ HTML = r"""<!doctype html>
           </div>
         </div>
 
+        <div class="caps-section">
+          <div class="caps-section-head">
+            <div class="caps-section-title">Resolve 21 AI ops</div>
+            <div class="caps-section-hint">Local Resolve AI operations (audio classification, IntelliSearch, slate, motion-deblur, speech). These run on Resolve's GPU/AI engine and do <strong>not</strong> consume the Claude analysis token budget above — tracked here for invocations, time, and files created.</div>
+          </div>
+          <div id="resolveAiOpsBlock" class="caps-usage-block">
+            <div id="resolveAiOpsSummary" class="caps-section-hint">loading…</div>
+            <table id="resolveAiOpsTable" class="resolve-ai-ops-table" style="display:none; width:100%; border-collapse:collapse; margin-top:8px; font-size:12px;">
+              <thead><tr style="text-align:left; opacity:0.7;">
+                <th style="padding:4px 6px;">Op</th><th style="padding:4px 6px;">Runs</th>
+                <th style="padding:4px 6px;">OK</th><th style="padding:4px 6px;">Time</th>
+                <th style="padding:4px 6px;">Files</th><th style="padding:4px 6px;">Created</th>
+              </tr></thead>
+              <tbody id="resolveAiOpsRows"></tbody>
+            </table>
+          </div>
+        </div>
+
         <div class="caps-section">
           <div class="caps-section-head">
             <div class="caps-section-title">Safety</div>
@@ -7040,6 +7058,59 @@ HTML = r"""<!doctype html>
         </svg>`;
     }
 
+    // ─── Resolve 21 AI ops ledger (read-only) ───────────────────────
+    function fmtMs(ms) {
+      ms = ms || 0;
+      if (ms < 1000) return ms + 'ms';
+      const s = ms / 1000;
+      return s < 60 ? s.toFixed(1) + 's' : (s / 60).toFixed(1) + 'm';
+    }
+    function fmtBytes(n) {
+      n = n || 0;
+      if (!n) return '—';
+      const u = ['B', 'KB', 'MB', 'GB', 'TB'];
+      let i = 0; let v = n;
+      while (v >= 1024 && i < u.length - 1) { v /= 1024; i++; }
+      return v.toFixed(v < 10 && i > 0 ? 1 : 0) + ' ' + u[i];
+    }
+    async function refreshResolveAiOps() {
+      const summaryEl = $('resolveAiOpsSummary');
+      const tableEl = $('resolveAiOpsTable');
+      const rowsEl = $('resolveAiOpsRows');
+      if (!summaryEl || !tableEl || !rowsEl) return;
+      const data = await api('/api/resolve_ai_usage').catch(() => ({ success: false }));
+      if (!data || !data.success) {
+        summaryEl.textContent = 'ledger unavailable';
+        tableEl.style.display = 'none';
+        return;
+      }
+      const totals = (data.summary && data.summary.totals) || {};
+      const byOp = (data.summary && data.summary.by_op) || {};
+      const ops = Object.keys(byOp).sort();
+      if (!ops.length) {
+        summaryEl.textContent = 'No Resolve AI ops recorded yet for this project.';
+        tableEl.style.display = 'none';
+        return;
+      }
+      summaryEl.innerHTML = `<strong>${totals.runs || 0}</strong> runs · `
+        + `<strong>${totals.successes || 0}</strong> ok / ${totals.failures || 0} failed · `
+        + `${fmtMs(totals.wall_clock_ms)} total · `
+        + `<strong>${totals.files_created || 0}</strong> files (${fmtBytes(totals.bytes_created)}) created`;
+      rowsEl.innerHTML = ops.map(op => {
+        const b = byOp[op];
+        const isRender = b.op_class === 'render';
+        return `<tr style="border-top:1px solid rgba(255,255,255,0.06);">
+          <td style="padding:4px 6px;">${escapeHtml(op)}${isRender ? ' <span style="opacity:0.6;">(media)</span>' : ''}</td>
+          <td style="padding:4px 6px;">${b.runs}</td>
+          <td style="padding:4px 6px;">${b.successes}</td>
+          <td style="padding:4px 6px;">${fmtMs(b.wall_clock_ms)}</td>
+          <td style="padding:4px 6px;">${b.files_created || '—'}</td>
+          <td style="padding:4px 6px;">${b.bytes_created ? fmtBytes(b.bytes_created) : '—'}</td>
+        </tr>`;
+      }).join('');
+      tableEl.style.display = '';
+    }
+
     // ─── Caps inspector + refusals + reset ──────────────────────────
     async function inspectCapsFromUI() {
       const clipId = ($('capsInspectClipId')?.value || '').trim();
@@ -9916,6 +9987,7 @@ HTML = r"""<!doctype html>
     refreshCapsWidget().catch(() => {});
     refreshCapsHistory().catch(() => {});
     refreshCapsRefusals().catch(() => {});
+    refreshResolveAiOps().catch(() => {});
 
     // Caps inspector + reset
     $('capsInspectBtn')?.addEventListener('click', () => inspectCapsFromUI().catch(alertError));
@@ -13613,6 +13685,20 @@ class Handler(BaseHTTPRequestHandler):
             except Exception as exc:
                 self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
             return
+        if path == "/api/resolve_ai_usage":
+            # Ledger of Resolve-local 21.0 AI ops (read straight from this
+            # project's brain DB — no Resolve round-trip needed).
+            try:
+                from src.utils import resolve_ai_ledger as _ledger
+                root = self.state.project_root
+                self._json({
+                    "success": True,
+                    "summary": _ledger.get_summary(project_root=root),
+                    "recent": _ledger.get_usage(project_root=root, limit=50),
+                })
+            except Exception as exc:
+                self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
+            return
         if path.startswith("/api/timeline_thumbnail/"):
             rel = unquote(path[len("/api/timeline_thumbnail/"):])
             # Path is <slug>/<vNN.png>; constrain it to live under _soul/timeline_versions

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.29.0"
+VERSION = "2.30.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 341-tool granular server instead
 """
 
-VERSION = "2.29.0"
+VERSION = "2.30.0"
 
 import base64
 import os
@@ -639,6 +639,42 @@ def _destructive_versioning_provider() -> Optional[Tuple[Any, Any, str, Optional
 _destructive_hook.register_project_root_provider(_destructive_versioning_provider)
 
 
+# ─── Resolve 21 AI-ops ledger plumbing ────────────────────────────────────────
+
+import uuid as _ledger_uuid
+from src.utils import resolve_ai_ledger as _resolve_ai_ledger
+
+# One id per server process so the ledger / dashboard can scope "this session".
+_AI_LEDGER_SESSION_ID = _ledger_uuid.uuid4().hex
+
+
+def _ai_ledger_root() -> Optional[str]:
+    """Best-effort project_root for the AI-ops ledger. None disables recording."""
+    try:
+        provider = _destructive_versioning_provider()
+        return provider[2] if provider else None
+    except Exception:
+        return None
+
+
+def _clip_file_size(item: Any) -> Tuple[Optional[str], Optional[int]]:
+    """(file_path, size_bytes) for a MediaPoolItem, or (path|None, None)."""
+    try:
+        path = item.GetClipProperty("File Path")
+        if isinstance(path, str) and path and os.path.exists(path):
+            return path, os.path.getsize(path)
+        return (path if isinstance(path, str) and path else None), None
+    except Exception:
+        return None, None
+
+
+def _ai_ledger_timed(op: str, *, clip_id: Optional[str] = None):
+    """Ledger context manager bound to the current project_root + session."""
+    return _resolve_ai_ledger.timed(
+        _ai_ledger_root(), op, clip_id=clip_id, session_id=_AI_LEDGER_SESSION_ID
+    )
+
+
 def _destructive_preference_provider(key: str) -> Any:
     """Reader for C6 preferences out of the existing media-analysis prefs file."""
     try:
@@ -12427,10 +12463,17 @@ def project_settings(action: str, params: Optional[Dict[str, Any]] = None) -> Di
         blocked = _consume_confirm_token(action="project_settings.generate_speech", params=p)
         if blocked:
             return blocked
-        new_item = proj.GenerateSpeech(settings, timecode)
+        with _ai_ledger_timed("generate_speech") as _rec:
+            new_item = proj.GenerateSpeech(settings, timecode)
+            _rec.success = bool(new_item)
+            if new_item:
+                path, nbytes = _clip_file_size(new_item)
+                _rec.output_path = path
+                _rec.output_bytes = nbytes
         if not new_item:
             return {"success": False}
-        return {"success": True, "new": new_item.GetName(), "new_id": new_item.GetUniqueId()}
+        return {"success": True, "new": new_item.GetName(), "new_id": new_item.GetUniqueId(),
+                "output_path": _rec.output_path, "output_bytes": _rec.output_bytes}
     return _unknown(action, ["get_name","set_name","get_setting","set_setting","get_unique_id","get_presets","set_preset","refresh_luts","get_gallery","export_frame_as_still","load_burnin_preset","insert_audio","get_color_groups","add_color_group","delete_color_group","apply_fairlight_preset","generate_speech"])
 
 
@@ -13414,19 +13457,28 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         missing = _requires_method(f, "PerformAudioClassification", "21.0")
         if missing:
             return missing
-        return {"success": bool(f.PerformAudioClassification())}
+        with _ai_ledger_timed("perform_audio_classification") as _rec:
+            ok = bool(f.PerformAudioClassification())
+            _rec.success = ok
+        return {"success": ok}
     elif action == "clear_audio_classification":
         missing = _requires_method(f, "ClearAudioClassification", "21.0")
         if missing:
             return missing
-        return {"success": bool(f.ClearAudioClassification())}
+        with _ai_ledger_timed("clear_audio_classification") as _rec:
+            ok = bool(f.ClearAudioClassification())
+            _rec.success = ok
+        return {"success": ok}
     elif action == "analyze_for_intellisearch":
         missing = _requires_method(f, "AnalyzeForIntellisearch", "21.0")
         if missing:
             return missing
         identify_faces = bool(_first_param(p, "identify_faces", "identifyFaces", default=False))
         is_better_mode = bool(_first_param(p, "is_better_mode", "isBetterMode", default=False))
-        return {"success": bool(f.AnalyzeForIntellisearch(identify_faces, is_better_mode))}
+        with _ai_ledger_timed("analyze_for_intellisearch") as _rec:
+            ok = bool(f.AnalyzeForIntellisearch(identify_faces, is_better_mode))
+            _rec.success = ok
+        return {"success": ok}
     elif action == "analyze_for_slate":
         missing = _requires_method(f, "AnalyzeForSlate", "21.0")
         if missing:
@@ -13434,7 +13486,10 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         marker_color = _first_param(p, "marker_color", "markerColor", default="Blue")
         if marker_color not in _MARKER_COLORS:
             return _err(f"Invalid marker_color {marker_color!r}. Valid colors: {', '.join(_MARKER_COLORS)}")
-        return {"success": bool(f.AnalyzeForSlate(marker_color))}
+        with _ai_ledger_timed("analyze_for_slate") as _rec:
+            ok = bool(f.AnalyzeForSlate(marker_color))
+            _rec.success = ok
+        return {"success": ok}
     elif action == "remove_motion_blur":
         missing = _requires_method(f, "RemoveMotionBlur", "21.0")
         if missing:
@@ -13454,14 +13509,25 @@ def folder(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, An
         blocked = _consume_confirm_token(action="folder.remove_motion_blur", params=p)
         if blocked:
             return blocked
-        result = f.RemoveMotionBlur(deblur)
-        created = []
-        for pair in (result or []):
-            try:
-                orig, new = pair
-                created.append({"original": orig.GetName(), "new": new.GetName(), "new_id": new.GetUniqueId()})
-            except Exception:
-                continue
+        with _ai_ledger_timed("remove_motion_blur") as _rec:
+            result = f.RemoveMotionBlur(deblur)
+            _rec.success = bool(result)
+            created = []
+            total_bytes = 0
+            for pair in (result or []):
+                try:
+                    orig, new = pair
+                    path, nbytes = _clip_file_size(new)
+                    if nbytes:
+                        total_bytes += nbytes
+                    created.append({"original": orig.GetName(), "new": new.GetName(),
+                                    "new_id": new.GetUniqueId(), "output_path": path, "output_bytes": nbytes})
+                except Exception:
+                    continue
+            # Folder deblur creates many files; record the first path + summed bytes.
+            if created:
+                _rec.output_path = created[0].get("output_path")
+                _rec.output_bytes = total_bytes or None
         return {"success": bool(result), "created": created}
     return _unknown(action, ["get_clips","get_name","get_subfolders","is_stale","get_unique_id","export","transcribe_audio","clear_transcription","perform_audio_classification","clear_audio_classification","analyze_for_intellisearch","analyze_for_slate","remove_motion_blur"])
 
@@ -13701,19 +13767,28 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         missing = _requires_method(clip, "PerformAudioClassification", "21.0")
         if missing:
             return missing
-        return {"success": bool(clip.PerformAudioClassification())}
+        with _ai_ledger_timed("perform_audio_classification", clip_id=p.get("clip_id")) as _rec:
+            ok = bool(clip.PerformAudioClassification())
+            _rec.success = ok
+        return {"success": ok}
     elif action == "clear_audio_classification":
         missing = _requires_method(clip, "ClearAudioClassification", "21.0")
         if missing:
             return missing
-        return {"success": bool(clip.ClearAudioClassification())}
+        with _ai_ledger_timed("clear_audio_classification", clip_id=p.get("clip_id")) as _rec:
+            ok = bool(clip.ClearAudioClassification())
+            _rec.success = ok
+        return {"success": ok}
     elif action == "analyze_for_intellisearch":
         missing = _requires_method(clip, "AnalyzeForIntellisearch", "21.0")
         if missing:
             return missing
         identify_faces = bool(_first_param(p, "identify_faces", "identifyFaces", default=False))
         is_better_mode = bool(_first_param(p, "is_better_mode", "isBetterMode", default=False))
-        return {"success": bool(clip.AnalyzeForIntellisearch(identify_faces, is_better_mode))}
+        with _ai_ledger_timed("analyze_for_intellisearch", clip_id=p.get("clip_id")) as _rec:
+            ok = bool(clip.AnalyzeForIntellisearch(identify_faces, is_better_mode))
+            _rec.success = ok
+        return {"success": ok}
     elif action == "analyze_for_slate":
         missing = _requires_method(clip, "AnalyzeForSlate", "21.0")
         if missing:
@@ -13721,7 +13796,10 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         marker_color = _first_param(p, "marker_color", "markerColor", default="Blue")
         if marker_color not in _MARKER_COLORS:
             return _err(f"Invalid marker_color {marker_color!r}. Valid colors: {', '.join(_MARKER_COLORS)}")
-        return {"success": bool(clip.AnalyzeForSlate(marker_color))}
+        with _ai_ledger_timed("analyze_for_slate", clip_id=p.get("clip_id")) as _rec:
+            ok = bool(clip.AnalyzeForSlate(marker_color))
+            _rec.success = ok
+        return {"success": ok}
     elif action == "remove_motion_blur":
         missing = _requires_method(clip, "RemoveMotionBlur", "21.0")
         if missing:
@@ -13741,10 +13819,17 @@ def media_pool_item(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         blocked = _consume_confirm_token(action="media_pool_item.remove_motion_blur", params=p)
         if blocked:
             return blocked
-        new_clip = clip.RemoveMotionBlur(deblur)
+        with _ai_ledger_timed("remove_motion_blur", clip_id=p.get("clip_id")) as _rec:
+            new_clip = clip.RemoveMotionBlur(deblur)
+            _rec.success = bool(new_clip)
+            if new_clip:
+                path, nbytes = _clip_file_size(new_clip)
+                _rec.output_path = path
+                _rec.output_bytes = nbytes
         if not new_clip:
             return {"success": False}
-        return {"success": True, "new": new_clip.GetName(), "new_id": new_clip.GetUniqueId()}
+        return {"success": True, "new": new_clip.GetName(), "new_id": new_clip.GetUniqueId(),
+                "output_path": _rec.output_path, "output_bytes": _rec.output_bytes}
     elif action == "get_audio_mapping":
         return {"mapping": clip.GetAudioMapping()}
     elif action == "get_mark_in_out":
@@ -13893,6 +13978,7 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
       get_caps(clip_id?, job_id?) -> {preset, caps, presets_available, usage?} — effective caps + usage rollup (vision tokens consumed per scope, percent of budget).
       set_caps_preset(preset, overrides?) -> {success, preset, overrides} — preset is minimal | standard | generous | unlimited. Overrides is a dict of {field: int|"unlimited"} that wins over the preset.
       get_usage(scope?, scope_key?, clip_id?, job_id?) -> {scope, usage} — raw usage rollup for one scope (clip | job | day).
+      get_resolve_ai_usage(session_only?, op?, limit?) -> {summary, recent} — ledger of Resolve 21 local AI ops (audio classification, IntelliSearch, slate, motion-deblur, speech). Tracks invocations, wall-clock, and files/bytes created by the two media-creating ops. Separate from get_caps/get_usage (those meter Claude-side tokens; these ops don't spend them).
       resolve_output_root(analysis_root?, source_paths?) -> {project_root}
       plan(target, depth?, analysis_root?, transcription?, vision?, dry_run?) -> {clips, artifacts}
       analyze_file(path|file_path, dry_run?, session_only?, persist?) -> {clips, manifest}
@@ -14045,6 +14131,27 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         except Exception as exc:
             out["usage_error"] = f"{type(exc).__name__}: {exc}"
         return out
+    if action == "get_resolve_ai_usage":
+        # Ledger of Resolve-local 21.0 AI ops (audio classification, IntelliSearch,
+        # slate, motion-deblur, speech generation). Distinct from get_caps/get_usage,
+        # which meter Claude-side analysis tokens — these ops don't spend those.
+        try:
+            vctx = _destructive_versioning_provider()
+            if vctx is None:
+                return _err("No project context — open a Resolve project first")
+            _r, _proj, project_root, _name = vctx
+            session_only = bool(p.get("session_only", False))
+            session_id = _AI_LEDGER_SESSION_ID if session_only else None
+            limit = int(p.get("limit", 50))
+            return {
+                "success": True,
+                "session_id": _AI_LEDGER_SESSION_ID,
+                "scope": "session" if session_only else "project",
+                "summary": _resolve_ai_ledger.get_summary(project_root=project_root, session_id=session_id),
+                "recent": _resolve_ai_ledger.get_usage(project_root=project_root, session_id=session_id, op=p.get("op"), limit=limit),
+            }
+        except Exception as exc:
+            return _err(f"{type(exc).__name__}: {exc}")
     if action == "set_caps_preset":
         preset = (p.get("preset") or "").strip().lower()
         from src.utils import analysis_caps as _ac

package/src/utils/resolve_ai_ledger.py

@@ -0,0 +1,242 @@
+"""Resolve 21 AI-ops ledger.
+
+Records each Resolve-local AI scripting op (audio classification, IntelliSearch,
+slate analysis, motion-deblur, speech generation). These run on Resolve's own
+GPU/AI engine and do NOT consume the Claude-side analysis token budget tracked
+in `analysis_caps`, so they get their own ledger.
+
+The value of the ledger is mostly the **wall-clock + file/byte accounting** for
+the two media-creating ops (`remove_motion_blur`, `generate_speech`). For the
+bool-returning analysis ops, an invocation counter + duration is what is
+reliable (some may queue work asynchronously inside Resolve, so the recorded
+duration is the script-call duration, not necessarily the engine completion).
+
+Persistence reuses `timeline_brain_db` (table `resolve_ai_op_usage`, schema v7).
+Every write is best-effort: a ledger failure must never block or corrupt the
+underlying Resolve op.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+from src.utils import timeline_brain_db
+
+logger = logging.getLogger("resolve-mcp.resolve-ai-ledger")
+
+OP_CLASS_ANALYSIS = "analysis"
+OP_CLASS_RENDER = "render"  # produces a new media file
+
+# op name -> (op_class, extra_required or None). The op names match the
+# consolidated-server action names.
+OP_META: Dict[str, Dict[str, Optional[str]]] = {
+    "perform_audio_classification": {"op_class": OP_CLASS_ANALYSIS, "extra_required": None},
+    "clear_audio_classification": {"op_class": OP_CLASS_ANALYSIS, "extra_required": None},
+    "analyze_for_intellisearch": {"op_class": OP_CLASS_ANALYSIS, "extra_required": "AI IntelliSearch"},
+    "analyze_for_slate": {"op_class": OP_CLASS_ANALYSIS, "extra_required": "AI Slate ID"},
+    "remove_motion_blur": {"op_class": OP_CLASS_RENDER, "extra_required": None},
+    "generate_speech": {"op_class": OP_CLASS_RENDER, "extra_required": "AI Speech Generator"},
+}
+
+
+def op_meta(op: str) -> Dict[str, Optional[str]]:
+    return OP_META.get(op, {"op_class": OP_CLASS_ANALYSIS, "extra_required": None})
+
+
+def _iso(when: Optional[float] = None) -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(when if when is not None else time.time()))
+
+
+def _day_bucket(when: Optional[float] = None) -> str:
+    return time.strftime("%Y-%m-%d", time.gmtime(when if when is not None else time.time()))
+
+
+def record_op(
+    *,
+    project_root: str,
+    op: str,
+    clip_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    success: bool = False,
+    wall_clock_ms: int = 0,
+    output_path: Optional[str] = None,
+    output_bytes: Optional[int] = None,
+    error: Optional[str] = None,
+) -> Optional[int]:
+    """Persist one ledger row. Returns the row id, or None on any failure.
+
+    Best-effort: never raises. Callers run this after the Resolve op so a ledger
+    problem cannot affect the op itself.
+    """
+    if not project_root:
+        return None
+    meta = op_meta(op)
+    now = time.time()
+    try:
+        with timeline_brain_db.transaction(project_root) as txn:
+            cursor = txn.execute(
+                """
+                INSERT INTO resolve_ai_op_usage(
+                    op, op_class, clip_id, session_id, success, wall_clock_ms,
+                    output_path, output_bytes, extra_required, error,
+                    occurred_at, day_bucket
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    op, meta["op_class"], clip_id, session_id, 1 if success else 0,
+                    int(wall_clock_ms), output_path,
+                    int(output_bytes) if output_bytes is not None else None,
+                    meta["extra_required"], error,
+                    _iso(now), _day_bucket(now),
+                ),
+            )
+            return cursor.lastrowid
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("resolve_ai_ledger.record_op failed: %s", exc)
+        return None
+
+
+class timed:
+    """Context manager that times a Resolve AI op and records it on exit.
+
+    Usage:
+        with resolve_ai_ledger.timed(project_root, "analyze_for_slate", clip_id=cid) as rec:
+            ok = bool(clip.AnalyzeForSlate(color))
+            rec.success = ok
+        # row written automatically; exceptions are recorded then re-raised.
+
+    For media-creating ops, set rec.output_path / rec.output_bytes before exit.
+    All recording is best-effort and never masks the op's own exception.
+    """
+
+    def __init__(
+        self,
+        project_root: Optional[str],
+        op: str,
+        *,
+        clip_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> None:
+        self.project_root = project_root
+        self.op = op
+        self.clip_id = clip_id
+        self.session_id = session_id
+        self.success: bool = False
+        self.output_path: Optional[str] = None
+        self.output_bytes: Optional[int] = None
+        self.error: Optional[str] = None
+        self.row_id: Optional[int] = None
+        self._start: float = 0.0
+
+    def __enter__(self) -> "timed":
+        self._start = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        wall_clock_ms = int((time.time() - self._start) * 1000)
+        if exc is not None and self.error is None:
+            self.error = f"{exc_type.__name__}: {exc}" if exc_type else str(exc)
+        if self.project_root:
+            self.row_id = record_op(
+                project_root=self.project_root,
+                op=self.op,
+                clip_id=self.clip_id,
+                session_id=self.session_id,
+                success=self.success,
+                wall_clock_ms=wall_clock_ms,
+                output_path=self.output_path,
+                output_bytes=self.output_bytes,
+                error=self.error,
+            )
+        return False  # never suppress the op's own exception
+
+
+def get_usage(
+    *,
+    project_root: str,
+    session_id: Optional[str] = None,
+    op: Optional[str] = None,
+    limit: int = 100,
+) -> List[Dict[str, Any]]:
+    """Return recent ledger rows, newest first."""
+    if not project_root:
+        return []
+    clauses: List[str] = []
+    args: List[Any] = []
+    if session_id:
+        clauses.append("session_id = ?")
+        args.append(session_id)
+    if op:
+        clauses.append("op = ?")
+        args.append(op)
+    where = (" WHERE " + " AND ".join(clauses)) if clauses else ""
+    try:
+        conn = timeline_brain_db.connect(project_root)
+        rows = conn.execute(
+            f"""
+            SELECT op, op_class, clip_id, session_id, success, wall_clock_ms,
+                   output_path, output_bytes, extra_required, error, occurred_at
+            FROM resolve_ai_op_usage{where}
+            ORDER BY id DESC LIMIT ?
+            """,
+            (*args, int(limit)),
+        ).fetchall()
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("resolve_ai_ledger.get_usage failed: %s", exc)
+        return []
+    return [dict(r) for r in rows]
+
+
+def get_summary(*, project_root: str, session_id: Optional[str] = None) -> Dict[str, Any]:
+    """Aggregate ledger rows into per-op and overall totals.
+
+    Returns counts, successes, total wall-clock, and total files/bytes created
+    (the latter meaningful only for render-class ops).
+    """
+    empty = {"by_op": {}, "totals": {"runs": 0, "successes": 0, "failures": 0,
+                                      "wall_clock_ms": 0, "files_created": 0, "bytes_created": 0}}
+    if not project_root:
+        return empty
+    clause = " WHERE session_id = ?" if session_id else ""
+    args = (session_id,) if session_id else ()
+    try:
+        conn = timeline_brain_db.connect(project_root)
+        rows = conn.execute(
+            f"""
+            SELECT op, op_class, success, wall_clock_ms, output_path, output_bytes
+            FROM resolve_ai_op_usage{clause}
+            """,
+            args,
+        ).fetchall()
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("resolve_ai_ledger.get_summary failed: %s", exc)
+        return empty
+
+    by_op: Dict[str, Dict[str, Any]] = {}
+    totals = {"runs": 0, "successes": 0, "failures": 0, "wall_clock_ms": 0,
+              "files_created": 0, "bytes_created": 0}
+    for r in rows:
+        op = r["op"]
+        bucket = by_op.setdefault(op, {
+            "op_class": r["op_class"], "runs": 0, "successes": 0, "failures": 0,
+            "wall_clock_ms": 0, "files_created": 0, "bytes_created": 0,
+        })
+        bucket["runs"] += 1
+        totals["runs"] += 1
+        if r["success"]:
+            bucket["successes"] += 1
+            totals["successes"] += 1
+        else:
+            bucket["failures"] += 1
+            totals["failures"] += 1
+        bucket["wall_clock_ms"] += r["wall_clock_ms"] or 0
+        totals["wall_clock_ms"] += r["wall_clock_ms"] or 0
+        if r["output_path"]:
+            bucket["files_created"] += 1
+            totals["files_created"] += 1
+        if r["output_bytes"]:
+            bucket["bytes_created"] += r["output_bytes"]
+            totals["bytes_created"] += r["output_bytes"]
+    return {"by_op": by_op, "totals": totals}

package/src/utils/timeline_brain_db.py

@@ -29,7 +29,7 @@ from typing import Callable, Dict, Iterator, Optional, Tuple
 
 logger = logging.getLogger("resolve-mcp.timeline-brain-db")
 
-SCHEMA_VERSION = 6
+SCHEMA_VERSION = 7
 DB_FILENAME = "timeline_brain.sqlite"
 SOUL_DIRNAME = "_soul"
 
@@ -422,6 +422,48 @@ def _migrate_v6_caps_events(conn: sqlite3.Connection) -> None:
     )
 
 
+# ── v7 migration: resolve_ai_op_usage ledger for Resolve 21 GPU/AI ops ──────
+
+
+@register_migration(7)
+def _migrate_v7_resolve_ai_op_usage(conn: sqlite3.Connection) -> None:
+    """Ledger for Resolve-local AI ops (audio classification, IntelliSearch,
+    slate, motion-deblur, speech generation).
+
+    These run on Resolve's own GPU/AI engine and do NOT consume the Claude-side
+    analysis token budget tracked in `analysis_token_usage`, so they get their
+    own ledger. The value is the wall-clock + file/byte accounting for the two
+    media-creating ops (remove_motion_blur, generate_speech). `op_class` is
+    'analysis' (no media produced) or 'render' (new media file written).
+    """
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS resolve_ai_op_usage (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            op TEXT NOT NULL,
+            op_class TEXT NOT NULL DEFAULT 'analysis',
+            clip_id TEXT,
+            session_id TEXT,
+            success INTEGER NOT NULL DEFAULT 0,
+            wall_clock_ms INTEGER NOT NULL DEFAULT 0,
+            output_path TEXT,
+            output_bytes INTEGER,
+            extra_required TEXT,
+            error TEXT,
+            occurred_at TEXT NOT NULL,
+            day_bucket TEXT NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_resolve_ai_op_usage_op
+            ON resolve_ai_op_usage(op);
+        CREATE INDEX IF NOT EXISTS ix_resolve_ai_op_usage_session
+            ON resolve_ai_op_usage(session_id);
+        CREATE INDEX IF NOT EXISTS ix_resolve_ai_op_usage_day
+            ON resolve_ai_op_usage(day_bucket);
+        """
+    )
+
+
 @register_migration(5)
 def _migrate_v5_analysis_token_usage(conn: sqlite3.Connection) -> None:
     """Track real vendor token + frame upload usage so caps can enforce budgets.