imprint-mcp 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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/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(),