imprint-mcp 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {

package/src/imprint/backend-ladder.ts

@@ -75,6 +75,8 @@ interface LadderResult {
 const log = createLog('backend');
 
 const DEFAULT_LADDER: ConcreteBackend[] = ['fetch', 'stealth-fetch', 'playbook'];
+const DEFAULT_PLAYBOOK_BACKEND_TIMEOUT_MS = 75_000;
+const DEFAULT_PLAYBOOK_BACKEND_STEP_TIMEOUT_MS = 20_000;
 
 /** Process-scoped memo of the backend that last succeeded for a site on the
  *  compile/test path (`runWorkflowWithLadder`). Lets the param-coverage suite
@@ -182,6 +184,22 @@ function sleepMs(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+function playbookBackendTimeoutMs(): number {
+  return positiveEnvMs('IMPRINT_PLAYBOOK_BACKEND_TIMEOUT_MS', DEFAULT_PLAYBOOK_BACKEND_TIMEOUT_MS);
+}
+
+function playbookBackendStepTimeoutMs(): number {
+  return positiveEnvMs(
+    'IMPRINT_PLAYBOOK_BACKEND_STEP_TIMEOUT_MS',
+    DEFAULT_PLAYBOOK_BACKEND_STEP_TIMEOUT_MS,
+  );
+}
+
+function positiveEnvMs(name: string, fallback: number): number {
+  const raw = Number(process.env[name] ?? fallback);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : fallback;
+}
+
 function withWorkflowDefaults(
   workflow: Workflow,
   params: Record<string, string | number | boolean>,
@@ -340,6 +358,8 @@ export async function runWithLadder(
             playbook: playbookPath(assetRoot, tool.site, tool.dir),
             params: paramsWithDefaults,
             site: tool.site,
+            stepTimeoutMs: playbookBackendStepTimeoutMs(),
+            maxDurationMs: playbookBackendTimeoutMs(),
           });
           break;
         }
@@ -1466,7 +1486,7 @@ export async function runWorkflowWithLadder(opts: {
           // A backend that finishes AFTER the probe returned (it lost the race but
           // is still cold-starting Chrome) pools its browser late — arm the idle
           // close so it's torn down rather than left lingering.
-          void inner.finally(() => armCompileCdpIdleClose());
+          void inner.finally(() => armCompileCdpIdleClose()).catch(() => {});
           const r = await Promise.race([
             inner,
             sleepMs(PROBE_TIMEOUT_MS).then(

package/src/imprint/mcp-server.ts

@@ -89,6 +89,24 @@ export function buildJsonSchema(parameters: WorkflowParameter[]): Tool['inputSch
 
 const log = createLog('mcp');
 
+export async function runSerializedBySite<T>(
+  queues: Map<string, Promise<void>>,
+  site: string,
+  task: () => Promise<T>,
+): Promise<T> {
+  const previous = queues.get(site) ?? Promise.resolve();
+  const run = previous.catch(() => undefined).then(task);
+  const tail = run.then(
+    () => undefined,
+    () => undefined,
+  );
+  queues.set(site, tail);
+  tail.finally(() => {
+    if (queues.get(site) === tail) queues.delete(site);
+  });
+  return await run;
+}
+
 /** Build the MCP Server with all discovered tools registered. */
 function buildServer(
   name: string,
@@ -127,6 +145,12 @@ function buildServer(
   // cdp-replay and re-pay the ~33s relaunch.
   const winnerCache = new Map<string, ConcreteBackend>();
 
+  // Browser-backed rungs share per-site state (CDP page/session, stealth token,
+  // winner memo, and backend cache). Parallel MCP calls can race that state and
+  // make Google Flights return fast empty result sets. Keep same-site execution
+  // sequential while allowing unrelated sites to proceed independently.
+  const siteExecutionQueues = new Map<string, Promise<void>>();
+
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
       name: t.workflow.toolName,
@@ -162,74 +186,76 @@ function buildServer(
       string | number | boolean
     >;
 
-    // Audit-only pacing: when the audit harness sets IMPRINT_AUDIT_PACING_MS,
-    // sleep before each tool call so the auditor's per-parameter differential
-    // probing of bot-defended idempotent reads stays steady enough not to trip
-    // the per-IP anti-bot defense. Unset in production → no delay.
-    const pacingMs = Number(process.env.IMPRINT_AUDIT_PACING_MS);
-    if (Number.isFinite(pacingMs) && pacingMs > 0) {
-      await new Promise((r) => setTimeout(r, pacingMs));
-    }
-
     try {
-      const ladder = resolveLadder('auto', tool.preferredOrder);
-      const { result, usedBackend, attempts } = await runWithLadder(
-        ladder,
-        tool,
-        args,
-        assetRoot,
-        stealthCache,
-        { cdpPool, winnerCache, skipBootstrapSplice: Boolean(tool.preferredOrder?.length) },
-      );
-      // Reset the idle timer for this site's pooled Chrome.
-      if (result.ok && usedBackend === 'cdp-replay' && cdpPool.has(tool.site)) {
-        const prev = cdpIdleTimers.get(tool.site);
-        if (prev) clearTimeout(prev);
-        const timer = setTimeout(() => {
-          const cf = cdpPool.get(tool.site);
-          if (cf) {
-            log(`closing idle CDP session for ${tool.site}`);
-            cf.close().catch(() => {});
-            cdpPool.delete(tool.site);
-            cdpIdleTimers.delete(tool.site);
-            // Drop this site's winner memo too: a memoized cdp-replay would now
-            // point at a closed Chrome and re-pay the cold relaunch.
-            for (const key of winnerCache.keys()) {
-              if (key.startsWith(`${tool.site}:`)) winnerCache.delete(key);
-            }
-          }
-        }, CDP_IDLE_TIMEOUT_MS);
-        timer.unref();
-        cdpIdleTimers.set(tool.site, timer);
-      }
-      if (!result.ok) {
-        const text = formatToolError(result);
-        return {
-          isError: true,
-          content: [{ type: 'text', text: `${text}\n(backend: ${usedBackend})` }],
-        };
-      }
-      try {
-        const cache = persistRuntimeBackendsCache({
+      return await runSerializedBySite(siteExecutionQueues, tool.site, async () => {
+        // Audit-only pacing: when the audit harness sets IMPRINT_AUDIT_PACING_MS,
+        // sleep before each actual workflow execution so same-site queued calls
+        // stay spaced out instead of all waiting concurrently before the queue.
+        // Unset in production -> no delay.
+        const pacingMs = Number(process.env.IMPRINT_AUDIT_PACING_MS);
+        if (Number.isFinite(pacingMs) && pacingMs > 0) {
+          await new Promise((r) => setTimeout(r, pacingMs));
+        }
+
+        const ladder = resolveLadder('auto', tool.preferredOrder);
+        const { result, usedBackend, attempts } = await runWithLadder(
+          ladder,
           tool,
+          args,
           assetRoot,
-          usedBackend,
-          attempts,
-        });
-        if (cache) {
-          tool.preferredOrder = cache.preferredOrder;
+          stealthCache,
+          { cdpPool, winnerCache, skipBootstrapSplice: Boolean(tool.preferredOrder?.length) },
+        );
+        // Reset the idle timer for this site's pooled Chrome.
+        if (result.ok && usedBackend === 'cdp-replay' && cdpPool.has(tool.site)) {
+          const prev = cdpIdleTimers.get(tool.site);
+          if (prev) clearTimeout(prev);
+          const timer = setTimeout(() => {
+            const cf = cdpPool.get(tool.site);
+            if (cf) {
+              log(`closing idle CDP session for ${tool.site}`);
+              cf.close().catch(() => {});
+              cdpPool.delete(tool.site);
+              cdpIdleTimers.delete(tool.site);
+              // Drop this site's winner memo too: a memoized cdp-replay would now
+              // point at a closed Chrome and re-pay the cold relaunch.
+              for (const key of winnerCache.keys()) {
+                if (key.startsWith(`${tool.site}:`)) winnerCache.delete(key);
+              }
+            }
+          }, CDP_IDLE_TIMEOUT_MS);
+          timer.unref();
+          cdpIdleTimers.set(tool.site, timer);
+        }
+        if (!result.ok) {
+          const text = formatToolError(result);
+          return {
+            isError: true,
+            content: [{ type: 'text', text: `${text}\n(backend: ${usedBackend})` }],
+          };
+        }
+        try {
+          const cache = persistRuntimeBackendsCache({
+            tool,
+            assetRoot,
+            usedBackend,
+            attempts,
+          });
+          if (cache) {
+            tool.preferredOrder = cache.preferredOrder;
+            log(
+              `  learned backend order for ${tool.workflow.toolName}: ${cache.preferredOrder.join(' → ')}`,
+            );
+          }
+        } catch (err) {
           log(
-            `  learned backend order for ${tool.workflow.toolName}: ${cache.preferredOrder.join(' → ')}`,
+            `  warning: could not persist backend order for ${tool.workflow.toolName}: ${err instanceof Error ? err.message : String(err)}`,
           );
         }
-      } catch (err) {
-        log(
-          `  warning: could not persist backend order for ${tool.workflow.toolName}: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      }
-      const text =
-        typeof result.data === 'string' ? result.data : JSON.stringify(result.data, null, 2);
-      return { content: [{ type: 'text', text: `${text}\n\n(backend: ${usedBackend})` }] };
+        const text =
+          typeof result.data === 'string' ? result.data : JSON.stringify(result.data, null, 2);
+        return { content: [{ type: 'text', text: `${text}\n\n(backend: ${usedBackend})` }] };
+      });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       return { isError: true, content: [{ type: 'text', text: `[INTERNAL] ${msg}` }] };

package/src/imprint/playbook-runner.ts

@@ -30,6 +30,10 @@ interface RunPlaybookOptions {
   headed?: boolean;
   /** Per-step timeout in ms. Default 30000. */
   stepTimeoutMs?: number;
+  /** Whole-playbook timeout in ms. Default unbounded for direct playbook runs. */
+  maxDurationMs?: number;
+  /** Timeout for diagnostic screenshots in ms. Default 5000. */
+  screenshotTimeoutMs?: number;
   /** Screenshot after every step (not just on failure). */
   trace?: boolean;
   /** Inject a Playwright Page for tests. */
@@ -44,6 +48,8 @@ interface RunPlaybookOptions {
 }
 
 const log = createLog('playbook');
+const DEFAULT_STEP_TIMEOUT_MS = 30000;
+const DEFAULT_SCREENSHOT_TIMEOUT_MS = 5000;
 
 export async function runPlaybook(opts: RunPlaybookOptions): Promise<ToolResult> {
   let playbook: Playbook;
@@ -57,7 +63,10 @@ export async function runPlaybook(opts: RunPlaybookOptions): Promise<ToolResult>
   // Generous default — Akamai sensor JS, A/B loaders, lazy bundles all
   // need real time to settle. Tight timeouts make broken sites look
   // worse than they are.
-  const stepTimeoutMs = opts.stepTimeoutMs ?? 30000;
+  const stepTimeoutMs = positiveMs(opts.stepTimeoutMs, DEFAULT_STEP_TIMEOUT_MS);
+  const screenshotTimeoutMs = positiveMs(opts.screenshotTimeoutMs, DEFAULT_SCREENSHOT_TIMEOUT_MS);
+  const deadlineAt =
+    opts.maxDurationMs !== undefined ? Date.now() + positiveMs(opts.maxDurationMs, 1) : null;
 
   let browser: Browser | undefined;
   let context: BrowserContext | undefined;
@@ -137,19 +146,42 @@ export async function runPlaybook(opts: RunPlaybookOptions): Promise<ToolResult>
 
     for (const [i, step] of playbook.steps.entries()) {
       lastStep = i + 1;
+      const budgetMs = budgetedTimeoutMs(
+        stepTimeoutMs,
+        deadlineAt,
+        `Playbook exceeded max duration before step ${lastStep}`,
+      );
       log(`step ${i + 1}/${playbook.steps.length}: ${step.action}`);
-      await executeStep(page, step, params, stepTimeoutMs);
+      await withTimeout(
+        executeStep(page, step, params, budgetMs),
+        budgetMs,
+        `Playbook step ${lastStep}/${playbook.steps.length} (${step.action})`,
+      );
       if (opts.trace) {
-        const traceShot = await screenshot(page, `${playbook.toolName}-trace`, lastStep);
+        const traceShot = await screenshot(
+          page,
+          `${playbook.toolName}-trace`,
+          lastStep,
+          screenshotTimeoutMs,
+        );
         log(`  url=${page.url()}`);
         if (traceShot) log(`  trace screenshot: ${traceShot}`);
       }
     }
-    await Promise.allSettled(pendingBodyReads);
+    const bodyReadBudgetMs = budgetedTimeoutMs(
+      stepTimeoutMs,
+      deadlineAt,
+      'Playbook exceeded max duration while reading captured responses',
+    );
+    await withTimeout(
+      Promise.allSettled(pendingBodyReads),
+      bodyReadBudgetMs,
+      'Playbook captured-response drain',
+    );
     const data = await extractResult(page, playbook.result, captured);
     return { ok: true, data };
   } catch (err) {
-    const screenshotPath = await screenshot(page, playbook.toolName, lastStep);
+    const screenshotPath = await screenshot(page, playbook.toolName, lastStep, screenshotTimeoutMs);
     const suffix = screenshotPath ? `\nscreenshot: ${screenshotPath}` : '';
     const errStr = errMsg(err);
     // Classify the failure mode honestly: a missing locator, a step
@@ -161,9 +193,10 @@ export async function runPlaybook(opts: RunPlaybookOptions): Promise<ToolResult>
     // bug, which over-attributes drift to defects. Map known
     // transient-shape errors to NETWORK so they count as `infra`
     // (re-runnable) rather than `tool_broken` (permanent defect).
-    const isTransient = /No locator matched|Timeout \d+ms exceeded|forResponse|waiting for/i.test(
-      errStr,
-    );
+    const isTransient =
+      /No locator matched|Timeout \d+ms exceeded|timed out after|exceeded max duration|forResponse|waiting for/i.test(
+        errStr,
+      );
     return {
       ok: false,
       error: isTransient ? 'NETWORK' : 'BAD_RESPONSE',
@@ -177,19 +210,58 @@ export async function runPlaybook(opts: RunPlaybookOptions): Promise<ToolResult>
   }
 }
 
-async function screenshot(page: Page, toolName: string, stepNum: number): Promise<string | null> {
+async function screenshot(
+  page: Page,
+  toolName: string,
+  stepNum: number,
+  timeoutMs: number,
+): Promise<string | null> {
   try {
     const { tmpdir } = await import('node:os');
     const { join } = await import('node:path');
     const ts = new Date().toISOString().replace(/[:.]/g, '-');
     const path = join(tmpdir(), `imprint-playbook-${toolName}-step${stepNum}-${ts}.png`);
-    await page.screenshot({ path, fullPage: true });
+    await withTimeout(page.screenshot({ path, fullPage: true }), timeoutMs, 'Playbook screenshot');
     return path;
   } catch {
     return null;
   }
 }
 
+function positiveMs(value: number | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+
+function budgetedTimeoutMs(
+  configuredMs: number,
+  deadlineAt: number | null,
+  errorMessage: string,
+): number {
+  if (deadlineAt === null) return configuredMs;
+  const remainingMs = deadlineAt - Date.now();
+  if (remainingMs <= 0) throw new Error(errorMessage);
+  return Math.max(1, Math.min(configuredMs, Math.floor(remainingMs)));
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  const boundedMs = positiveMs(timeoutMs, 1);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label} timed out after ${boundedMs}ms`)),
+          boundedMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 async function loadPlaybook(input: string | Playbook): Promise<Playbook> {
   if (typeof input !== 'string') return input;
   if (!existsSync(input)) {

package/src/imprint/probe-backends.ts

@@ -272,6 +272,27 @@ function backendResultTooSlow(result: BackendsCache['results'][string] | undefin
   return result?.outcome === 'ok' && result.tooSlow === true;
 }
 
+function invalidPreferredOrderReason(cache: BackendsCache): string | null {
+  for (const backend of cache.preferredOrder) {
+    const result = cache.results[backend];
+    if (backend === 'playbook' && result?.outcome !== 'ok') {
+      return 'preferredOrder includes playbook without a successful playbook result';
+    }
+    if (result && result.outcome !== 'ok') {
+      return `preferredOrder includes ${backend} with ${result.outcome} result`;
+    }
+  }
+  return null;
+}
+
+function existingBackendUsable(
+  backend: ConcreteBackend,
+  result: BackendsCache['results'][string] | undefined,
+): boolean {
+  if (!result) return backend !== 'playbook';
+  return result.outcome === 'ok';
+}
+
 async function probeWarmCdpReplay(
   tool: ResolvedTool,
   params: Record<string, string | number | boolean>,
@@ -358,6 +379,15 @@ export function loadBackendsCacheStatus(
         }
       }
     }
+    const invalidPreferredReason = invalidPreferredOrderReason(parsed);
+    if (invalidPreferredReason) {
+      if (opts.warn !== false) {
+        process.stderr.write(
+          `[imprint] backends.json at ${path} has unsafe preferred backends — ignoring (run \`${remediation}\` to regenerate): ${invalidPreferredReason}\n`,
+        );
+      }
+      return { status: 'invalid', path, reason: invalidPreferredReason, remediation };
+    }
     return { status: 'ok', path, cache: parsed };
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
@@ -438,17 +468,11 @@ export function persistRuntimeBackendsCache(opts: {
   const usedOkAttempt = observedOkAttempts.find((a) => a.backend === opts.usedBackend);
   const usedBackendTooSlow =
     usedOkAttempt !== undefined && usedOkAttempt.durationMs > preferredBackendMaxMs();
-  const existingFast = existingPreferred.filter(
-    (backend) => !backendResultTooSlow(results[backend]),
-  );
-  const existingSlow = existingPreferred.filter((backend) =>
-    backendResultTooSlow(results[backend]),
+  const existingUsable = existingPreferred.filter((backend) =>
+    existingBackendUsable(backend, results[backend]),
   );
-  const structuralFallbacks: ConcreteBackend[] = existsSync(
-    pathResolve(opts.tool.dir, 'playbook.yaml'),
-  )
-    ? ['playbook']
-    : [];
+  const existingFast = existingUsable.filter((backend) => !backendResultTooSlow(results[backend]));
+  const existingSlow = existingUsable.filter((backend) => backendResultTooSlow(results[backend]));
   const preferredOrder = uniqueBackends([
     ...(usedOkAttempt && !usedBackendTooSlow ? [opts.usedBackend] : []),
     ...existingFast,
@@ -456,7 +480,6 @@ export function persistRuntimeBackendsCache(opts: {
     ...existingSlow,
     ...slowObservedOk,
     ...(usedOkAttempt && usedBackendTooSlow ? [opts.usedBackend] : []),
-    ...structuralFallbacks,
   ]);
   const cache: BackendsCache = {
     probedAt: new Date().toISOString(),