token-pilot 0.15.0 → 0.16.0

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

@@ -29,6 +29,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -45,6 +46,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -88,6 +90,7 @@ export declare const TOOL_DEFINITIONS: ({
             show_imports?: undefined;
             show_docs?: undefined;
             depth?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -104,6 +107,71 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
+            module?: undefined;
+            export_only?: undefined;
+            check?: undefined;
+            pattern?: undefined;
+            name?: undefined;
+            ref?: undefined;
+            count?: undefined;
+            command?: undefined;
+            runner?: undefined;
+            timeout?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            path: {
+                type: string;
+                description: string;
+            };
+            symbols: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            context_before: {
+                type: string;
+                description: string;
+            };
+            context_after: {
+                type: string;
+                description: string;
+            };
+            show: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            show_imports?: undefined;
+            show_docs?: undefined;
+            depth?: undefined;
+            symbol?: undefined;
+            start_line?: undefined;
+            end_line?: undefined;
+            context_lines?: undefined;
+            line?: undefined;
+            context?: undefined;
+            include_callers?: undefined;
+            include_tests?: undefined;
+            include_changes?: undefined;
+            paths?: undefined;
+            scope?: undefined;
+            kind?: undefined;
+            limit?: undefined;
+            lang?: undefined;
+            include?: undefined;
+            recursive?: undefined;
+            max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -142,6 +210,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             context_lines?: undefined;
             line?: undefined;
             context?: undefined;
@@ -156,6 +225,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -190,6 +260,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             line?: undefined;
@@ -205,6 +276,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -232,6 +304,13 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            symbols: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
             line: {
                 type: string;
                 description: string;
@@ -269,6 +348,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -303,6 +383,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -318,6 +399,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -359,6 +441,10 @@ export declare const TOOL_DEFINITIONS: ({
                 type: string;
                 description: string;
             };
+            context_lines: {
+                type: string;
+                description: string;
+            };
             path?: undefined;
             show_imports?: undefined;
             show_docs?: undefined;
@@ -366,9 +452,9 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
-            context_lines?: undefined;
             line?: undefined;
             context?: undefined;
             include_callers?: undefined;
@@ -378,6 +464,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -413,6 +500,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -428,6 +516,7 @@ export declare const TOOL_DEFINITIONS: ({
             lang?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -458,6 +547,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -474,6 +564,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -512,6 +603,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -526,6 +618,7 @@ export declare const TOOL_DEFINITIONS: ({
             limit?: undefined;
             lang?: undefined;
             include?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -545,6 +638,10 @@ export declare const TOOL_DEFINITIONS: ({
     inputSchema: {
         type: "object";
         properties: {
+            verbose: {
+                type: string;
+                description: string;
+            };
             path?: undefined;
             show_imports?: undefined;
             show_docs?: undefined;
@@ -553,6 +650,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -608,6 +706,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -623,6 +722,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             check?: undefined;
             pattern?: undefined;
             name?: undefined;
@@ -669,6 +769,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -683,6 +784,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             ref?: undefined;
@@ -716,6 +818,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -732,6 +835,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             export_only?: undefined;
             pattern?: undefined;
             name?: undefined;
@@ -769,6 +873,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -784,6 +889,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -821,6 +927,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -836,6 +943,7 @@ export declare const TOOL_DEFINITIONS: ({
             lang?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -874,6 +982,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -890,6 +999,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;
@@ -928,6 +1038,7 @@ export declare const TOOL_DEFINITIONS: ({
             context_before?: undefined;
             context_after?: undefined;
             show?: undefined;
+            symbols?: undefined;
             start_line?: undefined;
             end_line?: undefined;
             context_lines?: undefined;
@@ -944,6 +1055,7 @@ export declare const TOOL_DEFINITIONS: ({
             include?: undefined;
             recursive?: undefined;
             max_depth?: undefined;
+            verbose?: undefined;
             module?: undefined;
             export_only?: undefined;
             check?: undefined;

package/dist/server/tool-definitions.js

@@ -10,6 +10,7 @@ export const MCP_INSTRUCTIONS = [
     '2. Starting work on a directory → explore_area (outline + imports + tests + git log in one call)',
     '3. Need to read a code file → smart_read (NOT Read/cat — returns structure, 60-80% fewer tokens)',
     '4. Need one function/class body → read_symbol (loads only that symbol, NOT the whole file)',
+    '4b. Need MULTIPLE function/class bodies from same file → read_symbols (batch — one call instead of N)',
     '5. Preparing an edit → read_for_edit (returns exact text for Edit old_string)',
     '6. Verify edits after editing → read_diff (only changed hunks — REQUIRES smart_read BEFORE editing)',
     '7. Multiple files at once → smart_read_many (batch up to 20 files)',
@@ -28,7 +29,7 @@ export const MCP_INSTRUCTIONS = [
     'WORKFLOWS:',
     '• Explore: project_overview → explore_area → smart_read → read_symbol',
     '• Edit: smart_read → read_for_edit → Edit → read_diff',
-    '• Refactor: find_usages → read_symbol → read_for_edit → Edit → test_summary',
+    '• Refactor: find_usages → read_symbols → read_for_edit → Edit → test_summary',
     '• Audit: code_audit + find_unused + Grep (for regex patterns)',
 ].join('\n');
 export const TOOL_DEFINITIONS = [
@@ -62,6 +63,25 @@ export const TOOL_DEFINITIONS = [
             required: ['path', 'symbol'],
         },
     },
+    {
+        name: 'read_symbols',
+        description: 'Batch read MULTIPLE symbols from ONE file in a single call — saves N-1 round-trips vs calling read_symbol N times. Returns all requested symbol bodies.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'File path' },
+                symbols: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of symbol names (max 10), e.g. ["UserService.create", "UserService.update", "UserService.delete"]',
+                },
+                context_before: { type: 'number', description: 'Lines of context before each symbol (default: 2)' },
+                context_after: { type: 'number', description: 'Lines of context after each symbol (default: 0)' },
+                show: { type: 'string', enum: ['full', 'head', 'tail', 'outline'], description: 'Display mode for each symbol (default: auto)' },
+            },
+            required: ['path', 'symbols'],
+        },
+    },
     {
         name: 'read_range',
         description: 'Read a specific line range from a file. Use when you know exact lines — lighter than reading the whole file.',
@@ -89,12 +109,17 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'read_for_edit',
-        description: 'Use INSTEAD OF Read when preparing an edit. Returns exact raw code around a symbol or line — copy directly as old_string for Edit tool. Optional: include_callers, include_tests, include_changes for enriched context.',
+        description: 'Use INSTEAD OF Read when preparing an edit. Returns exact raw code around a symbol or line — copy directly as old_string for Edit tool. Supports batch: pass "symbols" array to get multiple edit contexts in one call. Optional: include_callers, include_tests, include_changes for enriched context.',
         inputSchema: {
             type: 'object',
             properties: {
                 path: { type: 'string', description: 'File path' },
                 symbol: { type: 'string', description: 'Symbol name to edit (e.g. "UserService.updateUser")' },
+                symbols: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of symbol names for batch edit context (max 10). Alternative to single "symbol" — returns all symbols in one call.',
+                },
                 line: { type: 'number', description: 'Line number to edit (alternative to symbol)' },
                 context: { type: 'number', description: 'Lines of context around target (default: 5)' },
                 include_callers: { type: 'boolean', description: 'Show top callers of this symbol (saves a separate find_usages call)' },
@@ -122,7 +147,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.',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -131,6 +156,7 @@ export const TOOL_DEFINITIONS = [
                 kind: { type: 'string', enum: ['definitions', 'imports', 'usages', 'all'], description: 'Show only specific section (default: "all")' },
                 limit: { type: 'number', description: 'Max results per category (default: 50, max: 500)' },
                 lang: { type: 'string', description: 'Filter by language/extension (e.g., "php", "typescript")' },
+                context_lines: { type: 'number', description: 'Lines of source context around each match (0-10). When set, shows surrounding code — saves follow-up read_symbol calls.' },
             },
             required: ['symbol'],
         },
@@ -176,10 +202,12 @@ export const TOOL_DEFINITIONS = [
     // --- Analytics ---
     {
         name: 'session_analytics',
-        description: 'Show token savings report: calls, tokens saved, per-tool breakdown, top files, cache hits.',
+        description: 'Show token savings report: calls, tokens saved, per-tool breakdown, top files, cache hits. Use verbose=true for full breakdown (per-intent, decision insights, savings by category).',
         inputSchema: {
             type: 'object',
-            properties: {},
+            properties: {
+                verbose: { type: 'boolean', description: 'Show detailed breakdown: per-intent, savings by category, decision insights (default: false)' },
+            },
         },
     },
     // --- Analysis ---

package/dist/server.js

@@ -19,6 +19,7 @@ const execFilePromise = promisify(execFile);
 import { FileWatcher } from './git/file-watcher.js';
 import { handleSmartRead } from './handlers/smart-read.js';
 import { handleReadSymbol } from './handlers/read-symbol.js';
+import { handleReadSymbols } from './handlers/read-symbols.js';
 import { handleReadRange } from './handlers/read-range.js';
 import { handleReadDiff } from './handlers/read-diff.js';
 import { handleFindUsages } from './handlers/find-usages.js';
@@ -40,7 +41,7 @@ import { estimateTokens } from './core/token-estimator.js';
 import { checkPolicy, isFullReadTool } from './core/policy-engine.js';
 import { MCP_INSTRUCTIONS, TOOL_DEFINITIONS } from './server/tool-definitions.js';
 import { createTokenEstimates } from './server/token-estimates.js';
-import { validateSmartReadArgs, validateReadSymbolArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, } from './core/validation.js';
+import { validateSmartReadArgs, validateReadSymbolArgs, validateReadSymbolsArgs, validateReadRangeArgs, validateReadDiffArgs, validateFindUsagesArgs, validateSmartReadManyArgs, validateReadForEditArgs, validateRelatedFilesArgs, validateOutlineArgs, validateFindUnusedArgs, validateCodeAuditArgs, validateProjectOverviewArgs, validateModuleInfoArgs, validateSmartDiffArgs, validateExploreAreaArgs, validateSmartLogArgs, validateTestSummaryArgs, } from './core/validation.js';
 export async function createServer(projectRoot, options) {
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
@@ -288,6 +289,15 @@ export async function createServer(projectRoot, options) {
                     recordWithTrace({ tool: 'read_symbol', path: symArgs.path, tokensReturned: symTokens, tokensWouldBe: fullTokensSym || symTokens, timestamp: Date.now(), savingsCategory: detectSavingsCategory(symText), absPath: resolve(projectRoot, symArgs.path), args: symArgs });
                     return symResult;
                 }
+                case 'read_symbols': {
+                    const rsArgs = validateReadSymbolsArgs(args);
+                    const rsResult = await handleReadSymbols(rsArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, config.smartRead.advisoryReminders);
+                    const rsText = rsResult.content[0]?.text ?? '';
+                    const rsTokens = estimateTokens(rsText);
+                    const fullTokensRs = await fullFileTokens(rsArgs.path);
+                    recordWithTrace({ tool: 'read_symbols', path: rsArgs.path, tokensReturned: rsTokens, tokensWouldBe: fullTokensRs || rsTokens, timestamp: Date.now(), savingsCategory: 'compression', absPath: resolve(projectRoot, rsArgs.path), args: rsArgs });
+                    return rsResult;
+                }
                 case 'read_range': {
                     const rangeArgs = validateReadRangeArgs(args);
                     const rangeResult = await handleReadRange(rangeArgs, projectRoot, fileCache, contextRegistry, config.smartRead.advisoryReminders);
@@ -343,7 +353,7 @@ export async function createServer(projectRoot, options) {
                         recordWithTrace({ tool: 'find_usages', path: usagesArgs.symbol, tokensReturned: cachedUsages.tokenEstimate, tokensWouldBe: cachedUsages.tokensWouldBe ?? cachedUsages.tokenEstimate, timestamp: Date.now(), sessionCacheHit: true, savingsCategory: 'cache', args: usagesArgs });
                         return cachedUsages.result;
                     }
-                    const usagesResult = await handleFindUsages(usagesArgs, astIndex);
+                    const usagesResult = await handleFindUsages(usagesArgs, astIndex, projectRoot);
                     const usagesText = usagesResult.content[0]?.text ?? '';
                     const usagesTokens = estimateTokens(usagesText);
                     const usagesWouldBe = await estimateFindUsagesWorkflowTokens(usagesResult.meta.files);
@@ -447,8 +457,10 @@ export async function createServer(projectRoot, options) {
                     });
                     return outlineResult;
                 }
-                case 'session_analytics':
-                    return { content: [{ type: 'text', text: `TOKEN PILOT v${pkgVersion}\n\n${analytics.report()}` }] };
+                case 'session_analytics': {
+                    const verbose = args?.verbose === true;
+                    return { content: [{ type: 'text', text: `TOKEN PILOT v${pkgVersion}\n\n${analytics.report(verbose)}` }] };
+                }
                 case 'find_unused': {
                     const unusedArgs = validateFindUnusedArgs(args);
                     const cachedUnused = sessionCache?.get('find_unused', unusedArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "token-pilot",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "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",