smart-context-mcp 1.1.0 → 1.3.0

package/src/missed-opportunities.js

@@ -0,0 +1,255 @@
+/**
+ * Missed opportunities detector - identifies when devctx should have been used but wasn't
+ * 
+ * Analyzes session metrics to detect patterns where devctx would have helped.
+ * 
+ * Enable with environment variable: DEVCTX_DETECT_MISSED=true
+ * 
+ * Detection heuristics (based on session metrics):
+ * - Low devctx adoption in complex sessions (many operations, few devctx calls)
+ * - Sessions with 0 devctx usage but high operation count
+ * - Inferred complexity vs actual devctx usage
+ * 
+ * Note: We can't intercept native tool calls in real-time, so we analyze
+ * patterns from metrics after the fact.
+ */
+
+const sessionActivity = {
+  devctxOperations: 0,
+  totalOperations: 0, // Estimated from devctx calls + time-based heuristic
+  lastDevctxCall: 0,
+  sessionStart: Date.now(),
+  enabled: false,
+  warnings: [],
+};
+
+const DEVCTX_TOOLS = new Set([
+  'smart_read',
+  'smart_search',
+  'smart_context',
+  'smart_shell',
+  'smart_summary',
+  'smart_turn',
+  'smart_read_batch',
+  'build_index',
+]);
+
+/**
+ * Check if missed opportunity detection is enabled
+ */
+export const isMissedDetectionEnabled = () => {
+  const envValue = process.env.DEVCTX_DETECT_MISSED?.toLowerCase();
+  const enabled = envValue === 'true' || envValue === '1' || envValue === 'yes';
+  sessionActivity.enabled = enabled;
+  return enabled;
+};
+
+/**
+ * Record devctx tool usage
+ */
+export const recordDevctxOperation = () => {
+  if (!isMissedDetectionEnabled()) return;
+  
+  sessionActivity.devctxOperations += 1;
+  sessionActivity.totalOperations += 1;
+  sessionActivity.lastDevctxCall = Date.now();
+};
+
+/**
+ * Estimate total operations based on time and activity
+ * Heuristic: If no devctx calls for >2 minutes, likely agent is using native tools
+ */
+const estimateTotalOperations = () => {
+  const now = Date.now();
+  const sessionDuration = now - sessionActivity.sessionStart;
+  const timeSinceLastDevctx = now - sessionActivity.lastDevctxCall;
+  
+  // If session is active (recent devctx calls), estimate conservatively
+  if (timeSinceLastDevctx < 2 * 60 * 1000) {
+    return sessionActivity.totalOperations;
+  }
+  
+  // If long gap without devctx, estimate agent is using native tools
+  // Heuristic: ~1 operation per 10 seconds of activity
+  const estimatedNativeOps = Math.floor(timeSinceLastDevctx / 10000);
+  return sessionActivity.totalOperations + estimatedNativeOps;
+};
+
+/**
+ * Analyze session and detect missed opportunities
+ */
+export const analyzeMissedOpportunities = () => {
+  if (!isMissedDetectionEnabled()) return null;
+  
+  const now = Date.now();
+  const sessionDuration = now - sessionActivity.sessionStart;
+  const timeSinceLastDevctx = now - sessionActivity.lastDevctxCall;
+  const estimatedTotal = estimateTotalOperations();
+  
+  const opportunities = [];
+  
+  // Detection 1: Long session with no devctx usage
+  if (sessionDuration > 5 * 60 * 1000 && sessionActivity.devctxOperations === 0) {
+    opportunities.push({
+      type: 'no_devctx_usage',
+      severity: 'high',
+      reason: 'Session active for >5 minutes with 0 devctx calls. Agent may not be using devctx.',
+      suggestion: 'Use forcing prompt or check if MCP is active',
+      estimatedSavings: estimatedTotal * 10000, // Estimate ~10K tokens per operation
+    });
+  }
+  
+  // Detection 2: Low devctx adoption in active session
+  const devctxRatio = estimatedTotal > 0 ? sessionActivity.devctxOperations / estimatedTotal : 0;
+  if (estimatedTotal >= 10 && devctxRatio < 0.3) {
+    opportunities.push({
+      type: 'low_devctx_adoption',
+      severity: 'medium',
+      reason: `Low devctx adoption: ${sessionActivity.devctxOperations}/${estimatedTotal} operations (${Math.round(devctxRatio * 100)}%). Target: >50%.`,
+      suggestion: 'Agent may be using native tools. Consider forcing prompt.',
+      estimatedSavings: (estimatedTotal - sessionActivity.devctxOperations) * 8000,
+    });
+  }
+  
+  // Detection 3: Long gap without devctx (agent switched to native tools)
+  if (sessionActivity.devctxOperations > 0 && timeSinceLastDevctx > 3 * 60 * 1000) {
+    const minutesSince = Math.round(timeSinceLastDevctx / 60000);
+    opportunities.push({
+      type: 'devctx_usage_dropped',
+      severity: 'medium',
+      reason: `No devctx calls for ${minutesSince} minutes. Agent may have switched to native tools.`,
+      suggestion: 'Re-apply forcing prompt if task is still complex',
+      estimatedSavings: Math.floor(timeSinceLastDevctx / 10000) * 5000,
+    });
+  }
+  
+  // Detection 4: Session too short to analyze
+  if (sessionDuration < 60 * 1000 && opportunities.length === 0) {
+    return {
+      opportunities: [],
+      message: 'Session too short to analyze (<1 minute)',
+      devctxOperations: sessionActivity.devctxOperations,
+      estimatedTotal,
+    };
+  }
+  
+  return {
+    opportunities,
+    devctxOperations: sessionActivity.devctxOperations,
+    estimatedTotal,
+    devctxRatio: Math.round(devctxRatio * 100),
+    sessionDuration: Math.round(sessionDuration / 1000),
+    totalEstimatedSavings: opportunities.reduce((sum, opp) => sum + (opp.estimatedSavings || 0), 0),
+  };
+};
+
+/**
+ * Format missed opportunities as markdown
+ */
+export const formatMissedOpportunities = () => {
+  if (!isMissedDetectionEnabled()) return '';
+  
+  const analysis = analyzeMissedOpportunities();
+  if (!analysis) return '';
+  
+  // Don't show if session is too short or no opportunities
+  if (analysis.message || analysis.opportunities.length === 0) {
+    return '';
+  }
+  
+  const lines = [];
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push('⚠️ **Missed devctx opportunities detected:**');
+  lines.push('');
+  
+  // Show session stats
+  lines.push(`**Session stats:**`);
+  lines.push(`- Duration: ${analysis.sessionDuration}s`);
+  lines.push(`- devctx operations: ${analysis.devctxOperations}`);
+  lines.push(`- Estimated total operations: ${analysis.estimatedTotal}`);
+  lines.push(`- devctx adoption: ${analysis.devctxRatio}%`);
+  lines.push('');
+  
+  for (const opp of analysis.opportunities) {
+    const severityIcon = opp.severity === 'high' ? '🔴' : '🟡';
+    lines.push(`${severityIcon} **${opp.type.replace(/_/g, ' ')}**`);
+    lines.push(`- **Issue:** ${opp.reason}`);
+    lines.push(`- **Suggestion:** ${opp.suggestion}`);
+    
+    if (opp.estimatedSavings) {
+      lines.push(`- **Potential savings:** ~${formatTokens(opp.estimatedSavings)}`);
+    }
+    
+    lines.push('');
+  }
+  
+  if (analysis.totalEstimatedSavings > 0) {
+    lines.push(`**Total potential savings:** ~${formatTokens(analysis.totalEstimatedSavings)}`);
+    lines.push('');
+  }
+  
+  lines.push('**How to fix:**');
+  lines.push('1. Use forcing prompt: `Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)`');
+  lines.push('2. Check if index is built: `ls .devctx/index.json`');
+  lines.push('3. Verify MCP is active in Cursor settings');
+  lines.push('');
+  lines.push('*To disable: `export DEVCTX_DETECT_MISSED=false`*');
+  
+  return lines.join('\n');
+};
+
+/**
+ * Get session activity summary
+ */
+export const getSessionActivity = () => {
+  return {
+    devctxOperations: sessionActivity.devctxOperations,
+    totalOperations: sessionActivity.totalOperations,
+    estimatedTotal: estimateTotalOperations(),
+    sessionDuration: Date.now() - sessionActivity.sessionStart,
+    timeSinceLastDevctx: Date.now() - sessionActivity.lastDevctxCall,
+  };
+};
+
+/**
+ * Reset session activity (for testing or manual reset)
+ */
+export const resetSessionActivity = () => {
+  sessionActivity.devctxOperations = 0;
+  sessionActivity.totalOperations = 0;
+  sessionActivity.lastDevctxCall = 0;
+  sessionActivity.sessionStart = Date.now();
+  sessionActivity.warnings = [];
+};
+
+/**
+ * Testing helpers - expose internal state for test scenarios
+ */
+export const __testing__ = {
+  setSessionStart: (timestamp) => {
+    sessionActivity.sessionStart = timestamp;
+  },
+  setLastDevctxCall: (timestamp) => {
+    sessionActivity.lastDevctxCall = timestamp;
+  },
+  setTotalOperations: (count) => {
+    sessionActivity.totalOperations = count;
+  },
+  getSessionActivity: () => sessionActivity,
+};
+
+/**
+ * Format token count for display
+ */
+const formatTokens = (tokens) => {
+  if (tokens >= 1000000) {
+    return `${(tokens / 1000000).toFixed(1)}M tokens`;
+  }
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}K tokens`;
+  }
+  return `${tokens} tokens`;
+};
+

package/src/server.js

@@ -49,6 +49,72 @@ export const createDevctxServer = () => {
   // Enable streaming progress notifications
   setServerForStreaming(server);
 
+  // Register prompts
+  server.prompt(
+    'use-devctx',
+    'Force the agent to use devctx tools for the current task. Use this prompt at the start of your message to ensure devctx is used instead of native tools.',
+    {},
+    async () => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: 'Use devctx: smart_turn(start) → smart_context/smart_search → smart_read → smart_turn(end)',
+          },
+        },
+      ],
+    })
+  );
+
+  server.prompt(
+    'devctx-workflow',
+    'Complete devctx workflow template with all recommended steps. Includes session start, context building, file reading, and session end.',
+    {},
+    async () => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Follow this devctx workflow:
+
+1. smart_turn(start) - Start session and recover previous context
+2. smart_context(task) - Build complete context for the task
+3. smart_search(query) - Search for specific patterns if needed
+4. smart_read(file) - Read files with appropriate mode (outline/signatures/symbol)
+5. smart_turn(end) - Save checkpoint for next session
+
+Use devctx tools instead of native Read/Grep/Shell when possible.`,
+          },
+        },
+      ],
+    })
+  );
+
+  server.prompt(
+    'devctx-preflight',
+    'Preflight checklist before starting work. Ensures index is built and session is initialized.',
+    {},
+    async () => ({
+      messages: [
+        {
+          role: 'user',
+          content: {
+            type: 'text',
+            text: `Preflight checklist:
+
+1. build_index(incremental=true) - Build/update symbol index
+2. smart_turn(start) - Initialize session and recover context
+3. Proceed with your task using devctx tools
+
+This ensures optimal performance and context recovery.`,
+          },
+        },
+      ],
+    })
+  );
+
   server.tool(
     'smart_read',
     'Read a file with token-efficient modes. outline/signatures: compact structure (~90% savings). range: specific line range with line numbers. symbol: extract function/class/method by name (string or array for batch). full: file content capped at 12k chars. maxTokens: token budget — auto-selects the most detailed mode that fits (full -> outline -> signatures -> truncated). context=true (symbol mode only): includes callers, tests, and referenced types from the dependency graph; returns graphCoverage (imports/tests: full|partial|none) so the agent knows how reliable the cross-file context is. Responses are cached in memory per session and invalidated by file mtime; cached=true when served from cache. Every response includes a unified confidence block: { parser, truncated, cached, graphCoverage? }. Supports JS/TS, Python, Go, Rust, Java, C#, Kotlin, PHP, Swift, shell, Terraform, Dockerfile, SQL, JSON, TOML, YAML.',

package/src/storage/sqlite.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { projectRoot } from '../utils/runtime-config.js';
 
 export const STATE_DB_FILENAME = 'state.sqlite';
-export const SQLITE_SCHEMA_VERSION = 4;
+export const SQLITE_SCHEMA_VERSION = 5;
 export const ACTIVE_SESSION_SCOPE = 'project';
 export const EXPECTED_TABLES = [
   'active_session',
@@ -16,6 +16,7 @@ export const EXPECTED_TABLES = [
   'session_events',
   'sessions',
   'summary_cache',
+  'workflow_metrics',
 ];
 
 const MIGRATIONS = [
@@ -145,6 +146,34 @@ const MIGRATIONS = [
         ON context_access(session_id, timestamp DESC)`,
     ],
   },
+  {
+    version: 5,
+    statements: [
+      `CREATE TABLE IF NOT EXISTS workflow_metrics (
+        workflow_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        workflow_type TEXT NOT NULL,
+        session_id TEXT,
+        start_time TEXT NOT NULL,
+        end_time TEXT,
+        duration_ms INTEGER,
+        tools_used_json TEXT NOT NULL DEFAULT '[]',
+        steps_count INTEGER NOT NULL DEFAULT 0,
+        raw_tokens INTEGER NOT NULL DEFAULT 0,
+        compressed_tokens INTEGER NOT NULL DEFAULT 0,
+        saved_tokens INTEGER NOT NULL DEFAULT 0,
+        savings_pct REAL NOT NULL DEFAULT 0,
+        baseline_tokens INTEGER NOT NULL DEFAULT 0,
+        vs_baseline_pct REAL NOT NULL DEFAULT 0,
+        metadata_json TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE SET NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS idx_workflow_metrics_type_created
+        ON workflow_metrics(workflow_type, created_at DESC)`,
+      `CREATE INDEX IF NOT EXISTS idx_workflow_metrics_session
+        ON workflow_metrics(session_id, created_at DESC)`,
+    ],
+  },
 ];
 
 let sqliteModulePromise = null;

package/src/tools/smart-context.js

@@ -11,6 +11,9 @@ import { resolveSafePath } from '../utils/fs.js';
 import { countTokens } from '../tokenCounter.js';
 import { persistMetrics } from '../metrics.js';
 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 { 
   getDetailedDiff, 
   analyzeChangeImpact, 
@@ -1219,15 +1222,44 @@ export const smartContext = async ({
   const contentItems = context.filter((item) => typeof item.content === 'string' && item.content.length > 0).length;
   const primaryItem = context.find((item) => item.role === 'primary');
 
+  const savedTokens = Math.max(0, totalRawTokens - totalCompressedTokens);
+  
   await persistMetrics({
     tool: 'smart_context',
     target: `${root} :: ${task}`,
     rawTokens: totalRawTokens,
     compressedTokens: totalCompressedTokens,
-    savedTokens: Math.max(0, totalRawTokens - totalCompressedTokens),
+    savedTokens,
     savingsPct,
     timestamp: new Date().toISOString(),
   });
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_context',
+    savedTokens,
+    target: task,
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  let reason = DECISION_REASONS.TASK_CONTEXT;
+  if (diff) {
+    reason = DECISION_REASONS.DIFF_ANALYSIS;
+  } else if (context.some(c => c.role === 'caller' || c.role === 'test')) {
+    reason = DECISION_REASONS.RELATED_FILES;
+  }
+  
+  recordDecision({
+    tool: 'smart_context',
+    action: `build context for "${task}"`,
+    reason,
+    alternative: 'Multiple smart_read + smart_search calls',
+    expectedBenefit: `${EXPECTED_BENEFITS.TOKEN_SAVINGS(savedTokens)}, ${EXPECTED_BENEFITS.COMPLETE_CONTEXT}`,
+    context: `${context.length} files, ${totalCompressedTokens} tokens (${savingsPct}% compression)`,
+  });
 
   if (prefetch && context.length > 0) {
     try {

package/src/tools/smart-metrics.js

@@ -14,6 +14,7 @@ import {
   readMetricsEntries,
   resolveMetricsInput,
 } from '../metrics.js';
+import { analyzeAdoption } from '../analytics/adoption.js';
 
 const WINDOW_MS = {
   '24h': 24 * 60 * 60 * 1000,
@@ -197,6 +198,8 @@ export const smartMetrics = async ({
       .filter((entry) => (tool ? entry.tool === tool : true))
       .filter((entry) => (resolvedSessionId ? entry.sessionId === resolvedSessionId : true));
 
+    const adoption = analyzeAdoption(filteredEntries);
+    
     return {
       filePath: resolved.storagePath,
       storagePath: resolved.storagePath,
@@ -212,6 +215,7 @@ export const smartMetrics = async ({
       },
       invalidLines,
       summary: aggregateMetrics(filteredEntries),
+      adoption,
       latestEntries: buildLatestEntries(filteredEntries, latest),
     };
   }
@@ -229,6 +233,8 @@ export const smartMetrics = async ({
     window,
   });
 
+  const adoption = analyzeAdoption(entries);
+  
   return {
     filePath: resolved.storagePath,
     storagePath: resolved.storagePath,
@@ -244,6 +250,7 @@ export const smartMetrics = async ({
     },
     invalidLines,
     summary: aggregateMetrics(entries),
+    adoption,
     latestEntries: buildLatestEntries(entries, latest),
   };
 };

package/src/tools/smart-read-batch.js

@@ -18,6 +18,15 @@ export const smartReadBatch = async ({ files, maxTokens }) => {
         maxTokens: item.maxTokens,
       });
 
+      if (readResult.error) {
+        results.push({
+          filePath: item.path,
+          mode: item.mode ?? 'outline',
+          error: readResult.error,
+        });
+        continue;
+      }
+
       const itemTokens = countTokens(readResult.content);
 
       if (maxTokens && totalTokens + itemTokens > maxTokens && results.length > 0) {

package/src/tools/smart-read.js

@@ -9,6 +9,9 @@ import { isDockerfile, readTextFile } from '../utils/fs.js';
 import { projectRoot } from '../utils/paths.js';
 import { truncate } from '../utils/text.js';
 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';
 
 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';
@@ -363,7 +366,27 @@ const formatContextSections = (sections) => {
 };
 
 export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine, symbol, maxTokens, context: includeContext }) => {
-  const { fullPath, content } = readTextFile(filePath);
+  let fullPath, content;
+  
+  try {
+    const result = readTextFile(filePath);
+    fullPath = result.fullPath;
+    content = result.content;
+  } catch (error) {
+    const errorMessage = error.message || String(error);
+    return {
+      error: errorMessage,
+      filePath,
+      mode,
+      metrics: buildMetrics({
+        tool: 'smart_read',
+        target: filePath,
+        rawText: '',
+        compressedText: errorMessage,
+      }),
+    };
+  }
+
   const extension = path.extname(fullPath).toLowerCase();
   const mtime = getFileMtime(fullPath);
 
@@ -433,6 +456,38 @@ export const smartRead = async ({ filePath, mode = 'outline', startLine, endLine
   });
 
   await persistMetrics(metrics);
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_read',
+    savedTokens: metrics.savedTokens,
+    target: path.relative(projectRoot, fullPath),
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  const lineCount = content.split('\n').length;
+  let reason = DECISION_REASONS.LARGE_FILE;
+  let expectedBenefit = EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens);
+  
+  if (mode === 'symbol') {
+    reason = DECISION_REASONS.SYMBOL_EXTRACTION;
+  } else if (validBudget && effectiveMode !== mode) {
+    reason = DECISION_REASONS.TOKEN_BUDGET;
+  } else if (lineCount < 100) {
+    reason = `File is small (${lineCount} lines), but using ${effectiveMode} mode for consistency`;
+  }
+  
+  recordDecision({
+    tool: 'smart_read',
+    action: `read ${path.relative(projectRoot, fullPath)} (${effectiveMode} mode)`,
+    reason,
+    alternative: 'Read (full file)',
+    expectedBenefit,
+    context: `${lineCount} lines, ${metrics.rawTokens} tokens → ${metrics.compressedTokens} tokens`,
+  });
 
   const confidence = { parser, truncated, cached: cacheHit && !contextResult };
   if (contextResult) confidence.graphCoverage = contextResult.graphCoverage;

package/src/tools/smart-search.js

@@ -8,6 +8,9 @@ import { loadIndex, queryIndex, queryRelated } from '../index.js';
 import { projectRoot } from '../utils/paths.js';
 import { isBinaryBuffer, isDockerfile, resolveSafePath } from '../utils/fs.js';
 import { truncate } 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';
 
 const execFile = promisify(execFileCallback);
 const supportedGlobs = [
@@ -381,6 +384,34 @@ export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = f
   });
 
   await persistMetrics(metrics);
+  
+  // Record usage for feedback
+  recordToolUsage({
+    tool: 'smart_search',
+    savedTokens: metrics.savedTokens,
+    target: query,
+  });
+  
+  // Record devctx operation for missed opportunity detection
+  recordDevctxOperation();
+  
+  // Record decision explanation
+  let reason = DECISION_REASONS.MULTIPLE_FILES;
+  if (validIntent) {
+    reason = DECISION_REASONS.INTENT_AWARE;
+  }
+  if (indexHits && indexHits.size > 0) {
+    reason = DECISION_REASONS.INDEX_BOOST;
+  }
+  
+  recordDecision({
+    tool: 'smart_search',
+    action: `search "${query}"${validIntent ? ` (intent: ${validIntent})` : ''}`,
+    reason,
+    alternative: 'Grep (unranked results)',
+    expectedBenefit: `${EXPECTED_BENEFITS.TOKEN_SAVINGS(metrics.savedTokens)}, ${EXPECTED_BENEFITS.BETTER_RANKING}`,
+    context: `${dedupedMatches.length} matches in ${groups.length} files, ranked by relevance`,
+  });
 
   let retrievalConfidence = 'high';
   if (provenance) {