smart-context-mcp 1.4.0 → 1.6.0

package/src/utils/mutation-safety.js

@@ -0,0 +1,85 @@
+import { HARD_BLOCK_REPO_SAFETY_REASONS } from '../repo-safety.js';
+
+export const buildMutationSafety = (
+  repoSafety,
+  {
+    subject = 'Project-local context writes',
+  } = {},
+) => {
+  if (!repoSafety || repoSafety.available === false) {
+    return null;
+  }
+
+  const blockedBy = HARD_BLOCK_REPO_SAFETY_REASONS
+    .filter(([, field]) => repoSafety[field])
+    .map(([reason]) => reason);
+  const blocked = blockedBy.length > 0;
+  const stateDbPath = repoSafety.stateDbPath ?? '.devctx/state.sqlite';
+
+  return {
+    blocked,
+    blockedBy,
+    stateDbPath,
+    recommendedActions: repoSafety.recommendedActions ?? [],
+    message: blocked
+      ? `${subject} are blocked until git hygiene is fixed for ${stateDbPath}.`
+      : `${subject} are allowed for ${stateDbPath}.`,
+  };
+};
+
+export const buildDegradedMode = (
+  {
+    sideEffectsSuppressed = false,
+    repoSafety,
+    reason = 'repo_safety_blocked',
+    mode = 'read_only_snapshot',
+    impact = 'Write-side effects are paused while git hygiene is blocked.',
+  } = {},
+) => {
+  if (!sideEffectsSuppressed) {
+    return null;
+  }
+
+  const mutationSafety = buildMutationSafety(repoSafety);
+
+  return {
+    active: true,
+    reason,
+    mode,
+    impact,
+    blockedBy: mutationSafety?.blockedBy ?? [],
+    recommendedActions: mutationSafety?.recommendedActions ?? repoSafety?.recommendedActions ?? [],
+    message: mutationSafety?.blocked
+      ? `${impact} Reads continue in degraded mode until repo safety is fixed.`
+      : `${impact} Reads continue in degraded mode.`,
+  };
+};
+
+export const attachSafetyMetadata = (
+  result,
+  {
+    repoSafety = null,
+    sideEffectsSuppressed = false,
+    subject,
+    degradedReason,
+    degradedMode,
+    degradedImpact,
+  } = {},
+) => {
+  const mutationSafety = buildMutationSafety(repoSafety, { subject });
+  const degraded = buildDegradedMode({
+    sideEffectsSuppressed,
+    repoSafety,
+    reason: degradedReason,
+    mode: degradedMode,
+    impact: degradedImpact,
+  });
+
+  return {
+    ...result,
+    ...(mutationSafety ? { mutationSafety } : {}),
+    repoSafety,
+    sideEffectsSuppressed: Boolean(sideEffectsSuppressed),
+    ...(degraded ? { degradedMode: degraded } : {}),
+  };
+};

package/src/workflow-tracker.js

