token-pilot 0.16.2 → 0.18.0

package/dist/server/tool-definitions.js

@@ -9,26 +9,33 @@ export const MCP_INSTRUCTIONS = [
     '1. New codebase / unfamiliar project → project_overview',
     '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)',
+    '   - For navigation/browsing: smart_read(scope="nav") — names + lines only, 2-3x smaller',
+    '   - For public API overview: smart_read(scope="exports")',
     '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)',
-    '8. Find where a symbol is used → find_usages (semantic: definitions + imports + usages)',
-    '9. Understand file dependencies → related_files (imports, importers, tests — ranked by relevance)',
-    '10. List all symbols in a directory → outline (classes, functions, methods in one call)',
-    '11. Review git changes → smart_diff (NOT git diff — maps changes to functions/classes)',
-    '12. Commit history → smart_log (NOT git log — structured with categories)',
-    '13. Run tests → test_summary (NOT raw test output — structured pass/fail)',
-    '14. Code quality → code_audit (TODOs, deprecated, structural patterns)',
-    '15. Dead code → find_unused (unreferenced symbols across project)',
-    '16. Module architecture → module_info (deps, dependents, public API)',
+    '   - Preparing edit? Add include_edit_context=true to skip separate read_for_edit call',
+    '5. Need MULTIPLE function/class bodies from same file → read_symbols (batch — one call instead of N)',
+    '6. Preparing an edit → read_for_edit (returns exact text for Edit old_string)',
+    '7. Verify edits after editing → read_diff (only changed hunks — REQUIRES smart_read BEFORE editing)',
+    '8. Multiple files at once → smart_read_many (batch up to 20 files)',
+    '9. Find where a symbol is used → find_usages (semantic: definitions + imports + usages)',
+    '   - For initial discovery: find_usages(mode="list") — file:line only, 5-10x smaller',
+    '10. Understand file dependencies → related_files (imports, importers, tests — ranked by relevance)',
+    '11. List all symbols in a directory → outline (classes, functions, methods in one call)',
+    '12. Review git changes → smart_diff (NOT git diff — maps changes to functions/classes)',
+    '13. Commit history → smart_log (NOT git log — structured with categories)',
+    '14. Run tests → test_summary (NOT raw test output — structured pass/fail)',
+    '15. Code quality → code_audit (TODOs, deprecated, structural patterns)',
+    '16. Dead code → find_unused (unreferenced symbols across project)',
+    '17. Module architecture → module_info (deps, dependents, public API)',
+    '18. Read markdown/yaml/json/csv section → read_section (loads one heading/key/row-range, NOT the whole file)',
+    '   - For editing sections: read_for_edit(path, section="Section Name")',
     '',
     'USE DEFAULT TOOLS ONLY FOR: regex text search → Grep | exact raw content → Read | non-code configs → Read',
     '',
     'WORKFLOWS:',
     '• Explore: project_overview → explore_area → smart_read → read_symbol',
-    '• Edit: smart_read → read_for_edit → Edit → read_diff',
+    '• Edit: smart_read → read_symbol(include_edit_context=true) → Edit → read_diff',
+    '• Docs: smart_read (outline) → read_section → read_for_edit(section=) → Edit → read_diff',
     '• Refactor: find_usages → read_symbols → read_for_edit → Edit → test_summary',
     '• Audit: code_audit + find_unused + Grep (for regex patterns)',
 ].join('\n');
@@ -44,6 +51,11 @@ export const TOOL_DEFINITIONS = [
                 show_imports: { type: 'boolean', description: 'Include import details (default: true)' },
                 show_docs: { type: 'boolean', description: 'Include doc comments (default: true)' },
                 depth: { type: 'number', description: 'Max depth for nested symbols (default: 2)' },
+                scope: {
+                    type: 'string',
+                    enum: ['full', 'nav', 'exports'],
+                    description: 'Output scope: full (default, all details), nav (names + lines only, 2-3x smaller), exports (public API only)',
+                },
             },
             required: ['path'],
         },
@@ -59,13 +71,17 @@ export const TOOL_DEFINITIONS = [
                 context_before: { type: 'number', description: 'Lines of context before (default: 2)' },
                 context_after: { type: 'number', description: 'Lines of context after (default: 0)' },
                 show: { type: 'string', enum: ['full', 'head', 'tail', 'outline'], description: 'Display mode: full (all lines), head (first 50), tail (last 30), outline (head + methods + tail). Default: auto (full ≤300 lines, outline >300)' },
+                include_edit_context: {
+                    type: 'boolean',
+                    description: 'Append raw code block for Edit old_string (saves a read_for_edit call)',
+                },
             },
             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.',
+        description: 'Batch read MULTIPLE symbols from ONE file for UNDERSTANDING code — saves N-1 round-trips vs calling read_symbol N times. Returns formatted symbol bodies with show modes (full/head/tail/outline). Use this when READING code, not editing. For edit preparation use read_for_edit instead.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -95,6 +111,18 @@ export const TOOL_DEFINITIONS = [
             required: ['path', 'start_line', 'end_line'],
         },
     },
