token-pilot 0.13.0 → 0.14.1

package/dist/core/decision-trace.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Decision trace — captures pre/post-execution metadata for analytics.
+ * Provides instrumentation data for budget planner advisory.
+ */
+import type { ContextRegistry } from './context-registry.js';
+import type { FileCache } from './file-cache.js';
+export interface DecisionTrace {
+    fileSize?: number;
+    fileTotalLines?: number;
+    alreadyInContext: boolean;
+    estimatedCost: number;
+    actualCost: number;
+    cheaperAlternative?: string;
+    cheaperEstimate?: number;
+}
+export interface BuildTraceOptions {
+    absPath?: string;
+    tool: string;
+    args: Record<string, unknown>;
+    contextRegistry: ContextRegistry;
+    fileCache: FileCache;
+    tokensReturned: number;
+    tokensWouldBe: number;
+    recentlyEdited?: boolean;
+}
+/**
+ * Build a decision trace for a tool call.
+ * Gathers file metadata, context state, and budget planner advice.
+ */
+export declare function buildDecisionTrace(opts: BuildTraceOptions): DecisionTrace;
+//# sourceMappingURL=decision-trace.d.ts.map

package/dist/core/decision-trace.js

@@ -0,0 +1,45 @@
+/**
+ * Decision trace — captures pre/post-execution metadata for analytics.
+ * Provides instrumentation data for budget planner advisory.
+ */
+import { suggestCheaperAlternative } from './budget-planner.js';
+/**
+ * Build a decision trace for a tool call.
+ * Gathers file metadata, context state, and budget planner advice.
+ */
+export function buildDecisionTrace(opts) {
+    const { absPath, tool, args, contextRegistry, fileCache, tokensReturned, tokensWouldBe } = opts;
+    let fileSize;
+    let fileTotalLines;
+    let alreadyInContext = false;
+    if (absPath) {
+        // Get file info from cache if available
+        const cached = fileCache.get(absPath);
+        if (cached) {
+            fileSize = cached.structure?.meta?.bytes;
+            fileTotalLines = cached.lines?.length ?? cached.structure?.meta?.lines;
+        }
+        alreadyInContext = contextRegistry.hasAnyLoaded(absPath);
+    }
+    const trace = {
+        fileSize,
+        fileTotalLines,
+        alreadyInContext,
+        estimatedCost: tokensWouldBe,
+        actualCost: tokensReturned,
+    };
+    // Budget planner advisory
+    const symbolKnown = !!(args.symbol || args.name);
+    const suggestion = suggestCheaperAlternative(tool, args, {
+        fileLines: fileTotalLines,
+        alreadyInContext,
+        symbolKnown,
+        recentlyEdited: opts.recentlyEdited ?? false,
+    });
+    if (suggestion) {
+        trace.cheaperAlternative = suggestion.tool;
+        trace.cheaperEstimate = suggestion.estimatedTokens;
+    }
+    return trace;
+}
+//# sourceMappingURL=decision-trace.js.map

package/dist/core/intent-classifier.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Intent classifier — maps tool + args to a task intent category.
+ * Used for per-intent analytics: which workflows save most tokens?
+ */
+export type Intent = 'edit' | 'debug' | 'explore' | 'review' | 'analyze' | 'search' | 'read';
+/**
+ * Classify the intent of a tool call based on tool name and optional args.
+ * Returns a stable intent category for analytics grouping.
+ */
+export declare function classifyIntent(tool: string, _args?: Record<string, unknown>): Intent;
+/** Get all known intents for iteration in reports. */
+export declare const ALL_INTENTS: readonly Intent[];
+//# sourceMappingURL=intent-classifier.d.ts.map

package/dist/core/intent-classifier.js

