@colbymchenry/codegraph-darwin-arm64 0.9.4 → 0.9.5

package/lib/dist/mcp/tools.js

@@ -41,7 +41,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolHandler = exports.tools = void 0;
 exports.getExploreBudget = getExploreBudget;
 exports.getExploreOutputBudget = getExploreOutputBudget;
+exports.formatStaleBanner = formatStaleBanner;
+exports.formatStaleFooter = formatStaleFooter;
 const index_1 = __importStar(require("../index"));
+const worktree_1 = require("../sync/worktree");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const utils_1 = require("../utils");
@@ -241,6 +244,42 @@ function markSessionConsulted(sessionId) {
         // to write rather than overwrite an attacker-chosen target.
     }
 }
+/**
+ * Per-file staleness banner emitted at the top of a tool response when the
+ * file watcher has pending events for files referenced by the response.
+ * The agent uses this to fall back to Read for those specific files
+ * without waiting for the debounced sync (issue #403).
+ */
+function formatStaleBanner(stale) {
+    const now = Date.now();
+    const lines = stale.map((p) => {
+        const ageMs = Math.max(0, now - p.lastSeenMs);
+        const label = p.indexing ? 'indexing in progress' : 'pending sync';
+        return `  - ${p.path} (edited ${ageMs}ms ago, ${label})`;
+    });
+    return ('⚠️ Some files referenced below were edited since the last index sync — ' +
+        'their codegraph entries may be stale:\n' +
+        lines.join('\n') +
+        '\nFor accurate content of those specific files, Read them directly. ' +
+        'The rest of this response is fresh.');
+}
+/**
+ * Compact footer listing pending files that are NOT referenced in this
+ * response. Gives the agent a complete project-wide freshness picture
+ * without bloating the main banner.
+ */
+function formatStaleFooter(stale) {
+    const MAX = 5;
+    const now = Date.now();
+    const shown = stale.slice(0, MAX);
+    const lines = shown.map((p) => {
+        const ageMs = Math.max(0, now - p.lastSeenMs);
+        return `  - ${p.path} (edited ${ageMs}ms ago)`;
+    });
+    const more = stale.length > MAX ? `\n  - …and ${stale.length - MAX} more` : '';
+    return (`(Note: ${stale.length} file(s) elsewhere in this project are pending index ` +
+        `sync but were not referenced above:\n${lines.join('\n')}${more})`);
+}
 /**
  * Common projectPath property for cross-project queries
  */
