smart-context-mcp 1.1.0 → 1.2.0

package/src/analytics/adoption.js

@@ -0,0 +1,197 @@
+/**
+ * Adoption analytics - measures how often agents use devctx tools in practice
+ * 
+ * Limitations:
+ * - Complexity is inferred from operation count, not actual task complexity
+ * - Can't detect feedback shown (requires agent cooperation)
+ * - Can't detect forcing prompts (requires prompt analysis)
+ * - Can only measure when devctx IS used, not when it's ignored
+ */
+
+const DEVCTX_TOOLS = new Set([
+  'smart_read',
+  'smart_search',
+  'smart_context',
+  'smart_shell',
+  'smart_summary',
+  'smart_turn',
+  'smart_read_batch',
+  'smart_metrics',
+  'build_index',
+  'warm_cache',
+  'git_blame',
+  'cross_project',
+]);
+
+const inferComplexity = (opCount, fileCount) => {
+  if (opCount <= 2 && fileCount <= 1) return 'trivial';
+  if (opCount <= 5 && fileCount <= 3) return 'simple';
+  if (opCount <= 15 && fileCount <= 10) return 'moderate';
+  return 'complex';
+};
+
+const groupBySession = (entries) => {
+  const sessions = new Map();
+  
+  for (const entry of entries) {
+    const sessionId = entry.sessionId || entry.session_id || 'unknown';
+    
+    if (!sessions.has(sessionId)) {
+      sessions.set(sessionId, {
+        sessionId,
+        operations: [],
+        devctxTools: new Set(),
+        nativeTools: new Set(),
+        filesAccessed: new Set(),
+        totalRawTokens: 0,
+        totalCompressedTokens: 0,
+        totalSavedTokens: 0,
+      });
+    }
+    
+    const session = sessions.get(sessionId);
+    session.operations.push(entry);
+    
+    const tool = entry.tool;
+    if (DEVCTX_TOOLS.has(tool)) {
+      session.devctxTools.add(tool);
+    } else if (tool) {
+      session.nativeTools.add(tool);
+    }
+    
+    if (entry.target) {
+      session.filesAccessed.add(entry.target);
+    }
+    
+    session.totalRawTokens += Number(entry.rawTokens || entry.raw_tokens || 0);
+    session.totalCompressedTokens += Number(entry.compressedTokens || entry.compressed_tokens || 0);
+    session.totalSavedTokens += Number(entry.savedTokens || entry.saved_tokens || 0);
+  }
+  
+  return Array.from(sessions.values());
+};
+
+export const analyzeAdoption = (entries) => {
+  const sessions = groupBySession(entries);
+  
+  const sessionsWithDevctx = sessions.filter(s => s.devctxTools.size > 0);
+  const sessionsWithoutDevctx = sessions.filter(s => s.devctxTools.size === 0 && s.operations.length > 0);
+  
+  const byComplexity = {
+    trivial: { total: 0, withDevctx: 0 },
+    simple: { total: 0, withDevctx: 0 },
+    moderate: { total: 0, withDevctx: 0 },
+    complex: { total: 0, withDevctx: 0 },
+  };
+  
+  for (const session of sessions) {
+    const complexity = inferComplexity(session.operations.length, session.filesAccessed.size);
+    byComplexity[complexity].total += 1;
+    if (session.devctxTools.size > 0) {
+      byComplexity[complexity].withDevctx += 1;
+    }
+  }
+  
+  const nonTrivialSessions = sessions.filter(s => {
+    const complexity = inferComplexity(s.operations.length, s.filesAccessed.size);
+    return complexity !== 'trivial';
+  });
+  
+  const nonTrivialWithDevctx = nonTrivialSessions.filter(s => s.devctxTools.size > 0);
+  
+  const toolUsageCount = {};
+  for (const session of sessionsWithDevctx) {
+    for (const tool of session.devctxTools) {
+      toolUsageCount[tool] = (toolUsageCount[tool] || 0) + 1;
+    }
+  }
+  
+  return {
+    totalSessions: sessions.length,
+    sessionsWithDevctx: sessionsWithDevctx.length,
+    sessionsWithoutDevctx: sessionsWithoutDevctx.length,
+    adoptionRate: sessions.length > 0 
+      ? Number(((sessionsWithDevctx.length / sessions.length) * 100).toFixed(1))
+      : 0,
+    
+    nonTrivial: {
+      total: nonTrivialSessions.length,
+      withDevctx: nonTrivialWithDevctx.length,
+      adoptionRate: nonTrivialSessions.length > 0
+        ? Number(((nonTrivialWithDevctx.length / nonTrivialSessions.length) * 100).toFixed(1))
+        : 0,
+    },
+    
+    byComplexity: Object.fromEntries(
+      Object.entries(byComplexity).map(([level, stats]) => [
+        level,
+        {
+          ...stats,
+          adoptionRate: stats.total > 0 
+            ? Number(((stats.withDevctx / stats.total) * 100).toFixed(1))
+            : 0,
+        },
+      ])
+    ),
+    
+    toolUsageCount,
+    
+    avgToolsPerSession: sessionsWithDevctx.length > 0
+      ? Number((sessionsWithDevctx.reduce((sum, s) => sum + s.devctxTools.size, 0) / sessionsWithDevctx.length).toFixed(1))
+      : 0,
+    
+    avgTokenSavingsWhenUsed: sessionsWithDevctx.length > 0
+      ? Number((sessionsWithDevctx.reduce((sum, s) => sum + s.totalSavedTokens, 0) / sessionsWithDevctx.length).toFixed(0))
+      : 0,
+  };
+};
+
+export const formatAdoptionReport = (stats) => {
+  const lines = [];
+  
+  lines.push('');
+  lines.push('Adoption Analysis (Inferred from Tool Usage)');
+  lines.push('');
+  lines.push(`Total sessions:        ${stats.totalSessions}`);
+  lines.push(`Sessions with devctx:  ${stats.sessionsWithDevctx} (${stats.adoptionRate}%)`);
+  lines.push(`Sessions without:      ${stats.sessionsWithoutDevctx} (${100 - stats.adoptionRate}%)`);
+  lines.push('');
+  
+  lines.push('Non-Trivial Tasks Only:');
+  lines.push(`Total:                 ${stats.nonTrivial.total}`);
+  lines.push(`With devctx:           ${stats.nonTrivial.withDevctx} (${stats.nonTrivial.adoptionRate}%)`);
+  lines.push(`Without devctx:        ${stats.nonTrivial.total - stats.nonTrivial.withDevctx} (${100 - stats.nonTrivial.adoptionRate}%)`);
+  lines.push('');
+  
+  lines.push('By Inferred Complexity:');
+  for (const [level, data] of Object.entries(stats.byComplexity)) {
+    if (data.total === 0) continue;
+    lines.push(`- ${level.padEnd(10)} ${data.withDevctx}/${data.total} (${data.adoptionRate}%)`);
+  }
+  lines.push('');
+  
+  if (stats.sessionsWithDevctx > 0) {
+    lines.push('When devctx IS used:');
+    lines.push(`Avg tools/session:     ${stats.avgToolsPerSession}`);
+    lines.push(`Avg token savings:     ${stats.avgTokenSavingsWhenUsed.toLocaleString()} tokens`);
+    lines.push('');
+  }
+  
+  lines.push('Top Tools Used:');
+  const sortedTools = Object.entries(stats.toolUsageCount)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5);
+  for (const [tool, count] of sortedTools) {
+    lines.push(`- ${tool.padEnd(20)} ${count} sessions`);
+  }
+  lines.push('');
+  
+  lines.push('Limitations:');
+  lines.push('- Complexity inferred from operation count (not actual task complexity)');
+  lines.push('- Can only measure when devctx IS used (tool calls visible)');
+  lines.push('- Cannot measure feedback shown or forcing prompts (requires agent cooperation)');
+  lines.push('- Sessions without devctx may be simple tasks (not adoption failures)');
+  lines.push('');
+  
+  return lines.join('\n');
+};

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-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