@@ -0,0 +1,44 @@
+/**
+ * Intent classifier — maps tool + args to a task intent category.
+ * Used for per-intent analytics: which workflows save most tokens?
+ */
+const TOOL_INTENT_MAP = {
+    // Edit workflow
+    read_for_edit: 'edit',
+    // Review workflow
+    smart_diff: 'review',
+    smart_log: 'review',
+    read_diff: 'review',
+    // Explore workflow
+    project_overview: 'explore',
+    explore_area: 'explore',
+    outline: 'explore',
+    // Search workflow
+    find_usages: 'search',
+    related_files: 'search',
+    // Analyze workflow
+    code_audit: 'analyze',
+    find_unused: 'analyze',
+    module_info: 'analyze',
+    // Debug workflow
+    test_summary: 'debug',
+    // Read workflow (default for reading tools)
+    smart_read: 'read',
+    read_symbol: 'read',
+    read_range: 'read',
+    smart_read_many: 'read',
+    // Analytics (meta — classify as explore)
+    session_analytics: 'explore',
+};
+/**
+ * Classify the intent of a tool call based on tool name and optional args.
+ * Returns a stable intent category for analytics grouping.
+ */
+export function classifyIntent(tool, _args) {
+    return TOOL_INTENT_MAP[tool] ?? 'read';
+}
+/** Get all known intents for iteration in reports. */
+export const ALL_INTENTS = [
+    'edit', 'debug', 'explore', 'review', 'analyze', 'search', 'read',
+];
+//# sourceMappingURL=intent-classifier.js.map

package/dist/core/policy-engine.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Policy engine — configurable team policies for consistent token savings.
+ * Phase 1: advisory-only warnings, no blocking.
+ * Track 10: Team Policy Mode
+ */
+export interface PolicyConfig {
+    /** Advisory hints when an expensive tool is used where a cheaper alternative exists */
+    preferCheapReads: boolean;
+    /** Track if read_for_edit was called before edit (advisory) */
+    requireReadForEditBeforeEdit: boolean;
+    /** Always cache project overview in session cache */
+    cacheProjectOverview: boolean;
+    /** Warn after N full-file reads in a session */
+    maxFullFileReads: number;
+    /** Warn when a single response exceeds this token threshold */
+    warnOnLargeReads: boolean;
+    /** Token threshold for large read warning */
+    largeReadThreshold: number;
+}
+export declare const DEFAULT_POLICIES: PolicyConfig;
+export interface PolicyCheckContext {
+    fullFileReadsCount: number;
+    tokensReturned: number;
+    readForEditCalled?: Set<string>;
+    editTargetPath?: string;
+}
+export interface PolicyAdvisory {
+    level: 'info' | 'warn';
+    message: string;
+}
+/**
+ * Check policy rules and return advisory messages.
+ * Returns null if no policy violation detected.
+ */
+export declare function checkPolicy(policy: PolicyConfig, tool: string, context: PolicyCheckContext): PolicyAdvisory | null;
+/**
+ * Count how many full-file reads a tool represents.
+ * Returns 1 for full-read tools, 0 for targeted tools.
+ */
+export declare function isFullReadTool(tool: string): boolean;
+//# sourceMappingURL=policy-engine.d.ts.map

package/dist/core/policy-engine.js

