token-pilot 0.13.0 → 0.14.2

package/dist/core/session-cache.js

@@ -0,0 +1,162 @@
+import { createHash } from 'node:crypto';
+export class SessionCache {
+    maxEntries;
+    entries = new Map();
+    /** Reverse index: file path → set of cache keys that depend on it */
+    fileDepsIndex = new Map();
+    hits = 0;
+    misses = 0;
+    invalidations = 0;
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    /**
+     * Generate deterministic cache key from tool name + args.
+     * Sorts args keys for consistency regardless of insertion order.
+     */
+    static makeCacheKey(tool, args) {
+        const sorted = JSON.stringify(args, Object.keys(args).sort());
+        const hash = createHash('sha256').update(sorted).digest('hex').slice(0, 16);
+        return `${tool}:${hash}`;
+    }
+    /** Try to get a cached result. Returns null on miss. */
+    get(tool, args) {
+        const key = SessionCache.makeCacheKey(tool, args);
+        const entry = this.entries.get(key);
+        if (entry) {
+            this.hits++;
+            return entry;
+        }
+        this.misses++;
+        return null;
+    }
+    /** Store a result with its dependency metadata. */
+    set(tool, args, result, deps, tokenEstimate, tokensWouldBe) {
+        // LRU eviction if full
+        if (this.entries.size >= this.maxEntries) {
+            this.evictOldest();
+        }
+        const key = SessionCache.makeCacheKey(tool, args);
+        const fileDeps = new Set(deps.files ?? []);
+        const entry = {
+            result,
+            fileDeps,
+            dependsOnAst: deps.dependsOnAst ?? false,
+            dependsOnGit: deps.dependsOnGit ?? false,
+            cachedAt: Date.now(),
+            tokenEstimate,
+            tokensWouldBe,
+        };
+        this.entries.set(key, entry);
+        // Update reverse index
+        for (const dep of fileDeps) {
+            let keys = this.fileDepsIndex.get(dep);
+            if (!keys) {
+                keys = new Set();
+                this.fileDepsIndex.set(dep, keys);
+            }
+            keys.add(key);
+        }
+    }
+    /**
+     * Invalidate all entries that depend on any of the given files.
+     * Checks both exact path match and directory prefix match.
+     */
+    invalidateByFiles(filePaths) {
+        let count = 0;
+        const keysToDelete = new Set();
+        for (const changedFile of filePaths) {
+            // Exact match from reverse index
+            const exactKeys = this.fileDepsIndex.get(changedFile);
+            if (exactKeys) {
+                for (const key of exactKeys)
+                    keysToDelete.add(key);
+            }
+            // Directory prefix match: check if changedFile is under any cached dir dep
+            for (const [dep, keys] of this.fileDepsIndex) {
+                if (dep.endsWith('/') && changedFile.startsWith(dep)) {
+                    for (const key of keys)
+                        keysToDelete.add(key);
+                }
+            }
+        }
+        for (const key of keysToDelete) {
+            this.deleteEntry(key);
+            count++;
+        }
+        this.invalidations += count;
+        return count;
+    }
+    /** Invalidate all entries that depend on AST index state. */
+    invalidateByAst() {
+        let count = 0;
+        for (const [key, entry] of this.entries) {
+            if (entry.dependsOnAst) {
+                this.deleteEntry(key);
+                count++;
+            }
+        }
+        this.invalidations += count;
+        return count;
+    }
+    /** Invalidate all entries that depend on git state. */
+    invalidateByGit() {
+        let count = 0;
+        for (const [key, entry] of this.entries) {
+            if (entry.dependsOnGit) {
+                this.deleteEntry(key);
+                count++;
+            }
+        }
+        this.invalidations += count;
+        return count;
+    }
+    /** Clear all entries. */
+    invalidateAll() {
+        const count = this.entries.size;
+        this.entries.clear();
+        this.fileDepsIndex.clear();
+        this.invalidations += count;
+    }
+    /** Cache statistics for analytics. */
+    stats() {
+        const total = this.hits + this.misses;
+        return {
+            entries: this.entries.size,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total > 0 ? Math.round((this.hits / total) * 100) : 0,
+            invalidations: this.invalidations,
+        };
+    }
+    // --- Private helpers ---
+    deleteEntry(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        // Clean up reverse index
+        for (const dep of entry.fileDeps) {
+            const keys = this.fileDepsIndex.get(dep);
+            if (keys) {
+                keys.delete(key);
+                if (keys.size === 0)
+                    this.fileDepsIndex.delete(dep);
+            }
+        }
+        this.entries.delete(key);
+    }
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.entries) {
+            if (entry.cachedAt < oldestTime) {
+                oldestTime = entry.cachedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            this.deleteEntry(oldestKey);
+        }
+    }
+}
+//# sourceMappingURL=session-cache.js.map