@@ -363,7 +363,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);
 

package/src/tools/smart-shell.js

@@ -6,11 +6,21 @@ import { projectRoot } from '../utils/paths.js';
 import { pickRelevantLines, truncate, uniqueLines } from '../utils/text.js';
 
 const execFile = promisify(execFileCallback);
-const blockedPattern = /[|&;<>`\n\r]/;
+const isShellDisabled = () => process.env.DEVCTX_SHELL_DISABLED === 'true';
+const blockedPattern = /[|&;<>`\n\r$()]/;
 const allowedCommands = new Set(['pwd', 'ls', 'find', 'rg', 'git', 'npm', 'pnpm', 'yarn', 'bun']);
-const allowedGitSubcommands = new Set(['status', 'diff', 'show', 'log', 'branch', 'rev-parse']);
+const allowedGitSubcommands = new Set(['status', 'diff', 'show', 'log', 'branch', 'rev-parse', 'blame']);
 const allowedPackageManagerSubcommands = new Set(['test', 'run', 'lint', 'build', 'typecheck', 'check']);
-const safeRunScriptPattern = /^(test|lint|build|typecheck|check|smoke|verify)(:|$)/;
+const safeRunScriptPattern = /^(test|lint|build|typecheck|check|smoke|verify|eval)(:|$)/;
+const dangerousPatterns = [
+  /rm\s+-rf/i,
+  /sudo/i,
+  /curl.*\|/i,
+  /wget.*\|/i,
+  /eval/i,
+  /exec/i,
+];
+const MAX_COMMAND_LENGTH = 500;
 
 const tokenize = (command) => {
   const tokens = [];
@@ -67,12 +77,26 @@ const tokenize = (command) => {
 };
 
 const validateCommand = (command, tokens) => {
+  if (isShellDisabled()) {
+    return 'Shell execution is disabled (DEVCTX_SHELL_DISABLED=true)';
+  }
+
   if (!command.trim()) {
     return 'Command is empty';
   }
 
-  if (blockedPattern.test(command) || command.includes('$(')) {
-    return 'Shell operators are not allowed';
+  if (command.length > MAX_COMMAND_LENGTH) {
+    return `Command too long (max ${MAX_COMMAND_LENGTH} chars)`;
+  }
+
+  if (blockedPattern.test(command)) {
+    return 'Shell operators are not allowed (|, &, ;, <, >, `, $, (, ))';
+  }
+
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(command)) {
+      return `Dangerous pattern detected: ${pattern.source}`;
+    }
   }
 
   if (tokens.length === 0) {
@@ -82,11 +106,11 @@ const validateCommand = (command, tokens) => {
   const [baseCommand, subcommand, thirdToken] = tokens;
 
   if (!allowedCommands.has(baseCommand)) {
-    return `Command not allowed: ${baseCommand}`;
+    return `Command not allowed: ${baseCommand}. Allowed: ${[...allowedCommands].join(', ')}`;
   }
 
   if (baseCommand === 'git' && !allowedGitSubcommands.has(subcommand)) {
-    return `Git subcommand not allowed: ${subcommand ?? '(missing)'}`;
+    return `Git subcommand not allowed: ${subcommand ?? '(missing)'}. Allowed: ${[...allowedGitSubcommands].join(', ')}`;
   }
 
   if (baseCommand === 'find') {
@@ -99,11 +123,11 @@ const validateCommand = (command, tokens) => {
 
   if (['npm', 'pnpm', 'yarn', 'bun'].includes(baseCommand)) {
     if (!subcommand || !allowedPackageManagerSubcommands.has(subcommand)) {
-      return `Package manager subcommand not allowed: ${subcommand ?? '(missing)'}`;
+      return `Package manager subcommand not allowed: ${subcommand ?? '(missing)'}. Allowed: ${[...allowedPackageManagerSubcommands].join(', ')}`;
     }
 
     if (subcommand === 'run' && (!thirdToken || !safeRunScriptPattern.test(thirdToken))) {
-      return `Package manager script not allowed: ${thirdToken ?? '(missing)'}`;
+      return `Package manager script not allowed: ${thirdToken ?? '(missing)'}. Allowed pattern: ${safeRunScriptPattern.source}`;
     }
   }
 

package/src/tools/smart-turn.js

@@ -205,6 +205,7 @@ const startTurn = async ({
       })
     : null;
 
+
   return {
     phase: 'start',
     promptPreview: truncate(prompt, MAX_PROMPT_PREVIEW),

package/src/workflow-tracker-stub.js

@@ -0,0 +1,53 @@
+// Stub for workflow tracking (to be implemented in future version)
+// This avoids SQLite issues in tests while keeping the API available
+
+export const detectWorkflowType = () => null;
+export const getWorkflowBaseline = () => 0;
+export const startWorkflow = () => null;
+export const endWorkflow = () => null;
+export const getWorkflowMetrics = () => [];
+export const getWorkflowSummaryByType = () => [];
+export const autoTrackWorkflow = () => null;
+
+export const WORKFLOW_DEFINITIONS = {
+  debugging: {
+    name: 'Debugging',
+    description: 'Error-first, symbol-focused debugging workflow',
+    typicalTools: ['smart_turn', 'smart_search', 'smart_read', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 150000,
+    pattern: /debug|error|bug|fix|fail/i,
+  },
+  'code-review': {
+    name: 'Code Review',
+    description: 'Diff-aware, API-focused code review workflow',
+    typicalTools: ['smart_turn', 'smart_context', 'smart_read', 'git_blame', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 200000,
+    pattern: /review|pr|pull.?request|approve/i,
+  },
+  refactoring: {
+    name: 'Refactoring',
+    description: 'Graph-aware, test-verified refactoring workflow',
+    typicalTools: ['smart_turn', 'smart_context', 'smart_read', 'git_blame', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 180000,
+    pattern: /refactor|extract|rename|move|restructure/i,
+  },
+  testing: {
+    name: 'Testing',
+    description: 'Coverage-aware, TDD-friendly testing workflow',
+    typicalTools: ['smart_turn', 'smart_search', 'smart_read', 'smart_context', 'smart_shell'],
+    minTools: 3,
+    baselineTokens: 120000,
+    pattern: /test|spec|coverage|tdd/i,
+  },
+  architecture: {
+    name: 'Architecture Exploration',
+    description: 'Index-first, minimal-detail architecture exploration',
+    typicalTools: ['smart_turn', 'smart_context', 'smart_search', 'smart_read', 'cross_project'],
+    minTools: 3,
+    baselineTokens: 300000,
+    pattern: /architect|explore|understand|structure|design/i,
+  },
+};