+    {
+        name: 'read_section',
+        description: 'Read a specific section from Markdown, YAML, JSON, or CSV files. Markdown: by heading name. YAML/JSON: by top-level key. CSV: by row range (rows:1-50). Much cheaper than reading the whole file.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .md, .yaml, .yml, .json, or .csv file' },
+                heading: { type: 'string', description: 'Section heading (Markdown), top-level key (YAML/JSON), or row range "rows:1-50" (CSV). Case-insensitive.' },
+            },
+            required: ['path', 'heading'],
+        },
+    },
     {
         name: 'read_diff',
         description: 'Use INSTEAD OF re-reading whole file after edits. Shows only changed hunks. REQUIRES: call smart_read or read_for_edit BEFORE editing to create baseline snapshot.',
@@ -109,7 +137,7 @@ 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. Supports batch: pass "symbols" array to get multiple edit contexts in one call. 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. Unlike read_symbols (for reading/understanding), this returns unformatted code optimized for copy-paste into Edit. Optional: include_callers, include_tests, include_changes for enriched context.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -125,6 +153,10 @@ export const TOOL_DEFINITIONS = [
                 include_callers: { type: 'boolean', description: 'Show top callers of this symbol (saves a separate find_usages call)' },
                 include_tests: { type: 'boolean', description: 'Show related test file and test names' },
                 include_changes: { type: 'boolean', description: 'Show recent git changes in the target region' },
+                section: {
+                    type: 'string',
+                    description: 'Section to edit: heading (Markdown), top-level key (YAML/JSON), or "rows:1-50" (CSV). Returns raw section content for Edit old_string.',
+                },
             },
             required: ['path'],
         },
@@ -157,6 +189,11 @@ export const TOOL_DEFINITIONS = [
                 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.' },
+                mode: {
+                    type: 'string',
+                    enum: ['full', 'list'],
+                    description: 'Output mode: full (with context, default), list (file:line only, 5-10x smaller for initial discovery)',
+                },
             },
             required: ['symbol'],
         },

package/dist/server.js

@@ -36,12 +36,13 @@ import { handleSmartDiff } from './handlers/smart-diff.js';
 import { handleExploreArea } from './handlers/explore-area.js';
 import { handleSmartLog } from './handlers/smart-log.js';
 import { handleTestSummary } from './handlers/test-summary.js';
+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 { MCP_INSTRUCTIONS, TOOL_DEFINITIONS } from './server/tool-definitions.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, } from './core/validation.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) {
     const config = await loadConfig(projectRoot);
     const astIndex = new AstIndexClient(projectRoot, config.astIndex.timeout, {
@@ -273,6 +274,7 @@ export async function createServer(projectRoot, options) {
                             return nonCodeResult;
                         }
                     }
+                    // Dedup is handled inside handleSmartRead (step 5)
                     const result = await handleSmartRead(validArgs, projectRoot, astIndex, fileCache, contextRegistry, config);
                     const text = result.content[0]?.text ?? '';
                     const fullTokensSR = await fullFileTokens(validArgs.path);
@@ -283,6 +285,7 @@ export async function createServer(projectRoot, options) {
                 }
                 case 'read_symbol': {
                     const symArgs = validateReadSymbolArgs(args);
+                    // Dedup is handled inside handleReadSymbol
                     const symResult = await handleReadSymbol(symArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, config.smartRead.advisoryReminders);
                     const symText = symResult.content[0]?.text ?? '';
                     const symTokens = estimateTokens(symText);
@@ -308,6 +311,20 @@ export async function createServer(projectRoot, options) {
                     recordWithTrace({ tool: 'read_range', path: rangeArgs.path, tokensReturned: rangeTokens, tokensWouldBe: fullTokensRange || rangeTokens, timestamp: Date.now(), savingsCategory: detectSavingsCategory(rangeText), absPath: resolve(projectRoot, rangeArgs.path), args: rangeArgs });
                     return rangeResult;
                 }
+                case 'read_section': {
+                    const secArgs = validateReadSectionArgs(args);
+                    const secResult = await handleReadSection(secArgs, projectRoot, contextRegistry);
+                    const secText = secResult.content[0]?.text ?? '';
+                    const secTokens = estimateTokens(secText);
+                    const fullTokensSec = await fullFileTokens(secArgs.path);
+                    recordWithTrace({
+                        tool: 'read_section', path: secArgs.path,
+                        tokensReturned: secTokens, tokensWouldBe: fullTokensSec || secTokens,
+                        timestamp: Date.now(), savingsCategory: 'compression',
+                        absPath: resolve(projectRoot, secArgs.path), args: secArgs,
+                    });
+                    return secResult;
+                }
                 case 'read_diff': {
                     const diffArgs = validateReadDiffArgs(args);
                     const diffResult = await handleReadDiff(diffArgs, projectRoot, fileCache, contextRegistry);
@@ -319,7 +336,7 @@ export async function createServer(projectRoot, options) {
                 }
                 case 'read_for_edit': {
                     const editArgs = validateReadForEditArgs(args);
-                    const editResult = await handleReadForEdit(editArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex);
+                    const editResult = await handleReadForEdit(editArgs, projectRoot, symbolResolver, fileCache, contextRegistry, astIndex, { actionableHints: config.display.actionableHints });
                     const editText = editResult.content[0]?.text ?? '';
                     const editTokens = estimateTokens(editText);
                     const fullTokensEdit = await fullFileTokens(editArgs.path);

package/dist/types.d.ts

@@ -59,6 +59,7 @@ export interface ContextEntry {
     contentHash: string;
     tokenEstimate: number;
     loadedAt: number;
+    symbolNames?: string[];
 }
 export interface LoadedRegion {
     type: 'structure' | 'symbol' | 'range' | 'full';
@@ -89,6 +90,10 @@ export interface TokenPilotConfig {
         smallFileThreshold: number;
         showDependencyHints: boolean;
         advisoryReminders: boolean;
+        autoDelta: {
+            enabled: boolean;
+            maxAgeSec: number;
+        };
     };
     git: {
         watchHead: boolean;
@@ -110,6 +115,7 @@ export interface TokenPilotConfig {
         showReferences: boolean;
         maxDepth: number;
         showTokenSavings: boolean;
+        actionableHints: boolean;
     };
     contextMode: {
         enabled: boolean | 'auto';

package/package.json

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