token-pilot 0.24.1 → 0.26.5

package/dist/server/token-estimates.js

@@ -2,9 +2,31 @@
  * Token estimation functions for analytics.
  * Used to calculate "tokens would be" for honest savings reporting.
  */
-import { estimateTokens } from '../core/token-estimator.js';
-import { resolveSafePath } from '../core/validation.js';
-import { CODE_EXTENSIONS } from '../handlers/outline.js';
+import { estimateTokens } from "../core/token-estimator.js";
+import { resolveSafePath } from "../core/validation.js";
+import { CODE_EXTENSIONS } from "../handlers/outline.js";
+/**
+ * Honest savings classification for a tool's text output.
+ *
+ * Standalone (pure) so it can be unit-tested without spinning up the
+ * full token-estimates closure. Kept here because it's semantically
+ * tied to how this module reports wouldBe/returned pairs.
+ *
+ * v0.26.1 adds the 'none' branch: smart_read's small-file pass-through
+ * returns the file verbatim with a tiny header. Claiming wouldBe =
+ * fullFile for those calls was the root cause of the -2% "negative
+ * savings" line Opus 4.7 reported. With 'none', the recorder sets
+ * wouldBe = returned → 0% savings, no ghost overhead.
+ */
+export function detectSavingsCategoryPure(text) {
+    if (text.startsWith("REMINDER:") || text.startsWith("DEDUP:"))
+        return "dedup";
+    if (text.includes("returned in full, below threshold") ||
+        text.includes("returned in full, outline not smaller")) {
+        return "none";
+    }
+    return "compression";
+}
 /**
  * Creates token estimation functions bound to a project context.
  * Uses getter for projectRoot since it may change on auto-detect.
@@ -16,8 +38,8 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
             const cached = fileCache.get(absPath);
             if (cached)
                 return estimateTokens(cached.content);
-            const { readFile: readFileAsync } = await import('node:fs/promises');
-            const content = await readFileAsync(absPath, 'utf-8');
+            const { readFile: readFileAsync } = await import("node:fs/promises");
+            const content = await readFileAsync(absPath, "utf-8");
             return estimateTokens(content);
         }
         catch {
@@ -26,34 +48,46 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
     }
     async function estimateProjectOverviewWorkflowTokens(includeSections) {
         const sectionFiles = {
-            stack: ['package.json', 'composer.json', 'Cargo.toml', 'pyproject.toml', 'go.mod'],
-            ci: ['.gitlab-ci.yml', 'Jenkinsfile', '.circleci/config.yml', 'bitbucket-pipelines.yml', '.travis.yml'],
+            stack: [
+                "package.json",
+                "composer.json",
+                "Cargo.toml",
+                "pyproject.toml",
+                "go.mod",
+            ],
+            ci: [
+                ".gitlab-ci.yml",
+                "Jenkinsfile",
+                ".circleci/config.yml",
+                "bitbucket-pipelines.yml",
+                ".travis.yml",
+            ],
             quality: [
-                'tsconfig.json',
-                'vitest.config.ts',
-                'vitest.config.js',
-                'vitest.config.mts',
-                'jest.config.js',
-                'jest.config.ts',
-                'jest.config.mjs',
-                'eslint.config.js',
-                'eslint.config.mjs',
-                '.eslintrc',
-                '.eslintrc.js',
-                '.eslintrc.json',
-                '.eslintrc.yml',
-                'biome.json',
-                'biome.jsonc',
-                '.prettierrc',
-                '.prettierrc.js',
-                '.prettierrc.json',
-                'prettier.config.js',
-                'phpunit.xml',
-                'phpunit.xml.dist',
-                'phpstan.neon',
-                'phpstan.neon.dist',
+                "tsconfig.json",
+                "vitest.config.ts",
+                "vitest.config.js",
+                "vitest.config.mts",
+                "jest.config.js",
+                "jest.config.ts",
+                "jest.config.mjs",
+                "eslint.config.js",
+                "eslint.config.mjs",
+                ".eslintrc",
+                ".eslintrc.js",
+                ".eslintrc.json",
+                ".eslintrc.yml",
+                "biome.json",
+                "biome.jsonc",
+                ".prettierrc",
+                ".prettierrc.js",
+                ".prettierrc.json",
+                "prettier.config.js",
+                "phpunit.xml",
+                "phpunit.xml.dist",
+                "phpstan.neon",
+                "phpstan.neon.dist",
             ],
-            architecture: ['README.md'],
+            architecture: ["README.md"],
         };
         let total = 0;
         const seen = new Set();
@@ -65,15 +99,17 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
                 total += await fullFileTokens(file);
             }
         }
-        if (includeSections.includes('ci')) {
+        if (includeSections.includes("ci")) {
             try {
-                const { readdir: readDirAsync } = await import('node:fs/promises');
-                const workflowDir = resolveSafePath(getProjectRoot(), '.github/workflows');
-                const workflowFiles = await readDirAsync(workflowDir, { withFileTypes: true });
+                const { readdir: readDirAsync } = await import("node:fs/promises");
+                const workflowDir = resolveSafePath(getProjectRoot(), ".github/workflows");
+                const workflowFiles = await readDirAsync(workflowDir, {
+                    withFileTypes: true,
+                });
                 for (const file of workflowFiles) {
                     if (!file.isFile())
                         continue;
-                    if (!file.name.endsWith('.yml') && !file.name.endsWith('.yaml'))
+                    if (!file.name.endsWith(".yml") && !file.name.endsWith(".yaml"))
                         continue;
                     total += await fullFileTokens(`.github/workflows/${file.name}`);
                 }
@@ -82,7 +118,7 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
                 // ignore missing workflows dir
             }
         }
-        if (includeSections.includes('architecture')) {
+        if (includeSections.includes("architecture")) {
             total += 200;
         }
         return total;
@@ -90,8 +126,8 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
     async function estimateOutlineWorkflowTokens(relativePath, recursive, maxDepth) {
         const SAMPLE_LIMIT = 30;
         try {
-            const { readdir: readDirAsync } = await import('node:fs/promises');
-            const { resolve: resolvePath } = await import('node:path');
+            const { readdir: readDirAsync } = await import("node:fs/promises");
+            const { resolve: resolvePath } = await import("node:path");
             const absDir = resolveSafePath(getProjectRoot(), relativePath);
             const sampledFiles = [];
             let totalFiles = 0;
@@ -99,7 +135,7 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
                 const entries = await readDirAsync(dirPath, { withFileTypes: true });
                 for (const entry of entries) {
                     if (entry.isFile()) {
-                        const ext = entry.name.split('.').pop()?.toLowerCase() ?? '';
+                        const ext = entry.name.split(".").pop()?.toLowerCase() ?? "";
                         if (!CODE_EXTENSIONS.has(ext))
                             continue;
                         totalFiles++;
@@ -186,11 +222,7 @@ export function createTokenEstimates(getProjectRoot, fileCache) {
         total += (meta.changeCount ?? 0) * 40;
         return total;
     }
-    function detectSavingsCategory(text) {
-        if (text.startsWith('REMINDER:') || text.startsWith('DEDUP:'))
-            return 'dedup';
-        return 'compression';
-    }
+    const detectSavingsCategory = detectSavingsCategoryPure;
     return {
         fullFileTokens,
         estimateProjectOverviewWorkflowTokens,

package/dist/server/tool-definitions.js

@@ -287,7 +287,7 @@ export const TOOL_DEFINITIONS = [
     // --- Search & navigation ---
     {
         name: "find_usages",
-        description: "Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters. Use context_lines to include surrounding code.",
+        description: "Use INSTEAD OF Grep for finding symbol references. Semantic search — groups by: definitions, imports, usages. Supports scope, kind, limit, lang filters. Use context_lines to include surrounding code. HINT: for very short / generic symbols (≤4 chars like `id`, `err`, `Cmd`, `db`) Grep is usually cheaper than find_usages — the semantic grouping doesn't pay off when the symbol resolves ambiguously across thousands of files.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/server/tool-profiles.d.ts

@@ -0,0 +1,46 @@
+/**
+ * v0.26.3 — tool profiles.
+ *
+ * Idea lifted honestly from Token Savior's TOKEN_SAVIOR_PROFILE. When an
+ * MCP server advertises 22 tools, every tools/list response costs the
+ * agent ~3 k tokens before it does anything. Most sessions don't need
+ * every tool — a code-review agent uses smart_read + find_usages +
+ * outline and nothing else. A profile lets the user ship a narrower
+ * tools/list while keeping the handlers live (so a subagent or another
+ * user in the same server can still reach the full set if they know
+ * the name).
+ *
+ * Three profiles:
+ *   - full  (default): everything, same as pre-v0.26.3.
+ *   - nav  : read-only exploration. smart_read, outline, find_usages,
+ *            read_symbol, project_overview, module_info, related_files,
+ *            explore_area, smart_log, smart_diff.
+ *   - edit : nav + batch reads + everything Edit needs to hit a symbol
+ *            precisely. Adds read_symbols, read_range, read_section,
+ *            read_diff, read_for_edit, smart_read_many.
+ *
+ * Selection: TOKEN_PILOT_PROFILE=nav|edit|full env var. Unknown values
+ * fall back to full with a stderr warning. Silent on missing env.
+ */
+export type ToolProfile = "full" | "nav" | "edit";
+export declare const PROFILE_NAMES: readonly ToolProfile[];
+/** Minimum nav profile — exploration only, no editing support. */
+export declare const NAV_TOOLS: ReadonlySet<string>;
+/** Edit profile adds batch reads + edit-preparation tools. */
+export declare const EDIT_EXTRAS: ReadonlySet<string>;
+/**
+ * Decide which tools the LLM sees in tools/list given a profile.
+ * Pure — safe to unit-test without spinning up the server.
+ *
+ * Tool names NOT matched by any profile rule (e.g. future additions)
+ * fall into 'full' only, to stay conservative by default.
+ */
+export declare function filterToolsByProfile<T extends {
+    name: string;
+}>(tools: readonly T[], profile: ToolProfile): T[];
+/**
+ * Parse the TOKEN_PILOT_PROFILE env value. Unknown values get a warning
+ * and fall back to full — we never silently apply a guess.
+ */
+export declare function parseProfileEnv(envValue: string | undefined, warn?: (msg: string) => void): ToolProfile;
+//# sourceMappingURL=tool-profiles.d.ts.map