@@ -0,0 +1,76 @@
+/**
+ * Policy engine — configurable team policies for consistent token savings.
+ * Phase 1: advisory-only warnings, no blocking.
+ * Track 10: Team Policy Mode
+ */
+export const DEFAULT_POLICIES = {
+    preferCheapReads: true,
+    requireReadForEditBeforeEdit: true,
+    cacheProjectOverview: true,
+    maxFullFileReads: 10,
+    warnOnLargeReads: true,
+    largeReadThreshold: 2000,
+};
+/** Full-file read tools that count toward maxFullFileReads */
+const FULL_READ_TOOLS = new Set([
+    'smart_read',
+    'smart_read_many',
+]);
+/** Tools that indicate a cheaper alternative may exist */
+const EXPENSIVE_TOOLS = {
+    smart_read: 'Consider read_symbol() or read_range() for targeted reads',
+    smart_read_many: 'Consider reading files individually with read_symbol()',
+};
+/**
+ * Check policy rules and return advisory messages.
+ * Returns null if no policy violation detected.
+ */
+export function checkPolicy(policy, tool, context) {
+    // 1. Max full-file reads exceeded
+    if (policy.maxFullFileReads > 0 &&
+        FULL_READ_TOOLS.has(tool) &&
+        context.fullFileReadsCount >= policy.maxFullFileReads) {
+        return {
+            level: 'warn',
+            message: `POLICY: ${context.fullFileReadsCount} full-file reads this session (limit: ${policy.maxFullFileReads}). Consider read_symbol() or read_range() for targeted access.`,
+        };
+    }
+    // 2. Large read warning
+    if (policy.warnOnLargeReads &&
+        context.tokensReturned > policy.largeReadThreshold) {
+        return {
+            level: 'info',
+            message: `POLICY: Large response (~${context.tokensReturned} tokens). Future reads on this file: use read_symbol() or read_range() for targeted access.`,
+        };
+    }
+    // 3. Prefer cheap reads advisory
+    if (policy.preferCheapReads && EXPENSIVE_TOOLS[tool]) {
+        // Only advise when token count is high enough to matter
+        if (context.tokensReturned > 500) {
+            return {
+                level: 'info',
+                message: `POLICY: ${EXPENSIVE_TOOLS[tool]}`,
+            };
+        }
+    }
+    // 4. Require read_for_edit before edit
+    if (policy.requireReadForEditBeforeEdit &&
+        tool === 'edit' &&
+        context.editTargetPath &&
+        context.readForEditCalled &&
+        !context.readForEditCalled.has(context.editTargetPath)) {
+        return {
+            level: 'info',
+            message: `POLICY: Consider using read_for_edit("${context.editTargetPath}") before editing to get precise edit context.`,
+        };
+    }
+    return null;
+}
+/**
+ * Count how many full-file reads a tool represents.
+ * Returns 1 for full-read tools, 0 for targeted tools.
+ */
+export function isFullReadTool(tool) {
+    return FULL_READ_TOOLS.has(tool);
+}
+//# sourceMappingURL=policy-engine.js.map

package/dist/core/session-analytics.d.ts

@@ -1,4 +1,7 @@
 import type { ContextModeStatus } from '../integration/context-mode-detector.js';