package/dist/core/validation.d.ts

@@ -64,6 +64,9 @@ export declare function validateReadForEditArgs(args: unknown): {
     symbol?: string;
     line?: number;
     context?: number;
+    include_callers?: boolean;
+    include_tests?: boolean;
+    include_changes?: boolean;
 };
 /**
  * Validate related_files arguments.

package/dist/core/validation.js

@@ -184,6 +184,9 @@ export function validateReadForEditArgs(args) {
         symbol: optionalString(a.symbol, 'symbol'),
         line: optionalNumber(a.line, 'line'),
         context: optionalNumber(a.context, 'context'),
+        include_callers: optionalBool(a.include_callers, 'include_callers'),
+        include_tests: optionalBool(a.include_tests, 'include_tests'),
+        include_changes: optionalBool(a.include_changes, 'include_changes'),
     };
 }
 /**

package/dist/git/file-watcher.d.ts

@@ -18,10 +18,16 @@ export declare class FileWatcher {
     private watcher;
     private watchedFiles;
     private updateTimer;
+    private fileChangeCallback;
+    private astUpdateCallback;
     constructor(_projectRoot: string, fileCache: FileCache, contextRegistry: ContextRegistry, _ignore: string[], astIndex?: AstIndexClient);
     start(): void;
     /** Debounced ast-index incremental update after file changes */
     private scheduleIndexUpdate;
+    /** Register callback for file change/unlink events. */
+    onFileChange(callback: (absPath: string) => void): void;
+    /** Register callback for after AST index incremental update completes. */
+    onAstUpdate(callback: () => void): void;
     /** Add a specific file to watch. Called after smart_read/read_symbol loads a file. */
     watchFile(filePath: string): void;
     stop(): void;

package/dist/git/file-watcher.js