package/dist/server/tool-profiles.js

@@ -0,0 +1,81 @@
+/**
+ * v0.26.3 — tool profiles.
+ *
+ * Idea lifted honestly from Token Savior's TOKEN_SAVIOR_PROFILE. When an
+ * MCP server advertises 22 tools, every tools/list response costs the
+ * agent ~3 k tokens before it does anything. Most sessions don't need
+ * every tool — a code-review agent uses smart_read + find_usages +
+ * outline and nothing else. A profile lets the user ship a narrower
+ * tools/list while keeping the handlers live (so a subagent or another
+ * user in the same server can still reach the full set if they know
+ * the name).
+ *
+ * Three profiles:
+ *   - full  (default): everything, same as pre-v0.26.3.
+ *   - nav  : read-only exploration. smart_read, outline, find_usages,
+ *            read_symbol, project_overview, module_info, related_files,
+ *            explore_area, smart_log, smart_diff.
+ *   - edit : nav + batch reads + everything Edit needs to hit a symbol
+ *            precisely. Adds read_symbols, read_range, read_section,
+ *            read_diff, read_for_edit, smart_read_many.
+ *
+ * Selection: TOKEN_PILOT_PROFILE=nav|edit|full env var. Unknown values
+ * fall back to full with a stderr warning. Silent on missing env.
+ */
+export const PROFILE_NAMES = [
+    "full",
+    "nav",
+    "edit",
+];
+/** Minimum nav profile — exploration only, no editing support. */
+export const NAV_TOOLS = new Set([
+    "smart_read",
+    "read_symbol",
+    "outline",
+    "find_usages",
+    "project_overview",
+    "module_info",
+    "related_files",
+    "explore_area",
+    "smart_log",
+    "smart_diff",
+]);
+/** Edit profile adds batch reads + edit-preparation tools. */
+export const EDIT_EXTRAS = new Set([
+    "read_symbols",
+    "read_range",
+    "read_section",
+    "read_diff",
+    "read_for_edit",
+    "smart_read_many",
+]);
+/**
+ * Decide which tools the LLM sees in tools/list given a profile.
+ * Pure — safe to unit-test without spinning up the server.
+ *
+ * Tool names NOT matched by any profile rule (e.g. future additions)
+ * fall into 'full' only, to stay conservative by default.
+ */
+export function filterToolsByProfile(tools, profile) {
+    if (profile === "full")
+        return [...tools];
+    if (profile === "nav")
+        return tools.filter((t) => NAV_TOOLS.has(t.name));
+    // edit = nav + extras
+    return tools.filter((t) => NAV_TOOLS.has(t.name) || EDIT_EXTRAS.has(t.name));
+}
+/**
+ * Parse the TOKEN_PILOT_PROFILE env value. Unknown values get a warning
+ * and fall back to full — we never silently apply a guess.
+ */
+export function parseProfileEnv(envValue, warn = () => { }) {
+    if (!envValue)
+        return "full";
+    const lower = envValue.trim().toLowerCase();
+    if (lower === "full" || lower === "nav" || lower === "edit") {
+        return lower;
+    }
+    warn(`[token-pilot] Unknown TOKEN_PILOT_PROFILE="${envValue}". Expected full|nav|edit. Falling back to full.`);
+    return "full";
+}
+//# sourceMappingURL=tool-profiles.js.map