+import type { Intent } from './intent-classifier.js';
+import type { DecisionTrace } from './decision-trace.js';
+export type SavingsCategory = 'compression' | 'cache' | 'dedup' | 'none';
 export interface ToolCall {
     tool: string;
     path?: string;
@@ -6,7 +9,12 @@ export interface ToolCall {
     tokensWouldBe: number;
     timestamp: number;
     delegatedToContextMode?: boolean;
+    sessionCacheHit?: boolean;
+    savingsCategory?: SavingsCategory;
+    intent?: Intent;
+    decisionTrace?: DecisionTrace;
 }
+export type { Intent, DecisionTrace };
 /**
  * Tracks token savings and tool usage across a session.
  * When context-mode is detected, includes unified reporting.

package/dist/core/session-analytics.js

@@ -1,4 +1,5 @@
 import { formatDuration } from './format-duration.js';
+import { ALL_INTENTS } from './intent-classifier.js';
 /**
  * Tracks token savings and tool usage across a session.
  * When context-mode is detected, includes unified reporting.
@@ -24,10 +25,11 @@ export class SessionAnalytics {
         // Group by tool
         const byTool = new Map();
         for (const c of this.calls) {
-            const existing = byTool.get(c.tool) ?? { count: 0, tokens: 0, saved: 0 };
+            const existing = byTool.get(c.tool) ?? { count: 0, tokens: 0, saved: 0, wouldBe: 0 };
             existing.count++;
             existing.tokens += c.tokensReturned;
             existing.saved += Math.max(0, c.tokensWouldBe - c.tokensReturned);
+            existing.wouldBe += c.tokensWouldBe;
             byTool.set(c.tool, existing);
         }
         const lines = [
@@ -39,8 +41,12 @@ export class SessionAnalytics {
             '',
             'By tool:',
         ];
-        for (const [tool, stats] of byTool) {
-            lines.push(`  ${tool}: ${stats.count} calls, ~${stats.tokens} tokens returned, ~${stats.saved} saved`);
+        const sortedTools = Array.from(byTool.entries()).sort((a, b) => b[1].saved - a[1].saved);
+        for (const [tool, stats] of sortedTools) {
+            const reduction = stats.wouldBe > 0
+                ? Math.round((1 - stats.tokens / stats.wouldBe) * 100)
+                : 0;
+            lines.push(`  ${tool}: ${stats.count} calls, ~${stats.tokens} tokens returned, ~${stats.saved} saved (${reduction}% reduction)`);
         }
         // Top files by savings
         const byFile = new Map();
@@ -60,11 +66,48 @@ export class SessionAnalytics {
                 lines.push(`  ${file}: ~${saved} tokens saved`);
             }
         }
-        // Reminders served (compact reminders that avoided re-reads)
-        const reminders = this.calls.filter(c => c.tokensWouldBe > 0 && c.tokensReturned < c.tokensWouldBe * 0.1);
-        if (reminders.length > 0) {
+        const lowValueTools = sortedTools
+            .map(([tool, stats]) => ({
+            tool,
+            reduction: stats.wouldBe > 0 ? Math.round((1 - stats.tokens / stats.wouldBe) * 100) : 0,
+            count: stats.count,
+        }))
+            .filter((tool) => tool.reduction < 20);
+        if (lowValueTools.length > 0) {
             lines.push('');
-            lines.push(`Compact reminders served: ${reminders.length} (avoided full re-reads)`);
+            lines.push('Needs improvement:');
+            for (const tool of lowValueTools.slice(0, 5)) {
+                lines.push(`  ${tool.tool}: only ${tool.reduction}% reduction across ${tool.count} call${tool.count === 1 ? '' : 's'}`);
+            }
+        }
+        // Savings breakdown by category
+        const byCategory = { compression: 0, cache: 0, dedup: 0, none: 0 };
+        for (const c of this.calls) {
+            const cat = c.savingsCategory ?? 'none';
+            byCategory[cat] += Math.max(0, c.tokensWouldBe - c.tokensReturned);
+        }
+        if (totalWouldBe > totalReturned) {
+            lines.push('');
+            lines.push('Savings breakdown:');
+            if (byCategory.compression > 0)
+                lines.push(`  Compression (AST/structured): ~${byCategory.compression} tokens`);
+            if (byCategory.cache > 0)
+                lines.push(`  Cache hits (session cache): ~${byCategory.cache} tokens`);
+            if (byCategory.dedup > 0)
+                lines.push(`  Dedup (already in context): ~${byCategory.dedup} tokens`);
+        }
+        // Session cache hits
+        const cacheHits = this.calls.filter(c => c.sessionCacheHit);
+        if (cacheHits.length > 0) {
+            const cacheTokensSaved = cacheHits.reduce((s, c) => s + Math.max(0, c.tokensWouldBe - c.tokensReturned), 0);
+            lines.push('');
+            lines.push(`Session cache: ${cacheHits.length} hits / ${this.calls.length} calls (${Math.round(cacheHits.length / this.calls.length * 100)}% hit rate, ~${cacheTokensSaved} tokens saved)`);
+        }
+        // Dedup reminders served
+        const dedupCalls = this.calls.filter(c => c.savingsCategory === 'dedup');
+        if (dedupCalls.length > 0) {
+            lines.push('');
+            lines.push(`Compact reminders/dedup: ${dedupCalls.length} calls (avoided full re-reads)`);
         }
         // Delegation stats
         const delegated = this.calls.filter(c => c.delegatedToContextMode);
@@ -72,6 +115,42 @@ export class SessionAnalytics {
             lines.push('');
             lines.push(`Delegated to context-mode: ${delegated.length} calls`);
         }
+        // Per-intent breakdown (Track 2)
+        const callsWithIntent = this.calls.filter(c => c.intent);
+        if (callsWithIntent.length > 0) {
+            const byIntent = new Map();
+            for (const c of callsWithIntent) {
+                const intent = c.intent;
+                const existing = byIntent.get(intent) ?? { count: 0, saved: 0 };
+                existing.count++;
+                existing.saved += Math.max(0, c.tokensWouldBe - c.tokensReturned);
+                byIntent.set(intent, existing);
+            }
+            lines.push('');
+            lines.push('Per-intent breakdown:');
+            for (const intent of ALL_INTENTS) {
+                const stats = byIntent.get(intent);
+                if (stats) {
+                    lines.push(`  ${intent}: ${stats.count} call${stats.count === 1 ? '' : 's'}, ~${stats.saved} tokens saved`);
+                }
+            }
+        }
+        // Decision insights (Track 0)
+        const tracedCalls = this.calls.filter(c => c.decisionTrace);
+        if (tracedCalls.length > 0) {
+            const alreadyInContextCount = tracedCalls.filter(c => c.decisionTrace.alreadyInContext).length;
+            const totalEstimated = tracedCalls.reduce((s, c) => s + c.decisionTrace.estimatedCost, 0);
+            const totalActual = tracedCalls.reduce((s, c) => s + c.decisionTrace.actualCost, 0);
+            const avgReduction = totalEstimated > 0 ? Math.round((1 - totalActual / totalEstimated) * 100) : 0;
+            const missedSavings = tracedCalls.filter(c => c.decisionTrace.cheaperAlternative).length;
+            lines.push('');
+            lines.push('Decision insights:');
+            lines.push(`  Files already in context: ${alreadyInContextCount} of ${tracedCalls.length} calls (${Math.round(alreadyInContextCount / tracedCalls.length * 100)}%)`);
+            lines.push(`  Avg cost reduction: ${avgReduction}% (estimated → actual)`);
+            if (missedSavings > 0) {
+                lines.push(`  Missed savings opportunities: ${missedSavings} call${missedSavings === 1 ? '' : 's'} could have used cheaper tools`);
+            }
+        }
         // Context-mode companion status
         if (this.contextModeStatus.detected) {
             lines.push('');

package/dist/core/session-cache.d.ts

@@ -0,0 +1,74 @@
+export interface SessionCacheEntry {
+    /** Cached handler result */
+    result: {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        [key: string]: unknown;
+    };
+    /** Absolute file paths (or dir prefixes ending with '/') this result depends on */
+    fileDeps: Set<string>;
+    /** Invalidate when AST index rebuilds */
+    dependsOnAst: boolean;
+    /** Invalidate when git state changes (branch switch, new commits) */
+    dependsOnGit: boolean;
+    /** When this entry was cached */
+    cachedAt: number;
+    /** Estimated token count of the result */
+    tokenEstimate: number;
+    /** Original tokensWouldBe from the first (non-cached) call — for honest cache savings */
+    tokensWouldBe?: number;
+}
+export interface SessionCacheDeps {
+    files?: string[];
+    dependsOnAst?: boolean;
+    dependsOnGit?: boolean;
+}
+export declare class SessionCache {
+    private maxEntries;
+    private entries;
+    /** Reverse index: file path → set of cache keys that depend on it */
+    private fileDepsIndex;
+    private hits;
+    private misses;
+    private invalidations;
+    constructor(maxEntries: number);
+    /**
+     * Generate deterministic cache key from tool name + args.
+     * Sorts args keys for consistency regardless of insertion order.
+     */
+    static makeCacheKey(tool: string, args: object): string;
+    /** Try to get a cached result. Returns null on miss. */
+    get(tool: string, args: object): SessionCacheEntry | null;
+    /** Store a result with its dependency metadata. */
+    set(tool: string, args: object, result: {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        [key: string]: unknown;
+    }, deps: SessionCacheDeps, tokenEstimate: number, tokensWouldBe?: number): void;
+    /**
+     * Invalidate all entries that depend on any of the given files.
+     * Checks both exact path match and directory prefix match.
+     */
+    invalidateByFiles(filePaths: string[]): number;
+    /** Invalidate all entries that depend on AST index state. */
+    invalidateByAst(): number;
+    /** Invalidate all entries that depend on git state. */
+    invalidateByGit(): number;
+    /** Clear all entries. */
+    invalidateAll(): void;
+    /** Cache statistics for analytics. */
+    stats(): {
+        entries: number;
+        hits: number;
+        misses: number;
+        hitRate: number;
+        invalidations: number;
+    };
+    private deleteEntry;
+    private evictOldest;
+}
+//# sourceMappingURL=session-cache.d.ts.map

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;