davinci-resolve-mcp 2.29.0 → 2.31.0

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 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.31.0
+
+Adds the **AI Console** to the control panel — an interactive surface for the
+Resolve 21 local AI operations (Phase 2 of the staged AI-ops build: ledger →
+console → governance).
+
+A new **AI Console** tab runs the 21.0 ops against the current Media Pool folder
+or a specific clip:
+
+- **Capability matrix** — shows which AI methods this Resolve build exposes (green
+  = available, grey = absent on older builds) and which Extra each gated method
+  needs to actually run.
+- **Analysis** — Classify audio / Clear classification, IntelliSearch (with
+  identify-faces and Better-mode toggles), Analyze for slate (16-color marker
+  picker), Transcribe (with speaker-detection toggle), Clear transcription.
+- **Motion deblur** and **Speech generator** — full options forms; because both
+  create new media files they route through a confirmation modal (the same
+  confirm-token gate the MCP tools use) before running.
+- **Session** — Disable background tasks for the current Resolve session.
+- A live result readout, and the *Resolve 21 AI ops* ledger refreshes after each
+  run so file/byte totals stay current.
+
+Backend: a loopback-only `POST /api/resolve_ai/run` endpoint dispatches each op
+to the consolidated `folder` / `media_pool_item` / `project_settings` /
+`resolve_control` tools, relaying the confirm-token two-step. No new MCP tools or
+Resolve API surface — the console reuses the existing v2.29.0 actions. Validated
+live end-to-end against Resolve Studio 21.0.0.47.
+
+## 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.31.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.31.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.31.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -2378,6 +2378,51 @@ HTML = r"""<!doctype html>
       font-size: var(--text-xs);
       color: var(--text-muted);
     }
