smart-context-mcp 1.7.1 → 1.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-context-mcp",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "MCP server that reduces agent token usage by 90% with intelligent context compression, task checkpoint persistence, and workflow-aware agent guidance.",
   "author": "Francisco Caballero Portero <fcp1978@hotmail.com>",
   "type": "module",
@@ -26,6 +26,7 @@
     "./server": "./src/server.js"
   },
   "files": [
+    "README.md",
     "src/",
     "scripts/claude-hook.js",
     "scripts/check-repo-safety.js",

package/src/metrics.js

@@ -267,6 +267,18 @@ export const aggregateMetrics = (entries) => {
 
   const netSavedTokens = getNetSavedTokens(savedTokens, overheadTokens);
 
+  const topTools = tools
+    .slice()
+    .sort((a, b) => b.netSavedTokens - a.netSavedTokens)
+    .slice(0, 3)
+    .filter((tool) => tool.netSavedTokens > 0)
+    .map((tool) => ({
+      tool: tool.tool,
+      netSavedTokens: tool.netSavedTokens,
+      netSavingsPct: tool.netSavingsPct,
+      count: tool.count,
+    }));
+
   return {
     count: entries.length,
     rawTokens,
@@ -275,6 +287,7 @@ export const aggregateMetrics = (entries) => {
     savingsPct: rawTokens > 0 ? Number(((savedTokens / rawTokens) * 100).toFixed(2)) : 0,
     netSavedTokens,
     netSavingsPct: rawTokens > 0 ? Number(((netSavedTokens / rawTokens) * 100).toFixed(2)) : 0,
+    topTools,
     tools,
     overheadTokens,
     overheadPctOfRaw: rawTokens > 0 ? Number(((overheadTokens / rawTokens) * 100).toFixed(2)) : 0,

package/src/orchestration/base-orchestrator.js

@@ -8,6 +8,7 @@ import {
   extractNextStep,
   normalizeWhitespace,
   truncate,
+  isSimpleTask,
   MAX_FOCUS_LENGTH,
   MAX_GOAL_LENGTH,
 } from './policy/event-policy.js';
@@ -113,21 +114,25 @@ export const resolveManagedStart = async ({
   startMaxTokens = DEFAULT_START_MAX_TOKENS,
   startTurn = smartTurn,
   summaryTool = smartSummary,
+  enableFastPath = true,
 }) => {
+  const simpleTask = enableFastPath && isSimpleTask(prompt);
+
   const startResult = preparedStartResult ?? await startTurn({
     phase: 'start',
     sessionId,
     prompt,
-    ensureSession,
+    ensureSession: simpleTask ? false : ensureSession,
     maxTokens: startMaxTokens,
   });
 
-  if (!allowIsolation) {
+  if (!allowIsolation || simpleTask) {
     return {
       startResult,
       isolated: Boolean(startResult?.isolatedSession),
       previousSessionId: startResult?.previousSessionId ?? null,
       autoStarted: !preparedStartResult,
+      fastPath: simpleTask,
     };
   }
 
@@ -143,6 +148,7 @@ export const resolveManagedStart = async ({
   return {
     ...isolatedSession,
     autoStarted: !preparedStartResult,
+    fastPath: false,
   };
 };
 

package/src/orchestration/policy/event-policy.js

@@ -13,6 +13,39 @@ export const MIN_NEXT_STEP_LENGTH = 12;
 export const MAX_NEXT_STEP_CAPTURE_LENGTH = 180;
 export const MAX_RECOMMENDED_TOOLS = 3;
 
+const SIMPLE_TASK_PATTERNS = [
+  /^(move|rename|delete|add|remove|fix|update|change|modify|edit)\s+\w+/i,
+  /^(create|write|read|show|display|list|find)\s+(a|an|the)?\s*\w+/i,
+  /\b(one|single|this|that)\s+(file|function|class|component|method)\b/i,
+  /^(add|remove|update|fix)\s+(comment|import|export|type|interface)/i,
+];
+
+const COMPLEX_TASK_INDICATORS = [
+  /\b(refactor|migrate|redesign|architect|implement|integrate)\b/i,
+  /\b(all|every|entire|whole|across|throughout)\b/i,
+  /\b(system|architecture|infrastructure|framework)\b/i,
+  /\b(multiple|several|many)\s+(files|components|modules)\b/i,
+];
+
+export const isSimpleTask = (prompt) => {
+  if (!prompt || typeof prompt !== 'string') {
+    return false;
+  }
+
+  const normalized = normalizeWhitespace(prompt);
+  
+  if (normalized.length > 200) {
+    return false;
+  }
+
+  const hasComplexIndicator = COMPLEX_TASK_INDICATORS.some((pattern) => pattern.test(normalized));
+  if (hasComplexIndicator) {
+    return false;
+  }
+
+  return SIMPLE_TASK_PATTERNS.some((pattern) => pattern.test(normalized));
+};
+
 export const normalizeWhitespace = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
 
 export const truncate = (value, maxLength = DEFAULT_TRUNCATE_LENGTH) => {
@@ -132,9 +165,10 @@ export const runWorkflowPreflight = async ({
   startResult,
   contextTool = smartContext,
   searchTool = smartSearch,
+  skipPreflight = false,
 }) => {
   const preflight = workflowProfile.preflight;
-  if (!preflight) {
+  if (!preflight || skipPreflight) {
     return null;
   }
 
@@ -281,6 +315,7 @@ export const buildTaskRunnerAutomaticity = ({
   usedWrapper = false,
   overheadTokens = 0,
   managedByBaseOrchestrator = false,
+  fastPath = false,
 }) => {
   const safeOverheadTokens = Number.isFinite(overheadTokens) ? Math.max(0, overheadTokens) : 0;
   const checkpointPersisted = Boolean(endResult && !endResult.checkpoint?.skipped && !endResult.checkpoint?.blocked);
@@ -293,5 +328,6 @@ export const buildTaskRunnerAutomaticity = ({
     autoWrappedPrompt: usedWrapper && safeOverheadTokens > 0,
     isolatedSession: Boolean(startResult?.isolatedSession),
     contextOverheadTokens: safeOverheadTokens,
+    fastPath,
   };
 };

package/src/task-runner.js

@@ -62,6 +62,7 @@ const recordRunnerMetrics = async ({
   usedWrapper = false,
   blocked = false,
   doctorIssued = false,
+  fastPath = false,
 }) => {
   const startResult = result?.start ?? result?.startResult ?? null;
   const endResult = result?.end ?? (result?.phase === 'end' ? result : null);
@@ -83,6 +84,7 @@ const recordRunnerMetrics = async ({
     usedWrapper,
     overheadTokens: Number(result?.overheadTokens ?? 0),
     managedByBaseOrchestrator: WORKFLOW_COMMANDS.has(commandName),
+    fastPath,
   });
 
   await persistMetrics({
@@ -148,8 +150,10 @@ const runWorkflowCommand = async ({
     ensureSession: true,
     allowIsolation: false,
     startMaxTokens: DEFAULT_START_MAX_TOKENS,
+    enableFastPath: true,
   }));
   const start = startResolution.startResult;
+  const fastPath = startResolution.fastPath ?? false;
 
   const gate = evaluateRunnerGate({ startResult: start });
   let preflightSummary = null;
@@ -159,6 +163,7 @@ const runWorkflowCommand = async ({
       workflowProfile,
       prompt: requestedPrompt,
       startResult: start,
+      skipPreflight: fastPath,
     });
     preflightSummary = buildPreflightSummary(preflightResult);
   }
@@ -194,6 +199,7 @@ const runWorkflowCommand = async ({
       usedWrapper: false,
       blocked: true,
       doctorIssued: true,
+      fastPath,
     });
     return blockedResult;
   }
@@ -231,6 +237,7 @@ const runWorkflowCommand = async ({
     usedWrapper: true,
     blocked: false,
     doctorIssued: false,
+    fastPath,
   });
   return result;
 };

package/src/tools/smart-context.js

@@ -14,6 +14,8 @@ import { predictContextFiles, recordContextAccess } from '../context-patterns.js
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
+import { buildMetricsDisplay } from '../utils/metrics-display.js';
+import { createProgressReporter } from '../streaming.js';
 import { 
   getDetailedDiff, 
   analyzeChangeImpact, 
@@ -385,7 +387,15 @@ export const smartContext = async ({
   detail = 'balanced',
   include = DEFAULT_INCLUDE,
   prefetch = false,
+  progress: enableProgress = false,
 }) => {
+  const progress = enableProgress ? createProgressReporter('smart_context') : null;
+  const startTime = Date.now();
+  
+  if (progress) {
+    progress.report({ phase: 'planning', task: task.substring(0, 80) });
+  }
+  
   const resolvedIntent = (intent && VALID_INTENTS.has(intent)) ? intent : inferIntent(task);
   const root = projectRoot;
   const detailMode = VALID_DETAIL_MODES.has(detail) ? detail : 'balanced';
@@ -438,6 +448,14 @@ export const smartContext = async ({
       return impactB - impactA;
     });
     
+    if (progress) {
+      progress.report({ 
+        phase: 'diff-analysis', 
+        changedFiles: changed.files.length,
+        expandedFiles: expandedFiles.size,
+      });
+    }
+    
     diffSummary = {
       ref: changed.ref,
       totalChanged: changed.files.length + changed.skippedDeleted,
@@ -467,6 +485,10 @@ export const smartContext = async ({
       ...fallbackKeywords,
       extractFallbackSearchQuery(task),
     ]).slice(0, 6);
+    if (progress) {
+      progress.report({ phase: 'searching', queries: queryCandidates.length });
+    }
+    
     const searchResults = await Promise.all(
       queryCandidates.map((query) => smartSearch({ query, cwd: '.', intent: resolvedIntent }))
     );
@@ -602,6 +624,10 @@ export const smartContext = async ({
   }
 
   if (pendingReads.length > 0) {
+    if (progress) {
+      progress.report({ phase: 'reading', files: pendingReads.length });
+    }
+    
     const batchResults = await smartReadBatch({
       files: pendingReads.map(({ item }) => ({ path: item.absPath, mode: item.mode })),
     });
@@ -796,6 +822,28 @@ export const smartContext = async ({
     tests: coverageMin(perFile.map((c) => c.tests)),
   };
 
+  const filesIncluded = new Set(context.map((c) => c.file)).size;
+  const metricsDisplay = buildMetricsDisplay({
+    tool: 'smart_context',
+    target: task,
+    metrics: {
+      rawTokens: totalRawTokens,
+      compressedTokens: totalCompressedTokens,
+      savedTokens,
+    },
+    startTime: enableProgress ? startTime : null,
+    filesCount: filesIncluded,
+  });
+
+  if (progress) {
+    progress.complete({
+      task: task.substring(0, 80),
+      files: filesIncluded,
+      savedTokens,
+      savingsPct: totalRawTokens > 0 ? ((savedTokens / totalRawTokens) * 100).toFixed(1) : null,
+    });
+  }
+
   const result = {
     success: true,
     task,
@@ -807,7 +855,7 @@ export const smartContext = async ({
     metrics: {
       contentTokens,
       totalTokens: 0,
-      filesIncluded: new Set(context.map((c) => c.file)).size,
+      filesIncluded,
       filesEvaluated: expanded.size,
       savingsPct,
       detailMode,
@@ -825,6 +873,7 @@ export const smartContext = async ({
         }
       } : {})
     },
+    metricsDisplay,
     ...(includeSet.has('hints') ? { hints } : {}),
   };
 

package/src/tools/smart-read.js

@@ -12,6 +12,8 @@ import { countTokens } from '../tokenCounter.js';
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
+import { buildMetricsDisplay } from '../utils/metrics-display.js';
+import { createProgressReporter } from '../streaming.js';
 
 const execFile = promisify(execFileCb);
 import { summarizeGo, summarizeRust, summarizeJava, summarizeShell, summarizeTerraform, summarizeDockerfile, summarizeSql, extractGoSymbol, extractRustSymbol, extractJavaSymbol, summarizeCsharp, extractCsharpSymbol, summarizeKotlin, extractKotlinSymbol, summarizePhp, extractPhpSymbol, summarizeSwift, extractSwiftSymbol } from './smart-read/additional-languages.js';
@@ -408,14 +410,26 @@ const formatContextSections = (sections) => {
   return parts.length > 0 ? '\n' + parts.join('\n') : '';
 };
 
-export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine, symbol, maxTokens, context: includeContext, cwd }) => {
+export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine, symbol, maxTokens, context: includeContext, cwd, progress: enableProgress = false }) => {
+  const progress = enableProgress ? createProgressReporter('smart_read') : null;
+  const startTime = Date.now();
+  
   let fullPath, content;
   const effectiveRoot = cwd || projectRoot;
   
+  if (progress) {
+    progress.report({ phase: 'reading', file: filePath });
+  }
+  
   try {
     const result = readTextFile(filePath, effectiveRoot);
     fullPath = result.fullPath;
     content = result.content;
+    
+    if (progress) {
+      const rawTokens = countTokens(content);
+      progress.report({ phase: 'loaded', file: path.relative(effectiveRoot, fullPath), rawTokens });
+    }
   } catch (error) {
     const errorMessage = error.message || String(error);
     return {
@@ -479,6 +493,18 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
     cacheHit = g.cached;
   }
 
+  if (progress) {
+    const compressedTokens = countTokens(compressedText);
+    const rawTokens = countTokens(content);
+    progress.report({ 
+      phase: 'compressed', 
+      mode: effectiveMode,
+      rawTokens, 
+      compressedTokens,
+      ratio: rawTokens > 0 ? (rawTokens / compressedTokens).toFixed(1) : null,
+    });
+  }
+
   let contextResult = null;
 
   if (mode === 'symbol' && includeContext && symbol) {
@@ -545,6 +571,22 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
   const confidence = { parser, truncated, cached: cacheHit && !contextResult };
   if (contextResult) confidence.graphCoverage = contextResult.graphCoverage;
 
+  const metricsDisplay = buildMetricsDisplay({
+    tool: 'smart_read',
+    target: path.relative(effectiveRoot, fullPath),
+    metrics,
+    startTime: enableProgress ? startTime : null,
+  });
+
+  if (progress) {
+    progress.complete({
+      file: path.relative(effectiveRoot, fullPath),
+      mode: effectiveMode,
+      savedTokens: metrics.savedTokens,
+      savingsPct: metrics.savingsPct,
+    });
+  }
+
   const result = {
     filePath: fullPath,
     mode,
@@ -553,6 +595,7 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
     content: compressedText,
     confidence,
     metrics,
+    metricsDisplay,
   };
 
   if (cacheHit && !contextResult) result.cached = true;

package/src/tools/smart-search.js

@@ -12,6 +12,8 @@ import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
 import { IGNORED_DIRS, IGNORED_FILE_NAMES } from '../config/ignored-paths.js';
+import { buildMetricsDisplay } from '../utils/metrics-display.js';
+import { createProgressReporter } from '../streaming.js';
 
 const execFile = promisify(execFileCallback);
 const supportedGlobs = [
@@ -293,7 +295,14 @@ const buildCompactResult = (groups, totalMatches, query, root) => {
   return lines.join('\n');
 };
 
-export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = false }) => {
+export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = false, progress: enableProgress = false }) => {
+  const progress = enableProgress ? createProgressReporter('smart_search') : null;
+  const startTime = Date.now();
+  
+  if (progress) {
+    progress.report({ phase: 'searching', query });
+  }
+  
   const root = resolveSafePath(cwd);
   const rgMatches = _testForceWalk ? null : await searchWithRipgrep(root, query);
   const usedFallback = rgMatches === null;
@@ -340,6 +349,11 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
   let graphHits = null;
   let indexFreshness = 'unavailable';
   let loadedIndex = null;
+  
+  if (progress) {
+    progress.report({ phase: 'ranking', rawMatches: rawMatches.length });
+  }
+  
   try {
     loadedIndex = loadIndex(indexRoot);
     if (loadedIndex) {
@@ -422,6 +436,24 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
 
   const confidence = { level: retrievalConfidence, indexFreshness };
 
+  const metricsDisplay = buildMetricsDisplay({
+    tool: 'smart_search',
+    target: query,
+    metrics,
+    startTime: enableProgress ? startTime : null,
+    filesCount: groups.length,
+  });
+
+  if (progress) {
+    progress.complete({
+      query,
+      matches: dedupedMatches.length,
+      files: groups.length,
+      savedTokens: metrics.savedTokens,
+      savingsPct: metrics.savingsPct,
+    });
+  }
+
   const result = {
     query,
     root,
@@ -437,6 +469,7 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
     topFiles: groups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
     matches: compressedText,
     metrics,
+    metricsDisplay,
   };
 
   if (provenance) result.provenance = provenance;

package/src/tools/smart-shell.js

@@ -7,6 +7,7 @@ import { pickRelevantLines, truncate, uniqueLines } from '../utils/text.js';
 import { recordToolUsage } from '../usage-feedback.js';
 import { recordDecision, DECISION_REASONS, EXPECTED_BENEFITS } from '../decision-explainer.js';
 import { recordDevctxOperation } from '../missed-opportunities.js';
+import { buildMetricsDisplay } from '../utils/metrics-display.js';
 
 const execFile = promisify(execFileCallback);
 const isShellDisabled = () => process.env.DEVCTX_SHELL_DISABLED === 'true';
@@ -289,6 +290,13 @@ export const smartShell = async ({ command }) => {
     context: `${outputLines} lines → ${compressedText.split('\n').length} lines (relevant only)`,
   });
 
+  const metricsDisplay = buildMetricsDisplay({
+    tool: 'smart_shell',
+    target: command,
+    metrics,
+    startTime: null,
+  });
+
   const result = {
     command,
     exitCode: execution.code,
@@ -296,6 +304,7 @@ export const smartShell = async ({ command }) => {
     output: compressedText,
     confidence: { blocked: false, timedOut: !!execution.timedOut },
     metrics,
+    metricsDisplay,
   };
 
   if (execution.timedOut) result.timedOut = true;

package/src/utils/metrics-display.js

@@ -0,0 +1,63 @@
+const formatNumber = (value) => {
+  if (value >= 1000000) {
+    return `${(value / 1000000).toFixed(1)}M`;
+  }
+  if (value >= 1000) {
+    return `${(value / 1000).toFixed(1)}K`;
+  }
+  return String(value);
+};
+
+const formatRatio = (raw, compressed) => {
+  if (raw === 0 || compressed === 0) {
+    return null;
+  }
+  const ratio = raw / compressed;
+  if (ratio < 2) {
+    return null;
+  }
+  return `${ratio.toFixed(1)}:1`;
+};
+
+const formatDuration = (startTime) => {
+  if (!startTime) {
+    return null;
+  }
+  const elapsed = Date.now() - startTime;
+  if (elapsed < 1000) {
+    return `${elapsed}ms`;
+  }
+  return `${(elapsed / 1000).toFixed(1)}s`;
+};
+
+export const buildMetricsDisplay = ({ tool, target, metrics, startTime, filesCount }) => {
+  const parts = [`✓ ${tool}`];
+
+  if (target) {
+    const shortTarget = target.length > 40 ? `${target.slice(0, 37)}...` : target;
+    parts.push(shortTarget);
+  }
+
+  if (filesCount && filesCount > 1) {
+    parts.push(`${filesCount} files`);
+  }
+
+  if (metrics?.rawTokens > 0 && metrics?.compressedTokens > 0) {
+    const raw = formatNumber(metrics.rawTokens);
+    const compressed = formatNumber(metrics.compressedTokens);
+    const ratio = formatRatio(metrics.rawTokens, metrics.compressedTokens);
+    
+    if (ratio) {
+      parts.push(`${raw}→${compressed} tokens (${ratio})`);
+    } else {
+      parts.push(`${raw}→${compressed} tokens`);
+    }
+  }
+
+  const duration = formatDuration(startTime);
+  if (duration) {
+    parts.push(duration);
+  }
+
+  return parts.join(', ');
+};