@@ -17,6 +17,8 @@ export class FileWatcher {
     watcher = null;
     watchedFiles = new Set();
     updateTimer = null;
+    fileChangeCallback = null;
+    astUpdateCallback = null;
     constructor(_projectRoot, fileCache, contextRegistry, _ignore, astIndex) {
         this.fileCache = fileCache;
         this.contextRegistry = contextRegistry;
@@ -37,6 +39,7 @@ export class FileWatcher {
             if (this.fileCache.get(absPath)) {
                 this.fileCache.invalidate(absPath);
             }
+            this.fileChangeCallback?.(absPath);
             this.scheduleIndexUpdate();
         });
         this.watcher.on('unlink', (filePath) => {
@@ -44,6 +47,7 @@ export class FileWatcher {
             this.fileCache.invalidate(absPath);
             this.contextRegistry.forget(absPath);
             this.watchedFiles.delete(absPath);
+            this.fileChangeCallback?.(absPath);
             this.scheduleIndexUpdate();
         });
     }
@@ -53,10 +57,22 @@ export class FileWatcher {
             return;
         if (this.updateTimer)
             clearTimeout(this.updateTimer);
-        this.updateTimer = setTimeout(() => {
-            this.astIndex?.incrementalUpdate().catch(() => { });
+        this.updateTimer = setTimeout(async () => {
+            try {
+                await this.astIndex?.incrementalUpdate();
+                this.astUpdateCallback?.();
+            }
+            catch { /* ignore */ }
         }, FileWatcher.UPDATE_DEBOUNCE_MS);
     }
+    /** Register callback for file change/unlink events. */
+    onFileChange(callback) {
+        this.fileChangeCallback = callback;
+    }
+    /** Register callback for after AST index incremental update completes. */
+    onAstUpdate(callback) {
+        this.astUpdateCallback = callback;
+    }
     /** Add a specific file to watch. Called after smart_read/read_symbol loads a file. */
     watchFile(filePath) {
         const absPath = resolve(filePath);

package/dist/git/watcher.d.ts

@@ -7,6 +7,7 @@ export declare class GitWatcher {
     private watcher;
     private headRef;
     private enabled;
+    private branchSwitchCallback;
     constructor(projectRoot: string, fileCache: FileCache, contextRegistry: ContextRegistry, enabled: boolean);
     start(): Promise<void>;
     stop(): void;
@@ -19,6 +20,8 @@ export declare class GitWatcher {
      * Get files changed in the last N commits.
      */
     getRecentlyChangedFiles(commits?: number): Promise<string[]>;
+    /** Register callback for branch switch events. */
+    onBranchSwitchEvent(callback: (changedFiles: string[]) => void): void;
     private onBranchSwitch;
     private readHead;
 }

package/dist/git/watcher.js

@@ -11,6 +11,7 @@ export class GitWatcher {
     watcher = null;
     headRef = '';
     enabled;
+    branchSwitchCallback = null;
     constructor(projectRoot, fileCache, contextRegistry, enabled) {
         this.projectRoot = projectRoot;
         this.fileCache = fileCache;
@@ -78,6 +79,10 @@ export class GitWatcher {
             return [];
         }
     }
+    /** Register callback for branch switch events. */
+    onBranchSwitchEvent(callback) {
+        this.branchSwitchCallback = callback;
+    }
     async onBranchSwitch() {
         // On branch switch, get files that differ between old and new branch
         // and selectively invalidate only those
@@ -85,6 +90,7 @@ export class GitWatcher {
         if (changed.length > 0) {
             await this.fileCache.invalidateByGitDiff(changed);
             this.contextRegistry.invalidateByGitDiff(changed);
+            this.branchSwitchCallback?.(changed);
         }
     }
     async readHead() {

package/dist/handlers/code-audit.d.ts

@@ -1,9 +1,14 @@
 import type { AstIndexClient } from '../ast-index/client.js';
 import type { CodeAuditArgs } from '../core/validation.js';
-export declare function handleCodeAudit(args: CodeAuditArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
+type AuditResult = {
     content: Array<{
         type: 'text';
         text: string;
     }>;
-}>;
+    meta: {
+        files: string[];
+    };
+};
+export declare function handleCodeAudit(args: CodeAuditArgs, projectRoot: string, astIndex: AstIndexClient): Promise<AuditResult>;
+export {};
 //# sourceMappingURL=code-audit.d.ts.map

package/dist/handlers/code-audit.js

@@ -6,6 +6,7 @@ export async function handleCodeAudit(args, projectRoot, astIndex) {
                     type: 'text',
                     text: 'ast-index is not available (project root too broad or index oversized). Use Grep/ripgrep for pattern search.',
                 }],
+            meta: { files: [] },
         };
     }
     const limit = args.limit ?? 50;
@@ -27,6 +28,7 @@ export async function handleCodeAudit(args, projectRoot, astIndex) {
                         type: 'text',
                         text: `Unknown check type: "${args.check}". Use: pattern, todo, deprecated, annotations, all`,
                     }],
+                meta: { files: [] },
             };
     }
 }
@@ -42,6 +44,7 @@ async function handlePattern(pattern, lang, limit, projectRoot, astIndex) {
                         type: 'text',
                         text: `PATTERN SEARCH: "${pattern}"${lang ? ` (${lang})` : ''}\n\nNo matches found.\n\nHINT: Try Grep/ripgrep for text-based search if the pattern is not structural.`,
                     }],
+                meta: { files: [] },
             };
         }
         // Group by file