@@ -1,8 +1,47 @@
-import { withStateDb } from './storage/sqlite.js';
+import { getRepoMutationSafety } from './repo-safety.js';
+import { withStateDb, withStateDbSnapshot } from './storage/sqlite.js';
+import { getNetSavedTokens } from './metrics.js';
+
+const WORKFLOW_TRACKING_ENABLED_RE = /^(1|true|yes|on)$/i;
+const EMPTY_OBJECT = Object.freeze({});
+
+const parseJson = (value, fallback = EMPTY_OBJECT) => {
+  try {
+    return JSON.parse(value || JSON.stringify(fallback));
+  } catch {
+    return fallback;
+  }
+};
+
+const toRoundedPct = (covered, total) => (total > 0 ? Number(((covered / total) * 100).toFixed(2)) : 0);
+
+const buildWorkflowNetMetricsCoverage = ({ source, hasNetMetrics }) => ({
+  available: hasNetMetrics,
+  source: hasNetMetrics ? source : 'none',
+});
+
+const buildSummaryNetMetricsCoverage = ({ coveredWorkflows, totalWorkflows }) => ({
+  coveredWorkflows,
+  totalWorkflows,
+  uncoveredWorkflows: Math.max(0, totalWorkflows - coveredWorkflows),
+  coveragePct: toRoundedPct(coveredWorkflows, totalWorkflows),
+  complete: totalWorkflows > 0 && coveredWorkflows === totalWorkflows,
+});
+
+const getWorkflowMutationSafety = () => getRepoMutationSafety();
+
+const withWorkflowReadDb = (callback) => {
+  const safety = getWorkflowMutationSafety();
+  const reader = safety.shouldBlock ? withStateDbSnapshot : withStateDb;
+  return reader(callback);
+};
+
+export const isWorkflowTrackingEnabled = () =>
+  WORKFLOW_TRACKING_ENABLED_RE.test(process.env.DEVCTX_WORKFLOW_TRACKING ?? '');
 
 const isWorkflowTrackingAvailable = () => {
   try {
-    return withStateDb((db) => workflowTableExists(db));
+    return withWorkflowReadDb((db) => workflowTableExists(db));
   } catch {
     return false;
   }
@@ -93,6 +132,10 @@ export const getWorkflowBaseline = (workflowType) => {
  */
 export const startWorkflow = (workflowType, sessionId, metadata = {}) => {
   try {
+    if (getWorkflowMutationSafety().shouldBlock) {
+      return null;
+    }
+
     return withStateDb((db) => {
       if (!workflowTableExists(db)) {
         return null;
@@ -131,6 +174,10 @@ export const startWorkflow = (workflowType, sessionId, metadata = {}) => {
  */
 export const endWorkflow = (workflowId) => {
   try {
+    if (getWorkflowMutationSafety().shouldBlock) {
+      return null;
+    }
+
     return withStateDb((db) => {
       if (!workflowTableExists(db)) {
         return null;
@@ -140,7 +187,7 @@ export const endWorkflow = (workflowId) => {
     const workflow = db
       .prepare(
         `
-      SELECT workflow_type, session_id, start_time, baseline_tokens
+      SELECT workflow_type, session_id, start_time, baseline_tokens, metadata_json
       FROM workflow_metrics
       WHERE workflow_id = ?
     `,
@@ -160,7 +207,7 @@ export const endWorkflow = (workflowId) => {
     const metrics = db
       .prepare(
         `
-      SELECT tool, raw_tokens, compressed_tokens, saved_tokens
+      SELECT tool, raw_tokens, compressed_tokens, saved_tokens, metadata_json
       FROM metrics_events
       WHERE session_id = ? AND created_at >= ?
       ORDER BY created_at ASC
@@ -172,11 +219,33 @@ export const endWorkflow = (workflowId) => {
     const rawTokens = metrics.reduce((sum, m) => sum + (m.raw_tokens || 0), 0);
     const compressedTokens = metrics.reduce((sum, m) => sum + (m.compressed_tokens || 0), 0);
     const savedTokens = metrics.reduce((sum, m) => sum + (m.saved_tokens || 0), 0);
+    const overheadTokens = metrics.reduce((sum, metric) => {
+      try {
+        const metadata = JSON.parse(metric.metadata_json || '{}');
+        return sum + Math.max(0, Number(metadata.overheadTokens ?? 0));
+      } catch {
+        return sum;
+      }
+    }, 0);
+    const netSavedTokens = getNetSavedTokens(savedTokens, overheadTokens);
     const savingsPct = rawTokens > 0 ? ((savedTokens / rawTokens) * 100).toFixed(2) : 0;
+    const netSavingsPct = rawTokens > 0 ? ((netSavedTokens / rawTokens) * 100).toFixed(2) : 0;
 
     // Calculate vs baseline
     const baselineTokens = workflow.baseline_tokens || 0;
     const vsBaselinePct = baselineTokens > 0 ? (((baselineTokens - compressedTokens) / baselineTokens) * 100).toFixed(2) : 0;
+    const vsBaselineNetPct = baselineTokens > 0 ? (((baselineTokens - (compressedTokens + overheadTokens)) / baselineTokens) * 100).toFixed(2) : 0;
+    const persistedMetadata = parseJson(workflow.metadata_json);
+    const metadata = {
+      ...persistedMetadata,
+      summary: {
+        ...(persistedMetadata.summary ?? {}),
+        overheadTokens,
+        netSavedTokens,
+        netSavingsPct: Number(netSavingsPct),
+        vsBaselineNetPct: Number(vsBaselineNetPct),
+      },
+    };
 
     // Get unique tools used
     const toolsUsed = [...new Set(metrics.map((m) => m.tool))];
@@ -192,11 +261,24 @@ export const endWorkflow = (workflowId) => {
           compressed_tokens = ?,
           saved_tokens = ?,
           savings_pct = ?,
-          vs_baseline_pct = ?
+          vs_baseline_pct = ?,
+          metadata_json = ?
       WHERE workflow_id = ?
     `);
 
-    stmt.run(now, durationMs, JSON.stringify(toolsUsed), metrics.length, rawTokens, compressedTokens, savedTokens, savingsPct, vsBaselinePct, workflowId);
+    stmt.run(
+      now,
+      durationMs,
+      JSON.stringify(toolsUsed),
+      metrics.length,
+      rawTokens,
+      compressedTokens,
+      savedTokens,
+      savingsPct,
+      vsBaselinePct,
+      JSON.stringify(metadata),
+      workflowId,
+    );
 
       return {
         workflowId,
@@ -207,9 +289,13 @@ export const endWorkflow = (workflowId) => {
         rawTokens,
         compressedTokens,
         savedTokens,
+        overheadTokens,
+        netSavedTokens,
         savingsPct: Number(savingsPct),
+        netSavingsPct: Number(netSavingsPct),
         baselineTokens,
         vsBaselinePct: Number(vsBaselinePct),
+        vsBaselineNetPct: Number(vsBaselineNetPct),
       };
     });
   } catch {
@@ -222,7 +308,7 @@ export const endWorkflow = (workflowId) => {
  */
 export const getWorkflowMetrics = (options = {}) => {
   try {
-    return withStateDb((db) => {
+    return withWorkflowReadDb((db) => {
       if (!workflowTableExists(db)) {
         return [];
       }
@@ -279,8 +365,30 @@ export const getWorkflowMetrics = (options = {}) => {
 
       return workflows.map((w) => ({
         ...w,
-        toolsUsed: JSON.parse(w.tools_used_json || '[]'),
-        metadata: JSON.parse(w.metadata_json || '{}'),
+        ...(() => {
+          const metadata = parseJson(w.metadata_json);
+          const summary = metadata.summary ?? EMPTY_OBJECT;
+          const overheadTokens = Number(summary.overheadTokens ?? metadata.overheadTokens);
+          const hasOverhead = Number.isFinite(overheadTokens);
+          const hasPersistedNetMetrics = Number.isFinite(Number(summary.netSavedTokens));
+          const derivedNetSavedTokens = hasOverhead
+            ? getNetSavedTokens(w.saved_tokens, overheadTokens)
+            : undefined;
+          const hasNetMetrics = hasPersistedNetMetrics || hasOverhead;
+
+          return {
+            toolsUsed: parseJson(w.tools_used_json, []),
+            metadata,
+            overheadTokens: hasOverhead ? overheadTokens : undefined,
+            netSavedTokens: summary.netSavedTokens ?? derivedNetSavedTokens,
+            netSavingsPct: summary.netSavingsPct,
+            vsBaselineNetPct: summary.vsBaselineNetPct,
+            netMetricsCoverage: buildWorkflowNetMetricsCoverage({
+              source: hasPersistedNetMetrics ? 'persisted' : 'derived',
+              hasNetMetrics,
+            }),
+          };
+        })(),
       }));
     });
   } catch {
@@ -293,39 +401,95 @@ export const getWorkflowMetrics = (options = {}) => {
  */
 export const getWorkflowSummaryByType = () => {
   try {
-    return withStateDb((db) => {
+    return withWorkflowReadDb((db) => {
       if (!workflowTableExists(db)) {
         return [];
       }
-      const summary = db
-      .prepare(
-        `
-      SELECT 
-        workflow_type,
-        COUNT(*) as count,
-        SUM(raw_tokens) as total_raw_tokens,
-        SUM(compressed_tokens) as total_compressed_tokens,
-        SUM(saved_tokens) as total_saved_tokens,
-        AVG(savings_pct) as avg_savings_pct,
-        SUM(baseline_tokens) as total_baseline_tokens,
-        AVG(vs_baseline_pct) as avg_vs_baseline_pct,
-        AVG(duration_ms) as avg_duration_ms,
-        AVG(steps_count) as avg_steps_count
-      FROM workflow_metrics
-      WHERE end_time IS NOT NULL
-      GROUP BY workflow_type
-      ORDER BY count DESC
-    `,
-      )
-      .all();
-
-      return summary.map((s) => ({
-        ...s,
-        avgSavingsPct: Number(s.avg_savings_pct?.toFixed(2) || 0),
-        avgVsBaselinePct: Number(s.avg_vs_baseline_pct?.toFixed(2) || 0),
-        avgDurationMs: Math.round(s.avg_duration_ms || 0),
-        avgStepsCount: Math.round(s.avg_steps_count || 0),
-      }));
+      const workflows = db
+        .prepare(
+          `
+        SELECT
+          workflow_type,
+          raw_tokens,
+          compressed_tokens,
+          saved_tokens,
+          savings_pct,
+          baseline_tokens,
+          vs_baseline_pct,
+          duration_ms,
+          steps_count,
+          metadata_json
+        FROM workflow_metrics
+        WHERE end_time IS NOT NULL
+      `,
+        )
+        .all();
+
+      const grouped = new Map();
+
+      for (const workflow of workflows) {
+        const existing = grouped.get(workflow.workflow_type) ?? {
+          workflow_type: workflow.workflow_type,
+          count: 0,
+          total_raw_tokens: 0,
+          total_compressed_tokens: 0,
+          total_saved_tokens: 0,
+          total_overhead_tokens: 0,
+          total_net_saved_tokens: 0,
+          net_metrics_count: 0,
+          total_baseline_tokens: 0,
+          savingsPctSum: 0,
+          vsBaselinePctSum: 0,
+          durationMsSum: 0,
+          stepsCountSum: 0,
+        };
+
+        const metadata = parseJson(workflow.metadata_json);
+        const summary = metadata.summary ?? EMPTY_OBJECT;
+        const overheadTokens = Number(summary.overheadTokens);
+        const netSavedTokens = Number(summary.netSavedTokens);
+        const hasNetMetrics = Number.isFinite(overheadTokens) && Number.isFinite(netSavedTokens);
+
+        existing.count += 1;
+        existing.total_raw_tokens += workflow.raw_tokens || 0;
+        existing.total_compressed_tokens += workflow.compressed_tokens || 0;
+        existing.total_saved_tokens += workflow.saved_tokens || 0;
+        existing.total_baseline_tokens += workflow.baseline_tokens || 0;
+        existing.savingsPctSum += workflow.savings_pct || 0;
+        existing.vsBaselinePctSum += workflow.vs_baseline_pct || 0;
+        existing.durationMsSum += workflow.duration_ms || 0;
+        existing.stepsCountSum += workflow.steps_count || 0;
+
+        if (hasNetMetrics) {
+          existing.total_overhead_tokens += overheadTokens;
+          existing.total_net_saved_tokens += netSavedTokens;
+          existing.net_metrics_count += 1;
+        }
+
+        grouped.set(workflow.workflow_type, existing);
+      }
+
+      return [...grouped.values()]
+        .sort((left, right) => right.count - left.count)
+        .map((item) => ({
+          workflow_type: item.workflow_type,
+          count: item.count,
+          total_raw_tokens: item.total_raw_tokens,
+          total_compressed_tokens: item.total_compressed_tokens,
+          total_saved_tokens: item.total_saved_tokens,
+          total_overhead_tokens: item.total_overhead_tokens,
+          total_net_saved_tokens: item.total_net_saved_tokens,
+          net_metrics_count: item.net_metrics_count,
+          netMetricsCoverage: buildSummaryNetMetricsCoverage({
+            coveredWorkflows: item.net_metrics_count,
+            totalWorkflows: item.count,
+          }),
+          total_baseline_tokens: item.total_baseline_tokens,
+          avgSavingsPct: Number((item.savingsPctSum / item.count || 0).toFixed(2)),
+          avgVsBaselinePct: Number((item.vsBaselinePctSum / item.count || 0).toFixed(2)),
+          avgDurationMs: Math.round(item.durationMsSum / item.count || 0),
+          avgStepsCount: Math.round(item.stepsCountSum / item.count || 0),
+        }));
     });
   } catch {
     return [];
@@ -351,10 +515,68 @@ const workflowTableExists = (db) => {
   }
 };
 
+export const getActiveWorkflowForSession = (sessionId) => {
+  try {
+    return withWorkflowReadDb((db) => {
+      if (!workflowTableExists(db)) {
+        return null;
+      }
+
+      const workflow = db
+        .prepare(
+          `
+        SELECT
+          workflow_id,
+          workflow_type,
+          session_id,
+          start_time,
+          end_time,
+          duration_ms,
+          tools_used_json,
+          steps_count,
+          raw_tokens,
+          compressed_tokens,
+          saved_tokens,
+          savings_pct,
+          baseline_tokens,
+          vs_baseline_pct,
+          metadata_json,
+          created_at
+        FROM workflow_metrics
+        WHERE session_id = ? AND end_time IS NULL
+        ORDER BY created_at DESC
+        LIMIT 1
+      `,
+        )
+        .get(sessionId);
+
+      if (!workflow) {
+        return null;
+      }
+
+      return {
+        ...workflow,
+        toolsUsed: parseJson(workflow.tools_used_json, []),
+        metadata: parseJson(workflow.metadata_json),
+      };
+    });
+  } catch {
+    return null;
+  }
+};
+
 /**
  * Auto-detect and track workflow from session
  */
 export const autoTrackWorkflow = (sessionId, sessionGoal) => {
+  if (!sessionId || !isWorkflowTrackingEnabled()) {
+    return null;
+  }
+
+  if (getWorkflowMutationSafety().shouldBlock) {
+    return null;
+  }
+
   try {
     return withStateDb((db) => {
       // Check if table exists (migration v5)