token-pilot 0.17.0 → 0.19.0

package/dist/server/tool-definitions.js

@@ -27,14 +27,20 @@ export const MCP_INSTRUCTIONS = [
     '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")',
+    '19. Long session / before compaction → session_snapshot (capture goal, confirmed facts, files, next step as <200 token block)',
+    '   - Budget-constrained? Use smart_read(max_tokens=N) to auto-downgrade output size',
     '',
     '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_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)',
+    '• Long session: session_snapshot → compact context → continue with minimal state',
 ].join('\n');
 export const TOOL_DEFINITIONS = [
     // --- Core reading tools ---
@@ -53,6 +59,7 @@ export const TOOL_DEFINITIONS = [
                     enum: ['full', 'nav', 'exports'],
                     description: 'Output scope: full (default, all details), nav (names + lines only, 2-3x smaller), exports (public API only)',
                 },
+                max_tokens: { type: 'number', description: 'Token budget. If output exceeds this, auto-downgrades: full → outline → compact. Use for context-constrained sessions.' },
             },
             required: ['path'],
         },
@@ -108,6 +115,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.',
@@ -138,6 +157,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'],
         },
@@ -153,6 +176,7 @@ export const TOOL_DEFINITIONS = [
                     items: { type: 'string' },
                     description: 'Array of file paths',
                 },
+                max_tokens: { type: 'number', description: 'Token budget per file. If a file exceeds this, auto-downgrades to compact outline.' },
             },
             required: ['paths'],
         },
@@ -330,5 +354,21 @@ export const TOOL_DEFINITIONS = [
             required: ['command'],
         },
     },
+    // --- Session ---
+    {
+        name: 'session_snapshot',
+        description: 'Capture current session state as a compact markdown block (<200 tokens). Call before compaction, when switching direction, or periodically in long sessions. Model provides the facts, tool formats them.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goal: { type: 'string', description: 'Session goal — what and why' },
+                confirmed: { type: 'array', items: { type: 'string' }, description: 'Established facts (what has been verified)' },
+                files: { type: 'array', items: { type: 'string' }, description: 'Relevant file paths' },
+                blocked: { type: 'string', description: 'Current blocker or obstacle' },
+                next: { type: 'string', description: 'Next step to take' },
+            },
+            required: ['goal'],
+        },
+    },
 ];
 //# sourceMappingURL=tool-definitions.js.map

package/dist/server.js

@@ -36,12 +36,14 @@ 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 { handleSessionSnapshot } from './handlers/session-snapshot.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, {
@@ -153,6 +155,8 @@ export async function createServer(projectRoot, options) {
         : null;
     // Policy engine state
     let fullFileReadsCount = 0;
+    let totalCallCount = 0;
+    let totalTokensReturned = 0;
     const readForEditCalled = new Set();
     // Detect context-mode companion
     const cmEnabled = config.contextMode.enabled;
@@ -223,6 +227,8 @@ export async function createServer(projectRoot, options) {
             }),
         });
         // Policy tracking
+        totalCallCount++;
+        totalTokensReturned += rest.tokensReturned;
         if (isFullReadTool(rest.tool)) {
             fullFileReadsCount++;
         }
@@ -234,6 +240,8 @@ export async function createServer(projectRoot, options) {
             fullFileReadsCount,
             tokensReturned: rest.tokensReturned,
             readForEditCalled,
+            totalCallCount,
+            totalTokensReturned,
         });
         return advisory ? `\n${advisory.message}` : null;
     }
@@ -310,6 +318,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);
@@ -560,6 +582,17 @@ export async function createServer(projectRoot, options) {
                     recordWithTrace({ tool: 'test_summary', path: tsArgs.command, tokensReturned: tsTokens, tokensWouldBe: tsResult.rawTokens || tsTokens, timestamp: Date.now(), savingsCategory: 'compression', args: tsArgs });
                     return { content: tsResult.content };
                 }
+                case 'session_snapshot': {
+                    const snapshotArgs = args;
+                    if (!snapshotArgs.goal) {
+                        return { content: [{ type: 'text', text: 'Error: goal is required' }], isError: true };
+                    }
+                    const snapshotResult = handleSessionSnapshot(snapshotArgs);
+                    const snapshotText = snapshotResult.content[0]?.text ?? '';
+                    const snapshotTokens = estimateTokens(snapshotText);
+                    recordWithTrace({ tool: 'session_snapshot', tokensReturned: snapshotTokens, tokensWouldBe: snapshotTokens, timestamp: Date.now(), savingsCategory: 'compression' });
+                    return { content: snapshotResult.content };
+                }
                 default:
                     return {
                         content: [{ type: 'text', text: `Unknown tool: ${name}` }],

package/dist/types.d.ts

@@ -137,6 +137,8 @@ export interface TokenPilotConfig {
         maxFullFileReads: number;
         warnOnLargeReads: boolean;
         largeReadThreshold: number;
+        compactionCallThreshold: number;
+        compactionTokenThreshold: number;
     };
     ignore: string[];
 }

package/package.json

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