smart-context-mcp 1.4.0 → 1.6.0

package/src/hooks/claude-hooks.js

@@ -1,4 +1,6 @@
 import { persistMetrics } from '../metrics.js';
+import { buildOperationalContextLines } from '../client-contract.js';
+import { getRepoMutationSafety } from '../repo-safety.js';
 import { countTokens } from '../tokenCounter.js';
 import { smartSummary } from '../tools/smart-summary.js';
 import { smartTurn } from '../tools/smart-turn.js';
@@ -11,7 +13,7 @@ import {
 const HOOK_CLIENT = 'claude';
 const START_MAX_TOKENS = 350;
 const STOP_MAX_TOKENS = 300;
-const MAX_CONTEXT_LINES = 5;
+const MAX_CONTEXT_LINES = 7;
 const MAX_CONTEXT_CHARS = 420;
 const MAX_PROMPT_PREVIEW = 160;
 const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit']);
@@ -50,48 +52,12 @@ const buildHookKey = ({ sessionId, agentId = null }) =>
   agentId ? `${HOOK_CLIENT}:subagent:${sessionId}:${agentId}` : `${HOOK_CLIENT}:main:${sessionId}`;
 
 const buildAdditionalContext = ({ result, sessionStart = false }) => {
-  const lines = [];
-  const repoSafety = result?.repoSafety;
-  const summary = result?.summary;
-  const continuityState = result?.continuity?.state;
-
-  if (result?.found && summary) {
-    const label = sessionStart ? 'resume' : continuityState ?? 'resume';
-    lines.push(`devctx ${label}: session ${result.sessionId}`);
-
-    if (summary.goal) {
-      lines.push(`goal: ${truncate(summary.goal, 110)}`);
-    }
-
-    if (summary.currentFocus) {
-      lines.push(`focus: ${truncate(summary.currentFocus, 110)}`);
-    }
-
-    if (summary.nextStep) {
-      lines.push(`next: ${truncate(summary.nextStep, 110)}`);
-    }
-  } else if (result?.continuity?.state === 'ambiguous_resume') {
-    lines.push('devctx: multiple persisted sessions matched this prompt.');
-    if (result?.recommendedSessionId) {
-      lines.push(`recommended session: ${result.recommendedSessionId}`);
-    }
-  } else if (result?.autoCreated && summary?.goal) {
-    lines.push(`devctx new task session: ${truncate(summary.goal, 110)}`);
-  }
-
-  if (repoSafety?.isTracked || repoSafety?.isStaged) {
-    const reasons = [];
-    if (repoSafety.isTracked) {
-      reasons.push('tracked');
-    }
-    if (repoSafety.isStaged) {
-      reasons.push('staged');
-    }
-    lines.push(`repo safety: .devctx/state.sqlite is ${reasons.join(' and ')}; context writes are blocked.`);
-  }
-
-  const clipped = lines.slice(0, MAX_CONTEXT_LINES).join('\n').slice(0, MAX_CONTEXT_CHARS).trim();
-  return clipped || null;
+  return buildOperationalContextLines(result, {
+    sessionStart,
+    maxLineLength: 110,
+    maxLines: MAX_CONTEXT_LINES,
+    maxChars: MAX_CONTEXT_CHARS,
+  });
 };
 
 const buildHookContextResponse = (hookEventName, additionalContext) => {
@@ -107,6 +73,28 @@ const buildHookContextResponse = (hookEventName, additionalContext) => {
   };
 };
 
+const readHookTurnState = (hookKey) =>
+  getHookTurnState({
+    hookKey,
+    readOnly: getRepoMutationSafety().shouldBlock,
+  });
+
+const maybeSetTrackedTurnState = async ({ hookKey, state }) => {
+  if (getRepoMutationSafety().shouldBlock) {
+    return null;
+  }
+
+  return setHookTurnState({ hookKey, state });
+};
+
+const maybeDeleteTrackedTurnState = async ({ hookKey }) => {
+  if (getRepoMutationSafety().shouldBlock) {
+    return null;
+  }
+
+  return deleteHookTurnState({ hookKey });
+};
+
 const recordHookMetrics = async ({
   action,
   sessionId,
@@ -247,7 +235,7 @@ const maybeTrackTurn = async ({
     return null;
   }
 
-  return setHookTurnState({
+  return maybeSetTrackedTurnState({
     hookKey,
     state: {
       client: HOOK_CLIENT,
@@ -308,7 +296,7 @@ const handleUserPromptSubmit = async (input) => {
 
 const handlePostToolUse = async (input) => {
   const hookKey = buildHookKey({ sessionId: input.session_id });
-  const existing = await getHookTurnState({ hookKey });
+  const existing = await readHookTurnState(hookKey);
   if (!existing) {
     return null;
   }
@@ -332,7 +320,7 @@ const handlePostToolUse = async (input) => {
     updatedAt: new Date().toISOString(),
   };
 
-  await setHookTurnState({ hookKey, state: nextState });
+  await maybeSetTrackedTurnState({ hookKey, state: nextState });
   if (checkpoint.matched || touchedFiles.length > 0) {
     await recordHookMetrics({
       action: 'PostToolUse',
@@ -346,11 +334,22 @@ const handlePostToolUse = async (input) => {
 
 const handleStop = async (input) => {
   const hookKey = buildHookKey({ sessionId: input.session_id });
-  const state = await getHookTurnState({ hookKey });
+  const state = await readHookTurnState(hookKey);
   if (!state) {
     return null;
   }
 
+  if (getRepoMutationSafety().shouldBlock) {
+    await recordHookMetrics({
+      action: 'Stop',
+      sessionId: state.projectSessionId,
+      additionalContext: '',
+      blocked: false,
+      continuityState: state.continuityState,
+    });
+    return null;
+  }
+
   const enforcement = computeStopEnforcement(state, input.last_assistant_message);
   const shouldEnforce = (state.requireCheckpoint || state.meaningfulWriteCount > 0) && enforcement.shouldBlock;
   if (!shouldEnforce || state.checkpointed) {
@@ -361,7 +360,7 @@ const handleStop = async (input) => {
       blocked: false,
       continuityState: state.continuityState,
     });
-    await deleteHookTurnState({ hookKey });
+    await maybeDeleteTrackedTurnState({ hookKey });
     return null;
   }
 
@@ -384,7 +383,7 @@ const handleStop = async (input) => {
       autoAppended: true,
       continuityState: state.continuityState,
     });
-    await deleteHookTurnState({ hookKey });
+    await maybeDeleteTrackedTurnState({ hookKey });
     return null;
   }
 

package/src/metrics.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
-import { enforceRepoSafety } from './repo-safety.js';
+import { getRepoMutationSafety } from './repo-safety.js';
 import { countTokens } from './tokenCounter.js';
 import { projectRoot } from './utils/paths.js';
 import {
@@ -16,11 +16,6 @@ import {
 const defaultMetricsDir = () => path.join(projectRoot, '.devctx');
 const defaultMetricsFile = () => path.join(defaultMetricsDir(), 'metrics.jsonl');
 const resolveEnvMetricsFile = () => process.env.DEVCTX_METRICS_FILE?.trim() || null;
-const HARD_BLOCK_REPO_SAFETY_REASONS = [
-  ['tracked', 'isTracked'],
-  ['staged', 'isStaged'],
-];
-
 export const getMetricsFilePath = () => resolveEnvMetricsFile() ?? defaultMetricsFile();
 
 let lastEnsuredDir = null;
@@ -68,6 +63,9 @@ export const getEntrySavingsPct = (
   return rawTokens > 0 ? Number(((savedTokens / rawTokens) * 100).toFixed(2)) : 0;
 };
 
+export const getNetSavedTokens = (savedTokens, overheadTokens = 0) =>
+  Math.max(0, Number(savedTokens ?? 0) - Math.max(0, Number(overheadTokens ?? 0)));
+
 export const MAX_METRICS_BYTES = 1024 * 1024;
 export const KEEP_LINES_AFTER_ROTATION = 500;
 
@@ -89,16 +87,7 @@ const readActiveSessionIdFromDb = (db) =>
   db.prepare('SELECT session_id FROM active_session WHERE scope = ?').get(ACTIVE_SESSION_SCOPE)?.session_id ?? null;
 
 const getSqliteSafetyPolicy = () => {
-  const repoSafety = enforceRepoSafety();
-  const reasons = HARD_BLOCK_REPO_SAFETY_REASONS
-    .filter(([, field]) => repoSafety[field])
-    .map(([reason]) => reason);
-
-  return {
-    repoSafety,
-    shouldBlock: reasons.length > 0,
-    reasons,
-  };
+  return getRepoMutationSafety();
 };
 
 export const getActiveSessionId = async () => {
@@ -258,20 +247,34 @@ export const aggregateMetrics = (entries) => {
 
   const tools = [...byTool.values()]
     .map((item) => ({
+      constOverhead: overheadByTool.get(item.tool)?.overheadTokens ?? 0,
       ...item,
+    }))
+    .map((item) => ({
+      ...item,
+      overheadTokens: item.constOverhead,
+      netSavedTokens: getNetSavedTokens(item.savedTokens, item.constOverhead),
       savingsPct: item.rawTokens > 0 ? Number(((item.savedTokens / item.rawTokens) * 100).toFixed(2)) : 0,
+      netSavingsPct: item.rawTokens > 0
+        ? Number(((getNetSavedTokens(item.savedTokens, item.constOverhead) / item.rawTokens) * 100).toFixed(2))
+        : 0,
     }))
+    .map(({ constOverhead, ...item }) => item)
     .sort((a, b) => b.savedTokens - a.savedTokens || b.count - a.count || a.tool.localeCompare(b.tool));
 
   const overheadTools = [...overheadByTool.values()]
     .sort((a, b) => b.overheadTokens - a.overheadTokens || b.count - a.count || a.tool.localeCompare(b.tool));
 
+  const netSavedTokens = getNetSavedTokens(savedTokens, overheadTokens);
+
   return {
     count: entries.length,
     rawTokens,
     compressedTokens,
     savedTokens,
     savingsPct: rawTokens > 0 ? Number(((savedTokens / rawTokens) * 100).toFixed(2)) : 0,
+    netSavedTokens,
+    netSavingsPct: rawTokens > 0 ? Number(((netSavedTokens / rawTokens) * 100).toFixed(2)) : 0,
     tools,
     overheadTokens,
     overheadPctOfRaw: rawTokens > 0 ? Number(((overheadTokens / rawTokens) * 100).toFixed(2)) : 0,

package/src/orchestration/headless-wrapper.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import { persistMetrics } from '../metrics.js';
 import { countTokens } from '../tokenCounter.js';
+import { buildOperationalContextLines } from '../client-contract.js';
 import { smartSummary } from '../tools/smart-summary.js';
 import { smartTurn } from '../tools/smart-turn.js';
 
@@ -39,30 +40,13 @@ const extractNextStep = (value) => {
 };
 
 const buildContextLines = (startResult) => {
-  const summary = startResult?.summary ?? {};
-  const lines = [];
-
-  if (startResult?.sessionId) {
-    lines.push(`Persisted devctx session: ${startResult.sessionId}`);
-  }
-
-  if (summary.goal) {
-    lines.push(`Goal: ${truncate(summary.goal, 120)}`);
-  }
-
-  if (summary.currentFocus) {
-    lines.push(`Focus: ${truncate(summary.currentFocus, 120)}`);
-  }
-
-  if (summary.nextStep) {
-    lines.push(`Next step: ${truncate(summary.nextStep, 120)}`);
-  }
-
-  if (startResult?.continuity?.reason) {
-    lines.push(`Context status: ${truncate(startResult.continuity.reason, 120)}`);
-  }
-
-  return lines.slice(0, 5);
+  const context = buildOperationalContextLines(startResult, {
+    sessionStart: false,
+    maxLineLength: 120,
+    maxLines: 8,
+    maxChars: 560,
+  });
+  return context ? context.split('\n') : [];
 };
 
 export const buildWrappedPrompt = ({ prompt, startResult }) => {
@@ -95,7 +79,16 @@ const ensureIsolatedSession = async ({ prompt, sessionId, startResult }) => {
   if (sessionId || !startResult?.sessionId) {
     return {
       startResult,
-      isolated: false,
+      isolated: Boolean(startResult?.isolatedSession),
+      previousSessionId: startResult?.previousSessionId ?? null,
+    };
+  }
+
+  if (startResult?.isolatedSession) {
+    return {
+      startResult,
+      isolated: true,
+      previousSessionId: startResult.previousSessionId ?? null,
     };
   }
 
@@ -200,6 +193,7 @@ export const runHeadlessWrapper = async ({
   dryRun = false,
   streamOutput = false,
   runCommand = runChildProcess,
+  preparedStartResult = null,
 } = {}) => {
   if (!normalizeWhitespace(prompt)) {
     throw new Error('prompt is required');
@@ -209,7 +203,7 @@ export const runHeadlessWrapper = async ({
     throw new Error('command is required unless dryRun=true');
   }
 
-  const start = await smartTurn({
+  const start = preparedStartResult ?? await smartTurn({
     phase: 'start',
     sessionId,
     prompt,

package/src/repo-safety.js

@@ -4,6 +4,11 @@ import { execFileSync } from 'node:child_process';
 import { getStateDbPath } from './storage/sqlite.js';
 import { projectRoot } from './utils/runtime-config.js';
 
+export const HARD_BLOCK_REPO_SAFETY_REASONS = Object.freeze([
+  ['tracked', 'isTracked'],
+  ['staged', 'isStaged'],
+]);
+
 const hasGitignoreEntry = (content, entry) => {
   const target = entry.replace(/\/+$/, '');
   return content
@@ -164,3 +169,19 @@ export const enforceRepoSafety = ({
       : 'Repository safety checks failed.',
   };
 };
+
+export const getRepoMutationSafety = ({
+  root = projectRoot,
+  stateDbPath = getStateDbPath(),
+} = {}) => {
+  const repoSafety = enforceRepoSafety({ root, stateDbPath });
+  const reasons = HARD_BLOCK_REPO_SAFETY_REASONS
+    .filter(([, field]) => repoSafety[field])
+    .map(([reason]) => reason);
+
+  return {
+    repoSafety,
+    shouldBlock: reasons.length > 0,
+    reasons,
+  };
+};

package/src/server.js

@@ -10,6 +10,7 @@ import { smartReadBatch } from './tools/smart-read-batch.js';
 import { smartShell } from './tools/smart-shell.js';
 import { smartSummary } from './tools/smart-summary.js';
 import { smartStatus } from './tools/smart-status.js';
+import { smartDoctor } from './tools/smart-doctor.js';
 import { smartEdit } from './tools/smart-edit.js';
 import { smartMetrics } from './tools/smart-metrics.js';
 import { smartTurn } from './tools/smart-turn.js';
@@ -379,7 +380,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_summary',
-    'Maintain compressed conversation state across turns. Actions: get (retrieve current/last session), update (create or replace a session; omitted fields are cleared), append (add to existing session), auto_append (append only if something meaningful changed), checkpoint (event-driven orchestration that decides whether to auto-persist), reset (clear session), list_sessions (show all sessions), compact (apply retention/compaction to SQLite events), cleanup_legacy (inspect or remove imported legacy JSON/JSONL files). Sessions persist in project-local SQLite with 30-day retention defaults. Auto-generates sessionId from goal if omitted. `get` auto-resumes the active session when present, otherwise falls back to the best saved session when unambiguous; pass `sessionId: "auto"` to accept the recommended session even when multiple recent candidates exist. Returns a resume summary capped at maxTokens (default 500) plus compression metadata (`truncated`, `compressionLevel`, `omitted`) and `schemaVersion`. Includes `repoSafety` so agents can catch `.devctx/state.sqlite` git hygiene issues early; mutating actions are blocked at runtime when that SQLite file is tracked or staged. Tracks: goal, status, pinned context, unresolved questions, current focus, blockers, next step, completed steps, key decisions, and touched files.',
+    'Maintain compressed conversation state across turns. Actions: get (retrieve current/last session), update (create or replace a session; omitted fields are cleared), append (add to existing session), auto_append (append only if something meaningful changed), checkpoint (event-driven orchestration that decides whether to auto-persist), reset (clear session), list_sessions (show all sessions), compact (apply retention/compaction to SQLite events), cleanup_legacy (inspect or remove imported legacy JSON/JSONL files). Sessions persist in project-local SQLite with 30-day retention defaults. Auto-generates sessionId from goal if omitted. `get` auto-resumes the active session when present, otherwise falls back to the best saved session when unambiguous; pass `sessionId: "auto"` to accept the recommended session even when multiple recent candidates exist. Returns a resume summary capped at maxTokens (default 500) plus compression metadata (`truncated`, `compressionLevel`, `omitted`) and `schemaVersion`. Exposes `repoSafety`, `mutationSafety`, `degradedMode`, and `storageHealth` so agents can detect blocked, read-only, missing, oversized, locked, or corrupted local state. Tracks: goal, status, pinned context, unresolved questions, current focus, blockers, next step, completed steps, key decisions, and touched files.',
     {
       action: z.enum(['get', 'update', 'append', 'auto_append', 'checkpoint', 'reset', 'list_sessions', 'compact', 'cleanup_legacy']),
       sessionId: z.string().optional(),
@@ -445,7 +446,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_status',
-    'Display the current session context including goal, status, recent decisions, touched files, and progress. Returns a formatted summary of what has been done and what is being tracked in the active session. Use this to understand the current state of work without modifying the session. Supports format=detailed (default, full formatted output) or format=compact (minimal JSON). Optional maxItems limits how many recent items to show (default 10).',
+    'Display the current session context including goal, status, recent decisions, touched files, and progress. Returns a formatted summary of what has been done and what is being tracked in the active session. Use this to understand the current state of work without modifying the session. Supports format=detailed (default, full formatted output) or format=compact (minimal JSON). Optional maxItems limits how many recent items to show (default 10). Exposes `mutationSafety`, `repoSafety`, `degradedMode`, and `storageHealth` when repo-safety or SQLite storage health affects session reads.',
     {
       format: z.enum(['detailed', 'compact']).optional(),
       maxItems: z.number().int().min(1).max(50).optional(),
@@ -453,6 +454,15 @@ This ensures optimal performance and context recovery.`,
     async ({ format, maxItems }) => asTextResult(await smartStatus({ format, maxItems })),
   );
 
+  server.tool(
+    'smart_doctor',
+    'Run an operational health check for local devctx state. Aggregates repo hygiene, SQLite `storageHealth`, retention/compaction hygiene, and legacy JSON/JSONL cleanup guidance into one inspect-only result with explicit remediation steps. Use this when `.devctx/state.sqlite` is missing, oversized, locked, corrupted, or when you want a release/preflight check for local state durability.',
+    {
+      verifyIntegrity: z.boolean().optional(),
+    },
+    async ({ verifyIntegrity }) => asTextResult(await smartDoctor({ verifyIntegrity })),
+  );
+
   server.tool(
     'smart_edit',
     'Batch edit multiple files with pattern replacement. Supports literal string replacement or regex patterns. Use for bulk refactoring, removing patterns (comments, console.log, etc.), or renaming across files. Optional dryRun shows preview without modifying files. Returns match count and results per file.',
@@ -469,7 +479,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_turn',
-    'Orchestrate start/end of a meaningful agent turn so context usage becomes almost mandatory with low token overhead. `phase: "start"` rehydrates persisted context, classifies prompt continuity against the saved session, optionally auto-creates a planning session for a new substantial task, and can include compact metrics. `phase: "end"` writes a checkpoint through smart_summary and can optionally include compact metrics. Use this instead of manually chaining `smart_summary(get)` and `smart_summary(checkpoint)` when you want a single context-first turn workflow.',
+    'Orchestrate start/end of a meaningful agent turn so context usage becomes almost mandatory with low token overhead. `phase: "start"` rehydrates persisted context, classifies prompt continuity against the saved session, optionally auto-creates a planning session for a new substantial task, returns `recommendedPath` guidance for the next safe devctx actions, and can include compact metrics. `phase: "end"` writes a checkpoint through smart_summary, returns follow-up `recommendedPath` guidance, and can optionally include compact metrics. Both phases expose `mutationSafety` when repo-safety blocks persisted writes and now surface `storageHealth` when SQLite state is missing, oversized, locked, or corrupted. Use this instead of manually chaining `smart_summary(get)` and `smart_summary(checkpoint)` when you want a single context-first turn workflow.',
     {
       phase: z.enum(['start', 'end']),
       sessionId: z.string().optional(),
@@ -513,7 +523,7 @@ This ensures optimal performance and context recovery.`,
 
   server.tool(
     'smart_metrics',
-    'Inspect token metrics recorded in project-local SQLite storage by default. Returns aggregated totals, per-tool savings, and recent entries. Supports time windows (`24h`, `7d`, `30d`, `all`), optional tool filtering, and optional session filtering (`sessionId: "active"` resolves the current active session automatically). Pass `file` to inspect a legacy/custom JSONL file explicitly. When `.devctx/state.sqlite` is tracked or staged, reads fall back to a temporary read-only snapshot and report `sideEffectsSuppressed`; metrics writes from other tools are skipped until git hygiene is fixed.',
+    'Inspect token metrics recorded in project-local SQLite storage by default. Returns aggregated totals, per-tool savings, recent entries, adoption analysis, and `productQuality` signals measured from `smart_turn` orchestration events (continuity recovery, blocked-state remediation coverage, context-refresh signals, checkpoint persistence). Supports time windows (`24h`, `7d`, `30d`, `all`), optional tool filtering, and optional session filtering (`sessionId: "active"` resolves the current active session automatically). Pass `file` to inspect a legacy/custom JSONL file explicitly. When `.devctx/state.sqlite` is tracked or staged, reads fall back to a temporary read-only snapshot and expose `repoSafety`, `mutationSafety`, `degradedMode`, `sideEffectsSuppressed`, and `storageHealth`; metrics writes from other tools are skipped until git hygiene is fixed.',
     {
       file: z.string().optional(),
       tool: z.string().optional(),