@@ -483,6 +522,12 @@ class ToolHandler {
     // The directory the server last searched for a default project. Surfaced in
     // the "not initialized" error so users can see why detection missed.
     defaultProjectHint = null;
+    // Per-start-path cache of the git worktree/index mismatch (issue #155). The
+    // mismatch is a fixed property of (where the request came from → which
+    // .codegraph/ it resolves to), so the up-to-two `git rev-parse` spawns run
+    // once and every later tool call reuses the result — never shelling out to
+    // git on the hot path. `undefined` = not computed yet; `null` = no mismatch.
+    worktreeMismatchCache = new Map();
     constructor(cg) {
         this.cg = cg;
     }
@@ -632,6 +677,7 @@ class ToolHandler {
             cg.close();
         }
         this.projectCache.clear();
+        this.worktreeMismatchCache.clear();
     }
     /**
      * Validate that a value is a non-empty string within length bounds.
@@ -665,6 +711,132 @@ class ToolHandler {
         }
         return value;
     }
+    /**
+     * Cached git worktree/index mismatch for a tool call's effective project.
+     *
+     * The "effective project" is what the request targets: an explicit
+     * `projectPath` arg, else the directory the server resolved its default
+     * project from (`defaultProjectHint`), else cwd. Memoized per start path —
+     * see `worktreeMismatchCache`. Best-effort: if the project can't be resolved
+     * (e.g. nothing initialized yet), it reports "no mismatch" so a tool is never
+     * broken by this check.
+     */
+    worktreeMismatchFor(projectPath) {
+        const startPath = projectPath ?? this.defaultProjectHint ?? process.cwd();
+        const cached = this.worktreeMismatchCache.get(startPath);
+        if (cached !== undefined)
+            return cached;
+        let mismatch = null;
+        try {
+            mismatch = (0, worktree_1.detectWorktreeIndexMismatch)(startPath, this.getCodeGraph(projectPath).getProjectRoot());
+        }
+        catch {
+            // No resolvable project (or any other resolution error) → nothing to warn.
+            mismatch = null;
+        }
+        this.worktreeMismatchCache.set(startPath, mismatch);
+        return mismatch;
+    }
+    /**
+     * Prefix a successful read-tool result with a compact worktree-mismatch
+     * notice when the resolved index belongs to a different git working tree than
+     * the caller's (issue #155). Without this, an agent in a nested worktree
+     * silently trusts main-branch results. No-op on error results and when there
+     * is no mismatch. `codegraph_status` is excluded — it embeds its own verbose
+     * warning — so it stays out of this path.
+     */
+    withWorktreeNotice(result, projectPath) {
+        if (result.isError)
+            return result;
+        const mismatch = this.worktreeMismatchFor(projectPath);
+        if (!mismatch)
+            return result;
+        const notice = (0, worktree_1.worktreeMismatchNotice)(mismatch);
+        const [first, ...rest] = result.content;
+        if (first && first.type === 'text') {
+            return { ...result, content: [{ type: 'text', text: `${notice}\n\n${first.text}` }, ...rest] };
+        }
+        return result;
+    }
+    /**
+     * Annotate a successful read-tool result with per-file staleness — the
+     * non-blocking answer to issue #403. The file watcher tracks every event
+     * it sees per path; here we intersect "files referenced in this response"
+     * against that pending set and prepend a compact banner so the agent can
+     * fall back to Read for those *specific* files without waiting for the
+     * debounced sync to fire. Other pending files in the project (not
+     * referenced by this response) get a small footer so the agent has a
+     * complete picture without bloating the banner.
+     *
+     * Cost when nothing is pending — the common case — is one boolean check.
+     * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
+     */
+    withStalenessNotice(result, projectPath) {
+        if (result.isError)
+            return result;
+        let cg;
+        try {
+            cg = this.getCodeGraph(projectPath);
+        }
+        catch {
+            return result; // no default project — leave as is
+        }
+        // Cross-project `projectPath` calls open a cached CodeGraph WITHOUT a
+        // watcher (watchers are only attached to the default session project).
+        // When the cross-project path happens to be the same project as the
+        // default cg, the cached instance is the wrong one — its pendingFiles is
+        // permanently empty. Detect the equal-path case and prefer the default
+        // cg so the staleness signal still fires when an agent passes the
+        // explicit projectPath form of its own project.
+        if (this.cg && cg !== this.cg) {
+            try {
+                const sameProject = (0, path_1.resolve)(this.cg.getProjectRoot()) === (0, path_1.resolve)(cg.getProjectRoot());
+                if (sameProject)
+                    cg = this.cg;
+            }
+            catch {
+                /* getProjectRoot may throw on a closed instance — leave cg as is */
+            }
+        }
+        // Defensive: some test fakes inject a partial CodeGraph stub without the
+        // newer pending-files API. Treat missing/throwing as "no pending files."
+        let pending = [];
+        try {
+            pending = cg.getPendingFiles?.() ?? [];
+        }
+        catch {
+            return result;
+        }
+        if (pending.length === 0)
+            return result;
+        const [first, ...rest] = result.content;
+        if (!first || first.type !== 'text')
+            return result;
+        const text = first.text;
+        const inResponse = [];
+        const elsewhere = [];
+        for (const p of pending) {
+            // Substring match against the project-relative POSIX path — that's
+            // exactly the format both the watcher and every codegraph response
+            // emit, so a plain includes() is sufficient and avoids regex pitfalls.
+            if (text.includes(p.path))
+                inResponse.push(p);
+            else
+                elsewhere.push(p);
+        }
+        let banner = '';
+        if (inResponse.length > 0) {
+            banner = formatStaleBanner(inResponse);
+        }
+        let footer = '';
+        if (elsewhere.length > 0) {
+            footer = formatStaleFooter(elsewhere);
+        }
+        if (!banner && !footer)
+            return result;
+        const composed = [banner, text, footer].filter(Boolean).join('\n\n');
+        return { ...result, content: [{ type: 'text', text: composed }, ...rest] };
+    }
     /**
      * Execute a tool by name
      */
@@ -695,30 +867,51 @@ class ToolHandler {
                 if (typeof check === 'object' && check !== undefined)
                     return check;
             }
