mixdog 0.8.0 → 0.9.0

package/src/runtime/agent/orchestrator/tools/builtin/shell-jobs.mjs

@@ -1,4 +1,4 @@
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, watch as fsWatch, writeFileSync } from 'fs';
 import * as fsPromises from 'fs/promises';
 import { basename, join } from 'path';
@@ -15,6 +15,8 @@ import {
 } from '../../../../shared/background-tasks.mjs';
 import { startChildGuardian } from '../../../../shared/child-guardian.mjs';
 
+globalThis.__mixdogShellJobsRuntimeLoaded = true;
+
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -220,29 +222,62 @@ function killProcessTree(pid, signal = 'SIGTERM') {
 // owned children. Async jobs are intentionally CLI-owned; no restart replay or
 // daemon handoff is attempted.
 const _liveJobPids = new Set();
+const _liveJobIdsByPid = new Map();
 let _shellJobsExitHookInstalled = false;
-function _registerLiveJobPid(pid) {
-    if (Number.isFinite(pid) && pid > 0) _liveJobPids.add(pid);
+function _registerLiveJobPid(pid, jobId = null) {
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.add(pid);
+        if (jobId) _liveJobIdsByPid.set(pid, jobId);
+    }
 }
 function _unregisterLiveJobPid(pid) {
-    if (Number.isFinite(pid) && pid > 0) _liveJobPids.delete(pid);
+    if (Number.isFinite(pid) && pid > 0) {
+        _liveJobPids.delete(pid);
+        _liveJobIdsByPid.delete(pid);
+    }
 }
-function _sweepLiveJobsSync() {
-    for (const pid of _liveJobPids) {
-        try {
-            if (process.platform === 'win32') {
-                spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
+function _killLiveJobPid(pid, { sync = false } = {}) {
+    try {
+        if (process.platform === 'win32') {
+            if (sync) {
+                spawnSync('taskkill.exe', ['/pid', String(pid), '/t', '/f'], {
+                    windowsHide: true,
+                    stdio: 'ignore',
+                    timeout: 1500,
+                });
             } else {
-                try { process.kill(-pid, 'SIGKILL'); }
-                catch { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
+                spawn('taskkill', ['/pid', String(pid), '/t', '/f'], { windowsHide: true, stdio: 'ignore' });
             }
-        } catch { /* ignore */ }
+        } else {
+            try { process.kill(-pid, 'SIGKILL'); }
+            catch { try { process.kill(pid, 'SIGKILL'); } catch { /* ignore */ } }
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+function _sweepLiveJobsSync() {
+    for (const pid of _liveJobPids) {
+        _killLiveJobPid(pid, { sync: true });
     }
     _liveJobPids.clear();
+    _liveJobIdsByPid.clear();
+}
+function _ensureProcessListenerHeadroom(events, extra = 1) {
+    try {
+        if (typeof process.getMaxListeners !== 'function' || typeof process.setMaxListeners !== 'function') return;
+        const current = process.getMaxListeners();
+        if (current === 0) return;
+        let needed = current;
+        for (const event of events) needed = Math.max(needed, process.listenerCount(event) + extra);
+        if (needed > current) process.setMaxListeners(needed);
+    } catch { /* ignore */ }
 }
 function _installShellJobsExitHook() {
     if (_shellJobsExitHookInstalled) return;
     _shellJobsExitHookInstalled = true;
+    _ensureProcessListenerHeadroom(['exit', 'SIGTERM', 'SIGINT', 'SIGHUP'], 1);
     try { process.on('exit', _sweepLiveJobsSync); } catch { /* ignore */ }
     try { process.on('SIGTERM', _sweepLiveJobsSync); } catch { /* ignore */ }
     try { process.on('SIGINT', _sweepLiveJobsSync); } catch { /* ignore */ }
@@ -538,8 +573,8 @@ function refreshShellJob(jobId) {
     return detail;
 }
 
-export function startBackgroundShellJob({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellType, clientHostPid }) {
-    return _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellType, clientHostPid });
+export function startBackgroundShellJob({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellArgs, shellType, clientHostPid }) {
+    return _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellArgs, shellType, clientHostPid });
 }
 
 // In-process completion watcher. After a background shell task is spawned the
@@ -572,6 +607,20 @@ const jobNotifyCtxByJobId = new Map();
 // consuming the outcome, so the watcher must stay cancelled; the last waiter to
 // leave (count===0) owns the decision to re-arm a still-running job.
 const jobWaitWaiterCountByJobId = new Map();
+function markShellJobCancelledByShutdown(jobId, reason = 'shutdown') {
+    const detail = readShellJobDetail(jobId);
+    if (!detail || detail.status !== 'running') return false;
+    detail.status = 'cancelled';
+    detail.exitCode = 137;
+    detail.killed = true;
+    detail.error = `cancelled by runtime shutdown (${reason})`;
+    detail.finishedAt = new Date().toISOString();
+    try { writeFileSync(detail.exitPath || shellJobExitPath(jobId), '137'); } catch { /* ignore */ }
+    try { writeFileSync(detail.donePath || shellJobDonePath(jobId), ''); } catch { /* ignore */ }
+    writeShellJobDetail(detail);
+    _unregisterLiveJobPid(detail.pid);
+    return true;
+}
 // Register a synchronous task waiter. Paired with endShellJobWait in a
 // finally so the count can't leak on throw.
 export function beginShellJobWait(jobId) {
@@ -590,6 +639,26 @@ export function endShellJobWait(jobId) {
 export function clearShellJobNotifyCtx(jobId) {
     jobNotifyCtxByJobId.delete(jobId);
 }
+export function shutdownShellJobs(reason = 'runtime-close', { sync = false } = {}) {
+    const livePids = [..._liveJobPids];
+    const jobIds = new Set([..._liveJobIdsByPid.values()].filter(Boolean));
+    const watcherJobIds = [...backgroundShellJobWatchers.keys()];
+    for (const jobId of watcherJobIds) {
+        jobIds.add(jobId);
+        try { cancelBackgroundShellJobWatch(jobId); } catch { /* ignore */ }
+    }
+    for (const pid of livePids) _killLiveJobPid(pid, { sync });
+    _liveJobPids.clear();
+    _liveJobIdsByPid.clear();
+    let marked = 0;
+    for (const jobId of jobIds) {
+        try { if (markShellJobCancelledByShutdown(jobId, reason)) marked += 1; } catch { /* ignore */ }
+    }
+    backgroundShellJobWatchers.clear();
+    jobNotifyCtxByJobId.clear();
+    jobWaitWaiterCountByJobId.clear();
+    return { killed: livePids.length, cancelledJobs: marked, cancelledWatchers: watcherJobIds.length };
+}
 // Cancel (and unregister) an armed watcher without notifying. Idempotent: a
 // no-op when no watcher is armed, and the per-watcher cancel respects the
 // `settled` guard so it cannot race a real completion notify. The persistent
@@ -824,12 +893,12 @@ export function adoptForegroundShellJob({ command, cwd, pid, timeoutMs, mergeStd
     writeShellJobDetail(detail);
     if (Number.isFinite(pid) && pid > 0) {
         _installShellJobsExitHook();
-        _registerLiveJobPid(pid);
+        _registerLiveJobPid(pid, jobId);
     }
     return { ...detail, exitPath, donePath };
 }
 
-function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellType, clientHostPid }) {
+function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr, spawnEnv, shell, shellArg, shellArgs, shellType, clientHostPid }) {
     // Route ANY PowerShell shell to the PS wrapper, regardless of platform.
     // Gating on win32 sent shell:'powershell' on macOS/Linux down the POSIX
     // path below, which spawns `pwsh <wrapper>.sh` — pwsh then tries to run a
@@ -871,7 +940,8 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     // it trivial to distinguish a timeout (124) from a user-side
     // SIGTERM exit (143).
     const innerShellQ = shellQuoteSingle(shell);
-    const innerArgQ = shellQuoteSingle(shellArg);
+    const innerArgs = Array.isArray(shellArgs) && shellArgs.length > 0 ? shellArgs : [shellArg];
+    const innerArgsQ = innerArgs.filter((arg) => arg != null && String(arg).length > 0).map(shellQuoteSingle).join(' ');
     // Runtime enforcement proof: the wrapper touches <jobId>.enforced right
     // before exec'ing `timeout`, so the marker exists iff the timeout branch
     // actually ran under the wrapper's own env/cwd. A spawn-time probe can't
@@ -885,7 +955,7 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
     // status for processes that actually exited 0. `rm -- "$0"` removes
     // the staged wrapper .cmd.sh after donePath is published so a host
     // crash before this point still leaves the file for the sweep to GC.
-    const wrapped = `{ if command -v timeout >/dev/null 2>&1; then _to=timeout; elif command -v gtimeout >/dev/null 2>&1; then _to=gtimeout; else _to=; fi; if [ -n "$_to" ]; then touch ${shellQuoteSingle(enforcedPath)}; "$_to" ${timeoutSeconds} ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; else ${innerShellQ} ${innerArgQ} ${userCmdQuoted}; fi; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
+    const wrapped = `{ if command -v timeout >/dev/null 2>&1; then _to=timeout; elif command -v gtimeout >/dev/null 2>&1; then _to=gtimeout; else _to=; fi; if [ -n "$_to" ]; then touch ${shellQuoteSingle(enforcedPath)}; "$_to" ${timeoutSeconds} ${innerShellQ} ${innerArgsQ} ${userCmdQuoted}; else ${innerShellQ} ${innerArgsQ} ${userCmdQuoted}; fi; rc=$?; printf '%s' "$rc" > ${shellQuoteSingle(exitPath)}; touch ${shellQuoteSingle(donePath)}; rm -- "$0" 2>/dev/null; exit $rc; }`;
     // Stage the wrapped command to a .sh and let the script open its own
     // output files via `exec > … 2> …`. The parent does NOT pass file
     // descriptors via stdio inheritance (`stdio: 'ignore'` for all three).
@@ -919,7 +989,7 @@ function _startBackgroundShellJobImpl({ command, timeoutMs, workDir, mergeStderr
         label: 'shell-job',
     });
     _installShellJobsExitHook();
-    _registerLiveJobPid(child.pid);
+    _registerLiveJobPid(child.pid, jobId);
     const detail = {
         jobId,
         kind: 'bash',
@@ -1056,7 +1126,7 @@ function startBackgroundPowerShellJob({ command, timeoutMs, workDir, mergeStderr
         return { jobId, kind: 'bash', status: 'failed', error: 'PowerShell background task spawn returned no pid' };
     }
     _installShellJobsExitHook();
-    _registerLiveJobPid(childPid);
+    _registerLiveJobPid(childPid, jobId);
     const detail = {
         jobId,
         kind: 'bash',

package/src/runtime/agent/orchestrator/tools/builtin/snapshot-store.mjs

@@ -3,7 +3,7 @@ import { join } from 'path';
 import { writeJsonAtomicSync } from '../../../../shared/atomic-file.mjs';
 import { resolvePluginData } from '../../../../shared/plugin-paths.mjs';
 
-// Mixdog read/write/edit share a scoped snapshot store. Value stores the
+// Mixdog read/patch paths share a scoped snapshot store. Value stores the
 // mtime + size at read-time. A missing scope is fail-closed: snapshots without
 // a real scope id are NOT recorded under a shared default bucket (would let
 // worker A's read satisfy worker B's edit-gate across sessions via a persisted

package/src/runtime/agent/orchestrator/tools/builtin.mjs

@@ -19,6 +19,7 @@ import {
 } from './builtin/bash-tool.mjs';
 import {
     executeFindFilesTool,
+    executeFuzzyFindTool,
     executeListTool,
     executeTreeTool,
 } from './builtin/list-tool.mjs';
@@ -129,7 +130,7 @@ export {
 } from './builtin/cache-layers.mjs';
 export { atomicWrite } from './builtin/atomic-write.mjs';
 // ---------------------------------------------------------------------------
-// User-cwd persistence bridge: hook writes user-cwd.txt on SessionStart so
+// User-cwd persistence hook: writes user-cwd.txt on SessionStart so
 // the MCP server (spawned from cache dir) resolves the correct sandbox root.
 // Helper extracted to src/shared/user-cwd.mjs so server-main.mjs can import
 // the same primitive without circular-import risk.
@@ -252,9 +253,54 @@ const BUILTIN_TOOL_ALIASES = new Map([
     ['golb', 'glob'],
 ]);
 
+// Case-insensitive lookup of canonical builtin names, built once from the
+// declarative BUILTIN_TOOLS registry. Models trained on other coding-agent
+// CLIs frequently emit PascalCase tool names ("Read", "Shell", "Grep",
+// "List") for tools mixdog exposes in lowercase. Those calls used to fall
+// through to formatUnknownBuiltinToolMessage and, because the error did not
+// resolve the case mismatch, the model re-issued the SAME capitalised call
+// every iteration until the loop cap. A lowercase→canonical map makes the
+// dispatcher accept the case variant directly.
+const _BUILTIN_LOWER_TO_CANONICAL = new Map(
+    BUILTIN_TOOLS.map((t) => [String(t.name || '').toLowerCase(), t.name]).filter(([k]) => k),
+);
+
+// Well-known tool names from OTHER agent CLIs that have no mixdog builtin.
+// They cannot be silently remapped (their argument shapes differ — e.g.
+// Write{path,contents} vs apply_patch{patch}) so the unknown-tool error
+// surfaces a concrete redirect instead of a bare "unknown tool", which is
+// what kept models looping on a non-existent tool.
+const EXTERNAL_TOOL_REDIRECTS = new Map([
+    ['write', 'use `apply_patch` with an `*** Add File:` V4A section to create a file'],
+    ['edit', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['multiedit', 'use a single `apply_patch` call with multiple `*** Update File:` sections'],
+    ['strreplace', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['str_replace', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['str_replace_editor', 'use `apply_patch` with a `*** Update File:` V4A section'],
+    ['createfile', 'use `apply_patch` with an `*** Add File:` V4A section'],
+    ['create_file', 'use `apply_patch` with an `*** Add File:` V4A section'],
+    ['deletefile', 'use `apply_patch` with a `*** Delete File:` V4A section'],
+    ['delete_file', 'use `apply_patch` with a `*** Delete File:` V4A section'],
+    ['bash', 'use the `shell` tool'],
+    ['run', 'use the `shell` tool'],
+    ['runcommand', 'use the `shell` tool'],
+    ['terminal', 'use the `shell` tool'],
+    ['view', 'use the `read` tool'],
+    ['cat', 'use the `read` tool'],
+    ['ls', 'use the `list` tool'],
+    ['searchfiles', 'use the `grep` tool'],
+    ['codebase_search', 'use the `grep` or `code_graph` tool'],
+]);
+
 export function canonicalizeBuiltinToolName(name) {
     if (typeof name !== 'string') return name;
-    return BUILTIN_TOOL_ALIASES.get(name) || name;
+    const aliased = BUILTIN_TOOL_ALIASES.get(name);
+    if (aliased) return aliased;
+    // Exact match wins (cheapest, most common path).
+    if (_BUILTIN_LOWER_TO_CANONICAL.get(name) === name) return name;
+    // Case-insensitive fall-through: "Read"/"SHELL"/"Grep" → canonical.
+    const lowerCanonical = _BUILTIN_LOWER_TO_CANONICAL.get(name.toLowerCase());
+    return lowerCanonical || name;
 }
 
 function editDistance(a, b) {
@@ -294,6 +340,12 @@ export function suggestBuiltinToolName(name) {
 }
 
 export function formatUnknownBuiltinToolMessage(name, _args = {}, noun = 'builtin tool') {
+    // Concrete redirect for a well-known tool from another agent CLI whose
+    // argument shape differs from any mixdog builtin (so it cannot be
+    // case-normalised into one). Without this, the model re-issues the same
+    // non-existent tool every iteration until the loop cap.
+    const redirect = typeof name === 'string' ? EXTERNAL_TOOL_REDIRECTS.get(name.toLowerCase()) : null;
+    if (redirect) return `Error: unknown ${noun} "${name}" — ${redirect}.`;
     const suggestion = suggestBuiltinToolName(name);
     if (!suggestion) return `Error: unknown ${noun} "${name}"`;
     return `Error: unknown ${noun} "${name}". Did you mean "${suggestion}"?`;
@@ -308,7 +360,7 @@ process.on('exit', flushReadRangeIndexesSync);
 
 configureReadRangeIndexTelemetry({ trace: _ioTrace, hashText: _hashText });
 
-// Uniform tool-output cap (Codex `tool_output_token_limit` analogue): a SINGLE
+// Uniform tool-output cap (`tool_output_token_limit` analogue): a SINGLE
 // optional knob that bounds EVERY builtin string result before it enters the
 // lead context, on top of each tool's own caps. Default 0 = OFF (per-tool caps
 // only, no behaviour change). Set MIXDOG_TOOL_OUTPUT_MAX_BYTES (or pass
@@ -342,7 +394,7 @@ function capToolOutput(result, options = {}) {
     const bytes = Buffer.byteLength(result, 'utf8');
     if (bytes <= cap) return result;
     // Middle-truncate: keep head + tail (byte-accurate), drop the middle. Mirrors
-    // Codex middle truncation so the model still sees both ends of a runaway.
+    // Middle truncation so the model still sees both ends of a runaway.
     const half = Math.max(1, Math.floor(cap / 2) - 64);
     const head = _sliceToBytesFromStart(result, half);
     const tail = _sliceToBytesFromEnd(result, half);
@@ -371,7 +423,7 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
     const readStateScope = options?.readStateScope ?? options?.sessionId ?? null;
     const executeChildBuiltinTool = (childName, childArgs, childCwd = workDir, childOptions = null) =>
         executeBuiltinTool(childName, childArgs, childCwd, childOptions ? { ...options, ...childOptions } : options);
-    // Path policy: Claude Code's settings.json permissions (mcp__* allow) are the
+    // Path policy: host settings.json permissions (mcp__* allow) are the
     // sole arbiter for workspace-boundary decisions.
     const _toolResult = await (async () => {
     switch (toolName) {
@@ -389,6 +441,8 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
             return executeGrepTool(args, workDir, executeChildBuiltinTool, readStateScope, options);
         case 'glob':
             return executeGlobTool(args, workDir, options);
+        case 'find':
+            return executeFuzzyFindTool(args, workDir, options);
         case 'list':
             return executeListTool(args, workDir, options);
         case 'tree':

package/src/runtime/agent/orchestrator/tools/code-graph-state.mjs

@@ -0,0 +1,86 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve as pathResolve } from 'node:path';
+
+export const codeGraphCache = new Map();
+export const codeGraphDirtyPaths = new Map();
+
+const codeGraphDirtyGen = new Map();
+let drainCodeGraphCacheFn = null;
+
+export function canonicalGraphCwd(cwd) {
+  if (!cwd) throw new Error('code_graph requires cwd - caller did not provide a working directory');
+  const full = pathResolve(cwd);
+  return process.platform === 'win32' ? full.toLowerCase() : full;
+}
+
+export function canonicalGraphPath(p) {
+  const full = pathResolve(String(p || ''));
+  return process.platform === 'win32' ? full.toLowerCase() : full;
+}
+
+export function getCodeGraphGen(graphCwd) {
+  return codeGraphDirtyGen.get(graphCwd) || 0;
+}
+
+export function bumpCodeGraphGen(graphCwd) {
+  codeGraphDirtyGen.set(graphCwd, (codeGraphDirtyGen.get(graphCwd) || 0) + 1);
+}
+
+export function consumeCodeGraphDirtyPaths(cwd) {
+  const key = canonicalGraphCwd(cwd);
+  const set = codeGraphDirtyPaths.get(key);
+  if (!set || set.size === 0) return [];
+  codeGraphDirtyPaths.delete(key);
+  return [...set];
+}
+
+// Accept absolute written paths only; resolve affected indexed roots centrally.
+export function markCodeGraphDirtyPaths(paths) {
+  const values = Array.isArray(paths) ? paths : [paths];
+  const cleaned = values
+    .filter(Boolean)
+    .map((p) => canonicalGraphPath(p));
+  if (cleaned.length === 0) return;
+
+  const knownRoots = new Set([...codeGraphDirtyPaths.keys(), ...codeGraphCache.keys()]);
+  const affectedRoots = new Set();
+  for (const absPath of cleaned) {
+    let matchedThisPath = false;
+    for (const root of knownRoots) {
+      const canonRoot = canonicalGraphPath(root);
+      if (absPath.startsWith(canonRoot + '/') || absPath.startsWith(canonRoot + '\\') || absPath === canonRoot) {
+        affectedRoots.add(root);
+        matchedThisPath = true;
+      }
+    }
+    if (!matchedThisPath) {
+      let dir = dirname(absPath);
+      while (dir && dir !== dirname(dir)) {
+        if (existsSync(join(dir, 'package.json')) || existsSync(join(dir, '.git'))) {
+          affectedRoots.add(canonicalGraphCwd(dir));
+          break;
+        }
+        dir = dirname(dir);
+      }
+    }
+  }
+
+  for (const root of affectedRoots) {
+    if (!codeGraphDirtyPaths.has(root)) codeGraphDirtyPaths.set(root, new Set());
+    const set = codeGraphDirtyPaths.get(root);
+    for (const p of cleaned) set.add(p);
+
+    const canonRoot = canonicalGraphCwd(root);
+    codeGraphCache.delete(canonRoot);
+    bumpCodeGraphGen(canonRoot);
+  }
+}
+
+export function registerCodeGraphDrain(fn) {
+  drainCodeGraphCacheFn = typeof fn === 'function' ? fn : null;
+}
+
+export function drainCodeGraphCache() {
+  if (!drainCodeGraphCacheFn) return;
+  drainCodeGraphCacheFn();
+}

package/src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs

@@ -3,20 +3,20 @@ export const CODE_GRAPH_TOOL_DEFS = [
     name: 'code_graph',
     title: 'Code Graph',
     annotations: { title: 'Code Graph', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Inspect code structure. Top-level entry for code-related questions: symbols, definitions, references, callers, callees, imports, and related files. Use before read when structure can narrow the target; use grep for exact text.',
+    description: 'Code structure: symbols, refs, calls, imports, impact.',
     inputSchema: {
       type: 'object',
       properties: {
-        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'search', 'references', 'callers', 'callees', 'prewarm'], description: 'Operation: repo/file overview, import graph, symbol lookup/search, references, callers/callees, or cache prewarm.' },
-        file: { type: 'string', description: 'Target source file. Directory scope is only for references/callers; omit for repo-wide overview/search.' },
-        symbol: { type: 'string', description: 'Identifier or search keyword for symbol/search/reference/call modes.' },
-        symbols: { type: 'array', items: { type: 'string' }, description: 'Batch identifiers for find_symbol/callers/callees/references/prewarm.' },
-        body: { type: 'boolean', description: 'Return full symbol body for find_symbol. Default true.' },
-        language: { type: 'string', description: 'Optional language hint.' },
-        limit: { type: 'number', minimum: 1, description: 'Max results to return; clamped per mode.' },
-        depth: { type: 'number', minimum: 1, maximum: 5, description: 'callers only: 1 direct, 2-5 transitive.' },
-        page: { type: 'number', minimum: 1, description: 'callers depth>=2 page.' },
-        cwd: { type: 'string', description: 'Project root override; omit when runtime cwd is already the repo root.' },
+        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'search', 'references', 'callers', 'callees', 'prewarm'], description: 'Operation.' },
+        file: { type: 'string', description: 'Source file.' },
+        symbol: { type: 'string', description: 'Identifier or symbol keyword.' },
+        symbols: { type: 'array', items: { type: 'string' }, description: 'Batch identifiers.' },
+        body: { type: 'boolean', description: 'Include body.' },
+        language: { type: 'string', description: 'Language hint.' },
+        limit: { type: 'number', minimum: 1, description: 'Max results.' },
+        depth: { type: 'number', minimum: 1, maximum: 5, description: 'Caller depth.' },
+        page: { type: 'number', minimum: 1, description: 'Caller page.' },
+        cwd: { type: 'string', description: 'Project root.' },
       },
       required: ['mode'],
     },