@agentllm/codegraph-arkts 0.7.12 → 0.9.4-arkts.0

package/dist/mcp/index.d.ts

@@ -26,6 +26,12 @@ export declare class MCPServer {
     private toolHandler;
     private projectPath;
     private initPromise;
+    private clientSupportsRoots;
+    private rootsAttempted;
+    private originalPpid;
+    private hostPpid;
+    private ppidWatchdog;
+    private stopped;
     constructor(projectPath?: string);
     /**
      * Start the MCP server
@@ -55,6 +61,12 @@ export declare class MCPServer {
      * we never open the SQLite file twice concurrently.
      */
     private retryInitIfNeeded;
+    /**
+     * Resolve the project root via the MCP `roots/list` request and initialize
+     * from the first root the client reports. Falls back to the process cwd if
+     * the client returns no usable root or doesn't answer in time. See issue #196.
+     */
+    private initFromRoots;
     /**
      * Start file watching on the active CodeGraph instance.
      * Logs sync activity to stderr for diagnostics.

package/dist/mcp/index.js

@@ -51,11 +51,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolHandler = exports.tools = exports.StdioTransport = exports.MCPServer = void 0;
 const path = __importStar(require("path"));
-const fs = __importStar(require("fs"));
 const index_1 = __importStar(require("../index"));
+const sync_1 = require("../sync");
 const transport_1 = require("./transport");
 const tools_1 = require("./tools");
 const server_instructions_1 = require("./server-instructions");
+const wasm_runtime_flags_1 = require("../extraction/wasm-runtime-flags");
 /**
  * Convert a file:// URI to a filesystem path.
  * Handles URL encoding and Windows drive letter paths.
@@ -78,24 +79,82 @@ function fileUriToPath(uri) {
 /**
  * MCP Server Info
  */
-function getPackageVersion() {
-    try {
-        const packageJsonPath = path.join(__dirname, '..', '..', 'package.json');
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-        return packageJson.version ?? '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-}
 const SERVER_INFO = {
     name: 'codegraph',
-    version: getPackageVersion(),
+    version: '0.1.0',
 };
 /**
  * MCP Protocol Version
  */
 const PROTOCOL_VERSION = '2024-11-05';
+/**
+ * How long to wait for the client's `roots/list` response before giving up
+ * and falling back to the process cwd.
+ */
+const ROOTS_LIST_TIMEOUT_MS = 5000;
+/**
+ * How often to poll `process.ppid` to detect parent process death (see #277).
+ * 5s is a deliberate trade-off: the failure mode being guarded against is rare
+ * (parent SIGKILL'd), and longer poll = less wakeup overhead while idle.
+ */
+const DEFAULT_PPID_POLL_MS = 5000;
+/**
+ * Resolve the PPID watchdog poll interval from an env override. A value of
+ * `0` disables the watchdog entirely (escape hatch for embedded scenarios
+ * where the parent legitimately re-parents the server on purpose). Anything
+ * non-numeric or negative falls back to the default.
+ */
+function parsePpidPollMs(raw) {
+    if (raw === undefined || raw === '')
+        return DEFAULT_PPID_POLL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_PPID_POLL_MS;
+    if (parsed < 0)
+        return DEFAULT_PPID_POLL_MS;
+    return Math.floor(parsed);
+}
+/**
+ * Parse the host PID propagated across the `--liftoff-only` re-exec
+ * ({@link HOST_PPID_ENV}). Returns a positive integer PID, or null when
+ * unset/invalid — the direct-launch path, where the watchdog falls back to
+ * `process.ppid` divergence. PIDs of 0/1 are rejected (0 = unknown, 1 = init,
+ * i.e. already orphaned), so the watchdog doesn't latch onto init.
+ */
+function parseHostPpid(raw) {
+    if (raw === undefined || raw === '')
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 1)
+        return null;
+    return parsed;
+}
+/** True if a process with `pid` currently exists (signal-0 probe). */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract the first usable filesystem path from a `roots/list` result.
+ * Shape per MCP spec: `{ roots: [{ uri: "file:///path", name?: string }] }`.
+ * Returns null if the result is empty or malformed.
+ */
+function firstRootPath(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const roots = result.roots;
+    if (!Array.isArray(roots) || roots.length === 0)
+        return null;
+    const first = roots[0];
+    if (typeof first?.uri !== 'string')
+        return null;
+    return fileUriToPath(first.uri);
+}
 /**
  * MCP Server for CodeGraph
  *
@@ -110,6 +169,26 @@ class MCPServer {
     // In-flight background init kicked off from handleInitialize. Tracked so the
     // sync retry path doesn't race against it (double-opening the SQLite file).
     initPromise = null;
+    // Whether the client advertised the MCP `roots` capability during initialize.
+    // If so, and no explicit project path was given, we ask it for the workspace
+    // root via roots/list rather than guessing from the (often wrong) cwd.
+    clientSupportsRoots = false;
+    // Guards the one-shot deferred resolution (roots/list or cwd) so we don't
+    // re-issue roots/list on every tool call.
+    rootsAttempted = false;
+    // PPID watchdog — see start(). Captured at construction so we always have a
+    // baseline, even if start() runs after a fork-style reparent.
+    originalPpid = process.ppid;
+    // The MCP host's PID, propagated across the `--liftoff-only` re-exec (see
+    // HOST_PPID_ENV). When set, the watchdog polls it directly: the re-exec
+    // inserts an intermediate process whose *death* — not just our reparenting —
+    // is what we'd otherwise miss. null on the direct (bundled) launch path.
+    hostPpid = parseHostPpid(process.env[wasm_runtime_flags_1.HOST_PPID_ENV]);
+    ppidWatchdog = null;
+    // Idempotency guard for stop(). Without it, the watchdog can race with the
+    // stdin `end`/`close` handlers (or SIGTERM/SIGINT) and double-close cg and
+    // the transport before process.exit() lands.
+    stopped = false;
     constructor(projectPath) {
         this.projectPath = projectPath || null;
         this.transport = new transport_1.StdioTransport();
@@ -133,6 +212,35 @@ class MCPServer {
         // Detect this and shut down gracefully to prevent orphaned processes.
         process.stdin.on('end', () => this.stop());
         process.stdin.on('close', () => this.stop());
+        // PPID watchdog (#277). Linux doesn't propagate parent death to children,
+        // so when the MCP host (Claude Code, opencode, …) is SIGKILL'd by the OOM
+        // killer / a force-quit / a container teardown, the child is reparented to
+        // init/systemd and the stdin `end`/`close` events don't always fire. The
+        // server would then linger indefinitely, holding inotify watches, file
+        // descriptors, and the SQLite WAL. Poll `process.ppid` and shut down the
+        // moment it changes from what we observed at startup. Cross-platform:
+        // reparenting changes ppid on Linux *and* macOS; on Windows the value can
+        // also drop to 0 once the parent is gone. When the CLI re-execs itself for
+        // `--liftoff-only`, an intermediate process sits between us and the host and
+        // outlives it, so our own ppid wouldn't change — in that case we poll the
+        // host PID (propagated via HOST_PPID_ENV) for liveness instead. The watchdog
+        // is `.unref()`'d so it never holds the event loop open on its own.
+        const pollMs = parsePpidPollMs(process.env.CODEGRAPH_PPID_POLL_MS);
+        if (pollMs > 0) {
+            this.ppidWatchdog = setInterval(() => {
+                const current = process.ppid;
+                const ppidChanged = current !== this.originalPpid;
+                const hostGone = this.hostPpid !== null && !isProcessAlive(this.hostPpid);
+                if (ppidChanged || hostGone) {
+                    const reason = ppidChanged
+                        ? `ppid ${this.originalPpid} -> ${current}`
+                        : `host pid ${this.hostPpid} exited`;
+                    process.stderr.write(`[CodeGraph MCP] Parent process exited (${reason}); shutting down.\n`);
+                    this.stop();
+                }
+            }, pollMs);
+            this.ppidWatchdog.unref();
+        }
     }
     /**
      * Try to initialize CodeGraph for the default project.
@@ -145,6 +253,8 @@ class MCPServer {
      * are still possible.
      */
     async tryInitializeDefault(projectPath) {
+        // Record where we searched so a later "not initialized" error can name it.
+        this.toolHandler.setDefaultProjectHint(projectPath);
         // Walk up parent directories to find nearest .codegraph/
         const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(projectPath);
         if (!resolvedRoot) {
@@ -183,10 +293,28 @@ class MCPServer {
         // Already initialized successfully
         if (this.toolHandler.hasDefaultCodeGraph())
             return;
-        // No project path to retry with
-        if (!this.projectPath)
-            return;
-        const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(this.projectPath);
+        // No explicit path was given at initialize. Resolve it now, exactly once:
+        // ask the client via roots/list (if it advertised roots), else use cwd.
+        // Deferring to here lets a roots answer override the wrong cwd, and the
+        // one-shot guard means we never re-issue roots/list per tool call.
+        if (!this.projectPath && !this.rootsAttempted) {
+            this.rootsAttempted = true;
+            this.initPromise = (this.clientSupportsRoots
+                ? this.initFromRoots()
+                : this.tryInitializeDefault(process.cwd())).finally(() => { this.initPromise = null; });
+            try {
+                await this.initPromise;
+            }
+            catch { /* fall through to last-resort below */ }
+            if (this.toolHandler.hasDefaultCodeGraph())
+                return;
+        }
+        // Last resort: re-walk from the best candidate we have. Picks up projects
+        // initialized after the server started, and covers clients that sent no
+        // usable initialize signal at all.
+        const candidate = this.projectPath ?? process.cwd();
+        this.toolHandler.setDefaultProjectHint(candidate);
+        const resolvedRoot = (0, index_1.findNearestCodeGraphRoot)(candidate);
         if (!resolvedRoot)
             return;
         try {
@@ -207,6 +335,29 @@ class MCPServer {
             // Still failing — will retry on next tool call
         }
     }
+    /**
+     * Resolve the project root via the MCP `roots/list` request and initialize
+     * from the first root the client reports. Falls back to the process cwd if
+     * the client returns no usable root or doesn't answer in time. See issue #196.
+     */
+    async initFromRoots() {
+        let target = process.cwd();
+        try {
+            const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
+            const rootPath = firstRootPath(result);
+            if (rootPath) {
+                target = rootPath;
+            }
+            else {
+                process.stderr.write('[CodeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
+        }
+        await this.tryInitializeDefault(target);
+    }
     /**
      * Start file watching on the active CodeGraph instance.
      * Logs sync activity to stderr for diagnostics.
@@ -214,6 +365,15 @@ class MCPServer {
     startWatching() {
         if (!this.cg)
             return;
+        // When the watcher is intentionally disabled (e.g. WSL2 /mnt drives, or
+        // CODEGRAPH_NO_WATCH=1), say so explicitly and tell the user how to keep
+        // the graph fresh — otherwise the silent staleness is hard to diagnose.
+        const disabledReason = (0, sync_1.watchDisabledReason)(this.projectPath ?? process.cwd());
+        if (disabledReason) {
+            process.stderr.write(`[CodeGraph MCP] File watcher disabled — ${disabledReason}. ` +
+                `The graph will not auto-update; run \`codegraph sync\` (or install the git sync hooks via \`codegraph init\`) to refresh.\n`);
+            return;
+        }
         const started = this.cg.watch({
             onSyncComplete: (result) => {
                 if (result.filesChanged > 0) {
@@ -227,11 +387,22 @@ class MCPServer {
         if (started) {
             process.stderr.write('[CodeGraph MCP] File watcher active — graph will auto-sync on changes\n');
         }
+        else {
+            // start() can also return false when recursive fs.watch isn't supported.
+            process.stderr.write('[CodeGraph MCP] File watcher unavailable on this platform — run `codegraph sync` to refresh the graph after changes.\n');
+        }
     }
     /**
      * Stop the server
      */
     stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.ppidWatchdog) {
+            clearInterval(this.ppidWatchdog);
+            this.ppidWatchdog = null;
+        }
         // Close all cached cross-project connections first
         this.toolHandler.closeAll();
         // Close the main CodeGraph instance
@@ -284,17 +455,23 @@ class MCPServer {
      */
     async handleInitialize(request) {
         const params = request.params;
-        // Extract project path from rootUri or workspaceFolders
-        let projectPath = this.projectPath;
+        // Does the client support the MCP `roots` protocol? If so, and we have no
+        // explicit path, we ask it for the workspace root after the handshake
+        // instead of falling back to the (frequently wrong) cwd. See issue #196.
+        this.clientSupportsRoots = !!params?.capabilities?.roots;
+        // Explicit project signal, strongest first: a client-provided rootUri /
+        // workspaceFolders (LSP-style, non-standard but some clients send it), else
+        // the --path the server was launched with. cwd is NOT used here — we defer
+        // it so a roots/list answer can win over it.
+        let explicitPath = null;
         if (params?.rootUri) {
-            projectPath = fileUriToPath(params.rootUri);
+            explicitPath = fileUriToPath(params.rootUri);
         }
         else if (params?.workspaceFolders?.[0]?.uri) {
-            projectPath = fileUriToPath(params.workspaceFolders[0].uri);
+            explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
         }
-        // Fall back to current working directory if no path provided
-        if (!projectPath) {
-            projectPath = process.cwd();
+        else if (this.projectPath) {
+            explicitPath = this.projectPath;
         }
         // Respond to the handshake BEFORE doing any heavy initialization. Loading
         // the SQLite DB and the tree-sitter WASM runtime can take many seconds on
@@ -315,13 +492,20 @@ class MCPServer {
             serverInfo: SERVER_INFO,
             instructions: server_instructions_1.SERVER_INSTRUCTIONS,
         });
-        // Kick off the default-project init in the background. Tool calls that
-        // arrive before it finishes will see the "not initialized yet" path and
-        // fall through to `retryInitIfNeeded`, which now waits for this promise
-        // rather than racing against it with a second open.
-        this.initPromise = this.tryInitializeDefault(projectPath).finally(() => {
-            this.initPromise = null;
-        });
+        // If we know the project dir, kick off init in the background now. Tool
+        // calls that arrive before it finishes fall through to `retryInitIfNeeded`,
+        // which waits for this promise rather than racing it with a second open.
+        //
+        // If we DON'T know it (no rootUri, no --path), defer: the first tool call
+        // resolves it via roots/list (when the client supports roots) or cwd. This
+        // is the fix for issue #196 — clients that launch the server outside the
+        // project and don't pass a rootUri previously got a misleading "not
+        // initialized" error on every call.
+        if (explicitPath) {
+            this.initPromise = this.tryInitializeDefault(explicitPath).finally(() => {
+                this.initPromise = null;
+            });
+        }
     }
     /**
      * Handle tools/list request

package/dist/mcp/server-instructions.d.ts

@@ -1,2 +1,2 @@
-export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a SQLite knowledge graph of every symbol, edge, and file in the workspace. Reads are sub-millisecond; the index lags writes by about a second through the file watcher.\n\nPrimary goal: help LLM agents narrow decision space fast. Use it to reduce retrieval noise before editing, not as a second planner.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What is this task / feature / area about?\" | `codegraph_context` |\n| \"Give me a navigation-only slice for this task.\" | `codegraph_repo_map_slice` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Survey an unfamiliar module/topic\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Default LLM-first flow\n\n- Start with `codegraph_context` for the task-level picture.\n- Use `codegraph_repo_map_slice` next when you need a navigation-only slice that narrows the search space without assigning work.\n- Use `codegraph_node`, `codegraph_callers`, `codegraph_callees`, or `codegraph_impact` for focused follow-up on the symbols surfaced above.\n- Use `codegraph_explore` only when the area is genuinely unfamiliar and you need a broader source survey.\n\n### Rules of thumb\n\n- **Trust codegraph results.** Do NOT re-verify them with grep unless you need literal text not carried by the graph.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Use `codegraph_repo_map_slice`** when a coding task needs a noise-reduced navigation slice rather than a full exploration dump. It is navigation-only, not a planner, and should not assign steps.\n- **Use `codegraph_explore`** for broad unfamiliar areas, not narrow lookups.\n- **Trust structured short output first.** `context`, `impact`, and `repo_map_slice` are designed to narrow retrieval space directly for LLM use.\n- **Don't degrade into grep loops.** If codegraph already surfaced relevant symbols/files, continue from those results instead of restarting broad text search.\n- **Don't query immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync.\n\n### ArkTS notes\n\n- ArkTS is first-class in this fork. Treat `.ets` as ArkTS, not as downgraded TypeScript.\n- ArkTS facts come from vendored `ArkAnalyzer`, then flow through shared `search` / `context` / `impact` / `callers` / `callees`.\n- HarmonyOS-aware relations such as `module.json5`, ability/form declarations, lifecycle entry associations, and narrow `Want/IPC` design-time links are query-visible.\n- ArkTS mixed-language bridge paths are valid navigation signals. Use them to move from ArkTS UI code into TS / C++ / Rust bridge layers.\n- `Want/IPC` is structure-only in this fork. It is not a full runtime propagation, full IPC precision graph, or cross-process dataflow graph.\n- Treat ability / form / lifecycle / bridge relations as context-narrowing hints for coding and design work, not as exhaustive runtime truth.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n\n## Limitations\n\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
+export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\n## CodeGraph\n\nThis project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a SQLite knowledge graph of every symbol, edge, and file in the workspace. Reads are sub-millisecond; the index lags writes by about a second through the file watcher.\n\nPrimary goal: help LLM agents narrow decision space fast. Use it to reduce retrieval noise before editing, not as a second planner.\n\n### When to prefer codegraph over native search\n\nUse codegraph for **structural** questions \u2014 what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.\n\n| Question | Tool |\n|---|---|\n| \"Where is X defined?\" / \"Find symbol named X\" | `codegraph_search` |\n| \"What is this task / feature / area about?\" | `codegraph_context` |\n| \"I need the first hop for a coding task, but do not yet know the right ArkTS entry / bridge / file to inspect.\" | `codegraph_task_map` |\n| \"How does X reach/become Y? / trace the flow from X to Y\" | `codegraph_trace` |\n| \"What calls function Y?\" | `codegraph_callers` |\n| \"What does Y call?\" | `codegraph_callees` |\n| \"What would break if I changed Z?\" | `codegraph_impact` |\n| \"Show me Y's signature / source / docstring\" | `codegraph_node` |\n| \"Survey an unfamiliar module/topic\" | `codegraph_explore` |\n| \"What files exist under path/\" | `codegraph_files` |\n| \"Is the index healthy?\" | `codegraph_status` |\n\n### Default LLM-first flow\n\n- Start with `codegraph_task_map` when the task is implementation-oriented and you need a low-noise first hop before choosing which symbols or files to inspect.\n- Start with `codegraph_context` when you need a broader task-level picture and can afford a slightly richer response.\n- Use `codegraph_trace` when the question is specifically about a path from X to Y and the endpoints are already known enough to ask directly.\n- Use `codegraph_node`, `codegraph_callers`, `codegraph_callees`, or `codegraph_impact` for focused follow-up on the symbols surfaced above.\n- Use `codegraph_explore` only when the area is genuinely unfamiliar and you need a broader source survey.\n\n### Tool choice shortcuts\n\n- Use `codegraph_task_map` for coder-style work where the endpoint is not fully known yet and you want likely entry points, bridge hops, convergence points, and a compact confirmed path without a large context dump.\n- Use `codegraph_context` for planner-style or subsystem-orientation work where you want a wider structural picture, not just the first actionable path.\n- Use `codegraph_trace` after `task_map` or `context` has already surfaced plausible endpoints and you now want the explicit path.\n- Use `codegraph_explore` only after the lightweight tools still leave the area ambiguous.\n\n### Rules of thumb\n\n- **Trust codegraph results.** Do NOT re-verify them with grep unless you need literal text not carried by the graph.\n- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one call.\n- **Use `codegraph_task_map`** when a coding task needs a noise-reduced navigation slice rather than a full exploration dump. It is a first-hop / trace-launcher aid, not a planner, and should not assign steps.\n- **Use `codegraph_explore`** for broad unfamiliar areas, not narrow lookups.\n- **Trust structured short output first.** `context`, `impact`, and `task_map` are designed to narrow retrieval space directly for LLM use.\n- **Don't degrade into grep loops.** If codegraph already surfaced relevant symbols/files, continue from those results instead of restarting broad text search.\n- **Don't query immediately after editing a file** \u2014 the watcher needs ~500ms to debounce + sync.\n\n### ArkTS notes\n\n- ArkTS is first-class in this fork. Treat `.ets` as ArkTS, not as downgraded TypeScript.\n- ArkTS facts come from vendored `ArkAnalyzer`, then flow through shared `search` / `context` / `impact` / `callers` / `callees` / `trace`.\n- HarmonyOS-aware relations such as `module.json5`, ability/form declarations, lifecycle entry associations, and narrow `Want/IPC` design-time links are query-visible.\n- ArkTS mixed-language bridge paths are valid navigation signals. Use them to move from ArkTS UI code into TS / C++ / Rust bridge layers.\n- `Want/IPC` is structure-only in this fork. It is not a full runtime propagation, full IPC precision graph, or cross-process dataflow graph.\n- Treat ability / form / lifecycle / bridge relations as context-narrowing hints for coding and design work, not as exhaustive runtime truth.\n\n### If `.codegraph/` doesn't exist\n\nThe MCP server returns \"not initialized.\" Ask the user: *\"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?\"*\n\n## Limitations\n\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/tools.d.ts

@@ -97,19 +97,37 @@ export declare const tools: ToolDefinition[];
 export declare class ToolHandler {
     private cg;
     private projectCache;
+    private defaultProjectHint;
     constructor(cg: CodeGraph | null);
     /**
      * Update the default CodeGraph instance (e.g. after lazy initialization)
      */
     setDefaultCodeGraph(cg: CodeGraph): void;
+    /**
+     * Record the directory the server tried to resolve the default project from.
+     * Used only to make the "no default project" error actionable.
+     */
+    setDefaultProjectHint(searchedPath: string): void;
     /**
      * Whether a default CodeGraph instance is available
      */
     hasDefaultCodeGraph(): boolean;
+    /**
+     * Optional allowlist of exposed tools, parsed from the CODEGRAPH_MCP_TOOLS
+     * env var (comma-separated short names, e.g. "trace,search,node,context").
+     * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
+     * trim the tool surface without rebuilding the client config; the ablated
+     * tool is then truly absent from ListTools rather than merely denied on call.
+     * Matching is on the short form, so "trace" and "codegraph_trace" both work.
+     */
+    private toolAllowlist;
+    /** Whether a tool name passes the CODEGRAPH_MCP_TOOLS allowlist (if any). */
+    private isToolAllowed;
     /**
      * Get tool definitions with dynamic descriptions based on project size.
      * The codegraph_explore tool description includes a budget recommendation
-     * scaled to the number of indexed files.
+     * scaled to the number of indexed files. Honors the CODEGRAPH_MCP_TOOLS
+     * allowlist so a trimmed surface is reflected in ListTools.
      */
     getTools(): ToolDefinition[];
     /**
@@ -127,9 +145,19 @@ export declare class ToolHandler {
      */
     closeAll(): void;
     /**
-     * Validate that a value is a non-empty string
+     * Validate that a value is a non-empty string within length bounds.
+     *
+     * The `maxLength` cap protects against MCP clients that ship huge
+     * payloads (10MB+ query strings either by accident or maliciously).
+     * Without this, a single oversized input can pin the FTS5 index or
+     * exhaust memory before any real work runs.
      */
     private validateString;
+    /**
+     * Validate an optional path-like string input. Returns the value if
+     * valid (or undefined), or a ToolResult with the error.
+     */
+    private validateOptionalPath;
     /**
      * Execute a tool by name
      */
@@ -143,9 +171,9 @@ export declare class ToolHandler {
      */
     private handleContext;
     /**
-     * Handle codegraph_repo_map_slice
+     * Handle codegraph_task_map
      */
-    private handleRepoMapSlice;
+    private handleTaskMap;
     /**
      * Heuristic to detect if a query looks like a feature request
      */
@@ -162,6 +190,53 @@ export declare class ToolHandler {
      * Handle codegraph_impact
      */
     private handleImpact;
+    /**
+     * Handle codegraph_trace — shortest CALL PATH between two symbols.
+     *
+     * Exposes GraphTraverser.findPath: the chain of functions from `from` to `to`,
+     * each hop annotated with file:line and the call-site line. This is the
+     * capability grep/Read structurally cannot provide. When no static path
+     * exists, the chain has almost certainly broken at dynamic dispatch
+     * (callbacks, descriptors, metaclasses) — we say so and surface the start
+     * symbol's outgoing calls so the agent bridges the one missing hop with
+     * codegraph_node rather than blindly reading.
+     */
+    private handleTrace;
+    /**
+     * Describe a synthesized (dynamic-dispatch) edge for human output: how the
+     * callback was wired up — the bridge static parsing can't see. Returns null
+     * for ordinary static edges. Used by trace + the node trail so a synthesized
+     * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
+     */
+    private synthEdgeNote;
+    /**
+     * Read one trimmed source line at "relpath:line" (relative to the project
+     * root). `cache` holds split file contents so a multi-hop trace reads each
+     * file at most once. Returns null if the file/line can't be resolved.
+     */
+    private sourceLineAt;
+    /**
+     * Read a hop's body — filePath lines [startLine..endLine] — for inlining into
+     * a trace, capped (lines + chars) so the whole path stays path-scoped even on
+     * a 7-hop chain. Dedents to the body's own indentation and marks truncation.
+     * Shares `cache` with sourceLineAt so each file is read at most once per trace.
+     */
+    private sourceRangeAt;
+    /**
+     * Flow-from-named-symbols: an agent's codegraph_explore query is a bag of
+     * symbol names that usually spans the flow it's investigating (e.g.
+     * "PmsProductController getList PmsProductService list PmsProductServiceImpl").
+     * Surface the longest call chain AMONG those named symbols — scoped to what the
+     * agent explicitly named, so (unlike a fuzzy relevance set) there's no
+     * wrong-feature wandering. Rides synthesized edges, so controller→service-
+     * interface→impl shows up. Returns '' if no chain of >=3 nodes exists.
+     *
+     * Ambiguous tokens (Java `list` → dozens of nodes) are disambiguated by
+     * CO-NAMING: the agent names the class too, so we keep only `list` candidates
+     * whose qualifiedName contains another named token (`PmsProductServiceImpl::list`),
+     * dropping unrelated `OmsOrderService::list`.
+     */
+    private buildFlowFromNamedSymbols;
     /**
      * Handle codegraph_explore — deep exploration in a single call
      *
@@ -178,6 +253,16 @@ export declare class ToolHandler {
      * Handle codegraph_node
      */
     private handleNode;
+    /**
+     * Build the "trail" for a symbol: its direct callees (what it calls) and
+     * callers (what calls it), each with file:line — so codegraph_node doubles as
+     * the structural Grep→Read→expand primitive: a spot PLUS where to go next.
+     * Capped to stay cheap. Walk the graph by calling codegraph_node on a trail
+     * entry; no Read needed for covered hops. Empty edges on a non-leaf often mean
+     * dynamic dispatch the static graph couldn't resolve — that absence is itself
+     * a signal (read that one hop) rather than a dead end.
+     */
+    private formatTrail;
     /**
      * Handle codegraph_status
      */
@@ -238,11 +323,41 @@ export declare class ToolHandler {
     private formatSearchResults;
     private formatNodeList;
     private formatImpact;
+    /**
+     * Build a compact structural outline of a container symbol from its
+     * indexed children (methods, fields, properties, …) — name, kind,
+     * line number, and signature — so the agent gets the shape of a class
+     * without the full source of every method. Returns '' when the container
+     * has no indexed children, so the caller can fall back to full source.
+     */
+    private buildContainerOutline;
     private formatNodeDetails;
     private formatTaskContext;
+    private formatTaskMapOutput;
     private collectKeyLinks;
     private collectNextHops;
     private collectWhyIncluded;
+    private collectTaskMapInsights;
+    private findBoundedTaskMapPaths;
+    private collectTaskMapConvergencePoints;
+    private extendTaskMapPathCandidate;
+    private collectTaskMapTraceHints;
+    private collectTaskMapDisplayEntryPoints;
+    private buildTaskMapSummary;
+    private collectTaskMapKeyLinks;
+    private collectTaskMapNextHops;
+    private collectTaskMapWhyIncluded;
+    private formatTaskMapPath;
+    private formatTaskMapNode;
+    private compactTaskMapSteps;
+    private getTaskMapNodeScore;
+    private getTaskMapEdgeScore;
+    private getTaskMapBacktraceScore;
+    private isTaskMapBridgeNode;
+    private isTaskMapNativeNode;
+    private isTaskMapLegacyNode;
+    private isTaskMapBacktraceRoot;
+    private isTaskMapTerminalCandidate;
     private deserializeTaskContext;
     private textResult;
     private errorResult;