+            // Read tools resolve through a single result variable so cross-cutting
+            // notices — worktree-index mismatch (issue #155) and per-file
+            // staleness (issue #403) — can be applied in one place. status embeds
+            // its own verbose worktree warning but still flows through the
+            // staleness wrapper so its pending-files section stays consistent
+            // with what the read tools surface.
+            let result;
             switch (toolName) {
                 case 'codegraph_search':
-                    return await this.handleSearch(args);
+                    result = await this.handleSearch(args);
+                    break;
                 case 'codegraph_context':
-                    return await this.handleContext(args);
+                    result = await this.handleContext(args);
+                    break;
                 case 'codegraph_callers':
-                    return await this.handleCallers(args);
+                    result = await this.handleCallers(args);
+                    break;
                 case 'codegraph_callees':
-                    return await this.handleCallees(args);
+                    result = await this.handleCallees(args);
+                    break;
                 case 'codegraph_impact':
-                    return await this.handleImpact(args);
+                    result = await this.handleImpact(args);
+                    break;
                 case 'codegraph_explore':
-                    return await this.handleExplore(args);
+                    result = await this.handleExplore(args);
+                    break;
                 case 'codegraph_node':
-                    return await this.handleNode(args);
+                    result = await this.handleNode(args);
+                    break;
                 case 'codegraph_status':
+                    // status embeds the pending-files list as a first-class section
+                    // (see handleStatus), so we skip the auto-banner wrapper here to
+                    // avoid duplicating the same info at the top of the response.
                     return await this.handleStatus(args);
                 case 'codegraph_files':
-                    return await this.handleFiles(args);
+                    result = await this.handleFiles(args);
+                    break;
                 case 'codegraph_trace':
-                    return await this.handleTrace(args);
+                    result = await this.handleTrace(args);
+                    break;
                 default:
                     return this.errorResult(`Unknown tool: ${toolName}`);
             }
+            const withWorktree = this.withWorktreeNotice(result, args.projectPath);
+            return this.withStalenessNotice(withWorktree, args.projectPath);
         }
         catch (err) {
             return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -1870,16 +2063,34 @@ class ToolHandler {
      * Handle codegraph_status
      */
     async handleStatus(args) {
-        const cg = this.getCodeGraph(args.projectPath);
+        let cg = this.getCodeGraph(args.projectPath);
+        // Same trick as withStalenessNotice — when an explicit projectPath
+        // resolves to the same project as the default session cg, prefer the
+        // default so getPendingFiles() (only populated by the default's watcher)
+        // is non-empty when there are pending edits.
+        if (this.cg && cg !== this.cg) {
+            try {
+                if ((0, path_1.resolve)(this.cg.getProjectRoot()) === (0, path_1.resolve)(cg.getProjectRoot())) {
+                    cg = this.cg;
+                }
+            }
+            catch { /* closed instance — leave as is */ }
+        }
         const stats = cg.getStats();
+        // Warn when this index actually belongs to a different git working tree
+        // (e.g. the server resolved up from a nested worktree to the main checkout).
+        // Queries then reflect that tree's branch, not the worktree being edited.
+        // status shows the verbose, multi-line form; the read tools get the compact
+        // one-liner via withWorktreeNotice. Both share the cached detection.
+        const mismatch = this.worktreeMismatchFor(args.projectPath);
         const lines = [
             '## CodeGraph Status',
             '',
-            `**Files indexed:** ${stats.fileCount}`,
-            `**Total nodes:** ${stats.nodeCount}`,
-            `**Total edges:** ${stats.edgeCount}`,
-            `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`,
         ];
+        if (mismatch) {
+            lines.push(`> ⚠ ${(0, worktree_1.worktreeMismatchWarning)(mismatch).replace(/\n/g, '\n> ')}`, '');
+        }
+        lines.push(`**Files indexed:** ${stats.fileCount}`, `**Total nodes:** ${stats.nodeCount}`, `**Total edges:** ${stats.edgeCount}`, `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`);
         // Surface the active SQLite backend (node:sqlite, Node's built-in real
         // SQLite — full WAL + FTS5, no native build).
         lines.push(`**Backend:** node:sqlite (Node built-in) — full WAL + FTS5`);
@@ -1907,6 +2118,20 @@ class ToolHandler {
                 lines.push(`- ${lang}: ${count}`);
             }
         }
+        // Per-file freshness — the inverse of the auto-prepended staleness banner
+        // (issue #403). Surfacing it inside `status` gives the agent a single
+        // place to ask "is the index caught up?" rather than inferring from
+        // banners on other tool calls.
+        const pending = cg.getPendingFiles();
+        if (pending.length > 0) {
+            lines.push('', '### Pending sync:');
+            const now = Date.now();
+            for (const p of pending) {
+                const ageMs = Math.max(0, now - p.lastSeenMs);
+                const label = p.indexing ? 'indexing in progress' : 'pending sync';
+                lines.push(`- ${p.path} (edited ${ageMs}ms ago, ${label})`);
+            }
+        }
         return this.textResult(lines.join('\n'));
     }
     /**