+    .ai-op-row {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--space-3);
+      grid-column: 1 / -1;
+      margin: var(--space-1) 0;
+    }
+    .ai-op-btn {
+      padding: 6px 14px;
+      border-radius: var(--radius-sm, 6px);
+      border: 1px solid var(--border, rgba(255,255,255,0.18));
+      background: var(--accent, #3b82f6);
+      color: #fff;
+      font-size: var(--text-sm, 13px);
+      cursor: pointer;
+    }
+    .ai-op-btn:hover { filter: brightness(1.08); }
+    .ai-op-btn:disabled { opacity: 0.4; cursor: not-allowed; filter: none; }
+    .ai-op-btn.ghost { background: transparent; color: var(--text, inherit); }
+    .ai-op-btn.danger { background: #b4452f; }
+    .ai-caps-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+      gap: var(--space-2);
+      margin-top: var(--space-2);
+    }
+    .ai-caps-item {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      font-size: var(--text-xs);
+    }
+    .ai-caps-dot { width: 9px; height: 9px; border-radius: 50%; flex: 0 0 auto; }
+    .ai-caps-dot.on { background: #34a853; }
+    .ai-caps-dot.off { background: rgba(255,255,255,0.25); }
+    .ai-caps-extra { opacity: 0.6; }
+    .ai-console-result {
+      white-space: pre-wrap;
+      font-family: var(--mono, ui-monospace, monospace);
+      max-height: 240px;
+      overflow: auto;
+    }
+    .ai-console-result.ok { color: var(--text, inherit); }
+    .ai-console-result.err { color: #e06c5a; }
     .caps-section-subtitle {
       font-size: var(--text-xs);
       color: var(--text-muted);
@@ -3777,6 +3822,7 @@ HTML = r"""<!doctype html>
           <button class="nav-dropdown-item" data-panel-target="analysis" data-subpage-target="review" role="menuitem"><span class="nav-dropdown-icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="14" rx="2"></rect><circle cx="9" cy="10" r="2"></circle><path d="m21 17-5-5-9 9"></path></svg></span>Review</button>
         </div>
       </div>
+      <button class="control-tab" data-panel-target="aiconsole">AI Console</button>
       <div class="control-nav-item">
         <button class="control-tab has-menu" data-panel-target="diagnostics">Setup <span class="tab-chevron" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"></path></svg></span></button>
         <div class="nav-dropdown" role="menu" aria-label="Diagnostic pages">
@@ -4119,6 +4165,94 @@ HTML = r"""<!doctype html>
     </section>
   </main>
 
+  <main id="panel-aiconsole" class="panel control-grid">
+    <section class="span-12">
+      <div class="section-top">
+        <div>
+          <h2>Resolve 21 AI Console</h2>
+          <p class="section-sub">Run Resolve's local AI operations on the current Media Pool folder or a specific clip. These run on Resolve's GPU/AI engine — the analysis and slate ops are safe and reversible; <strong>motion-deblur</strong> and <strong>speech generation</strong> create new media files and ask for confirmation first. Source media is never modified. Every run is recorded in the <em>Resolve 21 AI ops</em> ledger (Preferences → Caps + Safety).</p>
+        </div>
+      </div>
+
+      <div id="aiConsoleCaps" class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-hint">Checking which AI methods this Resolve build exposes…</div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Target</div>
+          <div class="caps-section-hint">Folder ops run on the current Media Pool folder in Resolve. Choose <em>Specific clip</em> and paste a clip id (from <code>media_pool.get_clips</code>) to target one clip.</div></div>
+        <div class="settings-grid">
+          <label class="checkbox-row"><input type="radio" name="aiTarget" value="folder" checked><span>Current folder</span></label>
+          <label class="checkbox-row"><input type="radio" name="aiTarget" value="clip"><span>Specific clip</span></label>
+          <label>Clip id <input id="aiClipId" type="text" placeholder="(clip UniqueId)"></label>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Analysis</div>
+          <div class="caps-section-hint">Safe, reversible. IntelliSearch and Slate require their AI Extras (Extras Download Manager).</div></div>
+        <div class="settings-grid">
+          <div class="ai-op-row"><button class="ai-op-btn" data-ai-op="perform_audio_classification">Classify audio</button>
+            <button class="ai-op-btn ghost" data-ai-op="clear_audio_classification">Clear classification</button></div>
+          <div class="ai-op-row">
+            <button class="ai-op-btn" data-ai-op="analyze_for_intellisearch">IntelliSearch</button>
+            <label class="checkbox-row"><input id="aiIdentifyFaces" type="checkbox"><span>Identify faces</span></label>
+            <label class="checkbox-row"><input id="aiBetterMode" type="checkbox"><span>Better mode</span></label>
+          </div>
+          <div class="ai-op-row">
+            <button class="ai-op-btn" data-ai-op="analyze_for_slate">Analyze for slate</button>
+            <label>Marker <select id="aiSlateColor"></select></label>
+          </div>
+          <div class="ai-op-row">
+            <button class="ai-op-btn" data-ai-op="transcribe_audio">Transcribe</button>
+            <label class="checkbox-row"><input id="aiSpeakerDetection" type="checkbox"><span>Speaker detection</span></label>
+            <button class="ai-op-btn ghost" data-ai-op="clear_transcription">Clear transcription</button>
+          </div>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Motion deblur</div>
+          <div class="caps-section-hint">Renders new deblurred media. Creates files; asks for confirmation. Leave fields blank for Resolve defaults.</div></div>
+        <div class="settings-grid">
+          <label>Format <input id="aiDeblurFormat" type="text" placeholder="mov"></label>
+          <label>Codec <input id="aiDeblurCodec" type="text" placeholder="ProRes422"></label>
+          <label class="checkbox-row"><input id="aiDeblurExtreme" type="checkbox"><span>Extreme mode</span></label>
+          <label class="checkbox-row"><input id="aiDeblurMarkInOut" type="checkbox"><span>Use mark in/out</span></label>
+          <label class="checkbox-row"><input id="aiDeblurSourceRes" type="checkbox"><span>Render at source res</span></label>
+          <div class="ai-op-row"><button class="ai-op-btn danger" data-ai-op="remove_motion_blur">Remove motion blur</button></div>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Speech generator</div>
+          <div class="caps-section-hint">AI text-to-speech. Requires the AI Speech Generator Extra. Creates a new audio item; asks for confirmation.</div></div>
+        <div class="settings-grid">
+          <label style="grid-column:1/-1;">Text <textarea id="aiSpeechText" rows="2" placeholder="Text to synthesize"></textarea></label>
+          <label>Voice model <input id="aiSpeechVoice" type="text" placeholder="Female 1"></label>
+          <label>Speed <input id="aiSpeechSpeed" type="number" placeholder="(default)"></label>
+          <label>Pitch <input id="aiSpeechPitch" type="number" placeholder="(default)"></label>
+          <label>Variation <input id="aiSpeechVariation" type="number" placeholder="(default)"></label>
+          <label class="checkbox-row"><input id="aiSpeechAddTimeline" type="checkbox"><span>Add to timeline</span></label>
+          <label>Timecode <input id="aiSpeechTimecode" type="text" placeholder="01:00:00:00"></label>
+          <label>Audio track <input id="aiSpeechTrack" type="number" placeholder="(default)"></label>
+          <div class="ai-op-row"><button class="ai-op-btn danger" data-ai-op="generate_speech">Generate speech</button></div>
+        </div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Session</div>
+          <div class="caps-section-hint">Quiet Resolve's background tasks for this session before heavy work. Resets on restart.</div></div>
+        <div class="ai-op-row"><button class="ai-op-btn ghost" data-ai-op="disable_background_tasks">Disable background tasks</button></div>
+      </div>
+
+      <div class="caps-section" style="margin-top:12px;">
+        <div class="caps-section-head"><div class="caps-section-title">Result</div></div>
+        <div id="aiConsoleResult" class="ai-console-result caps-section-hint">No op run yet.</div>
+      </div>
+    </section>
+  </main>
+
   <main id="panel-diagnostics" class="panel control-grid">
     <section class="span-12 subpage active" data-subpage-scope="diagnostics" data-subpage="resolve">
       <h2>Resolve</h2>
@@ -4370,6 +4504,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>
@@ -4694,6 +4846,7 @@ HTML = r"""<!doctype html>
     const PANEL_LABELS = {
       overview: 'Overview',
       analysis: 'Analysis',
+      aiconsole: 'AI Console',
       diagnostics: 'Setup',
       projects: 'Projects',
       docs: 'Docs',
@@ -4702,6 +4855,7 @@ HTML = r"""<!doctype html>
     const PANEL_ICONS = {
       overview: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7"></rect><rect x="14" y="3" width="7" height="7"></rect><rect x="14" y="14" width="7" height="7"></rect><rect x="3" y="14" width="7" height="7"></rect></svg>',
       analysis: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 3v18h18"></path><path d="m19 9-5 5-4-4-3 3"></path></svg>',
+      aiconsole: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 8V4H8"></path><rect x="4" y="12" width="16" height="8" rx="2"></rect><path d="M2 14h2"></path><path d="M20 14h2"></path><path d="M15 13v2"></path><path d="M9 13v2"></path></svg>',
       diagnostics: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l2.1-2.1a6 6 0 0 1-7.6 7.6l-4 4a2.1 2.1 0 0 1-3-3l4-4a6 6 0 0 1 7.6-7.6z"></path></svg>',
       projects: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 7h5l2 3h11v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path><path d="M7 7V5a2 2 0 0 1 2-2h3l2 2h3a2 2 0 0 1 2 2v3"></path></svg>',
       docs: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"></path><path d="M4 4.5A2.5 2.5 0 0 1 6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5z"></path></svg>',
@@ -4864,6 +5018,9 @@ HTML = r"""<!doctype html>
         syncPreferencesPanel();
         refreshSetupDefaults().catch(alertError);
       }
+      if (next === 'aiconsole') {
+        initAiConsole();
+      }
       if (next === 'docs' && subpage) {
         loadDoc(subpage, { updateHash: false }).catch(alertError);
       }
@@ -7040,6 +7197,217 @@ 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 = '';
+    }
+
+    // ─── Resolve 21 AI Console ──────────────────────────────────────
+    const AI_MARKER_COLORS = ['Blue','Cyan','Green','Yellow','Red','Pink','Purple',
+      'Fuchsia','Rose','Lavender','Sky','Mint','Lemon','Sand','Cocoa','Cream'];
+    const AI_OP_LABELS = {
+      perform_audio_classification: 'Classify audio',
+      clear_audio_classification: 'Clear classification',
+      analyze_for_intellisearch: 'IntelliSearch',
+      analyze_for_slate: 'Analyze for slate',
+      transcribe_audio: 'Transcribe',
+      clear_transcription: 'Clear transcription',
+      remove_motion_blur: 'Remove motion blur',
+      generate_speech: 'Generate speech',
+      disable_background_tasks: 'Disable background tasks',
+    };
+    // Which features gate which buttons (key in resolve.ai_features.features).
+    const AI_OP_FEATURE = {
+      perform_audio_classification: 'perform_audio_classification',
+      clear_audio_classification: 'clear_audio_classification',
+      analyze_for_intellisearch: 'analyze_for_intellisearch',
+      analyze_for_slate: 'analyze_for_slate',
+      remove_motion_blur: 'remove_motion_blur',
+      generate_speech: 'generate_speech',
+      disable_background_tasks: 'disable_background_tasks',
+    };
+    let _aiConsoleInit = false;
+
+    function renderAiConsole() {
+      const feats = (state.boot?.resolve?.ai_features) || {};
+      const features = feats.features || {};
+      const requiresExtra = feats.requires_extra || {};
+      const capsEl = $('aiConsoleCaps');
+      if (capsEl) {
+        if (state.boot?.resolve?.available !== true) {
+          capsEl.innerHTML = '<div class="caps-section-hint">Resolve is not connected. Open a project in DaVinci Resolve, then reload.</div>';
+        } else {
+          const items = Object.keys(AI_OP_LABELS)
+            .filter(op => op in AI_OP_FEATURE)
+            .map(op => {
+              const key = AI_OP_FEATURE[op];
+              const on = !!features[key];
+              const extra = requiresExtra[key];
+              return `<div class="ai-caps-item"><span class="ai-caps-dot ${on ? 'on' : 'off'}"></span>`
+                + `<span>${escapeHtml(AI_OP_LABELS[op])}</span>`
+                + (extra ? `<span class="ai-caps-extra">· needs ${escapeHtml(extra)}</span>` : '')
+                + `</div>`;
+            }).join('');
+          capsEl.innerHTML = `<div class="caps-section-head"><div class="caps-section-title">Available on this Resolve build</div>`
+            + `<div class="caps-section-hint">A grey dot means the method is absent (older Resolve). "needs …" means the method is present but requires that Extra to actually run — install via Extras Download Manager.</div></div>`
+            + `<div class="ai-caps-grid">${items}</div>`;
+        }
+      }
+      // Slate color dropdown (once).
+      const sel = $('aiSlateColor');
+      if (sel && !sel.options.length) {
+        sel.innerHTML = AI_MARKER_COLORS.map(c => `<option value="${c}">${c}</option>`).join('');
+      }
+    }
+
+    function aiTarget() {
+      const checked = document.querySelector('input[name="aiTarget"]:checked');
+      return checked ? checked.value : 'folder';
+    }
+
+    function aiBuildParams(op) {
+      const params = {};
+      if (op === 'analyze_for_intellisearch') {
+        params.identify_faces = !!$('aiIdentifyFaces')?.checked;
+        params.is_better_mode = !!$('aiBetterMode')?.checked;
+      } else if (op === 'analyze_for_slate') {
+        params.marker_color = $('aiSlateColor')?.value || 'Blue';
+      } else if (op === 'transcribe_audio') {
+        if ($('aiSpeakerDetection')?.checked) params.use_speaker_detection = true;
+      } else if (op === 'remove_motion_blur') {
+        const d = {};
+        const fmt = ($('aiDeblurFormat')?.value || '').trim(); if (fmt) d.Format = fmt;
+        const codec = ($('aiDeblurCodec')?.value || '').trim(); if (codec) d.Codec = codec;
+        if ($('aiDeblurExtreme')?.checked) d.UseExtremeMode = true;
+        if ($('aiDeblurMarkInOut')?.checked) d.UseMarkInMarkOut = true;
+        if ($('aiDeblurSourceRes')?.checked) d.RenderAtSourceRes = true;
+        params.deblur_option = d;
+      } else if (op === 'generate_speech') {
+        const text = ($('aiSpeechText')?.value || '').trim();
+        const settings = { TextInput: text };
+        const voice = ($('aiSpeechVoice')?.value || '').trim(); if (voice) settings.VoiceModel = voice;
+        const num = (id) => { const v = ($(id)?.value || '').trim(); return v === '' ? null : Number(v); };
+        const speed = num('aiSpeechSpeed'); if (speed != null) settings.Speed = speed;
+        const pitch = num('aiSpeechPitch'); if (pitch != null) settings.Pitch = pitch;
+        const variation = num('aiSpeechVariation'); if (variation != null) settings.Variation = variation;
+        if ($('aiSpeechAddTimeline')?.checked) {
+          settings.AddToTimeline = true;
+          const track = num('aiSpeechTrack'); if (track != null) settings.AudioTrack = track;
+        }
+        params.speech_generation_settings = settings;
+        const tc = ($('aiSpeechTimecode')?.value || '').trim(); if (tc) params.timecode = tc;
+      }
+      return params;
+    }
+
+    function aiShowResult(op, payload, isErr) {
+      const el = $('aiConsoleResult');
+      if (!el) return;
+      el.classList.toggle('err', !!isErr);
+      el.classList.toggle('ok', !isErr);
+      const head = `${AI_OP_LABELS[op] || op} — ${new Date().toLocaleTimeString()}\n`;
+      el.textContent = head + JSON.stringify(payload, null, 2);
+    }
+
+    async function runAiOp(op) {
+      const target = (op === 'generate_speech' || op === 'disable_background_tasks') ? 'folder' : aiTarget();
+      const params = aiBuildParams(op);
+      if (target === 'clip') {
+        const clipId = ($('aiClipId')?.value || '').trim();
+        if (!clipId) { aiShowResult(op, { error: 'Enter a clip id, or switch target to Current folder.' }, true); return; }
+        params.clip_id = clipId;
+      }
+      if (op === 'generate_speech' && !params.speech_generation_settings?.TextInput) {
+        aiShowResult(op, { error: 'Enter text to synthesize.' }, true); return;
+      }
+      const buttons = document.querySelectorAll('.ai-op-btn');
+      buttons.forEach(b => { b.disabled = true; });
+      try {
+        let res = await api('/api/resolve_ai/run', {
+          method: 'POST', body: JSON.stringify({ op, target, params }),
+        }).catch(err => ({ success: false, error: String(err && err.message || err) }));
+        // Confirm-token two-step for the media-creating ops.
+        if (res && res.status === 'confirmation_required') {
+          const preview = res.preview || {};
+          const proceed = await brandedConfirm({
+            kicker: 'Creates new media',
+            title: AI_OP_LABELS[op] || op,
+            body: preview.warning || 'This operation creates new media. Proceed?',
+            detail: JSON.stringify(preview, null, 2),
+            confirmLabel: 'Run it',
+            tone: 'danger',
+          });
+          if (!proceed) { aiShowResult(op, { cancelled: true }, false); return; }
+          const params2 = { ...params, confirm_token: res.confirm_token };
+          res = await api('/api/resolve_ai/run', {
+            method: 'POST', body: JSON.stringify({ op, target, params: params2 }),
+          }).catch(err => ({ success: false, error: String(err && err.message || err) }));
+        }
+        aiShowResult(op, res, !(res && res.success));
+        // Refresh the ledger widget so creators' file/byte totals update.
+        refreshResolveAiOps().catch(() => {});
+      } finally {
+        buttons.forEach(b => { b.disabled = false; });
+      }
+    }
+
+    function initAiConsole() {
+      if (_aiConsoleInit) { renderAiConsole(); return; }
+      _aiConsoleInit = true;
+      renderAiConsole();
+      document.querySelectorAll('#panel-aiconsole .ai-op-btn').forEach(btn => {
+        btn.addEventListener('click', () => runAiOp(btn.dataset.aiOp));
+      });
+    }
+
     // ─── Caps inspector + refusals + reset ──────────────────────────
     async function inspectCapsFromUI() {
       const clipId = ($('capsInspectClipId')?.value || '').trim();
@@ -9916,6 +10284,7 @@ HTML = r"""<!doctype html>
     refreshCapsWidget().catch(() => {});
     refreshCapsHistory().catch(() => {});
     refreshCapsRefusals().catch(() => {});
+    refreshResolveAiOps().catch(() => {});
 
     // Caps inspector + reset
     $('capsInspectBtn')?.addEventListener('click', () => inspectCapsFromUI().catch(alertError));
@@ -10711,6 +11080,58 @@ def _resolve_identity() -> Dict[str, Any]:
     }
 
 
+# ── Resolve 21 AI Console: op dispatch ──────────────────────────────────────
+# Folder/clip-level ops are routed to the consolidated `folder` /
+# `media_pool_item` tools; project/resolve-level ops to their tools. The
+# consolidated tools own the confirm-token gate for the two media-creators, so
+# this dispatcher just relays params (incl. confirm_token) and the result.
+
+_AI_CONSOLE_FOLDER_OPS = frozenset({
+    "perform_audio_classification", "clear_audio_classification",
+    "analyze_for_intellisearch", "analyze_for_slate", "remove_motion_blur",
+    "transcribe_audio", "clear_transcription",
+})
+
+
+def _run_resolve_ai_op(body: Dict[str, Any]) -> Dict[str, Any]:
+    """Dispatch one AI Console op to the right consolidated server tool.
+
+    body = {op, target?, params?}. target is 'folder' (current Media Pool
+    folder, default) or 'clip' (params.clip_id required). Returns the tool's
+    response verbatim — including a {status:'confirmation_required', confirm_token,
+    preview} shape for the gated media-creating ops.
+    """
+    op = (body.get("op") or "").strip()
+    target = (body.get("target") or "folder").strip()
+    params = dict(body.get("params") or {})
+    if not op:
+        return {"success": False, "error": "op is required"}
+    try:
+        from src.server import (
+            folder as _folder_tool,
+            media_pool_item as _mpi_tool,
+            project_settings as _ps_tool,
+            resolve_control as _rc_tool,
+        )
+    except Exception as exc:  # pragma: no cover - import guard
+        return {"success": False, "error": f"server tools unavailable: {exc}"}
+
+    if op == "disable_background_tasks":
+        return _rc_tool("disable_background_tasks_for_current_session", {})
+    if op == "generate_speech":
+        return _ps_tool("generate_speech", params)
+    if op not in _AI_CONSOLE_FOLDER_OPS:
+        return {"success": False, "error": f"unknown op {op!r}"}
+    if target == "clip":
+        clip_id = params.get("clip_id") or body.get("clip_id")
+        if not clip_id:
+            return {"success": False, "error": "clip target requires a clip_id"}
+        params["clip_id"] = clip_id
+        return _mpi_tool(op, params)
+    # default: operate on the current Media Pool folder
+    return _folder_tool(op, params)
+
+
 def _clip_props(clip: Any) -> Dict[str, Any]:
     props, _ = _safe_call(clip, "GetClipProperty", "")
     return props if isinstance(props, dict) else {}
@@ -13613,6 +14034,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
@@ -13867,6 +14302,21 @@ class Handler(BaseHTTPRequestHandler):
             except Exception as exc:
                 self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
             return
+        if path == "/api/resolve_ai/run":
+            # Run a Resolve 21 AI op from the panel. Loopback-only because it
+            # mutates Resolve (and the media-creators write new files). The
+            # confirm-token two-step is handled by the consolidated tool; the
+            # 'confirmation_required' shape is relayed to the panel as 200.
+            if not _request_is_loopback(self):
+                self._json({"success": False, "error": "Loopback only."}, HTTPStatus.FORBIDDEN)
+                return
+            try:
+                result = _run_resolve_ai_op(body)
+                ok = bool(result.get("success")) or result.get("status") == "confirmation_required"
+                self._json(result, 200 if ok else 400)
+            except Exception as exc:
+                self._json({"success": False, "error": f"{type(exc).__name__}: {exc}"})
+            return
         if path == "/api/caps/reset_day":
             if not _request_is_loopback(self):
                 self._json({"success": False, "error": "Loopback only."}, HTTPStatus.FORBIDDEN)

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.29.0"
+VERSION = "2.31.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.31.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.