@@ -64,7 +67,7 @@ async function handlePattern(pattern, lang, limit, projectRoot, astIndex) {
             lines.push('');
         }
         lines.push('HINT: Use read_symbol() to inspect specific matches, or Grep for text-based counting.');
-        return { content: [{ type: 'text', text: lines.join('\n') }] };
+        return { content: [{ type: 'text', text: lines.join('\n') }], meta: { files: [...byFile.keys()] } };
     }
     catch (err) {
         // ast-grep not installed — return the error message
@@ -73,6 +76,7 @@ async function handlePattern(pattern, lang, limit, projectRoot, astIndex) {
                     type: 'text',
                     text: `PATTERN SEARCH ERROR:\n${err instanceof Error ? err.message : String(err)}\n\nFallback: Use Grep/ripgrep for text-based pattern search.`,
                 }],
+            meta: { files: [] },
         };
     }
 }
@@ -85,6 +89,7 @@ async function handleTodo(limit, projectRoot, astIndex) {
                     type: 'text',
                     text: 'TODO/FIXME COMMENTS: none found.\n\nHINT: ast-index may not detect all comment formats. Try Grep: grep -rn "TODO\\|FIXME\\|HACK" --include="*.ts"',
                 }],
+            meta: { files: [] },
         };
     }
     // Group by kind
@@ -106,7 +111,8 @@ async function handleTodo(limit, projectRoot, astIndex) {
         }
         lines.push('');
     }
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
+    const todoFiles = [...new Set(limited.map(e => e.file))];
+    return { content: [{ type: 'text', text: lines.join('\n') }], meta: { files: todoFiles } };
 }
 async function handleDeprecated(limit, projectRoot, astIndex) {
     const entries = await astIndex.deprecated();
@@ -117,6 +123,7 @@ async function handleDeprecated(limit, projectRoot, astIndex) {
                     type: 'text',
                     text: 'DEPRECATED SYMBOLS: none found.\n\nHINT: ast-index detects @Deprecated annotations. Try Grep for other deprecation patterns.',
                 }],
+            meta: { files: [] },
         };
     }
     const lines = [
@@ -129,7 +136,8 @@ async function handleDeprecated(limit, projectRoot, astIndex) {
     }
     lines.push('');
     lines.push('HINT: Use read_symbol() to inspect deprecated symbols before removing them.');
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
+    const depFiles = [...new Set(limited.map(e => e.file))];
+    return { content: [{ type: 'text', text: lines.join('\n') }], meta: { files: depFiles } };
 }
 async function handleAnnotations(name, limit, projectRoot, astIndex) {
     const entries = await astIndex.annotations(name);
@@ -140,6 +148,7 @@ async function handleAnnotations(name, limit, projectRoot, astIndex) {
                     type: 'text',
                     text: `ANNOTATIONS @${name}: none found.\n\nHINT: Try Grep for text-based search: grep -rn "@${name}" --include="*.ts"`,
                 }],
+            meta: { files: [] },
         };
     }
     // Group by file
