imprint-mcp 0.6.2 → 0.6.3

package/src/imprint/mcp-server.ts

@@ -49,6 +49,9 @@ interface RunMcpServerOptions {
   name?: string;
   /** Server version. */
   version?: string;
+  /** Optional exact tool-name allowlist. Used by audit sessions to keep
+   * human-interactive authentication workflows out of headless MCP exposure. */
+  includeToolNames?: readonly string[];
 }
 
 interface ResolvedTool extends DiscoveredTool {
@@ -58,6 +61,17 @@ interface ResolvedTool extends DiscoveredTool {
   preferredOrder?: ConcreteBackend[];
 }
 
+/** Exact allowlist selection used by bounded MCP sessions such as audit. An
+ * omitted allowlist preserves normal production behavior and exposes all tools. */
+export function selectMcpTools<T extends { workflow: { toolName: string } }>(
+  tools: readonly T[],
+  includeToolNames?: readonly string[],
+): T[] {
+  if (!includeToolNames) return [...tools];
+  const includedNames = new Set(includeToolNames);
+  return tools.filter((tool) => includedNames.has(tool.workflow.toolName));
+}
+
 /** Tool description shown to MCP clients. Includes the operator's
  *  recorded narration when present — surprisingly load-bearing for the
  *  LLM picking the right tool. */
@@ -437,7 +451,8 @@ function formatToolError(
 
 export async function runMcpServer(opts: RunMcpServerOptions): Promise<void> {
   const assetRoot = opts.assetRoot ?? imprintHomeDir();
-  const discovered = await discoverTools(assetRoot, opts.site, '[imprint mcp]');
+  const discoveredAll = await discoverTools(assetRoot, opts.site, '[imprint mcp]');
+  const discovered = selectMcpTools(discoveredAll, opts.includeToolNames);
   const tools: ResolvedTool[] = discovered.map((t) => {
     const playbookPath = pathResolve(t.dir, 'playbook.yaml');
     const cacheStatus = loadBackendsCacheStatus(t.site, assetRoot, t.dir, {

package/src/imprint/probe-backends.ts

@@ -26,6 +26,7 @@ import {
   BackendsCacheSchema,
   type ConcreteBackend,
   CronConfigSchema,
+  type ToolResult,
   WorkflowSchema,
 } from './types.ts';
 import { VERSION } from './version.ts';
@@ -120,20 +121,32 @@ export async function probeResolvedTool(
   log(`probing backends for ${tool.workflow.toolName}…`);
   log(`  params: ${JSON.stringify(params)}`);
 
-  // Try every backend (single-rung ladders) — operators want the full
-  // matrix, not just the first that worked. cdp-replay is included so it
-  // lands in preferredOrder when it works — without it, runtime always
-  // falls through fetch-bootstrap (~30-60s) before reaching the spliced-in
-  // cdp-replay rung, wasting time on every call.
+  // Probe the workflow's normal candidates first. Plain workflows keep the
+  // cheap fetch/stealth/playbook path; browser-backed API transports are only
+  // added if none of those candidates works.
   const stealthCache = new Map<string, StealthFetch>();
   const cdpPool = new Map<string, CdpBrowserFetch>();
   const allBackends = probeCandidateBackendsForWorkflow(tool.workflow);
   const results: BackendsCache['results'] = {};
   const working: BackendProbeCandidate[] = [];
   const preferredMaxMs = preferredBackendMaxMs();
+  const persistCurrentCache = (): BackendsCache => {
+    const cache: BackendsCache = {
+      probedAt: new Date().toISOString(),
+      imprintVersion: VERSION,
+      schemaVersion: 2,
+      workflowHash: workflowHash(tool.workflow),
+      capabilityHash: workflowCapabilityHash(tool.workflow),
+      preferredOrder: rankSuccessfulBackends(working),
+      results,
+    };
+    BackendsCacheSchema.parse(cache);
+    writeFileSync(outPath, `${JSON.stringify(cache, null, 2)}\n`);
+    return cache;
+  };
 
-  try {
-    for (const backend of allBackends) {
+  const probeCandidates = async (backends: ConcreteBackend[]): Promise<void> => {
+    for (const backend of backends) {
       log(`probing ${backend}…`);
       const t0 = Date.now();
       const { result, attempts } = await runWithLadder(
@@ -147,6 +160,14 @@ export async function probeResolvedTool(
       const durationMs = Date.now() - t0;
       const attempt = attempts[0];
 
+      const invariantFailure = backendInvariantProbeFailure(result);
+      if (invariantFailure) {
+        log(`  ${backend}: workflow rejected the request before transport — stopping probe`);
+        throw new Error(
+          `Backend-independent workflow failure for ${tool.workflow.toolName}: ${invariantFailure}`,
+        );
+      }
+
       if (!attempt) {
         results[backend] = { outcome: 'skipped', detail: 'no attempt recorded' };
         continue;
@@ -189,6 +210,11 @@ export async function probeResolvedTool(
           ...(warm?.ok ? { warmDurationMs: warm.durationMs, rankingDurationMs } : {}),
           tooSlow,
         });
+        // Keep a valid preferred backend durable as soon as one succeeds. A
+        // later optional candidate may tarpit until the aggregate preparation
+        // deadline; losing this earlier success would force an unnecessary
+        // reprobe and leave the suite with no prepared backend.
+        persistCurrentCache();
         log(
           `  ${backend}: OK in ${durationMs}ms${warm?.ok ? ` (warm ${warm.durationMs}ms)` : ''}${tooSlow ? ' (cold slow)' : ''}`,
         );
@@ -212,6 +238,14 @@ export async function probeResolvedTool(
         log(`  ${backend}: ${result.error} — ${result.message.slice(0, 100)}`);
       }
     }
+  };
+
+  try {
+    await probeCandidates(allBackends);
+    if (working.length === 0 && !allBackends.includes('cdp-replay')) {
+      log('default backends failed; probing browser-backed API fallbacks…');
+      await probeCandidates(['cdp-replay', 'fetch-bootstrap']);
+    }
   } finally {
     await closeProbeCdpPool(cdpPool);
   }
@@ -224,24 +258,24 @@ export async function probeResolvedTool(
     );
   }
 
-  const preferredOrder = rankSuccessfulBackends(working);
-  const cache: BackendsCache = {
-    probedAt: new Date().toISOString(),
-    imprintVersion: VERSION,
-    schemaVersion: 2,
-    workflowHash: workflowHash(tool.workflow),
-    capabilityHash: workflowCapabilityHash(tool.workflow),
-    preferredOrder,
-    results,
-  };
-  BackendsCacheSchema.parse(cache); // catch schema drift early
-
-  writeFileSync(outPath, `${JSON.stringify(cache, null, 2)}\n`);
-  log(`wrote ${outPath} — preferred: ${preferredOrder.join(' → ')}`);
+  const cache = persistCurrentCache();
+  log(`wrote ${outPath} — preferred: ${cache.preferredOrder.join(' → ')}`);
 
   return { cache, outPath };
 }
 
+/**
+ * Some generated-workflow failures happen before any HTTP request is sent.
+ * Retrying those through browser-backed transports is both expensive and
+ * misleading: a different transport cannot repair a deterministic transform.
+ * Keep remote HTTP BAD_RESPONSE failures probeable because bot defenses can
+ * return backend-specific 4xx responses.
+ */
+export function backendInvariantProbeFailure(result: ToolResult): string | null {
+  if (result.ok || result.error !== 'BAD_RESPONSE') return null;
+  return /^request transform failed for request \d+:/i.test(result.message) ? result.message : null;
+}
+
 export function rankSuccessfulBackends(candidates: BackendProbeCandidate[]): ConcreteBackend[] {
   return [...candidates]
     .sort((a, b) => {
@@ -302,9 +336,10 @@ function preferredBackendMaxMs(): number {
 
 function workflowNeedsBootstrap(workflow: ResolvedTool['workflow']): boolean {
   if (workflow.bootstrap) return true;
-  return workflow.requests.some((r) =>
-    (r.captures ?? []).some(
-      (c) => c.capability === 'browser_bootstrap' || c.capability === 'stealth_bootstrap',
+  return workflow.requests.some((request) =>
+    (request.captures ?? []).some(
+      (capture) =>
+        capture.capability === 'browser_bootstrap' || capture.capability === 'stealth_bootstrap',
     ),
   );
 }
@@ -313,7 +348,7 @@ export function probeCandidateBackendsForWorkflow(
   workflow: ResolvedTool['workflow'],
 ): ConcreteBackend[] {
   return workflowNeedsBootstrap(workflow) || prefersCdpReplayFirst(workflow)
-    ? ['fetch', 'fetch-bootstrap', 'cdp-replay', 'stealth-fetch', 'playbook']
+    ? ['fetch', 'cdp-replay', 'fetch-bootstrap', 'stealth-fetch', 'playbook']
     : ['fetch', 'stealth-fetch', 'playbook'];
 }
 

package/src/imprint/teach-state.ts

@@ -172,7 +172,18 @@ export function resolveWorkflowTriagedPath(
   if (!ws) return null;
 
   const explicitPath = resolveTeachStatePath(site, ws.triagedPath);
-  if (explicitPath) return explicitPath;
+  if (explicitPath) {
+    // Older/resumed runs could accidentally triage an already-triaged session,
+    // leaving state pointed at `*.triaged.triaged.json`. Prefer the original
+    // single-triaged sibling when it still exists: it contains the complete
+    // load-bearing request set, while the second pass may have filtered requests
+    // selected by the first pass.
+    const singleTriagedPath = explicitPath.replace(/(?:\.triaged){2,}\.json$/, '.triaged.json');
+    if (singleTriagedPath !== explicitPath && existsSync(singleTriagedPath)) {
+      return singleTriagedPath;
+    }
+    return explicitPath;
+  }
 
   if (!ws.completedSteps.includes('triage')) return null;
 
@@ -186,7 +197,20 @@ export function resolveWorkflowTriagedPath(
 export function toRelativeTeachStatePath(site: string, absPath: string): string {
   const localRelative = relativeToLocalSite(site, absPath);
   if (localRelative) return localRelative;
-  return `_external_/${pathBasename(absPath)}`;
+  // External artifacts are not copied under the site root. Persist their real
+  // absolute path so a later bounded resume can still resolve them; the former
+  // `_external_/<basename>` label looked portable but pointed at no actual file.
+  return pathResolve(absPath);
+}
+
+const TOOL_SCOPED_RESUME_STEPS = new Set<TeachStep>(['generate', 'compile-playbook', 'emit']);
+
+/** `--tool` scopes the atomic per-tool compile unit. Earlier phases operate on
+ * the recording as a whole, while register is site-level, so accepting the flag
+ * there would either ignore it or falsely claim the run was bounded. */
+export function validateToolScopedResumeStep(fromStep: TeachStep | undefined): string | null {
+  if (fromStep && TOOL_SCOPED_RESUME_STEPS.has(fromStep)) return null;
+  return 'error: --tool is only supported for bounded compile resumes starting at generate, compile-playbook, or emit';
 }
 
 export function buildTeachStateFromSession(
@@ -366,6 +390,7 @@ export function resolveStepStartTarget(
   site: string,
   state: TeachState,
   fromStep: TeachStep,
+  toolName?: string,
 ): { workflowKey: string; ws: WorkflowState } {
   // Exclude in-progress `_pending_*` placeholders: they never carry a candidate
   // and never reached far enough, so a stale one with a newer timestamp would
@@ -381,6 +406,19 @@ export function resolveStepStartTarget(
       ].join('\n'),
     );
   }
+  if (toolName) {
+    const target = entries.find(
+      ([workflowKey, ws]) => workflowKey === toolName || ws.candidate?.toolName === toolName,
+    );
+    if (!target) {
+      throw new Error(
+        `Cannot resume tool "${toolName}" for "${site}": it is not present in the persisted teach state.`,
+      );
+    }
+    const [workflowKey, ws] = target;
+    assertResumableAt(site, workflowKey, ws, fromStep);
+    return { workflowKey, ws };
+  }
   // Most-recently-updated resumable workflow — the run a developer just executed
   // and wants to resume a single phase of. Newly discovered orphan sessions can
   // have newer timestamps but only `record`/`redact`; they must not shadow the
@@ -423,6 +461,7 @@ export function selectMultiToolResumePlans(
   opts?: {
     noInteractive?: boolean;
     allTools?: boolean;
+    toolName?: string;
     plannedToolNames?: ReadonlySet<string>;
   },
 ): MultiToolResumeSelection {
@@ -445,6 +484,17 @@ export function selectMultiToolResumePlans(
     }
     plans.push({ workflowKey: key, candidate: ws.candidate, sharedContext: ws.sharedContext });
   }
+  if (opts?.toolName) {
+    const selected = plans.find(
+      (plan) => plan.workflowKey === opts.toolName || plan.candidate?.toolName === opts.toolName,
+    );
+    if (!selected) {
+      throw new Error(
+        `Cannot resume tool "${opts.toolName}": it is not resumable from "${fromStep}" in the selected recording.`,
+      );
+    }
+    return { plans: [selected], skipped };
+  }
   if (opts?.noInteractive && !opts.allTools && plans.length > 1) {
     const primary = plans.find((plan) => plan.candidate?.primary);
     const selected = primary ?? plans.find((plan) => plan.workflowKey === targetWorkflowKey);

package/src/imprint/teach.ts

@@ -150,6 +150,30 @@ export function hasDurableAuthState(
   return stored.cookies.length > 0 || (stored.storage?.length ?? 0) > 0;
 }
 
+export function resolvedArtifactCheckpointPath(
+  site: string,
+  _storedPath: string | undefined,
+  resolvedPath: string,
+): string {
+  // toRelative keeps managed artifacts site-relative and genuine external
+  // artifacts absolute, so both forms remain resolvable on the next resume.
+  return toRelative(site, resolvedPath);
+}
+
+export function selectCompileSessionArtifact(
+  resumedTriagedPath: string | null,
+  redactedPath: string | null,
+): { path: string | null; triaged: boolean } {
+  const derivedTriagedPath = redactedPath?.replace(/\.redacted\.json$/, '.triaged.json') ?? null;
+  const path =
+    (resumedTriagedPath && existsSync(resumedTriagedPath) ? resumedTriagedPath : null) ??
+    (derivedTriagedPath && existsSync(derivedTriagedPath) ? derivedTriagedPath : redactedPath);
+  return {
+    path,
+    triaged: path === resumedTriagedPath || path === derivedTriagedPath,
+  };
+}
+
 function fileSha256(path: string): string {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
@@ -205,6 +229,8 @@ interface TeachOptions {
   keepTest?: boolean;
   /** Non-interactive: compile every detected candidate instead of primary only. */
   allTools?: boolean;
+  /** Bounded resume: compile exactly one persisted candidate from the retained recording. */
+  tool?: string;
   /** Skip the replay-and-diff stage entirely. */
   skipReplay?: boolean;
   /** Run only specific phases of the teach chain. `fromStep` resumes a PRIOR run
@@ -490,6 +516,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   let workflowKey: string | null = null;
   let sessionPath: string | null = opts.fromSession ?? null;
   let redactedPath: string | null = null;
+  let resumedTriagedPath: string | null = null;
   let usingFromSession = false;
 
   const hasExisting = completedWorkflows.length > 0 || incompleteWorkflows.length > 0;
@@ -506,7 +533,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     // Non-interactive phase resume: start at a specific step, reusing a prior
     // run's persisted outputs. resolveStepStartTarget picks the most-recent
     // workflow and THROWS if it didn't reach far enough (the dependency guard).
-    const target = resolveStepStartTarget(site, state, opts.fromStep);
+    const target = resolveStepStartTarget(site, state, opts.fromStep, opts.tool);
     workflowKey = target.workflowKey;
     startFrom = opts.fromStep;
     sessionPath = resolveTeachStatePath(site, target.ws.sessionPath);
@@ -1215,9 +1242,14 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     }
     const ws = state.workflows[workflowKey];
     const resolvedTriagedPath = resolveWorkflowTriagedPath(site, ws);
-    if (ws && resolvedTriagedPath && !ws.triagedPath) {
+    resumedTriagedPath = resolvedTriagedPath;
+    if (
+      ws &&
+      resolvedTriagedPath &&
+      resolveTeachStatePath(site, ws.triagedPath) !== resolvedTriagedPath
+    ) {
       updateCheckpoint(site, state, workflowKey, 'triage', {
-        triagedPath: toRelative(site, resolvedTriagedPath),
+        triagedPath: resolvedArtifactCheckpointPath(site, ws.triagedPath, resolvedTriagedPath),
       });
     }
     // A `--from-step` resume into plan-prereqs/generate reconstructs the prior
@@ -1242,6 +1274,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       const selection = selectMultiToolResumePlans(state, workflowKey, startFrom, {
         noInteractive: opts.noInteractive,
         allTools: opts.allTools,
+        toolName: opts.tool,
         plannedToolNames,
       });
       for (const { workflowKey: skippedKey, reason } of selection.skipped) {
@@ -1325,15 +1358,12 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   // thousands of irrelevant requests (large auth recordings otherwise may never converge on a
   // playbook because of this). The detect-candidates summary already triages;
   // this aligns the compile session with it.
-  const triagedCandidate = redactedPath?.replace(/\.redacted\.json$/, '.triaged.json');
-  const sessionForCompile =
-    triagedCandidate && existsSync(triagedCandidate) ? triagedCandidate : redactedPath;
-  const useTriaged = sessionForCompile === triagedCandidate;
-  const compileSessionPath = requireSessionFile(sessionForCompile, {
+  const compileSessionArtifact = selectCompileSessionArtifact(resumedTriagedPath, redactedPath);
+  const compileSessionPath = requireSessionFile(compileSessionArtifact.path, {
     site,
     workflowKey: plans[0]?.workflowKey ?? workflowKey,
     startFrom,
-    kind: useTriaged ? 'triaged' : 'redacted',
+    kind: compileSessionArtifact.triaged ? 'triaged' : 'redacted',
   });
 
   // ── Clean up stale tools from previous teach runs ──
@@ -1380,66 +1410,61 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   const authDetected = plans.some((pl) => sharedContextHasAuth(pl.sharedContext));
   let buildPlanPath = '';
   let sharedModulesManifest: SharedModuleManifestEntry[] = [];
-  if ((selectedCandidates.length >= 2 || authDetected) && willGenerate && compileModel) {
-    const sidecar = buildPlanSidecarPath(site);
-    const firstWs = state.workflows[plans[0]?.workflowKey ?? ''];
-    // Reuse the cached plan only when resuming PAST plan-prereqs (e.g. --from-step
-    // generate). When plan-prereqs is the explicit target (`--only plan-prereqs` /
-    // `--from-step plan-prereqs`), the user is asking to rebuild shared modules, so
-    // force a fresh planner run instead of short-circuiting to the cached sidecar.
-    const alreadyPlanned =
-      opts.fromStep !== 'plan-prereqs' &&
-      plans.every((pl) =>
-        state.workflows[pl.workflowKey]?.completedSteps.includes('plan-prereqs'),
-      ) &&
-      existsSync(sidecar);
-    if (alreadyPlanned && firstWs) {
-      // Resume past plan-prereqs — reuse the persisted plan + manifest.
-      buildPlanPath = sidecar;
-      sharedModulesManifest = firstWs.sharedModules ?? [];
-    } else {
-      // Mute raw `[imprint …]` logs from the planning subtree (build-plan,
-      // teach-plan, prereq-builder) while the spinner is live — progress flows
-      // through onProgress → spinner.message instead, matching the replay and
-      // compile phases. The skip/timeout reason is surfaced cleanly below.
-      muteLog();
-      spinner.start('Planning shared modules');
-      try {
-        const prereq = await planAndBuildPrereqs({
-          site,
-          redactedSessionPath: compileSessionPath,
-          candidates: selectedCandidates,
-          sharedContext: plans[0]?.sharedContext,
-          siteClassifications,
-          providerName: compileProviderName,
-          model: compileModel,
-          onProgress: (msg) => spinner.message(msg),
-        });
-        buildPlanPath = prereq.buildPlanPath;
-        sharedModulesManifest = prereq.sharedModules;
-        const verified = sharedModulesManifest.filter((m) => m.verified).length;
-        spinner.stop(
-          buildPlanPath
-            ? `Build plan ready (${verified}/${sharedModulesManifest.length} shared module${sharedModulesManifest.length === 1 ? '' : 's'} verified).`
-            : 'Build plan skipped.',
-        );
-        if (prereq.skippedReason) p.log.warn(prereq.skippedReason);
-      } catch (err) {
-        spinner.stop('Build planning failed — compiling tools independently.');
-        p.log.warn(
-          `Build planning failed: ${err instanceof Error ? err.message : String(err)}\nTools will compile without shared modules.`,
-        );
-        buildPlanPath = '';
-        sharedModulesManifest = [];
-      } finally {
-        unmuteLog();
-      }
-      for (const pl of plans) {
-        updateCheckpoint(site, state, pl.workflowKey, 'plan-prereqs', {
-          buildPlanPath: buildPlanPath ? toRelative(site, buildPlanPath) : undefined,
-          sharedModules: sharedModulesManifest,
-        });
-      }
+  const sidecar = buildPlanSidecarPath(site);
+  const firstWs = state.workflows[plans[0]?.workflowKey ?? ''];
+  // A bounded primary-only resume still belongs to its original multi-tool
+  // build plan. Reuse that durable contract even though this invocation selects
+  // one tool; otherwise its assigned shared modules and producer-token contract
+  // silently disappear from the revision agent's context.
+  const alreadyPlanned =
+    opts.fromStep !== 'plan-prereqs' &&
+    plans.every((pl) => state.workflows[pl.workflowKey]?.completedSteps.includes('plan-prereqs')) &&
+    existsSync(sidecar);
+  if (willGenerate && compileModel && alreadyPlanned && firstWs) {
+    buildPlanPath = sidecar;
+    sharedModulesManifest = firstWs.sharedModules ?? [];
+  } else if ((selectedCandidates.length >= 2 || authDetected) && willGenerate && compileModel) {
+    // Mute raw `[imprint …]` logs from the planning subtree (build-plan,
+    // teach-plan, prereq-builder) while the spinner is live — progress flows
+    // through onProgress → spinner.message instead, matching the replay and
+    // compile phases. The skip/timeout reason is surfaced cleanly below.
+    muteLog();
+    spinner.start('Planning shared modules');
+    try {
+      const prereq = await planAndBuildPrereqs({
+        site,
+        redactedSessionPath: compileSessionPath,
+        candidates: selectedCandidates,
+        sharedContext: plans[0]?.sharedContext,
+        siteClassifications,
+        providerName: compileProviderName,
+        model: compileModel,
+        onProgress: (msg) => spinner.message(msg),
+      });
+      buildPlanPath = prereq.buildPlanPath;
+      sharedModulesManifest = prereq.sharedModules;
+      const verified = sharedModulesManifest.filter((m) => m.verified).length;
+      spinner.stop(
+        buildPlanPath
+          ? `Build plan ready (${verified}/${sharedModulesManifest.length} shared module${sharedModulesManifest.length === 1 ? '' : 's'} verified).`
+          : 'Build plan skipped.',
+      );
+      if (prereq.skippedReason) p.log.warn(prereq.skippedReason);
+    } catch (err) {
+      spinner.stop('Build planning failed — compiling tools independently.');
+      p.log.warn(
+        `Build planning failed: ${err instanceof Error ? err.message : String(err)}\nTools will compile without shared modules.`,
+      );
+      buildPlanPath = '';
+      sharedModulesManifest = [];
+    } finally {
+      unmuteLog();
+    }
+    for (const pl of plans) {
+      updateCheckpoint(site, state, pl.workflowKey, 'plan-prereqs', {
+        buildPlanPath: buildPlanPath ? toRelative(site, buildPlanPath) : undefined,
+        sharedModules: sharedModulesManifest,
+      });
     }
   }