@xtremestuff/dsh-plugin-resolve 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xtremestuff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# dsh-plugin-resolve
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) bundle that bridges
+**DaVinci Resolve** into DSH: it registers Resolve's MCP server through DSH's official
+mcp-client bridge, so every DSH agent can inspect and drive Resolve through ordinary,
+namespaced tools (`mcp__resolve__*`).
+
+DaVinci Resolve Studio **21.1** ships a native MCP server (`ResolveMCP`, stdio). This bundle
+registers that server automatically — and, when it is not available, falls back to the
+community [`davinci-resolve-mcp`](https://github.com/samuelgursky/davinci-resolve-mcp) server
+(37 compound / 390 granular tools over the official scripting API, Resolve 18.5+, free edition
+reachable via its in-app bridge).
+
+## What you get
+
+| Backend | Source | Requires | Tools |
+|---|---|---|---|
+| `native` (default when present) | `ResolveMCP` bundled with Resolve Studio 21.1+ | Resolve **Studio** 21.1+, External scripting = Local | `get_resolve_status`, `get_whats_new`, `search_scripting_api`, `get_scripting_api`, `get_scripting_docs`, `launch_resolve`, `run_script`, `run_script_unsafe` |
+| `community` (fallback) | `davinci-resolve-mcp` npm bootstrapper | Node.js (`npx`) + Resolve 18.5+ | 37 compound tools (projects, media pool, timeline editing, grading, Fusion, Fairlight, render, analysis) |
+
+With `mode: auto` (the default) the bundle picks the native server when its executable exists
+and falls back to the community server otherwise. If neither is available the plugin logs a
+warning and registers nothing — the rest of DSH boots normally.
+
+## Install
+
+Install `@xtremestuff/dsh-plugin-resolve` from the npm registry into your profile:
+
+```sh
+dsh plugin --profile <name> add @xtremestuff/dsh-plugin-resolve
+```
+
+(`<name>` is the profile to extend, e.g. `web` or `desktop`.) Equivalently, use the DSH
+Plugins page / `plugin_manager` tool (`install_bundle` with `@xtremestuff/dsh-plugin-resolve`),
+or run `pnpm add @xtremestuff/dsh-plugin-resolve` inside `~/.dsh/profiles/<name>`.
+
+The `dsh plugin` forwarder records the dependency and adds the bundle to the profile's
+`dsh.profile.bundles` layer list automatically. After installation the bundle is enabled;
+DSH reconciles the profile on the next start (or immediately in a live profile).
+
+Verify:
+
+```
+Plugins → @xtremestuff/dsh-plugin-resolve   (enabled)
+Settings → MCP servers                      (a "resolve" entry appears, registered by the plugin)
+```
+
+Then ask an agent:
+
+> Use the Resolve MCP to report whether Resolve is running and its version. Tell me the name
+> of the open project and how many timelines it contains. Do not change anything yet.
+
+### Local or development install
+
+To install from a checkout (e.g. while developing the bundle), pass the directory path to the
+same command:
+
+```sh
+dsh plugin --profile <name> add /path/to/dsh-plugin-resolve
+```
+
+DSH records it as a `link:` dependency; edits to the directory are picked up without
+re-publishing.
+
+## Usage
+
+There is nothing to invoke: once the bundle is enabled, Resolve's tools sit in every agent's
+tool list as `mcp__resolve__<tool>` and the agent picks them up whenever your task involves
+Resolve. Just have a project open in Resolve (or ask the agent to launch it) and talk.
+
+### Native backend (Resolve Studio 21.1+)
+
+The native server is a thin, deliberate surface: discover the scripting API, then act through
+`run_script`. Typical flow per task:
+
+1. **Status** — *"Is Resolve running, and which project is open?"*
+   (`mcp__resolve__get_resolve_status`; `mcp__resolve__launch_resolve` starts it if closed)
+2. **Discover** — *"Which scripting API calls exist for adding markers to a timeline?"*
+   (`mcp__resolve__search_scripting_api` / `mcp__resolve__get_scripting_api`)
+3. **Act** — the agent writes and runs a script against the live session
+   (`mcp__resolve__run_script`)
+
+Examples:
+
+> Add a blue marker at the start of every clip on the timeline named `Cut_v4`, then read back
+> the marker count.
+
+> Queue a ProRes 422 HQ render of the current timeline to `~/Movies/deliver` and report the job
+> id.
+
+> Rename every clip in the `Interviews` bin to `CAMERA_SCENE_TAKE` from its file metadata.
+
+### Community backend
+
+The compound server ships guarded workflow tools, so most tasks need no scripting at all — the
+agent calls one named tool, and destructive operations run through a plan → review → confirm
+gate:
+
+> List all projects and open the one called `My Film`.
+
+> Create a timeline called `Assembly Cut` from all clips in the current bin.
+
+> Probe this timeline for gaps, overlaps, and missing media, and list what needs fixing.
+
+> Build a ProRes 422 HQ render plan for this timeline, validate the settings, and queue the job.
+
+> Copy the review markers from the timeline to the selected clip and export a review report.
+
+### Working habits that pay off
+
+- **Name things explicitly** — "the timeline named `Cut_v4`", not "this timeline".
+- **Ask for a plan before execution** on anything destructive, and work on a **duplicated**
+  timeline until you trust the agent.
+- **Verify in Resolve** after write actions — a successful tool call should be followed by a
+  read-back check that the intended clips, ranges, or tracks actually changed.
+
+## Requirements
+
+- **Native backend:** DaVinci Resolve **Studio** 21.1+ (the native MCP server is Studio-only),
+  with `Preferences → System → General → External scripting` set to **Local**.
+  Default executable locations:
+
+  | OS | Path |
+  |---|---|
+  | macOS | `/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Applications/ResolveMCP` |
+  | Windows | `C:\Program Files\Blackmagic Design\DaVinci Resolve\ResolveMCP.exe` |
+  | Linux | `/opt/resolve/bin/ResolveMCP` |
+
+- **Community backend:** Node.js ≥ 20.9 on `PATH` (the bundle launches
+  `npx -y davinci-resolve-mcp`) and a Python 3.10+ environment the bootstrapper can set up
+  (it installs a managed copy under your user application-data directory on first run).
+
+## Configuration
+
+All options are optional row config on the `resolve-mcp` entry in
+[`cordis.patch.yml`](./cordis.patch.yml) (edit the installed copy, or overlay from your
+profile's own `cordis.patch.yml`):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `mode` | `auto` | `auto` (native, else community), `native`, or `community` |
+| `serverName` | `resolve` | Tool namespace: `mcp__<serverName>__<tool>`; must match `[A-Za-z0-9_-]{1,32}` |
+| `nativeCommand` | per-OS default | Path to the `ResolveMCP` executable |
+| `communityCommand` | `npx` | Bootstrapper executable (resolved against `PATH`) |
+| `communityArgs` | `['-y', 'davinci-resolve-mcp']` | Bootstrapper arguments |
+| `env` | — | Extra environment variables for the server process |
+| `cwd` | — | Working directory for the server process |
+| `toolCallTimeoutMs` | 60 000 | Per tool-call timeout |
+| `startupTimeoutMs` | — | Budget for connection + initial tool discovery |
+| `closeTimeoutMs` | 5 000 | Transport closure budget |
+
+Example — force the community server with a pinned package version:
+
+```yaml
+- id: resolve-mcp
+  name: '@xtremestuff/dsh-plugin-resolve'
+  config:
+    mode: community
+    communityArgs: ['-y', 'davinci-resolve-mcp@4.19.3']
+```
+
+## How it works
+
+1. The bundle's [`cordis.patch.yml`](./cordis.patch.yml) mounts the plugin in
+   [`lib/index.js`](./lib/index.js).
+2. The plugin picks the backend (native `ResolveMCP` or the community bootstrapper) and
+   registers its tools on the harness tool runtime, mirroring Blackmagic's own MCPB
+   distribution (`DaVinciResolve.mcpb`):
+   - **Native:** the tool catalog comes from a one-shot `--dump-tools` invocation at
+     activation (no persistent process); the server spawns lazily on the first tool
+     call, is killed after 5 minutes of idle, and respawns on demand.
+   - **Community:** the bootstrapper runs persistently and its tools are discovered over
+     a live MCP handshake at activation.
+3. Tools are registered as `mcp__resolve__<tool>` with per-call timeouts and cancellation
+   support.
+4. The registration is lifetime-scoped: disabling or uninstalling the bundle disposes the
+   transport and withdraws its tools.
+
+## Safety notes
+
+- `run_script` (native server) executes Python with the scripting API's privileges;
+  `run_script_unsafe` adds system access. Prefer the community server's guarded workflow tools
+  for destructive work — they implement plan → review → confirm gates and refuse
+  verified-destructive operations (e.g. `TimelineItem.CopyGrades`) until you acknowledge.
+- Treat project names, client names, and file paths as data leaving your machine when your LLM
+  is a cloud model.
+- Work on a duplicated timeline until you trust an agent with write access.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# dsh-plugin-resolve bundle patch.
+#
+# Mounts the Resolve bridge plugin. It registers DaVinci Resolve's MCP server
+# with DSH's MCP server manager (`ctx.mcpManager`) for this bundle's lifetime,
+# so Resolve's tools appear to DSH agents as `mcp__resolve__*`.
+#
+# Backend selection (config `mode`):
+#   auto      (default) native ResolveMCP when present, else the community server
+#   native            DaVinci Resolve Studio 21.1+ bundled `ResolveMCP` (stdio)
+#   community         `davinci-resolve-mcp` npm bootstrapper (stdio, 37 compound /
+#                     390 granular tools, Resolve 18.5+, free edition via bridge)
+#
+# Zero-config by default. Override any field by editing this row, e.g.:
+#
+#   config:
+#     mode: community
+#     serverName: resolve
+#     communityArgs: ['-y', 'davinci-resolve-mcp']
+
+- insert:
+    - id: resolve-mcp
+      name: dsh-plugin-resolve

package/icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4D6BFE"/>
+      <stop offset="1" stop-color="#7B2FF7"/>
+    </linearGradient>
+  </defs>
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="#101318"/>
+  <circle cx="32" cy="32" r="20" fill="none" stroke="url(#g)" stroke-width="4"/>
+  <path d="M28 23 L43 32 L28 41 Z" fill="url(#g)"/>
+</svg>

package/lib/index.js

@@ -0,0 +1,561 @@
+/**
+ * dsh-plugin-resolve — bridges DaVinci Resolve into DeepSeek Harness (DSH).
+ *
+ * This Cordis plugin registers DaVinci Resolve's MCP server with DSH's tool
+ * runtime, mirroring Blackmagic's own MCPB distribution for Claude
+ * (`DaVinciResolve.mcpb` shipped inside the Resolve app):
+ *
+ *  - Native backend (Resolve Studio 21.1+ `ResolveMCP`): the tool catalog is
+ *    obtained at boot with a one-shot `--dump-tools` invocation (no
+ *    persistent process). The real server is spawned lazily on the first
+ *    tool call, killed after an idle timeout, and respawned on demand.
+ *  - Community backend (`davinci-resolve-mcp` npm bootstrapper): no
+ *    `--dump-tools` support, so the server runs persistently and its tools
+ *    are discovered over a live MCP handshake at activation.
+ *
+ * Tools are registered on the harness tool registry as
+ * `mcp__resolve__<tool>` (e.g. `mcp__resolve__get_resolve_status`,
+ * `mcp__resolve__run_script`). The implementation is self-contained
+ * (node: builtins only), so a `link:` development install works without a
+ * node_modules next to the checkout and a registry install adds no
+ * transitive packages.
+ *
+ * The registration lives for this plugin's lifetime: disabling or
+ * uninstalling this bundle disposes the transport and withdraws its tools.
+ *
+ * Row config (all optional):
+ *   mode               'auto' | 'native' | 'community'   (default 'auto')
+ *   serverName         tool namespace                     (default 'resolve')
+ *   nativeCommand      ResolveMCP executable path         (default per platform)
+ *   communityCommand   bootstrapper executable            (default 'npx')
+ *   communityArgs      bootstrapper arguments             (default ['-y', 'davinci-resolve-mcp'])
+ *   env                extra environment for the server   (object of strings)
+ *   cwd                working directory for the server   (string)
+ *   toolCallTimeoutMs  per tool-call timeout              (number, ms)
+ *
+ * @module dsh-plugin-resolve
+ */
+
+import { spawn, spawnSync } from 'node:child_process'
+import { statSync } from 'node:fs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'dsh-plugin-resolve'
+
+/** Services required by this plugin (tool registration). */
+export const inject = ['tools']
+
+/** Default `ResolveMCP` executable locations shipped with Resolve Studio 21.1+. */
+const NATIVE_DEFAULTS = {
+  darwin: '/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Applications/ResolveMCP',
+  win32: 'C:\\Program Files\\Blackmagic Design\\DaVinci Resolve\\ResolveMCP.exe',
+  linux: '/opt/resolve/bin/ResolveMCP',
+}
+
+/** Default community-server launch: the npm bootstrapper over stdio. */
+const COMMUNITY_DEFAULT_COMMAND = 'npx'
+const COMMUNITY_DEFAULT_ARGS = ['-y', 'davinci-resolve-mcp']
+
+/** MCP `serverName` pattern enforced by DSH's tool naming. */
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/
+
+/** Budgets, aligned with Blackmagic's MCPB wrapper. */
+const DUMP_TIMEOUT_MS = 10_000
+const INIT_TIMEOUT_MS = 30_000
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000
+const DEFAULT_TOOL_CALL_TIMEOUT_MS = 60_000
+
+/**
+ * Resolve a bare executable name against `PATH`.
+ * @param {string} command - absolute/relative path or bare command name.
+ * @returns {string | undefined} the usable path, or undefined when not found.
+ */
+function resolveExecutable(command) {
+  if (command.includes('/') || command.includes('\\')) {
+    return isExecutable(command) ? command : undefined
+  }
+  const pathEnv = process.env.PATH ?? ''
+  for (const dir of pathEnv.split(':')) {
+    if (!dir) continue
+    const candidate = `${dir}/${command}`
+    if (isExecutable(candidate)) return candidate
+  }
+  return undefined
+}
+
+/**
+ * @param {string} path
+ * @returns {boolean} true when the path is an existing regular file.
+ */
+function isExecutable(path) {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Rewrite an MCP input schema into DSH's supported JSON-Schema subset.
+ * DSH rejects `type` arrays (e.g. `["integer","string"]` on the native
+ * server's thumbnail frame-offset/timecode params). A single-type array
+ * collapses to that type; a true union drops `type` so the parameter is
+ * left unconstrained for DSH while the MCP server validates it.
+ * @param {unknown} node
+ * @returns {unknown} a sanitized copy of the schema node.
+ */
+function sanitizeSchema(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return node
+  const out = { ...node }
+  if (Array.isArray(out.type)) {
+    const supported = out.type.filter((t) => typeof t === 'string')
+    if (supported.length === 1) out.type = supported[0]
+    else delete out.type
+  }
+  if (out.properties && typeof out.properties === 'object' && !Array.isArray(out.properties)) {
+    out.properties = Object.fromEntries(
+      Object.entries(out.properties).map(([key, value]) => [key, sanitizeSchema(value)]),
+    )
+  }
+  if (out.items !== undefined) out.items = sanitizeSchema(out.items)
+  return out
+}
+
+/**
+ * Pick the backend and its stdio launch spec for the configured mode.
+ * @param {object} config - resolved row config.
+ * @returns {{kind: 'native'|'community', command: string, args: string[]} | undefined}
+ */
+function pickBackend(config) {
+  const mode = config.mode ?? 'auto'
+  if (mode !== 'auto' && mode !== 'native' && mode !== 'community') {
+    throw new Error(`dsh-plugin-resolve: unknown mode "${mode}" (expected 'auto', 'native', or 'community')`)
+  }
+
+  if (mode === 'native' || mode === 'auto') {
+    const command = config.nativeCommand ?? NATIVE_DEFAULTS[process.platform]
+    const resolved = command ? resolveExecutable(command) : undefined
+    if (resolved) return { kind: 'native', command: resolved, args: [] }
+    if (mode === 'native') return undefined
+  }
+
+  if (mode === 'community' || mode === 'auto') {
+    const command = config.communityCommand ?? COMMUNITY_DEFAULT_COMMAND
+    const resolved = command ? resolveExecutable(command) : undefined
+    if (resolved) {
+      const args = Array.isArray(config.communityArgs) ? config.communityArgs : COMMUNITY_DEFAULT_ARGS
+      return { kind: 'community', command: resolved, args }
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Shared stdio JSON-RPC machinery for one server child process.
+ * Newline-delimited JSON-RPC over stdin/stdout; pending responses are
+ * tracked by id, and client lines may be queued until the child finishes
+ * its internal handshake.
+ */
+class StdioJsonRpc {
+  /**
+   * @param {object} opts
+   * @param {string} opts.command
+   * @param {string[]} opts.args
+   * @param {Record<string, string>} [opts.env]
+   * @param {string} [opts.cwd]
+   * @param {(message: string) => void} [opts.onStderr]
+   * @param {(code: number|null, signal: string) => void} [opts.onExit]
+   */
+  constructor(opts) {
+    this.child = spawn(opts.command, opts.args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: opts.env ? { ...process.env, ...opts.env } : process.env,
+      cwd: opts.cwd,
+    })
+    this.nextId = 1
+    /** @type {Map<number, {resolve: (v: any) => void, reject: (e: Error) => void}>} */
+    this.pending = new Map()
+    this.queued = []
+    this.buffer = ''
+    this.initialized = false
+    this.closed = false
+    this.child.on('exit', (code, signal) => {
+      this.#settleAll(`server exited (code=${code} signal=${signal})`)
+      if (opts.onExit) opts.onExit(code, signal)
+    })
+    this.child.on('error', (error) => {
+      this.#settleAll(`server process error: ${String(error)}`)
+    })
+    this.child.stdout.on('data', (chunk) => this.#onData(chunk))
+    if (opts.onStderr) this.child.stderr.on('data', (chunk) => opts.onStderr(String(chunk)))
+    else this.child.stderr.on('data', () => {}) // drain: a full stderr pipe deadlocks the server
+  }
+
+  /** @param {Buffer|String} chunk */
+  #onData(chunk) {
+    this.buffer += chunk.toString()
+    let newline
+    while ((newline = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, newline).trim()
+      this.buffer = this.buffer.slice(newline + 1)
+      if (!line) continue
+      let message
+      try {
+        message = JSON.parse(line)
+      } catch {
+        continue
+      }
+      if (message.id === '__wrapper_init__') {
+        this.initialized = true
+        this.#flushQueue()
+        continue
+      }
+      if (message.id !== undefined && this.pending.has(message.id)) {
+        const waiter = this.pending.get(message.id)
+        this.pending.delete(message.id)
+        if (message.error !== undefined) waiter.reject(new Error(message.error.message ?? 'MCP RPC error'))
+        else waiter.resolve(message.result)
+      }
+    }
+  }
+
+  /** Send a raw JSON-RPC line, queueing it until the child is initialized. */
+  sendLine(line) {
+    if (this.closed) return
+    if (this.initialized) this.child.stdin.write(line + '\n')
+    else this.queued.push(line)
+  }
+
+  /** Perform the internal handshake (Blackmagic `__wrapper_init__` convention). */
+  start() {
+    // Written directly (not queued): the init response is what unlocks the queue.
+    this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: '__wrapper_init__', method: 'initialize', params: {} }) + '\n')
+    this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n')
+  }
+
+  #flushQueue() {
+    const lines = this.queued
+    this.queued = []
+    for (const line of lines) this.child.stdin.write(line + '\n')
+  }
+
+  /**
+   * Send a JSON-RPC request and await its response.
+   * @param {string} method
+   * @param {object} [params]
+   * @param {number} [timeoutMs]
+   */
+  request(method, params, timeoutMs = 15_000) {
+    if (this.closed) return Promise.reject(new Error('MCP transport is closed'))
+    const id = this.nextId++
+    this.sendLine(JSON.stringify({ jsonrpc: '2.0', id, method, params: params ?? {} }))
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.pending.delete(id)) reject(new Error(`MCP request "${method}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      this.pending.set(id, {
+        resolve: (value) => { clearTimeout(timer); resolve(value) },
+        reject: (error) => { clearTimeout(timer); reject(error) },
+      })
+    })
+  }
+
+  /** @param {string} reason */
+  #settleAll(reason) {
+    if (this.closed && this.pending.size === 0) return
+    for (const [id, waiter] of this.pending) {
+      this.pending.delete(id)
+      waiter.reject(new Error(reason))
+    }
+  }
+
+  /** Kill the child process and settle every pending request. */
+  dispose() {
+    this.closed = true
+    this.#settleAll('MCP transport disposed')
+    try { this.child.stdin.end() } catch { /* already gone */ }
+    this.child.kill()
+  }
+}
+
+/**
+ * Lazy stdio server following Blackmagic's MCPB wrapper: the process is
+ * spawned on first use, killed after an idle timeout, and respawned on
+ * demand. Callers get a stable `callTool` surface.
+ */
+class LazyStdioServer {
+  /**
+   * @param {object} opts
+   * @param {string} opts.command
+   * @param {string[]} opts.args
+   * @param {Record<string, string>} [opts.env]
+   * @param {string} [opts.cwd]
+   * @param {(message: string) => void} [opts.onLog]
+   * @param {number} [opts.idleTimeoutMs]
+   * @param {number} [opts.initTimeoutMs]
+   */
+  constructor(opts) {
+    this.opts = opts
+    this.rpc = null
+    this.idleTimer = null
+    this.initTimer = null
+  }
+
+  #resetIdleTimer() {
+    if (this.idleTimer) clearTimeout(this.idleTimer)
+    this.idleTimer = setTimeout(() => {
+      if (this.rpc) {
+        this.opts.onLog?.('ResolveMCP: idle timeout, stopping server')
+        this.#stopChild()
+      }
+    }, this.opts.idleTimeoutMs ?? IDLE_TIMEOUT_MS)
+  }
+
+  #stopChild() {
+    this.rpc?.dispose()
+    this.rpc = null
+    if (this.idleTimer) { clearTimeout(this.idleTimer); this.idleTimer = null }
+    if (this.initTimer) { clearTimeout(this.initTimer); this.initTimer = null }
+  }
+
+  /** Spawn (if needed) and initialize the child, waiting for readiness. */
+  async #ensureStarted() {
+    if (this.rpc && this.rpc.initialized) {
+      this.#resetIdleTimer()
+      return
+    }
+    if (this.rpc && !this.rpc.initialized) {
+      // Already spawning; wait for the in-flight handshake.
+      this.#resetIdleTimer()
+      await new Promise((resolve) => {
+        const check = () => (this.rpc?.initialized ? resolve() : setTimeout(check, 50))
+        check()
+      })
+      return
+    }
+    const rpc = new StdioJsonRpc({
+      command: this.opts.command,
+      args: this.opts.args,
+      env: { ...(this.opts.env ?? {}), BMD_IS_MCPB: '1' },
+      cwd: this.opts.cwd,
+      onStderr: (message) => this.opts.onLog?.(message.trimEnd()),
+      onExit: () => {
+        if (this.rpc === rpc) {
+          this.rpc = null
+          if (this.initTimer) { clearTimeout(this.initTimer); this.initTimer = null }
+          if (this.idleTimer) { clearTimeout(this.idleTimer); this.idleTimer = null }
+        }
+      },
+    })
+    this.rpc = rpc
+    rpc.start()
+    this.#resetIdleTimer()
+    await new Promise((resolve, reject) => {
+      this.initTimer = setTimeout(() => {
+        this.initTimer = null
+        reject(new Error(`MCP server did not initialize within ${INIT_TIMEOUT_MS / 1000}s`))
+        this.#stopChild()
+      }, this.opts.initTimeoutMs ?? INIT_TIMEOUT_MS)
+      const check = () => {
+        if (this.rpc !== rpc) { reject(new Error('MCP server process died during startup')); return }
+        if (rpc.initialized) {
+          if (this.initTimer) { clearTimeout(this.initTimer); this.initTimer = null }
+          resolve()
+        } else setTimeout(check, 25)
+      }
+      check()
+    })
+  }
+
+  /**
+   * Call one tool, spawning the server lazily.
+   * @param {string} toolName
+   * @param {object} [args]
+   * @param {number} [timeoutMs]
+   * @param {AbortSignal} [signal]
+   */
+  async callTool(toolName, args, timeoutMs = DEFAULT_TOOL_CALL_TIMEOUT_MS, signal) {
+    if (signal?.aborted) throw new Error('aborted')
+    await this.#ensureStarted()
+    const rpc = this.rpc
+    if (!rpc) throw new Error('MCP server unavailable')
+    this.#resetIdleTimer()
+    const promise = rpc.request('tools/call', { name: toolName, arguments: args ?? {} }, timeoutMs)
+    if (signal) signal.addEventListener('abort', () => {
+      // JSON-RPC has no cancel; drop the waiter so the caller's signal wins.
+      for (const [id, waiter] of rpc.pending) {
+        rpc.pending.delete(id)
+        waiter.reject(new Error('aborted'))
+      }
+    }, { once: true })
+    return promise
+  }
+
+  /** Stop the child (if running) and release timers. */
+  dispose() {
+    this.#stopChild()
+  }
+}
+
+/**
+ * One-shot `--dump-tools` probe of the native ResolveMCP binary
+ * (Blackmagic MCPB convention). Returns the live tool definitions without
+ * keeping a server process alive.
+ * @param {string} command
+ * @returns {{tools: any[], instructions?: string} | undefined}
+ */
+function dumpTools(command) {
+  try {
+    const result = spawnSync(command, ['--dump-tools'], {
+      env: { ...process.env, BMD_IS_MCPB: '1' },
+      timeout: DUMP_TIMEOUT_MS,
+      encoding: 'utf-8',
+      windowsHide: true,
+    })
+    if (result.status === 0 && result.stdout) {
+      const dump = JSON.parse(result.stdout)
+      return { tools: dump.tools ?? [], instructions: dump.instructions }
+    }
+  } catch {
+    // fall through: the caller decides how to recover
+  }
+  return undefined
+}
+
+/**
+ * Extract the user-facing text from an MCP content array.
+ * @param {any} content
+ * @returns {string}
+ */
+function extractContentText(content) {
+  if (!Array.isArray(content)) return ''
+  return content
+    .map((part) => (part && part.type === 'text' && typeof part.text === 'string' ? part.text : ''))
+    .join('\n')
+}
+
+/**
+ * Register DaVinci Resolve's MCP server with DSH.
+ *
+ * Fails safe: when no backend is available (Resolve not installed, free
+ * edition without the community server, no `npx`) the plugin logs a warning
+ * and registers nothing, so the rest of the harness boots normally.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - plugin context.
+ * @param {object} [config] - resolved row config.
+ */
+export async function apply(ctx, config = {}) {
+  const log = ctx.logger
+
+  const serverName = String(config.serverName ?? 'resolve')
+  if (!SERVER_NAME_PATTERN.test(serverName)) {
+    throw new Error(`dsh-plugin-resolve: serverName "${serverName}" must match [A-Za-z0-9_-]{1,32}`)
+  }
+
+  const backend = pickBackend(config)
+  if (!backend) {
+    const hint =
+      config.mode === 'native'
+        ? 'Install DaVinci Resolve Studio 21.1+ (the native MCP server is Studio-only) and set config.nativeCommand if it lives elsewhere.'
+        : config.mode === 'community'
+          ? 'Install Node.js (npx) or set config.communityCommand to the davinci-resolve-mcp bootstrapper.'
+          : 'Install DaVinci Resolve Studio 21.1+ (native ResolveMCP) or Node.js (community server via npx).'
+    log.warn(`dsh-plugin-resolve: no Resolve MCP backend found on this machine. ${hint} No server registered.`)
+    return
+  }
+
+  const toolCallTimeoutMs = typeof config.toolCallTimeoutMs === 'number' ? config.toolCallTimeoutMs : DEFAULT_TOOL_CALL_TIMEOUT_MS
+  const env = config.env && typeof config.env === 'object' ? config.env : undefined
+  const cwd = typeof config.cwd === 'string' && config.cwd ? config.cwd : undefined
+  const onLog = (message) => log.debug(`resolve-mcp: ${message}`)
+
+  /** @type {LazyStdioServer|StdioJsonRpc|null} */
+  let server = null
+  /** @type {Array<{name: string}>} */
+  let tools = []
+
+  try {
+    if (backend.kind === 'native') {
+      // Blackmagic pattern: one-shot dump for the catalog, lazy process for calls.
+      const dump = dumpTools(backend.command)
+      if (dump && dump.tools.length > 0) {
+        tools = dump.tools
+        server = new LazyStdioServer({ command: backend.command, args: backend.args, env, cwd, onLog })
+      } else {
+        log.warn('dsh-plugin-resolve: --dump-tools unavailable; falling back to a persistent server for tool discovery.')
+      }
+    }
+
+    if (server === null) {
+      // Community backend (or native dump failure): persistent server + live discovery.
+      const rpc = new StdioJsonRpc({ command: backend.command, args: backend.args, env, cwd, onStderr: onLog })
+      rpc.start()
+      const initOk = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), INIT_TIMEOUT_MS)
+        const check = () => (rpc.initialized ? (clearTimeout(timer), resolve(true)) : setTimeout(check, 25))
+        check()
+      })
+      if (!initOk) throw new Error('MCP server did not initialize within 30s')
+      const listed = await rpc.request('tools/list', {}, INIT_TIMEOUT_MS)
+      tools = listed?.tools ?? []
+      server = rpc
+    }
+
+    /** @type {Array<() => void>} */
+    const disposers = []
+    for (const tool of tools) {
+      const publicName = `mcp__${serverName}__${tool.name}`
+      const definition = {
+        name: publicName,
+        description: tool.description ?? '',
+        parameters: sanitizeSchema(tool.inputSchema) ?? { type: 'object', properties: {} },
+        output: {
+          schema: {
+            type: 'object',
+            properties: {
+              content: { type: 'array', items: {} },
+              structuredContent: {},
+            },
+            required: ['content'],
+            additionalProperties: false,
+          },
+          render: (_args, value) => [{ type: 'text', text: extractContentText(value?.content) }],
+        },
+        execute: async (args, exec) => {
+          const result = await server.callTool(tool.name, args ?? {}, toolCallTimeoutMs, exec?.signal)
+          if (result?.isError === true) {
+            const text = Array.isArray(result.content)
+              ? result.content.map((part) => (part?.type === 'text' ? part.text : '')).join('\n')
+              : 'tool reported an error'
+            throw new Error(text || 'tool reported an error')
+          }
+          return {
+            content: result?.content ?? [],
+            ...(result?.structuredContent !== undefined ? { structuredContent: result.structuredContent } : {}),
+          }
+        },
+      }
+      disposers.push(ctx.tools.register(definition))
+    }
+
+    // Lifetime scope: uninstalling the bundle disposes the transport and
+    // withdraws every registered tool. `ctx.effect(execute, label)` runs
+    // `execute` at registration and collects whatever it *returns* as the
+    // teardown hook — so return the disposer from a thunk.
+    ctx.effect(() => () => {
+      for (const dispose of disposers.reverse()) {
+        try { dispose() } catch { /* already withdrawn */ }
+      }
+      server.dispose()
+    }, 'dsh-plugin-resolve.mcp')
+
+    log.info(
+      `dsh-plugin-resolve: registered ${tools.length} Resolve tools as mcp__${serverName}__* via ${backend.kind} backend ` +
+        `(${backend.command} ${backend.args.join(' ')}${backend.kind === 'native' ? ', lazy spawn on first call, idle kill after 5 min' : ''}).`,
+    )
+  } catch (error) {
+    server?.dispose()
+    log.warn(`dsh-plugin-resolve: could not start the Resolve MCP server (${backend.kind} backend at ${backend.command}): ${String(error)}. No tools registered.`)
+  }
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@xtremestuff/dsh-plugin-resolve",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "DSH bundle that bridges DaVinci Resolve into DSH: registers Resolve 21.1+ native ResolveMCP (stdio) or the davinci-resolve-mcp community server with DSH's mcp-client bridge, exposing Resolve's tools as first-class agent tools.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "bundle",
+    "plugin",
+    "davinci-resolve",
+    "mcp",
+    "video-editing",
+    "post-production"
+  ],
+  "license": "MIT",
+  "author": "xtremestuff",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xtremestuff/dsh-plugin-resolve.git"
+  },
+  "homepage": "https://github.com/xtremestuff/dsh-plugin-resolve#readme",
+  "bugs": {
+    "url": "https://github.com/xtremestuff/dsh-plugin-resolve/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.2.0-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.1.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}