smart-context-mcp 1.6.2 → 1.7.1

package/src/orchestration/headless-wrapper.js

@@ -1,123 +1,13 @@
 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';
-
-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 context = buildOperationalContextLines(startResult, {
-    sessionStart: false,
-    maxLineLength: 120,
-    maxLines: 8,
-    maxChars: 560,
-  });
-  return context ? context.split('\n') : [];
-};
-
-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: Boolean(startResult?.isolatedSession),
-      previousSessionId: startResult?.previousSessionId ?? null,
-    };
-  }
-
-  if (startResult?.isolatedSession) {
-    return {
-      startResult,
-      isolated: true,
-      previousSessionId: startResult.previousSessionId ?? null,
-    };
-  }
-
-  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,
-  };
-};
+import {
+  buildWrappedPrompt,
+  computeContextOverhead,
+  finalizeManagedRun,
+  recordAgentWrapperMetric,
+  resolveManagedStart,
+} from './base-orchestrator.js';
+import { normalizeWhitespace } from './policy/event-policy.js';
+import { detectClient } from '../utils/client-detection.js';
 
 const runChildProcess = ({ command, args, env, stdinText, streamOutput }) => new Promise((resolve, reject) => {
   const child = spawn(command, args, {
@@ -154,36 +44,8 @@ const runChildProcess = ({ command, args, env, stdinText, streamOutput }) => new
   }
 });
 
-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',
+  client = null,
   prompt,
   command,
   args = [],
@@ -195,6 +57,8 @@ export const runHeadlessWrapper = async ({
   runCommand = runChildProcess,
   preparedStartResult = null,
 } = {}) => {
+  const resolvedClient = client ?? detectClient();
+
   if (!normalizeWhitespace(prompt)) {
     throw new Error('prompt is required');
   }
@@ -203,41 +67,32 @@ export const runHeadlessWrapper = async ({
     throw new Error('command is required unless dryRun=true');
   }
 
-  const start = preparedStartResult ?? await smartTurn({
-    phase: 'start',
-    sessionId,
+  const sessionResolution = await resolveManagedStart({
     prompt,
+    sessionId,
+    preparedStartResult,
     ensureSession: true,
-    maxTokens: START_MAX_TOKENS,
+    allowIsolation: true,
   });
-  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));
+  const overheadTokens = computeContextOverhead({ prompt, wrappedPrompt });
 
-  await persistMetrics({
-    tool: 'agent_wrapper',
-    action: `${client}:start`,
+  await recordAgentWrapperMetric({
+    phase: 'start',
+    client: resolvedClient,
     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(),
+    dryRun,
+    overheadTokens,
+    isolatedSession: sessionResolution.isolated,
+    previousSessionId: sessionResolution.previousSessionId ?? null,
+    autoStarted: sessionResolution.autoStarted,
   });
 
   const finalArgs = stdinPrompt ? [...args] : [...args, wrappedPrompt];
   if (dryRun) {
     return {
-      client,
+      client: resolvedClient,
       dryRun: true,
       command,
       args: finalArgs,
@@ -262,36 +117,25 @@ export const runHeadlessWrapper = async ({
     streamOutput,
   });
 
-  const resolvedEvent = inferEndEvent({ requestedEvent: event, childResult });
-  const end = await smartTurn({
-    phase: 'end',
+  const { resolvedEvent, endResult } = await finalizeManagedRun({
+    prompt,
+    childResult,
     sessionId: effectiveStart.sessionId ?? sessionId ?? undefined,
-    event: resolvedEvent,
-    update: buildEndUpdate({ prompt, childResult }),
-    maxTokens: END_MAX_TOKENS,
+    requestedEvent: event,
   });
 
-  await persistMetrics({
-    tool: 'agent_wrapper',
-    action: `${client}:end`,
+  await recordAgentWrapperMetric({
+    phase: 'end',
+    client: resolvedClient,
     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(),
+    isolatedSession: sessionResolution.isolated,
+    exitCode: childResult.exitCode,
+    event: resolvedEvent,
+    autoStarted: sessionResolution.autoStarted,
   });
 
   return {
-    client,
+    client: resolvedClient,
     command,
     args: finalArgs,
     wrappedPrompt,
@@ -301,7 +145,7 @@ export const runHeadlessWrapper = async ({
     stdout: childResult.stdout,
     stderr: childResult.stderr,
     start: effectiveStart,
-    end,
+    end: endResult,
     sessionId: effectiveStart.sessionId ?? sessionId ?? null,
     isolatedSession: sessionResolution.isolated,
   };

package/src/orchestration/policy/event-policy.js

@@ -0,0 +1,297 @@
+import { smartContext } from '../../tools/smart-context.js';
+import { smartSearch } from '../../tools/smart-search.js';
+
+export const SAFE_CONTINUITY_STATES = new Set(['aligned', 'resume']);
+
+export const MAX_TOP_FILES = 3;
+export const MAX_PREFLIGHT_HINTS = 2;
+export const MAX_FOCUS_LENGTH = 140;
+export const MAX_GOAL_LENGTH = 120;
+export const MAX_NEXT_STEP_LENGTH = 150;
+export const DEFAULT_TRUNCATE_LENGTH = 160;
+export const MIN_NEXT_STEP_LENGTH = 12;
+export const MAX_NEXT_STEP_CAPTURE_LENGTH = 180;
+export const MAX_RECOMMENDED_TOOLS = 3;
+
+export const normalizeWhitespace = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+
+export const truncate = (value, maxLength = DEFAULT_TRUNCATE_LENGTH) => {
+  const normalized = normalizeWhitespace(value);
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  if (maxLength <= 3) {
+    return '';
+  }
+
+  return `${normalized.slice(0, maxLength - 3)}...`;
+};
+
+const asArray = (value) => Array.isArray(value) ? value : [];
+
+export const uniqueCompact = (values) => [...new Set(
+  asArray(values)
+    .map((value) => normalizeWhitespace(value))
+    .filter(Boolean),
+)];
+
+export const extractContextTopFiles = (topFiles) => uniqueCompact(asArray(topFiles).map((item) => {
+  if (typeof item === 'string') {
+    return item;
+  }
+
+  return item?.file ?? item?.path ?? '';
+})).slice(0, MAX_TOP_FILES);
+
+export const extractPreflightTopFiles = (preflightResult) => {
+  if (!preflightResult) {
+    return [];
+  }
+
+  if (preflightResult.tool === 'smart_context') {
+    return uniqueCompact(asArray(preflightResult.result?.context).map((item) => item?.file).filter(Boolean)).slice(0, MAX_TOP_FILES);
+  }
+
+  if (preflightResult.tool === 'smart_search') {
+    return extractContextTopFiles(preflightResult.result?.topFiles);
+  }
+
+  return [];
+};
+
+export const extractPreflightHints = (preflightResult) => {
+  if (!preflightResult) {
+    return [];
+  }
+
+  if (preflightResult.tool === 'smart_context') {
+    return uniqueCompact(preflightResult.result?.hints).slice(0, MAX_PREFLIGHT_HINTS);
+  }
+
+  if (preflightResult.tool === 'smart_search') {
+    const totalMatches = Number(preflightResult.result?.totalMatches ?? 0);
+    if (totalMatches > 0) {
+      return [`${totalMatches} search match(es) surfaced for the workflow target`];
+    }
+  }
+
+  return [];
+};
+
+export const buildPreflightSummary = (preflightResult) => {
+  if (!preflightResult) {
+    return null;
+  }
+
+  return {
+    tool: preflightResult.tool,
+    topFiles: extractPreflightTopFiles(preflightResult),
+    hints: extractPreflightHints(preflightResult),
+    totalMatches: Number(preflightResult.result?.totalMatches ?? 0),
+  };
+};
+
+export const buildPreflightTask = ({ workflowProfile, prompt, startResult }) => {
+  if (!workflowProfile || typeof workflowProfile !== 'object') {
+    return '';
+  }
+
+  const normalizedPrompt = normalizeWhitespace(prompt);
+  const persistedNextStep = normalizeWhitespace(startResult?.summary?.nextStep);
+  const currentFocus = normalizeWhitespace(startResult?.summary?.currentFocus);
+  const refreshedTopFiles = extractContextTopFiles(startResult?.refreshedContext?.topFiles);
+
+  if (workflowProfile.commandName === 'continue' || workflowProfile.commandName === 'resume') {
+    if (persistedNextStep) {
+      return persistedNextStep;
+    }
+    if (currentFocus) {
+      return currentFocus;
+    }
+  }
+
+  if (workflowProfile.commandName === 'task' && currentFocus && persistedNextStep) {
+    return `${currentFocus}. ${persistedNextStep}`;
+  }
+
+  if (normalizedPrompt) {
+    return normalizedPrompt;
+  }
+
+  if (refreshedTopFiles.length > 0) {
+    return `Inspect ${refreshedTopFiles.join(', ')} and continue the persisted task`;
+  }
+
+  return workflowProfile.label;
+};
+
+export const runWorkflowPreflight = async ({
+  workflowProfile,
+  prompt,
+  startResult,
+  contextTool = smartContext,
+  searchTool = smartSearch,
+}) => {
+  const preflight = workflowProfile.preflight;
+  if (!preflight) {
+    return null;
+  }
+
+  const preflightTask = buildPreflightTask({ workflowProfile, prompt, startResult });
+
+  if (preflight.tool === 'smart_context') {
+    const request = {
+      task: preflightTask,
+      detail: preflight.detail ?? 'minimal',
+      include: preflight.include ?? ['hints'],
+      maxTokens: preflight.maxTokens ?? 1200,
+    };
+    const result = await contextTool(request);
+    return {
+      tool: 'smart_context',
+      request,
+      result,
+    };
+  }
+
+  if (preflight.tool === 'smart_search') {
+    const request = {
+      query: preflightTask,
+      intent: preflight.intent ?? workflowProfile.workflowIntent,
+    };
+    const result = await searchTool(request);
+    return {
+      tool: 'smart_search',
+      request,
+      result,
+    };
+  }
+
+  return null;
+};
+
+export const buildContinuityGuidance = ({ startResult }) => {
+  const continuityState = startResult?.continuity?.state ?? 'unknown';
+  const lines = [`- Continuity: ${continuityState}`];
+  const nextStep = normalizeWhitespace(startResult?.summary?.nextStep);
+  const currentFocus = normalizeWhitespace(startResult?.summary?.currentFocus);
+  const refreshedTopFiles = extractContextTopFiles(startResult?.refreshedContext?.topFiles);
+  const recommendedNextTools = asArray(startResult?.recommendedPath?.nextTools)
+    .map((tool) => normalizeWhitespace(tool))
+    .filter(Boolean)
+    .slice(0, MAX_RECOMMENDED_TOOLS);
+
+  if (currentFocus) {
+    lines.push(`- Persisted focus: ${truncate(currentFocus, MAX_FOCUS_LENGTH)}`);
+  }
+
+  if (nextStep) {
+    lines.push(`- Persisted next step: ${truncate(nextStep, MAX_FOCUS_LENGTH)}`);
+  }
+
+  if (refreshedTopFiles.length > 0) {
+    lines.push(`- Refreshed top files: ${refreshedTopFiles.join(', ')}`);
+  }
+
+  if (recommendedNextTools.length > 0) {
+    lines.push(`- smart_turn suggested: ${recommendedNextTools.join(' -> ')}`);
+  }
+
+  if (startResult?.isolatedSession) {
+    lines.push('- Session handling: smart_turn already isolated this work from the previous session; revalidate before assuming old focus.');
+  } else if (continuityState === 'aligned' || continuityState === 'resume') {
+    lines.push('- Session handling: reuse the active session context and stay close to the persisted next step unless the task proves otherwise.');
+  } else if (continuityState === 'possible_shift' || continuityState === 'context_mismatch') {
+    lines.push('- Session handling: treat this as a shifted slice, validate the working set early, and avoid silent context reuse.');
+  }
+
+  return lines;
+};
+
+export const buildWorkflowPromptWithPolicy = ({
+  prompt,
+  workflowProfile,
+  preflightSummary,
+  startResult,
+}) => {
+  const lines = [
+    prompt,
+    '',
+    'Workflow policy:',
+    `- Mode: ${workflowProfile.policyMode}`,
+    `- Intent: ${workflowProfile.workflowIntent}`,
+    `- Prefer this tool order: ${workflowProfile.nextTools.join(' -> ')}`,
+  ];
+
+  if (workflowProfile.checkpointStrategy) {
+    lines.push(`- Checkpoint rule: ${workflowProfile.checkpointStrategy}`);
+  }
+
+  lines.push(...buildContinuityGuidance({ startResult }));
+
+  if (preflightSummary?.tool) {
+    lines.push(`- Preflight: ${preflightSummary.tool}`);
+  }
+
+  if (preflightSummary?.topFiles?.length) {
+    lines.push(`- Focus files: ${preflightSummary.topFiles.join(', ')}`);
+  }
+
+  if (preflightSummary?.hints?.length) {
+    lines.push(`- Signals: ${preflightSummary.hints.map((hint) => truncate(hint, 120)).join(' | ')}`);
+  }
+
+  return lines.join('\n');
+};
+
+export const buildWorkflowPolicyPayload = ({ commandName, workflowProfile, preflightSummary }) => ({
+  commandName,
+  label: workflowProfile.label,
+  policyMode: workflowProfile.policyMode,
+  intent: workflowProfile.workflowIntent,
+  specialized: workflowProfile.specialized,
+  nextTools: [...workflowProfile.nextTools],
+  checkpointStrategy: workflowProfile.checkpointStrategy,
+  preflight: preflightSummary,
+});
+
+export const extractNextStep = (value) => {
+  const normalized = normalizeWhitespace(value);
+  if (!normalized) {
+    return '';
+  }
+
+  const explicitMatch = normalized.match(new RegExp(
+    `(?:next step|siguiente paso)\\s*[:\\-]\\s*([^.;\\n]{${MIN_NEXT_STEP_LENGTH},${MAX_NEXT_STEP_CAPTURE_LENGTH}})`,
+    'i',
+  ));
+  if (explicitMatch?.[1]) {
+    return truncate(explicitMatch[1], MAX_NEXT_STEP_LENGTH);
+  }
+
+  return '';
+};
+
+export const buildTaskRunnerAutomaticity = ({
+  isWorkflowCommand = false,
+  startResult = null,
+  endResult = null,
+  workflowPolicy = null,
+  usedWrapper = false,
+  overheadTokens = 0,
+  managedByBaseOrchestrator = false,
+}) => {
+  const safeOverheadTokens = Number.isFinite(overheadTokens) ? Math.max(0, overheadTokens) : 0;
+  const checkpointPersisted = Boolean(endResult && !endResult.checkpoint?.skipped && !endResult.checkpoint?.blocked);
+
+  return {
+    managedByBaseOrchestrator,
+    autoStartTriggered: isWorkflowCommand && Boolean(startResult),
+    autoPreflightTriggered: isWorkflowCommand && Boolean(workflowPolicy?.preflight?.tool),
+    autoCheckpointTriggered: checkpointPersisted,
+    autoWrappedPrompt: usedWrapper && safeOverheadTokens > 0,
+    isolatedSession: Boolean(startResult?.isolatedSession),
+    contextOverheadTokens: safeOverheadTokens,
+  };
+};