mixdog 0.9.3 → 0.9.5

package/src/standalone/hook-bus/handlers.mjs

@@ -0,0 +1,481 @@
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import {
+  DEFAULT_AGENT_TIMEOUT_S,
+  DEFAULT_COMMAND_TIMEOUT_S,
+  DEFAULT_PROMPT_TIMEOUT_S,
+  EXIT2_BLOCK_EVENTS,
+  MAX_BUFFER_BYTES,
+  MESSAGE_DISPLAY_TIMEOUT_S,
+  PLAIN_STDOUT_CONTEXT_EVENTS,
+  TOOL_IF_EVENTS,
+  TOP_LEVEL_DECISION_EVENTS,
+  USER_PROMPT_TIMEOUT_S,
+  limitText,
+} from './constants.mjs';
+
+function globToRegExp(glob) {
+  let out = '^';
+  for (const ch of String(glob || '')) {
+    if (ch === '*') out += '.*';
+    else if (ch === '?') out += '.';
+    else out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`${out}$`);
+}
+
+function primaryArgFor(toolName, toolInput) {
+  const input = toolInput && typeof toolInput === 'object' ? toolInput : {};
+  if (toolName === 'Bash' || toolName === 'bash' || toolName === 'shell') return input.command ?? '';
+  if (input.file_path != null) return input.file_path;
+  if (input.path != null) return input.path;
+  if (input.command != null) return input.command;
+  if (input.file != null) return input.file;
+  return '';
+}
+
+export function ifConditionPasses(ifExpr, eventName, toolName, toolInput) {
+  if (ifExpr == null || String(ifExpr).trim() === '') return true;
+  if (!TOOL_IF_EVENTS.has(eventName)) return false;
+  const m = /^\s*([A-Za-z0-9_*]+)\s*\(([^)]*)\)\s*$/.exec(String(ifExpr));
+  if (!m) return true;
+  const [, tool, pattern] = m;
+  if (tool !== '*' && tool !== toolName) return false;
+  try {
+    return globToRegExp(pattern.trim()).test(String(primaryArgFor(toolName, toolInput)));
+  } catch {
+    return true;
+  }
+}
+
+function resolvePlaceholders(str, projectDir, pluginData, pluginRoot = null) {
+  if (typeof str !== 'string') return str;
+  const resolvedProject = projectDir || process.cwd();
+  const resolvedPluginRoot = pluginRoot || resolvedProject;
+  const resolvedPluginData = pluginData || resolvedProject;
+  return str
+    .replace(/\$\{CLAUDE_PROJECT_DIR\}/g, resolvedProject)
+    .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, resolvedPluginRoot)
+    .replace(/\$\{CLAUDE_PLUGIN_DATA\}/g, resolvedPluginData)
+    .replace(/\$\{MIXDOG_PROJECT_DIR\}/g, resolvedProject)
+    .replace(/\$\{MIXDOG_PLUGIN_ROOT\}/g, resolvedPluginRoot)
+    .replace(/\$\{MIXDOG_PLUGIN_DATA\}/g, resolvedPluginData);
+}
+
+export function handlerTimeoutS(handler, eventName) {
+  if (Number.isFinite(handler.timeout) && handler.timeout > 0) return handler.timeout;
+  if (handler.type === 'prompt') return DEFAULT_PROMPT_TIMEOUT_S;
+  if (handler.type === 'agent') return DEFAULT_AGENT_TIMEOUT_S;
+  if (handler.type === 'mcp_tool') return DEFAULT_COMMAND_TIMEOUT_S;
+  if (eventName === 'UserPromptSubmit') return USER_PROMPT_TIMEOUT_S;
+  if (eventName === 'MessageDisplay') return MESSAGE_DISPLAY_TIMEOUT_S;
+  return DEFAULT_COMMAND_TIMEOUT_S;
+}
+
+export function defaultShellKind() {
+  return process.platform === 'win32' ? 'powershell' : 'bash';
+}
+
+function commandSpawnSpec(handler, projectDir, pluginData) {
+  const command = resolvePlaceholders(handler.command, projectDir, pluginData, handler._pluginRoot || null);
+  if (Array.isArray(handler.args)) {
+    return {
+      command,
+      args: handler.args.map((a) => resolvePlaceholders(String(a), projectDir, pluginData, handler._pluginRoot || null)),
+      shellKind: 'exec',
+    };
+  }
+  const shellKind = handler.shell === 'powershell' || handler.shell === 'bash'
+    ? handler.shell
+    : defaultShellKind();
+  if (shellKind === 'powershell') {
+    return {
+      command: process.platform === 'win32' ? 'powershell.exe' : 'pwsh',
+      args: ['-NoProfile', '-NonInteractive', '-Command', command],
+      shellKind,
+    };
+  }
+  return {
+    command: process.platform === 'win32' ? 'bash.exe' : 'bash',
+    args: ['-lc', command],
+    shellKind,
+  };
+}
+
+function hookEnv(projectDir, pluginData, payload, pluginRoot = null) {
+  const resolvedProject = projectDir || process.cwd();
+  const resolvedPluginRoot = pluginRoot || resolvedProject;
+  const resolvedPluginData = pluginData || resolvedProject;
+  const env = {
+    ...process.env,
+    MIXDOG_PROJECT_DIR: resolvedProject,
+    MIXDOG_PLUGIN_ROOT: resolvedPluginRoot,
+    MIXDOG_PLUGIN_DATA: resolvedPluginData,
+    CLAUDE_PROJECT_DIR: resolvedProject,
+    CLAUDE_PLUGIN_ROOT: resolvedPluginRoot,
+    CLAUDE_PLUGIN_DATA: resolvedPluginData,
+  };
+  const effortLevel = payload?.effort?.level || payload?.effort;
+  if (effortLevel) env.CLAUDE_EFFORT = String(effortLevel);
+  return env;
+}
+
+export function runCommandHandler(handler, payload, eventName, pluginData, onSpawnError = null, onRewake = null) {
+  const projectDir = payload.cwd || process.cwd();
+  const effectivePluginData = handler._pluginData || pluginData || null;
+  const stdin = JSON.stringify(payload);
+  const timeoutMs = Math.round(handlerTimeoutS(handler, eventName) * 1000);
+  const spec = commandSpawnSpec(handler, projectDir, effectivePluginData);
+  const baseOpts = {
+    cwd: existsSync(projectDir) ? projectDir : undefined,
+    env: hookEnv(projectDir, effectivePluginData, payload, handler._pluginRoot || null),
+    windowsHide: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  };
+
+  if (handler.asyncRewake === true) {
+    try {
+      const child = spawn(spec.command, spec.args, {
+        ...baseOpts,
+      });
+      let bgStdout = '';
+      let bgStderr = '';
+      let bgStdoutBytes = 0;
+      let bgStderrBytes = 0;
+      let killed = false;
+      child.stdout?.on('data', (chunk) => {
+        bgStdoutBytes += chunk.length;
+        if (bgStdoutBytes <= MAX_BUFFER_BYTES) bgStdout += chunk.toString('utf8');
+      });
+      child.stderr?.on('data', (chunk) => {
+        bgStderrBytes += chunk.length;
+        if (bgStderrBytes <= MAX_BUFFER_BYTES) bgStderr += chunk.toString('utf8');
+      });
+      const killTimer = setTimeout(() => {
+        killed = true;
+        try { child.stdout?.removeAllListeners('data'); } catch {}
+        try { child.stderr?.removeAllListeners('data'); } catch {}
+        try { child.kill('SIGTERM'); } catch {}
+      }, timeoutMs);
+      killTimer.unref?.();
+      child.on('error', (error) => {
+        clearTimeout(killTimer);
+        if (typeof onSpawnError === 'function') onSpawnError(error);
+      });
+      child.on('close', (code) => {
+        clearTimeout(killTimer);
+        try {
+          if (!killed && code === 2 && typeof onRewake === 'function') {
+            const text = (bgStderr || '').trim() || (bgStdout || '').trim();
+            onRewake({ eventName, payload, text });
+          }
+        } catch {}
+      });
+      child.stdin?.end(stdin);
+      return Promise.resolve({ exitCode: 0, stdout: '', stderr: '', async: true });
+    } catch (error) {
+      return Promise.resolve({
+        exitCode: -1,
+        stdout: '',
+        stderr: error?.message || String(error),
+        timedOut: false,
+        spawnError: error,
+      });
+    }
+  }
+
+  if (handler.async === true) {
+    try {
+      const child = spawn(spec.command, spec.args, {
+        ...baseOpts,
+        detached: true,
+        stdio: ['pipe', 'ignore', 'ignore'],
+      });
+      child.on('error', (error) => {
+        if (typeof onSpawnError === 'function') onSpawnError(error);
+      });
+      child.stdin?.end(stdin);
+      child.unref?.();
+      return Promise.resolve({ exitCode: 0, stdout: '', stderr: '', async: true });
+    } catch (error) {
+      return Promise.resolve({
+        exitCode: -1,
+        stdout: '',
+        stderr: error?.message || String(error),
+        timedOut: false,
+        spawnError: error,
+      });
+    }
+  }
+
+  return new Promise((resolveRun) => {
+    let child;
+    let settled = false;
+    let stdout = '';
+    let stderr = '';
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let timedOut = false;
+    let timer = null;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolveRun(result);
+    };
+    try {
+      child = spawn(spec.command, spec.args, baseOpts);
+    } catch (error) {
+      finish({
+        exitCode: -1,
+        stdout: '',
+        stderr: error?.message || String(error),
+        timedOut: false,
+        spawnError: error,
+      });
+      return;
+    }
+    timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGTERM'); } catch {}
+      finish({
+        exitCode: -1,
+        stdout,
+        stderr: stderr || `hook command timed out after ${timeoutMs}ms`,
+        timedOut,
+        spawnError: null,
+      });
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdout?.on('data', (chunk) => {
+      stdoutBytes += chunk.length;
+      if (stdoutBytes <= MAX_BUFFER_BYTES) stdout += chunk.toString('utf8');
+    });
+    child.stderr?.on('data', (chunk) => {
+      stderrBytes += chunk.length;
+      if (stderrBytes <= MAX_BUFFER_BYTES) stderr += chunk.toString('utf8');
+    });
+    child.on('error', (error) => {
+      finish({
+        exitCode: -1,
+        stdout,
+        stderr: stderr || error?.message || String(error),
+        timedOut: false,
+        spawnError: error,
+      });
+    });
+    child.on('close', (code) => {
+      finish({
+        exitCode: timedOut ? -1 : (typeof code === 'number' ? code : 0),
+        stdout,
+        stderr,
+        timedOut,
+        spawnError: null,
+      });
+    });
+    try {
+      child.stdin?.end(stdin);
+    } catch {}
+  });
+}
+
+function resolveHeaderValue(value, allowed) {
+  if (typeof value !== 'string') return String(value ?? '');
+  return value.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (_m, braced, bare) => {
+    const name = braced || bare;
+    return allowed.has(name) ? (process.env[name] || '') : '';
+  });
+}
+
+export async function runHttpHandler(handler, payload, eventName) {
+  if (typeof fetch !== 'function') {
+    return { exitCode: -1, stdout: '', stderr: 'fetch is not available', timedOut: false, spawnError: new Error('fetch is not available') };
+  }
+  const timeoutMs = Math.round(handlerTimeoutS(handler, eventName) * 1000);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  try {
+    const allowed = new Set(Array.isArray(handler.allowedEnvVars) ? handler.allowedEnvVars.map(String) : []);
+    const headers = { 'Content-Type': 'application/json' };
+    if (handler.headers && typeof handler.headers === 'object' && !Array.isArray(handler.headers)) {
+      for (const [key, value] of Object.entries(handler.headers)) {
+        headers[key] = resolveHeaderValue(value, allowed);
+      }
+    }
+    const response = await fetch(handler.url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      return { exitCode: 1, stdout: text, stderr: `HTTP ${response.status} ${response.statusText}`.trim(), timedOut: false, spawnError: null };
+    }
+    return { exitCode: 0, stdout: text, stderr: '', timedOut: false, spawnError: null };
+  } catch (error) {
+    const aborted = error?.name === 'AbortError';
+    return {
+      exitCode: -1,
+      stdout: '',
+      stderr: aborted ? `HTTP hook timed out: ${handler.url}` : (error?.message || String(error)),
+      timedOut: aborted,
+      spawnError: aborted ? null : error,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function runMcpToolHandler(handler, payload, eventName, mcpToolRunner) {
+  const timeoutMs = Math.round(handlerTimeoutS(handler, eventName) * 1000);
+  let name = String(handler.tool || '').trim();
+  if (handler.server && !name.startsWith('mcp__')) {
+    name = `mcp__${String(handler.server).trim()}__${name}`;
+  }
+  if (!name) {
+    return { exitCode: -1, stdout: '', stderr: 'mcp_tool handler missing tool name', timedOut: false, spawnError: null };
+  }
+  let timer = null;
+  try {
+    const runPromise = Promise.resolve(mcpToolRunner({ name, args: payload }));
+    const text = await Promise.race([
+      runPromise,
+      new Promise((_r, reject) => {
+        timer = setTimeout(() => reject(new Error(`mcp_tool hook timed out: ${name}`)), timeoutMs);
+        // No unref: this timer must keep the event loop alive so the race can
+        // settle even when the runner promise never resolves. Cleared in finally.
+      }),
+    ]);
+    return { exitCode: 0, stdout: limitText(String(text ?? '')), stderr: '', timedOut: false, spawnError: null };
+  } catch (error) {
+    const timedOut = /timed out/i.test(error?.message || '');
+    return { exitCode: -1, stdout: '', stderr: error?.message || String(error), timedOut, spawnError: null };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export async function runPromptHandler(handler, payload, eventName, promptRunner) {
+  const timeoutMs = Math.round(handlerTimeoutS(handler, eventName) * 1000);
+  const prompt = String(handler.prompt || '');
+  if (!prompt) {
+    return { exitCode: -1, stdout: '', stderr: 'prompt handler missing prompt', timedOut: false, spawnError: null };
+  }
+  let timer = null;
+  try {
+    const runPromise = Promise.resolve(promptRunner({ prompt, payload, timeoutMs }));
+    const text = await Promise.race([
+      runPromise,
+      new Promise((_r, reject) => {
+        timer = setTimeout(() => reject(new Error(`prompt hook timed out: ${eventName}`)), timeoutMs);
+        // No unref: this timer must keep the event loop alive so the race can
+        // settle even when the runner promise never resolves. Cleared in finally.
+      }),
+    ]);
+    const raw = String(text ?? '').trim();
+    const deny = (reason) => ({ exitCode: 2, stdout: '', stderr: reason, timedOut: false, spawnError: null });
+    const allow = () => ({ exitCode: 0, stdout: '', stderr: '', timedOut: false, spawnError: null });
+    let verdict = null;
+    try {
+      verdict = JSON.parse(raw);
+    } catch {
+      verdict = undefined;
+    }
+    if (verdict && typeof verdict === 'object') {
+      if (verdict.ok === false) return deny(String(verdict.reason || `blocked by ${eventName} prompt hook`));
+      return allow();
+    }
+    // plain-text response
+    const lowered = raw.toLowerCase();
+    if (!raw || ['yes', 'true', 'allow', 'ok'].includes(lowered)) return allow();
+    if (['no', 'false', 'deny', 'block'].includes(lowered)) return deny(raw || `blocked by ${eventName} prompt hook`);
+    return allow();
+  } catch (error) {
+    const timedOut = /timed out/i.test(error?.message || '');
+    return { exitCode: -1, stdout: '', stderr: error?.message || String(error), timedOut, spawnError: null };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export function parseHandlerOutput(run, eventName) {
+  const out = {
+    block: false,
+    reason: null,
+    permissionDecision: null,
+    updatedInput: null,
+    updatedToolOutput: null,
+    additionalContext: null,
+    systemMessage: null,
+    suppressOutput: false,
+    continueFlag: undefined,
+    askReason: null,
+  };
+  if (run.timedOut || run.spawnError || run.async) return out;
+  if (run.exitCode === 2) {
+    if (EXIT2_BLOCK_EVENTS.has(eventName)) {
+      out.block = true;
+      out.reason = limitText((run.stderr || '').trim()) || `blocked by ${eventName} hook`;
+    }
+    return out;
+  }
+  if (run.exitCode !== 0) return out;
+  const rawText = (run.stdout || '').trim();
+  if (!rawText) return out;
+  if (!(rawText.startsWith('{') || rawText.startsWith('['))) {
+    if (PLAIN_STDOUT_CONTEXT_EVENTS.has(eventName)) out.additionalContext = limitText(rawText);
+    return out;
+  }
+  try {
+    const json = JSON.parse(rawText);
+    if (!json || typeof json !== 'object' || Array.isArray(json)) return out;
+    if (json.continue === false) {
+      out.continueFlag = false;
+      out.block = true;
+      out.reason = limitText(json.stopReason || json.reason || `stopped by ${eventName} hook`);
+    }
+    if (json.decision === 'block' && TOP_LEVEL_DECISION_EVENTS.has(eventName)) {
+      out.block = true;
+      out.reason = limitText(json.reason || out.reason || `blocked by ${eventName} hook`);
+    }
+    if (json.suppressOutput) out.suppressOutput = true;
+    if (typeof json.systemMessage === 'string') out.systemMessage = limitText(json.systemMessage);
+    if (typeof json.additionalContext === 'string') out.additionalContext = limitText(json.additionalContext);
+
+    const hso = json.hookSpecificOutput;
+    const hsoMatches = hso && typeof hso === 'object'
+      && (!hso.hookEventName || hso.hookEventName === eventName);
+    if (hsoMatches) {
+      if (typeof hso.additionalContext === 'string') out.additionalContext = limitText(hso.additionalContext);
+      if (hso.updatedInput && typeof hso.updatedInput === 'object' && !Array.isArray(hso.updatedInput)) {
+        out.updatedInput = hso.updatedInput;
+      }
+      if (hso.updatedToolOutput != null) out.updatedToolOutput = hso.updatedToolOutput;
+      if (hso.permissionDecision) out.permissionDecision = String(hso.permissionDecision).toLowerCase();
+      if (hso.permissionDecisionReason) out.reason = out.reason || limitText(hso.permissionDecisionReason);
+      if (eventName === 'PermissionRequest' && hso.decision && typeof hso.decision === 'object') {
+        const behavior = String(hso.decision.behavior || '').toLowerCase();
+        if (behavior === 'deny') {
+          out.block = true;
+          out.reason = out.reason || limitText(hso.decision.reason || `denied by ${eventName} hook`);
+        }
+        if (hso.decision.updatedInput && typeof hso.decision.updatedInput === 'object' && !Array.isArray(hso.decision.updatedInput)) {
+          out.updatedInput = hso.decision.updatedInput;
+        }
+      }
+    }
+    if (eventName === 'PreToolUse') {
+      if (out.permissionDecision === 'deny') {
+        out.block = true;
+        out.reason = out.reason || `denied by ${eventName} hook`;
+      } else if (out.permissionDecision === 'ask') {
+        out.askReason = out.reason || `ask requested by ${eventName} hook`;
+      }
+    }
+  } catch {
+    if (PLAIN_STDOUT_CONTEXT_EVENTS.has(eventName)) out.additionalContext = limitText(rawText);
+  }
+  return out;
+}

package/src/standalone/hook-bus/payload.mjs

@@ -0,0 +1,31 @@
+export function compactValue(value) {
+  if (value == null) return value;
+  if (typeof value === 'string') return value.length > 180 ? `${value.slice(0, 180)}...` : value;
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.slice(0, 8).map(compactValue);
+  if (typeof value === 'object') {
+    const out = {};
+    for (const [key, val] of Object.entries(value).slice(0, 12)) {
+      if (/token|secret|key|password/i.test(key)) {
+        out[key] = '<redacted>';
+      } else {
+        out[key] = compactValue(val);
+      }
+    }
+    return out;
+  }
+  return String(value);
+}
+
+export function summarizePayload(payload = {}) {
+  if (!payload || typeof payload !== 'object') return String(payload ?? '');
+  const parts = [];
+  if (payload.sessionId || payload.session_id) parts.push(`session=${payload.sessionId || payload.session_id}`);
+  if (payload.name || payload.tool_name) parts.push(`name=${payload.name || payload.tool_name}`);
+  if (payload.provider || payload.model) parts.push([payload.provider, payload.model].filter(Boolean).join('/'));
+  if (payload.prompt) parts.push(`prompt=${String(payload.prompt).slice(0, 60).replace(/\s+/g, ' ')}`);
+  if (payload.reason) parts.push(`reason=${String(payload.reason).slice(0, 120)}`);
+  if (payload.error) parts.push(`error=${String(payload.error).slice(0, 120)}`);
+  if (payload.elapsedMs != null) parts.push(`${payload.elapsedMs}ms`);
+  return parts.join(' · ');
+}

package/src/standalone/hook-bus/rules.mjs

@@ -0,0 +1,77 @@
+import { compactValue } from './payload.mjs';
+import { defaultShellKind } from './handlers.mjs';
+
+export function matchesList(pattern, value) {
+  if (pattern == null || pattern === '*' || pattern === 'all') return true;
+  const items = Array.isArray(pattern) ? pattern : [pattern];
+  return items.some((item) => {
+    const text = String(item || '').trim();
+    if (!text || text === '*' || text === 'all') return true;
+    if (text.endsWith('*')) return String(value || '').startsWith(text.slice(0, -1));
+    return text === String(value || '');
+  });
+}
+
+export function ruleMatches(rule, input) {
+  if (!rule || typeof rule !== 'object' || rule.enabled === false) return false;
+  const toolPattern = rule.tool ?? rule.name ?? rule.tools;
+  if (!matchesList(toolPattern, input.name)) return false;
+  if (rule.cwd && !String(input.cwd || '').includes(String(rule.cwd))) return false;
+  const match = rule.match ?? rule.contains;
+  if (match != null) {
+    const haystack = JSON.stringify({ args: input.args ?? null, cwd: input.cwd ?? null });
+    const needles = Array.isArray(match) ? match : [match];
+    if (!needles.some((needle) => haystack.includes(String(needle)))) return false;
+  }
+  return true;
+}
+
+export function decisionFromRule(rule, input) {
+  const action = String(rule.action || rule.decision || 'allow').toLowerCase();
+  if (action === 'deny' || action === 'block') {
+    return { action: 'deny', reason: rule.reason || rule.message || `blocked by hook rule for ${input.name}` };
+  }
+  if (action === 'modify' || action === 'rewrite') {
+    const nextArgs = rule.args && typeof rule.args === 'object'
+      ? rule.args
+      : { ...(input.args || {}), ...(rule.patch || {}) };
+    return { action: 'modify', args: nextArgs, reason: rule.reason || rule.message || `modified by hook rule for ${input.name}` };
+  }
+  if (action === 'ask') {
+    return { action: 'ask', reason: rule.reason || rule.message || `approval requested by hook rule for ${input.name}` };
+  }
+  return { action: 'allow', reason: rule.reason || rule.message || null };
+}
+
+export function summarizeRule(rule, index) {
+  return {
+    index,
+    enabled: rule.enabled !== false,
+    tool: rule.tool ?? rule.name ?? rule.tools ?? '*',
+    action: rule.action || rule.decision || 'allow',
+    match: rule.match ?? rule.contains ?? null,
+    cwd: rule.cwd || null,
+    reason: rule.reason || rule.message || null,
+    patch: compactValue(rule.patch || rule.args || null),
+  };
+}
+
+export function handlerDedupeKey(handler) {
+  if (!handler || typeof handler !== 'object') return '';
+  const ifKey = handler.if != null ? `|if:${JSON.stringify(handler.if)}` : '';
+  if (handler.type === 'command') {
+    return `command:${handler._pluginRoot || ''}:${handler.command || ''}:${JSON.stringify(handler.args || null)}${ifKey}`;
+  }
+  if (handler.type === 'http') return `http:${handler.url || ''}${ifKey}`;
+  if (handler.type === 'mcp_tool') return `mcp_tool:${handler.server || ''}:${handler.tool || ''}${ifKey}`;
+  if (handler.type === 'prompt') return `prompt:${handler.prompt || ''}${ifKey}`;
+  return `${handler.type || 'unknown'}:${JSON.stringify(handler)}`;
+}
+
+export function shellCountFor(handler) {
+  if (handler?.type === 'command') {
+    if (handler.args) return 'exec';
+    return handler.shell === 'powershell' || handler.shell === 'bash' ? handler.shell : defaultShellKind();
+  }
+  return handler?.type || 'unknown';
+}