imprint-mcp 0.4.6 → 0.4.7

package/src/imprint/mcp-server.ts

@@ -87,15 +87,82 @@ export function buildJsonSchema(parameters: WorkflowParameter[]): Tool['inputSch
   };
 }
 
+export function shouldSkipBootstrapSplice(preferredOrder?: ConcreteBackend[]): boolean {
+  return Boolean(preferredOrder?.length && !preferredOrder.includes('fetch-bootstrap'));
+}
+
+export function withPreferredFallbacks(
+  ladder: ConcreteBackend[],
+  preferredOrder?: ConcreteBackend[],
+): ConcreteBackend[] {
+  const next = [...ladder];
+  if (preferredOrder?.includes('fetch-bootstrap') && !next.includes('cdp-replay')) {
+    const idx = next.indexOf('fetch-bootstrap');
+    if (idx !== -1) next.splice(idx + 1, 0, 'cdp-replay');
+  }
+  if (
+    (preferredOrder?.includes('fetch-bootstrap') || preferredOrder?.includes('cdp-replay')) &&
+    !next.includes('stealth-fetch')
+  ) {
+    const cdpIdx = next.indexOf('cdp-replay');
+    const fbIdx = next.indexOf('fetch-bootstrap');
+    const idx = cdpIdx !== -1 ? cdpIdx : fbIdx;
+    if (idx !== -1) next.splice(idx + 1, 0, 'stealth-fetch');
+  }
+  return next;
+}
+
+export function applyExecutionFallbacks(
+  ladder: ConcreteBackend[],
+  execution?: { skipPlaybookFallback?: boolean },
+): ConcreteBackend[] {
+  if (!execution?.skipPlaybookFallback || ladder.length <= 1) return ladder;
+  return ladder.filter((backend) => backend !== 'playbook');
+}
+
+export function buildSiteSpacingMap(
+  tools: Array<{ site: string; workflow: { execution?: { minCallSpacingMs?: number } } }>,
+): Map<string, number> {
+  const out = new Map<string, number>();
+  for (const tool of tools) {
+    const spacing = Math.max(0, tool.workflow.execution?.minCallSpacingMs ?? 0);
+    if (spacing > (out.get(tool.site) ?? 0)) out.set(tool.site, spacing);
+  }
+  return out;
+}
+
 const log = createLog('mcp');
 
 export async function runSerializedBySite<T>(
   queues: Map<string, Promise<void>>,
   site: string,
   task: () => Promise<T>,
+  opts: {
+    minCallSpacingMs?: number;
+    lastFinishedAt?: Map<string, number>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+  } = {},
 ): Promise<T> {
   const previous = queues.get(site) ?? Promise.resolve();
-  const run = previous.catch(() => undefined).then(task);
+  const run = previous
+    .catch(() => undefined)
+    .then(async () => {
+      const spacingMs = Math.max(0, opts.minCallSpacingMs ?? 0);
+      const lastFinishedAt = opts.lastFinishedAt;
+      const now = opts.now ?? Date.now;
+      const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+      if (spacingMs > 0 && lastFinishedAt) {
+        const elapsed = now() - (lastFinishedAt.get(site) ?? 0);
+        const waitMs = spacingMs - elapsed;
+        if (waitMs > 0) await sleep(waitMs);
+      }
+      try {
+        return await task();
+      } finally {
+        lastFinishedAt?.set(site, now());
+      }
+    });
   const tail = run.then(
     () => undefined,
     () => undefined,
@@ -119,7 +186,7 @@ function buildServer(
     {
       capabilities: { tools: {} },
       instructions:
-        'Imprint runs deterministic workflows captured from real browser sessions. Tools prefer fetch API replay, may use gated fetch-bootstrap only for declared browser-minted state, then cdp-replay (API requests run inside a live trusted Chrome so a protected POST refreshes its anti-bot token between calls) for multi-step state-changing flows, then stealth-fetch for bot-defense state, and playbook only for full DOM interaction. Error codes: AUTH_EXPIRED (401, run `imprint login <site>`); STATE_MISSING (required cookie/state was unavailable or ambiguous); FORBIDDEN (403); RATE_LIMITED (429, back off); BAD_RESPONSE (other 4xx/5xx); NETWORK (fetch failed); UNKNOWN (everything else).',
+        'Imprint runs deterministic workflows captured from real browser sessions. Tools prefer fetch API replay, front-load cdp-replay when a workflow needs reusable live-browser request state, may use gated fetch-bootstrap for one-shot browser-minted state, then stealth-fetch for bot-defense state, and playbook only for full DOM interaction. Error codes: AUTH_EXPIRED (401, run `imprint login <site>`); STATE_MISSING (required cookie/state was unavailable or ambiguous); FORBIDDEN (403); RATE_LIMITED (429, back off); BAD_RESPONSE (other 4xx/5xx); NETWORK (fetch failed); UNKNOWN (everything else).',
     },
   );
 
@@ -150,6 +217,8 @@ function buildServer(
   // 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>>();
+  const siteLastFinishedAt = new Map<string, number>();
+  const siteMinCallSpacingMs = buildSiteSpacingMap(tools);
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t) => ({
@@ -187,75 +256,93 @@ function buildServer(
     >;
 
     try {
-      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));
-        }
+      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,
-          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({
+          const ladder = withPreferredFallbacks(
+            resolveLadder('auto', tool.preferredOrder),
+            tool.preferredOrder,
+          );
+          const executionLadder = applyExecutionFallbacks(ladder, tool.workflow.execution);
+          const { result, usedBackend, attempts } = await runWithLadder(
+            executionLadder,
             tool,
+            args,
             assetRoot,
-            usedBackend,
-            attempts,
-          });
-          if (cache) {
-            tool.preferredOrder = cache.preferredOrder;
+            stealthCache,
+            {
+              cdpPool,
+              winnerCache,
+              skipBootstrapSplice: shouldSkipBootstrapSplice(tool.preferredOrder),
+            },
+          );
+          // Reset the idle timer for this site's pooled Chrome. The pool may be
+          // retained even when a CDP-backed workflow response failed; that keeps
+          // later calls warm, but still needs an idle reap.
+          if (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})` }] };
+        },
+        {
+          minCallSpacingMs: siteMinCallSpacingMs.get(tool.site),
+          lastFinishedAt: siteLastFinishedAt,
+        },
+      );
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       return { isError: true, content: [{ type: 'text', text: `[INTERNAL] ${msg}` }] };

package/src/imprint/probe-backends.ts

@@ -340,14 +340,37 @@ function workflowHash(workflow: ResolvedTool['workflow']): string {
 
 function capabilityHash(workflow: ResolvedTool['workflow']): string {
   const caps = {
-    bootstrap: Boolean(workflow.bootstrap),
-    captures: workflow.requests.flatMap((r) =>
-      (r.captures ?? []).map((c) => `${c.source}:${c.name}:${c.capability}`),
-    ),
+    requestTransformModule: workflow.requestTransformModule ?? null,
+    bootstrap: workflow.bootstrap
+      ? {
+          url: workflow.bootstrap.url,
+          captures: workflow.bootstrap.captures ?? [],
+        }
+      : null,
+    requests: workflow.requests.map((r) => ({
+      method: r.method.toUpperCase(),
+      effect: r.effect ?? null,
+      stateRefs: stateRefsInWorkflowRequest(r),
+      captures: r.captures ?? [],
+    })),
   };
   return createHash('sha256').update(JSON.stringify(caps)).digest('hex');
 }
 
+function stateRefsInWorkflowRequest(
+  request: ResolvedTool['workflow']['requests'][number],
+): string[] {
+  const refs = new Set<string>();
+  const scan = (text: string | undefined): void => {
+    if (!text) return;
+    for (const match of text.matchAll(/\$\{state\.([A-Za-z0-9_]+)\}/g)) refs.add(match[1] ?? '');
+  };
+  scan(request.url);
+  scan(request.body);
+  for (const value of Object.values(request.headers ?? {})) scan(value);
+  return [...refs].filter(Boolean).sort();
+}
+
 /** Read backends.json with status information. Runtime can still fall back to
  *  the default ladder, while status commands can explain why a cache was not
  *  usable. */
@@ -367,8 +390,11 @@ export function loadBackendsCacheStatus(
     if (parsed.schemaVersion && parsed.schemaVersion >= 2 && parsed.workflowHash) {
       const workflowPath = pathResolve(toolDir, 'workflow.json');
       if (existsSync(workflowPath)) {
-        const currentHash = workflowHashSync(readFileSync(workflowPath, 'utf8'));
-        if (currentHash !== parsed.workflowHash) {
+        const current = workflowCacheHashesSync(readFileSync(workflowPath, 'utf8'));
+        if (
+          current.workflowHash !== parsed.workflowHash &&
+          (!parsed.capabilityHash || current.capabilityHash !== parsed.capabilityHash)
+        ) {
           const reason = 'workflow hash changed';
           if (opts.warn !== false) {
             process.stderr.write(
@@ -496,10 +522,15 @@ export function persistRuntimeBackendsCache(opts: {
   return cache;
 }
 
-function workflowHashSync(workflowJson: string): string {
-  return createHash('sha256')
-    .update(JSON.stringify(WorkflowSchema.parse(JSON.parse(workflowJson))))
-    .digest('hex');
+function workflowCacheHashesSync(workflowJson: string): {
+  workflowHash: string;
+  capabilityHash: string;
+} {
+  const workflow = WorkflowSchema.parse(JSON.parse(workflowJson));
+  return {
+    workflowHash: workflowHash(workflow),
+    capabilityHash: capabilityHash(workflow),
+  };
 }
 
 function backendsCacheRemediation(site: string, toolName?: string): string {

package/src/imprint/runtime.ts

@@ -133,18 +133,6 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
     }
   }
 
-  // rawResponses feeds parser modules and the final return shape. responseSlots
-  // keeps legacy request.extract aliases without replacing raw parser input.
-  const responseSlots: ResponseSlot[] = [];
-  const state: Record<string, unknown> = { ...(opts.initialState ?? {}) };
-
-  // Per-execution mutable jar. Never shared across MCP/cron calls.
-  const cookieJar = new RuntimeCookieJar(credentials.cookies);
-  const liveCredentials: CredentialStore = { ...credentials, cookies: cookieJar.toJSON() };
-  const stateCapabilities = collectStateCapabilities(opts.workflow);
-  const dependencyPreflight = preflightStateDependencies(opts.workflow, state, stateCapabilities);
-  if (!dependencyPreflight.ok) return dependencyPreflight.result;
-
   type TransformResult = string | { url: string; body?: string; headers?: Record<string, string> };
   let requestTransform:
     | ((
@@ -152,6 +140,7 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
         url: string,
         responses: unknown[],
         params?: Record<string, string | number | boolean>,
+        state?: Record<string, unknown>,
       ) => TransformResult)
     | null = null;
   if (opts.workflow.requestTransformModule && opts.workflowPath) {
@@ -161,12 +150,34 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
         opts.workflow.requestTransformModule,
       );
       const mod = await import(transformPath);
+      if (typeof mod.prepareParams === 'function') {
+        const prepared = await mod.prepareParams(params);
+        if (prepared && typeof prepared === 'object') {
+          for (const [k, v] of Object.entries(prepared)) {
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+              params[k] = v;
+            }
+          }
+        }
+      }
       if (typeof mod.transform === 'function') requestTransform = mod.transform;
     } catch {
       // Non-fatal — proceed without transform.
     }
   }
 
+  // rawResponses feeds parser modules and the final return shape. responseSlots
+  // keeps legacy request.extract aliases without replacing raw parser input.
+  const responseSlots: ResponseSlot[] = [];
+  const state: Record<string, unknown> = { ...(opts.initialState ?? {}) };
+
+  // Per-execution mutable jar. Never shared across MCP/cron calls.
+  const cookieJar = new RuntimeCookieJar(credentials.cookies);
+  const liveCredentials: CredentialStore = { ...credentials, cookies: cookieJar.toJSON() };
+  const stateCapabilities = collectStateCapabilities(opts.workflow);
+  const dependencyPreflight = preflightStateDependencies(opts.workflow, state, stateCapabilities);
+  if (!dependencyPreflight.ok) return dependencyPreflight.result;
+
   for (let i = 0; i < opts.workflow.requests.length; i++) {
     const req = opts.workflow.requests[i];
     if (!req) continue;
@@ -190,6 +201,7 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
           subbed.url,
           responseSlots.map((s) => s.raw),
           params,
+          state,
         );
         if (typeof transformResult === 'string') {
           subbed.url = transformResult;

package/src/imprint/stealth-fetch.ts

@@ -74,6 +74,20 @@ export interface TokenCache {
   /** Lower-cased response headers of the bootstrap navigation, so callers can
    *  satisfy `response_header` bootstrap captures. Optional. */
   bootstrapResponseHeaders?: Record<string, string>;
+  /** Browser-generated requests observed while the bootstrap page loaded. Lets
+   *  workflows capture replay headers minted by page JavaScript for later XHRs. */
+  observedRequests?: Array<{
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: string;
+    resourceType?: string;
+    response?: {
+      status: number;
+      headers: Record<string, string>;
+      body?: string;
+    };
+  }>;
   /** The bootstrap browser's actual `navigator.userAgent`, captured live. Reused
    *  for the post-bootstrap fetches so the wire UA matches the binary that minted
    *  the cookies (and its client hints below). Absent if capture failed or on
@@ -509,6 +523,42 @@ export async function bootstrapStealthToken(args: BootstrapArgs): Promise<TokenC
     });
 
     const page = await context.newPage();
+    const observedRequests: NonNullable<TokenCache['observedRequests']> = [];
+    const observedByRequest = new Map<
+      unknown,
+      NonNullable<TokenCache['observedRequests']>[number]
+    >();
+    const pendingResponseCaptures = new Set<Promise<void>>();
+    page.on('request', (request) => {
+      const entry: NonNullable<TokenCache['observedRequests']>[number] = {
+        method: request.method(),
+        url: request.url(),
+        headers: request.headers(),
+        ...(request.postData() !== null ? { body: request.postData() as string } : {}),
+        resourceType: request.resourceType(),
+      };
+      observedRequests.push(entry);
+      observedByRequest.set(request, entry);
+      if (observedRequests.length > 100) observedRequests.shift();
+    });
+    page.on('response', (response) => {
+      const entry = observedByRequest.get(response.request());
+      if (!entry || !shouldCaptureObservedBody(entry)) return;
+      const pending = (async () => {
+        try {
+          const headers = await response.allHeaders();
+          entry.response = {
+            status: response.status(),
+            headers,
+            body: await response.text(),
+          };
+        } catch {
+          // best-effort — response reuse simply won't match without a body
+        }
+      })();
+      pendingResponseCaptures.add(pending);
+      void pending.finally(() => pendingResponseCaptures.delete(pending));
+    });
     // Patch navigator.webdriver ONLY on the vanilla-Playwright fallback. When the
     // stealth plugin is active it already removes the property natively (a real
     // Chrome lacks it); stacking our Object.defineProperty on top leaves a
@@ -662,6 +712,7 @@ export async function bootstrapStealthToken(args: BootstrapArgs): Promise<TokenC
     );
 
     await page.waitForTimeout(300);
+    await settlePendingResponseCaptures(pendingResponseCaptures, 2_000);
 
     // Capture cookies scoped to the recording's registrable domain
     // (eTLD+1). Naive `.split('.').slice(-2)` was wrong for multi-part
@@ -686,6 +737,7 @@ export async function bootstrapStealthToken(args: BootstrapArgs): Promise<TokenC
       bootstrappedAt: Date.now(),
       bootstrapHtml,
       bootstrapResponseHeaders,
+      observedRequests,
       userAgent: capturedUserAgent,
       clientHints,
     };
@@ -694,6 +746,25 @@ export async function bootstrapStealthToken(args: BootstrapArgs): Promise<TokenC
   }
 }
 
+function shouldCaptureObservedBody(
+  entry: NonNullable<TokenCache['observedRequests']>[number],
+): boolean {
+  const type = entry.resourceType?.toLowerCase();
+  if (type && type !== 'xhr' && type !== 'fetch') return false;
+  return true;
+}
+
+async function settlePendingResponseCaptures(
+  pending: Set<Promise<void>>,
+  timeoutMs: number,
+): Promise<void> {
+  if (pending.size === 0) return;
+  await Promise.race([
+    Promise.allSettled([...pending]),
+    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+  ]);
+}
+
 async function defaultUnderlyingFetch(
   url: string,
   init: FetchInit,

package/src/imprint/stealth-token-cache.ts

@@ -57,6 +57,19 @@ export function loadCachedToken(siteDir: string, maxAgeSeconds: number): TokenCa
       cookies: raw.cookies,
       sensorHeaders: raw.sensorHeaders,
       bootstrappedAt: raw.bootstrappedAt,
+      ...(typeof raw.bootstrapHtml === 'string' ? { bootstrapHtml: raw.bootstrapHtml } : {}),
+      ...(raw.bootstrapResponseHeaders &&
+      typeof raw.bootstrapResponseHeaders === 'object' &&
+      !Array.isArray(raw.bootstrapResponseHeaders)
+        ? { bootstrapResponseHeaders: raw.bootstrapResponseHeaders as Record<string, string> }
+        : {}),
+      ...(Array.isArray(raw.observedRequests)
+        ? { observedRequests: stripDurableObservedResponseBodies(raw.observedRequests) }
+        : {}),
+      ...(typeof raw.userAgent === 'string' ? { userAgent: raw.userAgent } : {}),
+      ...(raw.clientHints && typeof raw.clientHints === 'object' && !Array.isArray(raw.clientHints)
+        ? { clientHints: raw.clientHints as Record<string, string> }
+        : {}),
     };
   } catch {
     return null;
@@ -69,7 +82,16 @@ export function saveCachedToken(siteDir: string, token: TokenCache): void {
     mkdirSync(siteDir, { recursive: true });
     const p = tokenPath(siteDir);
     const tmp = `${p}.${process.pid}.tmp`;
-    writeFileSync(tmp, `${JSON.stringify(token)}\n`, 'utf8');
+    writeFileSync(
+      tmp,
+      `${JSON.stringify({
+        ...token,
+        ...(token.observedRequests
+          ? { observedRequests: stripDurableObservedResponseBodies(token.observedRequests) }
+          : {}),
+      })}\n`,
+      'utf8',
+    );
     renameSync(tmp, p);
   } catch (err) {
     log(
@@ -78,6 +100,21 @@ export function saveCachedToken(siteDir: string, token: TokenCache): void {
   }
 }
 
+function stripDurableObservedResponseBodies(
+  observedRequests: NonNullable<TokenCache['observedRequests']>,
+): NonNullable<TokenCache['observedRequests']> {
+  return observedRequests.map((req) => {
+    if (!req.response || req.response.body === undefined) return req;
+    return {
+      ...req,
+      response: {
+        status: req.response.status,
+        headers: req.response.headers,
+      },
+    };
+  });
+}
+
 /** Remove a cached token (best-effort) — call when a site's teach run ends. */
 export function clearCachedToken(siteDir: string): void {
   try {

package/src/imprint/types.ts

@@ -221,6 +221,42 @@ const BootstrapCaptureSchema = z.discriminatedUnion('source', [
     header: z.string(),
     mode: z.enum(['first', 'last', 'all']).optional().default('last'),
   }),
+  /** Read a header from a browser-generated request observed during bootstrap
+   *  navigation. This is for replay tokens produced by page JavaScript for an
+   *  XHR/fetch request, where neither HTML nor response headers contain the
+   *  value. `urlPattern` is a JavaScript regular expression tested against the
+   *  observed request URL. */
+  CaptureCommonSchema.extend({
+    source: z.literal('request_header'),
+    header: z.string(),
+    method: z.string().optional(),
+    urlPattern: z.string().optional(),
+    mode: z.enum(['first', 'last', 'all']).optional().default('last'),
+  }),
+  /** Read a value from a browser-generated request URL observed during
+   *  bootstrap navigation. This is for per-page request ids or URL tokens that
+   *  are generated alongside browser XHR/fetch calls. `urlPattern` selects the
+   *  observed request; `pattern` extracts the value from that request URL. */
+  CaptureCommonSchema.extend({
+    source: z.literal('request_url_regex'),
+    pattern: z.string(),
+    group: z.number().int().nonnegative().optional().default(1),
+    method: z.string().optional(),
+    urlPattern: z.string().optional(),
+    mode: z.enum(['first', 'last', 'all']).optional().default('last'),
+  }),
+  /** Read a value from a browser-generated request body observed during
+   *  bootstrap navigation. This is for page-minted replay tokens embedded in
+   *  POST bodies (for example form-encoded RPC envelopes) where neither the URL
+   *  nor request headers carry the value. */
+  CaptureCommonSchema.extend({
+    source: z.literal('request_body_regex'),
+    pattern: z.string(),
+    group: z.number().int().nonnegative().optional().default(1),
+    method: z.string().optional(),
+    urlPattern: z.string().optional(),
+    mode: z.enum(['first', 'last', 'all']).optional().default('last'),
+  }),
 ]);
 export type BootstrapCapture = z.infer<typeof BootstrapCaptureSchema>;
 
@@ -295,6 +331,15 @@ export const WorkflowSchema = z.object({
       exhaustedBackends: z.array(z.string()),
     })
     .optional(),
+  /** Optional runtime hints for provider-specific replay constraints. */
+  execution: z
+    .object({
+      /** Minimum end-to-start spacing between MCP calls for the same site. */
+      minCallSpacingMs: z.number().int().nonnegative().optional(),
+      /** Do not enter the DOM playbook rung after API/browser-backed rungs fail. */
+      skipPlaybookFallback: z.boolean().optional(),
+    })
+    .optional(),
 });
 export type Workflow = z.infer<typeof WorkflowSchema>;