@@ -161,7 +170,8 @@ async function handleAnnotations(name, limit, projectRoot, astIndex) {
         }
         lines.push('');
     }
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
+    const annFiles = [...new Set(limited.map(e => e.file))];
+    return { content: [{ type: 'text', text: lines.join('\n') }], meta: { files: annFiles } };
 }
 async function handleAll(limit, projectRoot, astIndex) {
     // Run todo + deprecated in parallel
@@ -196,6 +206,10 @@ async function handleAll(limit, projectRoot, astIndex) {
     sections.push('');
     sections.push('HINT: Use code_audit(check="pattern", pattern="...") for structural pattern search (requires ast-grep).');
     sections.push('      Use Grep for text-based counting and regex search.');
-    return { content: [{ type: 'text', text: sections.join('\n') }] };
+    const allFiles = [...new Set([
+            ...todos.slice(0, limit).map(e => e.file),
+            ...deprecated.slice(0, limit).map(e => e.file),
+        ])];
+    return { content: [{ type: 'text', text: sections.join('\n') }], meta: { files: allFiles } };
 }
 //# sourceMappingURL=code-audit.js.map

package/dist/handlers/explore-area.d.ts

@@ -1,9 +1,19 @@
 import type { AstIndexClient } from '../ast-index/client.js';
 import type { ExploreAreaArgs } from '../core/validation.js';
+export interface ExploreAreaMeta {
+    dir: string;
+    codeFiles: string[];
+    testFiles: string[];
+    internalDeps: string[];
+    importedBy: string[];
+    externalDeps: string[];
+    changeCount: number;
+}
 export declare function handleExploreArea(args: ExploreAreaArgs, projectRoot: string, astIndex: AstIndexClient): Promise<{
     content: Array<{
         type: 'text';
         text: string;
     }>;
+    meta: ExploreAreaMeta;
 }>;
 //# sourceMappingURL=explore-area.d.ts.map

package/dist/handlers/explore-area.js

@@ -20,6 +20,15 @@ export async function handleExploreArea(args, projectRoot, astIndex) {
     if (!pathStat) {
         return {
             content: [{ type: 'text', text: `Path "${args.path}" not found.` }],
+            meta: {
+                dir: args.path,
+                codeFiles: [],
+                testFiles: [],
+                internalDeps: [],
+                importedBy: [],
+                externalDeps: [],
+                changeCount: 0,
+            },
         };
     }
     if (!pathStat.isDirectory()) {
@@ -49,17 +58,17 @@ export async function handleExploreArea(args, projectRoot, astIndex) {
         lines.push('');
     }
     // Imports
-    const importLines = extractResult(importsSection);
+    const importLines = extractResult(importsSection)?.lines ?? null;
     if (importLines) {
         lines.push(...importLines);
     }
     // Tests
-    const testLines = extractResult(testsSection);
+    const testLines = extractResult(testsSection)?.lines ?? null;
     if (testLines) {
         lines.push(...testLines);
     }
     // Changes
-    const changeLines = extractResult(changesSection);
+    const changeLines = extractResult(changesSection)?.lines ?? null;
     if (changeLines) {
         lines.push(...changeLines);
     }
@@ -69,7 +78,18 @@ export async function handleExploreArea(args, projectRoot, astIndex) {
         lines.push('... truncated. Use outline() on specific subdirectories for details.');
     }
     lines.push('HINT: Use smart_read(file) for details, read_symbol(path, symbol) for source code, find_usages(symbol) for references.');
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        meta: {
+            dir: relDir,
+            codeFiles: codeFiles.map((file) => relative(projectRoot, file)).sort(),
+            testFiles: extractResult(testsSection)?.testFiles ?? [],
+            internalDeps: extractResult(importsSection)?.internalDeps ?? [],
+            importedBy: extractResult(importsSection)?.importedBy ?? [],
+            externalDeps: extractResult(importsSection)?.externalDeps ?? [],
+            changeCount: extractResult(changesSection)?.count ?? 0,
+        },
+    };
 }
 // ──────────────────────────────────────────────
 // Outline section — reuses outlineDir from outline.ts
@@ -84,7 +104,7 @@ async function buildOutlineSection(absPath, projectRoot, astIndex) {
 // ──────────────────────────────────────────────
 async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
     if (!astIndex.isAvailable() || astIndex.isDisabled() || astIndex.isOversized()) {
-        return [];
+        return { lines: [], internalDeps: [], importedBy: [], externalDeps: [] };
     }
     const filesToAnalyze = codeFiles.slice(0, MAX_IMPORT_FILES);
     const externalDeps = new Set();
@@ -150,7 +170,12 @@ async function buildImportsSection(codeFiles, absPath, projectRoot, astIndex) {
     }
     if (lines.length > 0)
         lines.push('');
-    return lines;
+    return {
+        lines,
+        internalDeps: Array.from(internalDeps).sort(),
+        importedBy: Array.from(importedBy).sort(),
+        externalDeps: Array.from(externalDeps).sort(),
+    };
 }
 // ──────────────────────────────────────────────
 // Tests section — find test/spec files matching area files
@@ -215,11 +240,11 @@ async function buildTestsSection(codeFiles, absPath, projectRoot) {
         catch { /* skip unreadable dirs */ }
     }
     if (testFiles.length === 0)
-        return [];
+        return { lines: [], testFiles: [] };
     const lines = [];
     lines.push(`TESTS: ${testFiles.join(', ')}`);
     lines.push('');
-    return lines;
+    return { lines, testFiles: [...testFiles].sort() };
 }
 // ──────────────────────────────────────────────
 // Changes section — recent git log for this area
