token-pilot 0.12.0 → 0.14.1

package/dist/core/context-registry.js

@@ -47,6 +47,11 @@ export class ContextRegistry {
             return false;
         return entry.loaded.some(r => r.symbolName === symbolName);
     }
+    /** Check if any region of a file has been loaded into context. */
+    hasAnyLoaded(path) {
+        const entry = this.entries.get(path);
+        return !!entry && entry.loaded.length > 0;
+    }
     isStale(path, currentHash) {
         const entry = this.entries.get(path);
         if (!entry)
@@ -91,6 +96,56 @@ export class ContextRegistry {
         lines.push('HINT: File unchanged since last read. Use read_symbol() to reload specific parts, or read_diff() to see changes.');
         return lines.join('\n');
     }
+    /** Check if file was loaded in full (type='full' region exists). */
+    isFullyLoaded(path) {
+        const entry = this.entries.get(path);
+        if (!entry)
+            return false;
+        return entry.loaded.some(r => r.type === 'full');
+    }
+    /**
+     * Generate a compact dedup reminder for read_symbol.
+     * Fires when same symbol was already loaded OR full file is in context.
+     */
+    symbolReminder(path, symbolName) {
+        const entry = this.entries.get(path);
+        if (!entry)
+            return '';
+        const elapsed = formatDuration(Date.now() - entry.loadedAt);
+        const symbolRegion = entry.loaded.find(r => r.symbolName === symbolName);
+        const fullRegion = entry.loaded.find(r => r.type === 'full');
+        if (fullRegion) {
+            const loc = symbolRegion ? ` Symbol at [L${symbolRegion.startLine}-${symbolRegion.endLine}].` : '';
+            return [
+                `DEDUP: "${symbolName}" in ${path} — full file already in context (loaded ${elapsed} ago, ${fullRegion.tokens} tokens, unchanged).${loc}`,
+                'HINT: File unchanged. No need to re-read. Use read_for_edit() if you need exact code for editing.',
+            ].join('\n');
+        }
+        if (symbolRegion) {
+            return [
+                `DEDUP: "${symbolName}" in ${path} — already loaded ${elapsed} ago [L${symbolRegion.startLine}-${symbolRegion.endLine}] (${symbolRegion.tokens} tokens, unchanged).`,
+                'HINT: Symbol unchanged since last read. No need to re-read.',
+            ].join('\n');
+        }
+        return '';
+    }
+    /**
+     * Generate a compact dedup reminder for read_range.
+     * Only fires when full file is in context.
+     */
+    rangeReminder(path, startLine, endLine) {
+        const entry = this.entries.get(path);
+        if (!entry)
+            return '';
+        const fullRegion = entry.loaded.find(r => r.type === 'full');
+        if (!fullRegion)
+            return '';
+        const elapsed = formatDuration(Date.now() - entry.loadedAt);
+        return [
+            `DEDUP: ${path} [L${startLine}-${endLine}] — full file already in context (loaded ${elapsed} ago, ${fullRegion.tokens} tokens, unchanged).`,
+            'HINT: File unchanged. No need to re-read. Use read_for_edit() if you need exact code for editing.',
+        ].join('\n');
+    }
     forget(path, symbolName) {
         if (symbolName) {
             const entry = this.entries.get(path);

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