smart-context-mcp 1.0.3 → 1.0.4

package/src/orchestration/headless-wrapper.js

@@ -0,0 +1,314 @@
+import { spawn } from 'node:child_process';
+import { persistMetrics } from '../metrics.js';
+import { countTokens } from '../tokenCounter.js';
+import { smartSummary } from '../tools/smart-summary.js';
+import { smartTurn } from '../tools/smart-turn.js';
+
+const DEFAULT_EVENT = 'session_end';
+const START_MAX_TOKENS = 350;
+const END_MAX_TOKENS = 350;
+const SAFE_CONTINUITY_STATES = new Set(['aligned', 'resume']);
+
+const normalizeWhitespace = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+
+const truncate = (value, maxLength = 160) => {
+  const normalized = normalizeWhitespace(value);
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  if (maxLength <= 3) {
+    return '';
+  }
+
+  return `${normalized.slice(0, maxLength - 3)}...`;
+};
+
+const extractNextStep = (value) => {
+  const normalized = normalizeWhitespace(value);
+  if (!normalized) {
+    return '';
+  }
+
+  const explicitMatch = normalized.match(/(?:next step|siguiente paso)\s*[:\-]\s*([^.;\n]{12,180})/i);
+  if (explicitMatch?.[1]) {
+    return truncate(explicitMatch[1], 150);
+  }
+
+  return '';
+};
+
+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);
+};
+
+export const buildWrappedPrompt = ({ prompt, startResult }) => {
+  const lines = buildContextLines(startResult);
+  if (lines.length === 0) {
+    return prompt;
+  }
+
+  return [
+    'Use the persisted devctx project context below only if it is relevant to the user request.',
+    ...lines.map((line) => `- ${line}`),
+    '',
+    'User request:',
+    prompt,
+  ].join('\n');
+};
+
+const buildFreshSessionUpdate = (prompt) => {
+  const preview = truncate(prompt, 140);
+  return {
+    goal: truncate(prompt, 120),
+    status: 'planning',
+    currentFocus: preview,
+    pinnedContext: [preview],
+    nextStep: 'Inspect the relevant code, validate task boundaries, and checkpoint the first concrete milestone.',
+  };
+};
+
+const ensureIsolatedSession = async ({ prompt, sessionId, startResult }) => {
+  if (sessionId || !startResult?.sessionId) {
+    return {
+      startResult,
+      isolated: false,
+    };
+  }
+
+  if (SAFE_CONTINUITY_STATES.has(startResult.continuity?.state ?? '')) {
+    return {
+      startResult,
+      isolated: false,
+    };
+  }
+
+  const created = await smartSummary({
+    action: 'update',
+    update: buildFreshSessionUpdate(prompt),
+    maxTokens: START_MAX_TOKENS,
+  });
+  const isolatedStart = await smartTurn({
+    phase: 'start',
+    sessionId: created.sessionId,
+    prompt,
+    ensureSession: false,
+    maxTokens: START_MAX_TOKENS,
+  });
+
+  return {
+    startResult: isolatedStart,
+    isolated: true,
+    previousSessionId: startResult.sessionId,
+  };
+};
+
+const runChildProcess = ({ command, args, env, stdinText, streamOutput }) => new Promise((resolve, reject) => {
+  const child = spawn(command, args, {
+    env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  let stdout = '';
+  let stderr = '';
+
+  child.stdout.on('data', (chunk) => {
+    const text = chunk.toString();
+    stdout += text;
+    if (streamOutput) {
+      process.stdout.write(text);
+    }
+  });
+
+  child.stderr.on('data', (chunk) => {
+    const text = chunk.toString();
+    stderr += text;
+    if (streamOutput) {
+      process.stderr.write(text);
+    }
+  });
+
+  child.on('error', reject);
+  child.on('close', (exitCode, signal) => resolve({ exitCode: exitCode ?? 0, signal, stdout, stderr }));
+
+  if (stdinText) {
+    child.stdin.end(stdinText);
+  } else {
+    child.stdin.end();
+  }
+});
+
+const buildEndUpdate = ({ prompt, childResult }) => {
+  const combinedOutput = [childResult.stdout, childResult.stderr].filter(Boolean).join('\n');
+  const nextStep = extractNextStep(combinedOutput);
+  const update = {
+    currentFocus: truncate(prompt, 140),
+  };
+
+  if (nextStep) {
+    update.nextStep = nextStep;
+  } else if (childResult.exitCode === 0) {
+    update.nextStep = 'Review the latest headless agent output and checkpoint any concrete file changes before continuing.';
+  } else {
+    update.status = 'blocked';
+    update.whyBlocked = `Headless agent command exited with code ${childResult.exitCode}.`;
+    update.nextStep = 'Review the headless agent stderr/output and rerun the command once the issue is fixed.';
+  }
+
+  return update;
+};
+
+const inferEndEvent = ({ requestedEvent, childResult }) => {
+  if (requestedEvent) {
+    return requestedEvent;
+  }
+
+  return childResult.exitCode === 0 ? DEFAULT_EVENT : 'blocker';
+};
+
+export const runHeadlessWrapper = async ({
+  client = 'generic',
+  prompt,
+  command,
+  args = [],
+  sessionId,
+  event,
+  stdinPrompt = false,
+  dryRun = false,
+  streamOutput = false,
+  runCommand = runChildProcess,
+} = {}) => {
+  if (!normalizeWhitespace(prompt)) {
+    throw new Error('prompt is required');
+  }
+
+  if (!dryRun && !normalizeWhitespace(command)) {
+    throw new Error('command is required unless dryRun=true');
+  }
+
+  const start = await smartTurn({
+    phase: 'start',
+    sessionId,
+    prompt,
+    ensureSession: true,
+    maxTokens: START_MAX_TOKENS,
+  });
+  const sessionResolution = await ensureIsolatedSession({ prompt, sessionId, startResult: start });
+  const effectiveStart = sessionResolution.startResult;
+  const wrappedPrompt = buildWrappedPrompt({ prompt, startResult: effectiveStart });
+  const overheadTokens = Math.max(0, countTokens(wrappedPrompt) - countTokens(prompt));
+
+  await persistMetrics({
+    tool: 'agent_wrapper',
+    action: `${client}:start`,
+    sessionId: effectiveStart.sessionId ?? null,
+    rawTokens: 0,
+    compressedTokens: 0,
+    savedTokens: 0,
+    savingsPct: 0,
+    metadata: {
+      isContextOverhead: overheadTokens > 0,
+      overheadTokens,
+      client,
+      dryRun,
+      isolatedSession: sessionResolution.isolated,
+      previousSessionId: sessionResolution.previousSessionId ?? null,
+    },
+    timestamp: new Date().toISOString(),
+  });
+
+  const finalArgs = stdinPrompt ? [...args] : [...args, wrappedPrompt];
+  if (dryRun) {
+    return {
+      client,
+      dryRun: true,
+      command,
+      args: finalArgs,
+      wrappedPrompt,
+      overheadTokens,
+      start: effectiveStart,
+      sessionId: effectiveStart.sessionId ?? sessionId ?? null,
+      isolatedSession: sessionResolution.isolated,
+    };
+  }
+
+  const childResult = await runCommand({
+    command,
+    args: finalArgs,
+    env: {
+      ...process.env,
+      DEVCTX_TURN_SESSION_ID: effectiveStart.sessionId ?? '',
+      DEVCTX_TURN_CONTINUITY_STATE: effectiveStart.continuity?.state ?? '',
+      DEVCTX_TURN_CONTEXT: wrappedPrompt,
+    },
+    stdinText: stdinPrompt ? wrappedPrompt : '',
+    streamOutput,
+  });
+
+  const resolvedEvent = inferEndEvent({ requestedEvent: event, childResult });
+  const end = await smartTurn({
+    phase: 'end',
+    sessionId: effectiveStart.sessionId ?? sessionId ?? undefined,
+    event: resolvedEvent,
+    update: buildEndUpdate({ prompt, childResult }),
+    maxTokens: END_MAX_TOKENS,
+  });
+
+  await persistMetrics({
+    tool: 'agent_wrapper',
+    action: `${client}:end`,
+    sessionId: effectiveStart.sessionId ?? null,
+    rawTokens: 0,
+    compressedTokens: 0,
+    savedTokens: 0,
+    savingsPct: 0,
+    metadata: {
+      client,
+      exitCode: childResult.exitCode,
+      event: resolvedEvent,
+      isContextOverhead: false,
+      overheadTokens: 0,
+      isolatedSession: sessionResolution.isolated,
+    },
+    timestamp: new Date().toISOString(),
+  });
+
+  return {
+    client,
+    command,
+    args: finalArgs,
+    wrappedPrompt,
+    overheadTokens,
+    exitCode: childResult.exitCode,
+    signal: childResult.signal,
+    stdout: childResult.stdout,
+    stderr: childResult.stderr,
+    start: effectiveStart,
+    end,
+    sessionId: effectiveStart.sessionId ?? sessionId ?? null,
+    isolatedSession: sessionResolution.isolated,
+  };
+};

package/src/repo-safety.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { getStateDbPath } from './storage/sqlite.js';
+import { projectRoot } from './utils/runtime-config.js';
+
+const hasGitignoreEntry = (content, entry) => {
+  const target = entry.replace(/\/+$/, '');
+  return content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.replace(/\/+$/, ''))
+    .includes(target);
+};
+
+const runGit = (args, cwd) => {
+  try {
+    const stdout = execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return {
+      ok: true,
+      code: 0,
+      stdout: stdout.trim(),
+      stderr: '',
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      code: Number.isInteger(error.status) ? error.status : null,
+      stdout: typeof error.stdout === 'string' ? error.stdout.trim() : '',
+      stderr: typeof error.stderr === 'string' ? error.stderr.trim() : '',
+      errorCode: error.code ?? null,
+    };
+  }
+};
+
+const toRelativePath = (basePath, targetPath) => path.relative(basePath, path.resolve(targetPath)).replace(/\\/g, '/');
+
+const getStagedFiles = (gitRoot, filePath) => {
+  const result = runGit(['diff', '--cached', '--name-only', '--', filePath], gitRoot);
+  if (!result.ok) {
+    return [];
+  }
+
+  return result.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+};
+
+export const getRepoSafety = ({
+  root = projectRoot,
+  stateDbPath = getStateDbPath(),
+} = {}) => {
+  const repoRootResult = runGit(['rev-parse', '--show-toplevel'], root);
+
+  if (!repoRootResult.ok || !repoRootResult.stdout) {
+    return {
+      available: false,
+      isGitRepo: false,
+      riskLevel: 'unknown',
+      warnings: [],
+      recommendedActions: [],
+    };
+  }
+
+  const gitRoot = repoRootResult.stdout;
+  const relativeStateDbPath = toRelativePath(gitRoot, stateDbPath);
+  const projectGitignorePath = path.join(root, '.gitignore');
+  const gitignoreContent = fs.existsSync(projectGitignorePath)
+    ? fs.readFileSync(projectGitignorePath, 'utf8')
+    : '';
+  const projectIgnoreEntryPresent = hasGitignoreEntry(gitignoreContent, '.devctx/');
+
+  const ignoredResult = runGit(['check-ignore', relativeStateDbPath], gitRoot);
+  const trackedResult = runGit(['ls-files', '--error-unmatch', relativeStateDbPath], gitRoot);
+
+  const isIgnored = ignoredResult.code === 0;
+  const isTracked = trackedResult.code === 0;
+  const stagedPaths = getStagedFiles(gitRoot, relativeStateDbPath);
+  const isStaged = stagedPaths.length > 0;
+  const warnings = [];
+  const recommendedActions = [];
+
+  if (isTracked) {
+    warnings.push(`${relativeStateDbPath} is tracked by git and can be committed accidentally.`);
+    recommendedActions.push(`Untrack ${relativeStateDbPath} and keep .devctx/ ignored before committing.`);
+  }
+
+  if (isStaged) {
+    warnings.push(`${relativeStateDbPath} is staged for commit.`);
+    recommendedActions.push(`Unstage ${relativeStateDbPath} before committing.`);
+  } else if (!isIgnored) {
+    warnings.push(`${relativeStateDbPath} is not ignored by git.`);
+    recommendedActions.push('Add .devctx/ to the project .gitignore before relying on project-local state.');
+  }
+
+  if (!projectIgnoreEntryPresent) {
+    recommendedActions.push('Ensure the project .gitignore contains `.devctx/` for explicit local-state hygiene.');
+  }
+
+  return {
+    available: true,
+    isGitRepo: true,
+    gitRoot,
+    stateDbPath: relativeStateDbPath,
+    projectGitignorePath: path.relative(root, projectGitignorePath).replace(/\\/g, '/'),
+    projectIgnoreEntryPresent,
+    isIgnored,
+    isTracked,
+    isStaged,
+    stagedPaths,
+    riskLevel: warnings.length > 0 ? 'warning' : 'ok',
+    warnings,
+    recommendedActions,
+  };
+};
+
+export const enforceRepoSafety = ({
+  root = projectRoot,
+  stateDbPath = getStateDbPath(),
+} = {}) => {
+  const safety = getRepoSafety({ root, stateDbPath });
+
+  if (!safety.available) {
+    return {
+      ...safety,
+      enforced: false,
+      ok: true,
+      violations: [],
+      message: 'Repository safety checks skipped because no git repository was detected.',
+    };
+  }
+
+  const violations = [];
+
+  if (!safety.projectIgnoreEntryPresent) {
+    violations.push('The project .gitignore does not include .devctx/.');
+  }
+
+  if (!safety.isIgnored) {
+    violations.push(`${safety.stateDbPath} is not ignored by git.`);
+  }
+
+  if (safety.isTracked) {
+    violations.push(`${safety.stateDbPath} is tracked by git.`);
+  }
+
+  if (safety.isStaged) {
+    violations.push(`${safety.stateDbPath} is staged for commit.`);
+  }
+
+  return {
+    ...safety,
+    enforced: true,
+    ok: violations.length === 0,
+    violations,
+    message: violations.length === 0
+      ? 'Repository safety checks passed.'
+      : 'Repository safety checks failed.',
+  };
+};

package/src/server.js

@@ -9,6 +9,8 @@ import { smartContext } from './tools/smart-context.js';
 import { smartReadBatch } from './tools/smart-read-batch.js';
 import { smartShell } from './tools/smart-shell.js';
 import { smartSummary } from './tools/smart-summary.js';
+import { smartMetrics } from './tools/smart-metrics.js';
+import { smartTurn } from './tools/smart-turn.js';
 import { projectRoot, projectRootSource } from './utils/paths.js';
 
 const require = createRequire(import.meta.url);
@@ -123,9 +125,9 @@ export const createDevctxServer = () => {
 
   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), reset (clear session), list_sessions (show all sessions). Sessions persist in .devctx/sessions/ with 30-day retention. Auto-generates sessionId from goal if not provided. Returns a resume summary capped at maxTokens (default 500) plus compression metadata (`truncated`, `compressionLevel`, `omitted`) and `schemaVersion`. 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`. 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.',
     {
-      action: z.enum(['get', 'update', 'append', 'reset', 'list_sessions']),
+      action: z.enum(['get', 'update', 'append', 'auto_append', 'checkpoint', 'reset', 'list_sessions', 'compact', 'cleanup_legacy']),
       sessionId: z.string().optional(),
       update: z.object({
         goal: z.string().optional(),
@@ -140,10 +142,87 @@ export const createDevctxServer = () => {
         nextStep: z.string().optional(),
         touchedFiles: z.array(z.string()).optional(),
       }).optional(),
+      event: z.enum(['manual', 'milestone', 'decision', 'blocker', 'status_change', 'file_change', 'task_switch', 'task_complete', 'session_end', 'read_only', 'heartbeat']).optional(),
+      force: z.boolean().optional(),
       maxTokens: z.number().int().min(100).max(2000).optional(),
+      retentionDays: z.number().int().min(1).max(3650).optional(),
+      keepLatestEventsPerSession: z.number().int().min(0).max(10000).optional(),
+      keepLatestMetrics: z.number().int().min(0).max(100000).optional(),
+      vacuum: z.boolean().optional(),
+      apply: z.boolean().optional(),
     },
-    async ({ action, sessionId, update, maxTokens }) =>
-      asTextResult(await smartSummary({ action, sessionId, update, maxTokens })),
+    async ({ action, sessionId, update, event, force, maxTokens, retentionDays, keepLatestEventsPerSession, keepLatestMetrics, vacuum, apply }) =>
+      asTextResult(await smartSummary({
+        action,
+        sessionId,
+        update,
+        event,
+        force,
+        maxTokens,
+        retentionDays,
+        keepLatestEventsPerSession,
+        keepLatestMetrics,
+        vacuum,
+        apply,
+      })),
+  );
+
+  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.',
+    {
+      phase: z.enum(['start', 'end']),
+      sessionId: z.string().optional(),
+      prompt: z.string().optional(),
+      update: z.object({
+        goal: z.string().optional(),
+        status: z.enum(['planning', 'in_progress', 'blocked', 'completed']).optional(),
+        pinnedContext: z.array(z.string()).optional(),
+        unresolvedQuestions: z.array(z.string()).optional(),
+        currentFocus: z.string().optional(),
+        whyBlocked: z.string().optional(),
+        completed: z.array(z.string()).optional(),
+        decisions: z.array(z.string()).optional(),
+        blockers: z.array(z.string()).optional(),
+        nextStep: z.string().optional(),
+        touchedFiles: z.array(z.string()).optional(),
+      }).optional(),
+      event: z.enum(['manual', 'milestone', 'decision', 'blocker', 'status_change', 'file_change', 'task_switch', 'task_complete', 'session_end', 'read_only', 'heartbeat']).optional(),
+      force: z.boolean().optional(),
+      maxTokens: z.number().int().min(100).max(2000).optional(),
+      ensureSession: z.boolean().optional(),
+      includeMetrics: z.boolean().optional(),
+      metricsWindow: z.enum(['24h', '7d', '30d', 'all']).optional(),
+      latestMetrics: z.number().int().min(1).max(20).optional(),
+    },
+    async ({ phase, sessionId, prompt, update, event, force, maxTokens, ensureSession, includeMetrics, metricsWindow, latestMetrics }) =>
+      asTextResult(await smartTurn({
+        phase,
+        sessionId,
+        prompt,
+        update,
+        event,
+        force,
+        maxTokens,
+        ensureSession,
+        includeMetrics,
+        metricsWindow,
+        latestMetrics,
+      })),
+  );
+
+  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.',
+    {
+      file: z.string().optional(),
+      tool: z.string().optional(),
+      sessionId: z.string().optional(),
+      window: z.enum(['24h', '7d', '30d', 'all']).optional(),
+      latest: z.number().int().min(1).max(50).optional(),
+    },
+    async ({ file, tool, sessionId, window, latest }) =>
+      asTextResult(await smartMetrics({ file, tool, sessionId, window, latest })),
   );
 
   return server;