token-pilot 0.29.0 → 0.30.1

package/dist/cli/tool-audit.d.ts

@@ -22,6 +22,11 @@ export interface ToolAuditRow {
     /** Calls where the recorder claimed NO savings (pass-through) — separate so
      *  they don't poison the reduction average. */
     noneCalls: number;
+    /** Calls where the MCP response was served from the session cache (the model
+     *  replayed cached tokens).  These contribute to `saved` but the mechanism
+     *  is token re-use, not structural compression — useful to split out so the
+     *  "Est.Saved*" column is understood correctly. */
+    cacheHitCalls: number;
     /** True when reduction is below the low-value threshold AND we have enough
      *  samples (≥5) to make a claim — avoids flagging tools after 1 bad run. */
     lowValue: boolean;

package/dist/cli/tool-audit.js

@@ -24,12 +24,15 @@ export function aggregateToolCalls(events, lowValueThreshold = 20, minSamples =
             tokensReturned: 0,
             tokensWouldBe: 0,
             noneCalls: 0,
+            cacheHitCalls: 0,
         };
         row.count++;
         row.tokensReturned += e.tokensReturned;
         row.tokensWouldBe += e.tokensWouldBe;
         if (e.savingsCategory === "none")
             row.noneCalls++;
+        if (e.sessionCacheHit)
+            row.cacheHitCalls++;
         byTool.set(e.tool, row);
     }
     const rows = [];
@@ -47,6 +50,7 @@ export function aggregateToolCalls(events, lowValueThreshold = 20, minSamples =
             saved,
             reductionPct,
             noneCalls: r.noneCalls,
+            cacheHitCalls: r.cacheHitCalls,
             lowValue,
         });
     }