@@ -228,24 +253,25 @@ async function buildChangesSection(relDir, projectRoot) {
     try {
         const { stdout } = await execFileAsync('git', ['log', '--oneline', '-5', '--', relDir], { cwd: projectRoot, timeout: 5000 });
         if (!stdout.trim())
-            return [];
+            return { lines: [], count: 0 };
         const lines = [];
+        const commits = stdout.trim().split('\n');
         lines.push('RECENT CHANGES:');
-        for (const line of stdout.trim().split('\n')) {
+        for (const line of commits) {
             lines.push(`  ${line}`);
         }
         lines.push('');
-        return lines;
+        return { lines, count: commits.length };
     }
     catch {
-        return [];
+        return { lines: [], count: 0 };
     }
 }
 // ──────────────────────────────────────────────
 // Helpers
 // ──────────────────────────────────────────────
 function extractResult(settled) {
-    if (settled.status === 'fulfilled' && settled.value && settled.value.length > 0) {
+    if (settled.status === 'fulfilled' && settled.value) {
         return settled.value;
     }
     return null;

package/dist/handlers/find-unused.d.ts

@@ -9,5 +9,8 @@ export declare function handleFindUnused(args: FindUnusedArgs, astIndex: AstInde
         type: 'text';
         text: string;
     }>;
+    meta: {
+        files: string[];
+    };
 }>;
 //# sourceMappingURL=find-unused.d.ts.map

package/dist/handlers/find-unused.js

@@ -18,7 +18,7 @@ export async function handleFindUnused(args, astIndex) {
         return { content: [{ type: 'text', text: 'find_unused is disabled: ' + (astIndex.isDisabled()
                         ? 'project root not detected. Call smart_read() on any project file first — this auto-detects the project root and enables ast-index tools.'
                         : 'ast-index built >50k files (likely includes node_modules). Ensure node_modules is in .gitignore.') +
-                        '\nAlternative: use grep_search to find unused exports manually.' }] };
+                        '\nAlternative: use grep_search to find unused exports manually.' }], meta: { files: [] } };
     }
     const requestLimit = (args.limit ?? 30) + 20; // extra to compensate for filtering
     const unused = await astIndex.unusedSymbols({
@@ -67,6 +67,7 @@ export async function handleFindUnused(args, astIndex) {
                         ? `No unused symbols found in module "${args.module}".${excluded > 0 ? ` (${excluded} constructors/protocol methods excluded)` : ''}`
                         : `No unused symbols found in the project.${excluded > 0 ? ` (${excluded} constructors/protocol methods excluded)` : ''}`,
                 }],
+            meta: { files: [] },
         };
     }
     const lines = [];
@@ -100,7 +101,7 @@ export async function handleFindUnused(args, astIndex) {
         lines.push(`(${langExcluded} constructors/protocol methods excluded)`);
     }
     lines.push('NOTE: Verify before removing — symbols may be used dynamically, in tests, or via framework conventions.');
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
+    return { content: [{ type: 'text', text: lines.join('\n') }], meta: { files: uniqueFiles } };
 }
 /**
  * Find decorators for a symbol by matching name + line in the outline tree.

package/dist/handlers/find-usages.d.ts

@@ -15,5 +15,12 @@ export declare function handleFindUsages(args: FindUsagesArgs, astIndex: AstInde
         type: 'text';
         text: string;
     }>;
+    meta: {
+        files: string[];
+        definitions: number;
+        imports: number;
+        usages: number;
+        total: number;
+    };
 }>;
 //# sourceMappingURL=find-usages.d.ts.map