package/dist/server.js

@@ -44,7 +44,9 @@ import { handleReadSection } from "./handlers/read-section.js";
 import { detectContextMode } from "./integration/context-mode-detector.js";
 import { estimateTokens } from "./core/token-estimator.js";
 import { checkPolicy, isFullReadTool } from "./core/policy-engine.js";
+import { appendToolCall } from "./core/tool-call-log.js";
 import { MCP_INSTRUCTIONS, TOOL_DEFINITIONS, } from "./server/tool-definitions.js";
+import { filterToolsByProfile, parseProfileEnv, } from "./server/tool-profiles.js";
 import { createTokenEstimates } from "./server/token-estimates.js";
 import { validateSmartReadArgs, validateReadSymbolArgs, validateReadSymbolsArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, validateReadSectionArgs, } from "./core/validation.js";
 export async function createServer(projectRoot, options) {
@@ -240,14 +242,33 @@ export async function createServer(projectRoot, options) {
         capabilities: { tools: {} },
         instructions: MCP_INSTRUCTIONS,
     });
+    // v0.26.3 — tool profiles. TOKEN_PILOT_PROFILE=nav|edit|full (default
+    // full) trims the advertised tools/list payload. Handlers stay live,
+    // so a subagent that explicitly names a filtered-out tool still gets
+    // a response — we just don't brag about every tool upfront.
+    const activeProfile = parseProfileEnv(process.env.TOKEN_PILOT_PROFILE, (m) => process.stderr.write(m + "\n"));
+    const advertisedTools = filterToolsByProfile(TOOL_DEFINITIONS, activeProfile);
+    if (activeProfile !== "full") {
+        process.stderr.write(`[token-pilot] Profile: ${activeProfile} — advertising ${advertisedTools.length}/${TOOL_DEFINITIONS.length} tools. Unset TOKEN_PILOT_PROFILE for the full set.\n`);
+    }
     server.setRequestHandler(ListToolsRequestSchema, () => ({
-        tools: TOOL_DEFINITIONS,
+        tools: advertisedTools,
     }));
     // Token estimation functions (extracted to server/token-estimates.ts)
     const { fullFileTokens, estimateProjectOverviewWorkflowTokens, estimateOutlineWorkflowTokens, estimateRelatedFilesWorkflowTokens, estimateFindUsagesWorkflowTokens, estimateExploreAreaWorkflowTokens, detectSavingsCategory, } = createTokenEstimates(() => projectRoot, fileCache);
     /** Record analytics with intent classification and decision trace. Returns policy advisory if any. */
     function recordWithTrace(call) {
         const { absPath, args, recentlyEdited, ...rest } = call;
+        // v0.26.1 — honest accounting. When a handler signals 'none' as
+        // the savings category (e.g. smart_read small-file pass-through),
+        // we weren't compressing anything — the caller got the file back
+        // verbatim plus a tiny header. Claiming wouldBe = fullFile here
+        // produced the -2% "negative savings" line on Opus 4.7's
+        // session_analytics. Zero the delta: 0% savings claimed, no ghost
+        // overhead.
+        if (rest.savingsCategory === "none") {
+            rest.tokensWouldBe = rest.tokensReturned;
+        }
         analytics.record({
             ...rest,
             intent: classifyIntent(rest.tool),
@@ -279,6 +300,22 @@ export async function createServer(projectRoot, options) {
             totalCallCount,
             totalTokensReturned,
         });
+        // v0.26.2 — persist for cumulative tool-audit. Fire-and-forget;
+        // disk failures must not block the tool-response path. The audit
+        // CLI reads all archives + current to build a per-tool savings
+        // distribution across sessions, which is the foundation for any
+        // future prune/fix decision.
+        void appendToolCall(projectRoot, {
+            ts: rest.timestamp,
+            session_id: call.sessionId ?? "",
+            tool: rest.tool,
+            path: rest.path,
+            tokensReturned: rest.tokensReturned,
+            tokensWouldBe: rest.tokensWouldBe,
+            savingsCategory: rest.savingsCategory ?? "compression",
+            sessionCacheHit: rest.sessionCacheHit,
+            delegatedToContextMode: rest.delegatedToContextMode,
+        });
         return advisory ? `\n${advisory.message}` : null;
     }
     // Handle tool calls with validated arguments

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.24.1",
+  "version": "0.26.5",
   "description": "Save up to 80% tokens when AI reads code — MCP server for token-efficient code navigation, AST-aware structural reading instead of dumping full files into context window",
   "type": "module",
   "main": "dist/index.js",

package/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "token-pilot": {
-      "command": "sh",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/start.sh"]
-    }
-  }
-}