@@ -74,7 +78,7 @@ Run a few MCP tool calls from your AI client, then re-run \`npx token-pilot tool
     lines.push(`Token Pilot — tool audit`);
     lines.push(`  ${opts.totalEvents} calls across ${rows.length} tools (cumulative across sessions)`);
     lines.push("");
-    lines.push("  Tool                     Calls      Saved   Returned  Reduction");
+    lines.push("  Tool                     Calls  Est.Saved*   Returned  Reduction");
     lines.push("  ─────────────────────────────────────────────────────────────────");
     for (const r of rows) {
         const tool = r.tool.padEnd(24);
@@ -91,6 +95,10 @@ Run a few MCP tool calls from your AI client, then re-run \`npx token-pilot tool
         lines.push("Low-value tools flagged above have <20% token reduction across ≥5 calls.");
         lines.push("Consider: check their `none` passthrough count, or whether a cheaper alternative (Grep, Read) would do the job.");
     }
+    lines.push("");
+    lines.push("* Est.Saved is estimated against a full-file read baseline. Actual prompt");
+    lines.push("  savings depend on client caching — use `cacheHitCalls` in --json output");
+    lines.push("  to distinguish structural compression from cache re-use.");
     return lines.join("\n");
 }
 export async function runToolAudit(opts) {

package/dist/core/edit-prep-state.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared disk state so a PreToolUse:Edit hook subprocess can tell whether
+ * the main-thread agent actually called `read_for_edit` before the Edit.
+ *
+ * Why file-backed: hook subprocesses spawn fresh per-call and see no
+ * in-process state from the MCP server. Keyed by a hash of projectRoot so
+ * two concurrent projects on the same machine don't cross-contaminate.
+ * Entries expire after 30 minutes — long enough to cover a typical edit
+ * session, short enough that a stale prep from a previous conversation
+ * doesn't let a bad Edit slip through tomorrow.
+ *
+ * All operations are best-effort: any I/O error is swallowed silently.
+ * A broken state file must NEVER block an Edit — it's a soft guardrail,
+ * not a file-system invariant. If the prep file is unreadable we act as
+ * if "no prep exists" and the hook behaves per its enforcement mode.
+ */
+declare function stateDir(): string;
+declare function stateFile(projectRoot: string): string;
+/**
+ * Record that `read_for_edit` was just called for `absPath`.
+ * Safe to call in any order, from any process — atomically rewrites the
+ * state file so a racing read never sees a half-written JSON.
+ */
+export declare function markEditPrepared(projectRoot: string, absPath: string, now?: number): void;
+/**
+ * Has `read_for_edit` been called for `absPath` recently enough to
+ * authorise a follow-up Edit? Auto-prunes entries older than TTL.
+ */
+export declare function isEditPrepared(projectRoot: string, absPath: string, now?: number, ttlMs?: number): boolean;
+/**
+ * Clear all prep state for a project root. Intended for tests and for the
+ * `doctor` CLI if we ever want an explicit reset button.
+ */
+export declare function clearEditPrep(projectRoot: string): void;
+/** Exposed for tests so they don't need to import tmpdir themselves. */
+export declare const __test__: {
+    stateDir: typeof stateDir;
+    stateFile: typeof stateFile;
+    DEFAULT_TTL_MS: number;
+};
+export {};
+//# sourceMappingURL=edit-prep-state.d.ts.map

package/dist/core/edit-prep-state.js

@@ -0,0 +1,108 @@
+/**
+ * Shared disk state so a PreToolUse:Edit hook subprocess can tell whether
+ * the main-thread agent actually called `read_for_edit` before the Edit.
+ *
+ * Why file-backed: hook subprocesses spawn fresh per-call and see no
+ * in-process state from the MCP server. Keyed by a hash of projectRoot so
+ * two concurrent projects on the same machine don't cross-contaminate.
+ * Entries expire after 30 minutes — long enough to cover a typical edit
+ * session, short enough that a stale prep from a previous conversation
+ * doesn't let a bad Edit slip through tomorrow.
+ *
+ * All operations are best-effort: any I/O error is swallowed silently.
+ * A broken state file must NEVER block an Edit — it's a soft guardrail,
+ * not a file-system invariant. If the prep file is unreadable we act as
+ * if "no prep exists" and the hook behaves per its enforcement mode.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+const STATE_DIR_NAME = "token-pilot-edit-prep";
+const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 minutes
+function stateDir() {
+    return join(tmpdir(), STATE_DIR_NAME);
+}
+function stateFile(projectRoot) {
+    const hash = createHash("sha1")
+        .update(resolve(projectRoot))
+        .digest("hex")
+        .slice(0, 16);
+    return join(stateDir(), `${hash}.json`);
+}
+function loadState(projectRoot) {
+    try {
+        const txt = readFileSync(stateFile(projectRoot), "utf-8");
+        const parsed = JSON.parse(txt);
+        if (parsed &&
+            typeof parsed === "object" &&
+            "paths" in parsed &&
+            typeof parsed.paths === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        /* corrupt / missing — fall through */
+    }
+    return { paths: {} };
+}
+function pruneExpired(state, ttlMs, now) {
+    const fresh = {};
+    for (const [p, ts] of Object.entries(state.paths)) {
+        if (typeof ts === "number" && now - ts < ttlMs) {
+            fresh[p] = ts;
+        }
+    }
+    return { paths: fresh };
+}
+/**
+ * Record that `read_for_edit` was just called for `absPath`.
+ * Safe to call in any order, from any process — atomically rewrites the
+ * state file so a racing read never sees a half-written JSON.
+ */
+export function markEditPrepared(projectRoot, absPath, now = Date.now()) {
+    try {
+        const dir = stateDir();
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const state = pruneExpired(loadState(projectRoot), DEFAULT_TTL_MS, now);
+        state.paths[resolve(absPath)] = now;
+        const file = stateFile(projectRoot);
+        const tmp = `${file}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state));
+        renameSync(tmp, file);
+    }
+    catch {
+        /* best-effort — see module doc */
+    }
+}
+/**
+ * Has `read_for_edit` been called for `absPath` recently enough to
+ * authorise a follow-up Edit? Auto-prunes entries older than TTL.
+ */
+export function isEditPrepared(projectRoot, absPath, now = Date.now(), ttlMs = DEFAULT_TTL_MS) {
+    const state = pruneExpired(loadState(projectRoot), ttlMs, now);
+    return typeof state.paths[resolve(absPath)] === "number";
+}
+/**
+ * Clear all prep state for a project root. Intended for tests and for the
+ * `doctor` CLI if we ever want an explicit reset button.
+ */
+export function clearEditPrep(projectRoot) {
+    try {
+        const file = stateFile(projectRoot);
+        if (existsSync(file)) {
+            writeFileSync(file, JSON.stringify({ paths: {} }));
+        }
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Exposed for tests so they don't need to import tmpdir themselves. */
+export const __test__ = {
+    stateDir,
+    stateFile,
+    DEFAULT_TTL_MS,
+};
+//# sourceMappingURL=edit-prep-state.js.map

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

@@ -6,8 +6,6 @@
 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 */
@@ -25,13 +23,11 @@ export declare const DEFAULT_POLICIES: PolicyConfig;
 export interface PolicyCheckContext {
     fullFileReadsCount: number;
     tokensReturned: number;
-    readForEditCalled?: Set<string>;
-    editTargetPath?: string;
     totalCallCount?: number;
     totalTokensReturned?: number;
 }
 export interface PolicyAdvisory {
-    level: 'info' | 'warn';
+    level: "info" | "warn";
     message: string;
 }
 /**

package/dist/core/policy-engine.js

@@ -5,7 +5,6 @@
  */
 export const DEFAULT_POLICIES = {
     preferCheapReads: true,
-    requireReadForEditBeforeEdit: true,
     cacheProjectOverview: true,
     maxFullFileReads: 10,
     warnOnLargeReads: true,
@@ -14,14 +13,11 @@ export const DEFAULT_POLICIES = {
     compactionTokenThreshold: 8000,
 };
 /** Full-file read tools that count toward maxFullFileReads */
-const FULL_READ_TOOLS = new Set([
-    'smart_read',
-    'smart_read_many',
-]);
+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()',
+    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.
@@ -33,7 +29,7 @@ export function checkPolicy(policy, tool, context) {
         FULL_READ_TOOLS.has(tool) &&
         context.fullFileReadsCount >= policy.maxFullFileReads) {
         return {
-            level: 'warn',
+            level: "warn",
             message: `POLICY: ${context.fullFileReadsCount} full-file reads this session (limit: ${policy.maxFullFileReads}). Consider read_symbol() or read_range() for targeted access.`,
         };
     }
@@ -41,7 +37,7 @@ export function checkPolicy(policy, tool, context) {
     if (policy.warnOnLargeReads &&
         context.tokensReturned > policy.largeReadThreshold) {
         return {
-            level: 'info',
+            level: "info",
             message: `POLICY: Large response (~${context.tokensReturned} tokens). Future reads on this file: use read_symbol() or read_range() for targeted access.`,
         };
     }
@@ -50,29 +46,18 @@ export function checkPolicy(policy, tool, context) {
         // Only advise when token count is high enough to matter
         if (context.tokensReturned > 500) {
             return {
-                level: 'info',
+                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.`,
-        };
-    }
-    // 5. Session compaction advisory — by call count
+    // 4. Session compaction advisory — by call count
     if (policy.compactionCallThreshold > 0 &&
         context.totalCallCount !== undefined &&
         context.totalCallCount > 0 &&
         context.totalCallCount % policy.compactionCallThreshold === 0) {
         return {
-            level: 'info',
+            level: "info",
             message: `COMPACTION: ${context.totalCallCount} tool calls this session. Consider calling session_snapshot() to capture state, then compact context.`,
         };
     }
@@ -84,7 +69,7 @@ export function checkPolicy(policy, tool, context) {
         context.totalCallCount % 5 === 0 // don't spam every call, check every 5th
     ) {
         return {
-            level: 'info',
+            level: "info",
             message: `COMPACTION: ~${context.totalTokensReturned} tokens returned this session. Consider calling session_snapshot() to capture state, then compact context.`,
         };
     }

package/dist/handlers/explore-area.js

@@ -42,7 +42,12 @@ export async function handleExploreArea(args, projectRoot, astIndex) {
         absPath = dirname(absPath);
     }
     const relDir = relative(projectRoot, absPath) || ".";
-    const include = args.include ?? ["outline", "imports", "tests", "changes"];
+    // v0.30.0 — narrowed default from all 4 sections to the two cheap ones.
+    // Telemetry (docker-local-env, 2026-04-24) showed the all-4 default giving
+    // negative token reduction (-7%): `imports` builds a full dep graph and
+    // `tests` walks subtrees, both easily outweighing the raw-file baseline.
+    // Callers who need imports/tests now opt in explicitly via `include`.
+    const include = args.include ?? ["outline", "changes"];
     // Collect code files for import/test analysis
     const codeFiles = await listCodeFiles(absPath);
     // Run all sections in parallel

package/dist/handlers/read-for-edit.d.ts

@@ -1,7 +1,7 @@
-import type { AstIndexClient } from '../ast-index/client.js';
-import type { SymbolResolver } from '../core/symbol-resolver.js';
-import type { FileCache } from '../core/file-cache.js';
-import type { ContextRegistry } from '../core/context-registry.js';
+import type { AstIndexClient } from "../ast-index/client.js";
+import type { SymbolResolver } from "../core/symbol-resolver.js";
+import type { FileCache } from "../core/file-cache.js";
+import type { ContextRegistry } from "../core/context-registry.js";
 export interface ReadForEditArgs {
     path: string;
     symbol?: string;
@@ -17,7 +17,7 @@ export declare function handleReadForEdit(args: ReadForEditArgs, projectRoot: st
     actionableHints?: boolean;
 }): Promise<{
     content: Array<{
-        type: 'text';
+        type: "text";
         text: string;
     }>;
 }>;