imprint-mcp 0.6.1 → 0.6.2

package/src/imprint/mcp-live-verifier-server.ts

@@ -0,0 +1,359 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join as pathJoin } from 'node:path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  type CallToolResult,
+  ListToolsRequestSchema,
+  type Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  type LiveIntegrationEvidence,
+  runCapturedIntegrationCase,
+} from './compile-verification.ts';
+import {
+  LIVE_VERIFICATION_EVIDENCE_FILE,
+  LiveVerificationReportSchema,
+  appendLiveVerifierLog,
+  assertReportCoversWorkflowParameters,
+  effectiveParamsForEvidence,
+  hasSuiteReceiptForSession,
+  persistLiveVerificationEvidence,
+  prepareLiveVerificationBackend,
+  readPersistedLiveVerificationEvidence,
+  runLiveIntegrationSuite,
+} from './live-verifier.ts';
+import { loadCredentialStore } from './runtime.ts';
+import { buildZodValidator } from './tool-loader.ts';
+import { WorkflowSchema } from './types.ts';
+
+export function joinBackendPreparation<T>(
+  state: { current?: { promise: Promise<T>; forceReprobe: boolean } },
+  forceReprobe: boolean,
+  start: () => Promise<T>,
+): { promise: Promise<T>; joined: boolean } {
+  if (state.current && (!forceReprobe || state.current.forceReprobe)) {
+    return { promise: state.current.promise, joined: true };
+  }
+
+  // A forced reprobe must not be satisfied by an ordinary preparation that
+  // was already in flight. Queue it behind that preparation so both calls do
+  // not race while updating the same backend cache. Further callers can join
+  // the queued forced preparation.
+  const preceding = state.current?.promise;
+  const started = preceding ? preceding.then(start, start) : start();
+  const promise = started.finally(() => {
+    if (state.current?.promise === promise) state.current = undefined;
+  });
+  state.current = { promise, forceReprobe };
+  return { promise, joined: false };
+}
+
+const RUN_TOOL: Tool = {
+  name: 'run_live_integration_test',
+  description:
+    'Run a targeted live call for a specific unresolved semantic question. Repeated parameters are allowed when the reason explains why.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      params: { type: 'object', additionalProperties: true },
+      reason: { type: 'string' },
+    },
+    required: ['params', 'reason'],
+  },
+};
+
+const PREPARE_BACKEND_TOOL: Tool = {
+  name: 'prepare_live_backend',
+  description:
+    'Reuse the preferred backend and probe only when no valid preference exists. Set forceReprobe only after a transport, network, or browser-infrastructure failure from that backend; never reprobe for empty, incorrect, or otherwise semantic output failures.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      params: { type: 'object', additionalProperties: true },
+      reason: { type: 'string' },
+      forceReprobe: { type: 'boolean' },
+    },
+    required: ['params', 'reason'],
+  },
+};
+
+const RUN_SUITE_TOOL: Tool = {
+  name: 'run_live_integration_suite',
+  description:
+    'Run the compiler-proposed final integration suite. A justified rerun is allowed after failure, timeout, or backend reprobe.',
+  inputSchema: {
+    type: 'object',
+    properties: { reason: { type: 'string' } },
+    additionalProperties: false,
+  },
+};
+
+const SUBMIT_TOOL: Tool = {
+  name: 'submit_verification_report',
+  description: 'Submit the final structured semantic verification report exactly once.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      status: {
+        type: 'string',
+        enum: ['approved', 'approved_with_gaps', 'changes_required', 'inconclusive'],
+      },
+      summary: { type: 'string' },
+      baseline: {
+        type: 'object',
+        properties: {
+          verdict: {
+            type: 'string',
+            enum: ['semantically_correct', 'tool_broken', 'bad_parameters', 'infrastructure'],
+          },
+          reason: { type: 'string' },
+        },
+        required: ['verdict', 'reason'],
+      },
+      parameters: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            verdict: {
+              type: 'string',
+              enum: ['works', 'no_op', 'broken', 'untestable'],
+            },
+            reason: { type: 'string' },
+          },
+          required: ['name', 'verdict', 'reason'],
+          additionalProperties: false,
+        },
+      },
+      issues: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            summary: { type: 'string' },
+            expected: { type: 'string' },
+            observed: { type: 'string' },
+            suggestedFix: { type: 'string' },
+          },
+          required: ['summary', 'expected', 'observed', 'suggestedFix'],
+          additionalProperties: false,
+        },
+      },
+      gaps: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['status', 'summary', 'baseline', 'parameters', 'issues', 'gaps'],
+  },
+};
+
+export async function runLiveVerifierMcpServer(opts: {
+  workflowPath: string;
+  reportPath: string;
+  sessionLabel: string;
+  logPath?: string;
+  attempt?: number;
+}): Promise<void> {
+  const workflow = WorkflowSchema.parse(JSON.parse(readFileSync(opts.workflowPath, 'utf8')));
+  const validator = buildZodValidator(workflow.parameters);
+  const credentials = (await loadCredentialStore(workflow.site)) ?? undefined;
+  let submitted = false;
+  const backendPreparation: {
+    current?: {
+      promise: Promise<Awaited<ReturnType<typeof prepareLiveVerificationBackend>>>;
+      forceReprobe: boolean;
+    };
+  } = {};
+  const evidencePath = pathJoin(dirname(opts.reportPath), LIVE_VERIFICATION_EVIDENCE_FILE);
+  let targetedCallSequence = readPersistedLiveVerificationEvidence(evidencePath).reduce(
+    (highest, item) => {
+      const match = /^targeted-call-(\d+)$/.exec(item.label);
+      return match ? Math.max(highest, Number(match[1])) : highest;
+    },
+    0,
+  );
+  const hasSuiteReceipt = (): boolean => hasSuiteReceiptForSession(evidencePath, opts.sessionLabel);
+
+  const server = new Server(
+    { name: 'imprint-live-verifier', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [PREPARE_BACKEND_TOOL, RUN_SUITE_TOOL, RUN_TOOL, SUBMIT_TOOL],
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> => {
+    if (request.params.name === 'prepare_live_backend') {
+      const input = request.params.arguments as {
+        params?: unknown;
+        reason?: unknown;
+        forceReprobe?: unknown;
+      };
+      if (typeof input.reason !== 'string' || !input.reason.trim()) {
+        return errorResult('reason must explain the backend preparation or reprobe');
+      }
+      const parsed = validator.safeParse(input.params ?? {});
+      if (!parsed.success) return errorResult(`invalid tool params: ${parsed.error.message}`);
+      try {
+        const forceReprobe = input.forceReprobe === true;
+        const preparation = joinBackendPreparation(backendPreparation, forceReprobe, () =>
+          prepareLiveVerificationBackend({
+            workflowPath: opts.workflowPath,
+            params: parsed.data as Record<string, string | number | boolean>,
+            reason: input.reason as string,
+            forceReprobe,
+            logPath: opts.logPath,
+            attempt: opts.attempt,
+          }),
+        );
+        if (preparation.joined) {
+          appendLiveVerifierLog(opts.logPath, {
+            type: 'backend.prepare.joined',
+            attempt: opts.attempt,
+            reason: input.reason,
+            forceReprobe: input.forceReprobe === true,
+          });
+        }
+        const result = await preparation.promise;
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      } catch (error) {
+        return errorResult(error instanceof Error ? error.message : String(error));
+      }
+    }
+    if (request.params.name === 'run_live_integration_suite') {
+      const input = request.params.arguments as { reason?: unknown };
+      try {
+        const suite = await runLiveIntegrationSuite({
+          toolDir: dirname(opts.workflowPath),
+          logPath: opts.logPath,
+          attempt: opts.attempt,
+          reason: typeof input.reason === 'string' ? input.reason : undefined,
+          sessionLabel: opts.sessionLabel,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(suite) }] };
+      } catch (error) {
+        return errorResult(error instanceof Error ? error.message : String(error));
+      }
+    }
+    if (request.params.name === 'run_live_integration_test') {
+      if (!hasSuiteReceipt())
+        return errorResult('run the final integration suite before a targeted call');
+      const input = request.params.arguments as { params?: unknown; reason?: unknown };
+      if (typeof input.reason !== 'string' || !input.reason.trim()) {
+        return errorResult('reason must explain the unresolved semantic question');
+      }
+      const parsed = validator.safeParse(input.params ?? {});
+      if (!parsed.success) return errorResult(`invalid tool params: ${parsed.error.message}`);
+      const label = `targeted-call-${++targetedCallSequence}`;
+      const startedAt = Date.now();
+      appendLiveVerifierLog(opts.logPath, {
+        type: 'targeted-call.started',
+        attempt: opts.attempt,
+        label,
+        reason: input.reason,
+        params: parsed.data,
+      });
+      let run: Awaited<ReturnType<typeof runCapturedIntegrationCase>>;
+      try {
+        run = await runCapturedIntegrationCase({
+          caseName: label,
+          workflowPath: opts.workflowPath,
+          params: parsed.data as Record<string, string | number | boolean>,
+          credentials,
+          preferredOnlyBackend: true,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        appendLiveVerifierLog(opts.logPath, {
+          type: 'targeted-call.failed',
+          attempt: opts.attempt,
+          label,
+          error: message,
+        });
+        return errorResult(message);
+      }
+      const supplemental: LiveIntegrationEvidence = {
+        schemaVersion: 1 as const,
+        kind: 'call',
+        label,
+        caseName: label,
+        toolName: workflow.toolName,
+        requestedParams: parsed.data as Record<string, string | number | boolean>,
+        effectiveParams: effectiveParamsForEvidence(
+          workflow.parameters,
+          parsed.data as Record<string, string | number | boolean>,
+        ),
+        result: run.result,
+        usedBackend: run.usedBackend,
+        attempts: run.attempts,
+        durationMs: Date.now() - startedAt,
+      };
+      persistLiveVerificationEvidence(evidencePath, [supplemental]);
+      appendLiveVerifierLog(opts.logPath, {
+        type: 'targeted-call.completed',
+        attempt: opts.attempt,
+        record: supplemental,
+      });
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              label: supplemental.label,
+              toolName: workflow.toolName,
+              requestedParams: parsed.data,
+              result: run.result,
+              usedBackend: run.usedBackend,
+              attempts: run.attempts,
+            }),
+          },
+        ],
+      };
+    }
+    if (request.params.name === 'submit_verification_report') {
+      if (submitted) return errorResult('verification report was already submitted');
+      const parsed = LiveVerificationReportSchema.safeParse(request.params.arguments);
+      if (!parsed.success)
+        return errorResult(`invalid verification report: ${parsed.error.message}`);
+      if (!hasSuiteReceipt()) {
+        return errorResult('run the final integration suite before submitting');
+      }
+      try {
+        assertReportCoversWorkflowParameters(parsed.data, workflow.parameters);
+      } catch (error) {
+        return errorResult(error instanceof Error ? error.message : String(error));
+      }
+      submitted = true;
+      appendLiveVerifierLog(opts.logPath, {
+        type: 'report.submitted',
+        attempt: opts.attempt,
+        report: parsed.data,
+      });
+      writeFileSync(opts.reportPath, `${JSON.stringify(parsed.data, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+      });
+      return {
+        content: [{ type: 'text', text: 'Report accepted. End the verification session now.' }],
+      };
+    }
+    return errorResult(`unknown tool: ${request.params.name}`);
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Server.connect() resolves after initialization; it does not own the
+  // process lifetime. Keep stdio alive until the verifier disconnects, just
+  // like the compile MCP server does, or Codex can lose the server during its
+  // initialize handshake.
+  await new Promise<void>((resolve) => {
+    const close = (): void => resolve();
+    transport.onclose = close;
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+  });
+}
+
+function errorResult(message: string): CallToolResult {
+  return { isError: true, content: [{ type: 'text', text: message }] };
+}

package/src/imprint/mcp-server.ts

@@ -61,10 +61,20 @@ interface ResolvedTool extends DiscoveredTool {
 /** Tool description shown to MCP clients. Includes the operator's
  *  recorded narration when present — surprisingly load-bearing for the
  *  LLM picking the right tool. */
-function buildToolDescription(w: ResolvedTool['workflow']): string {
+export function buildToolDescription(w: ResolvedTool['workflow']): string {
   const base = w.intent.description;
   const said = w.intent.userSaid?.trim();
-  return said ? `${base}\n\nRecording context: "${said}"` : base;
+  const context = said ? `${base}\n\nRecording context: "${said}"` : base;
+  if (!w.limitations?.length) return context;
+  const limitations = w.limitations
+    .map((entry) => {
+      const omitted = entry.omittedParameters?.length
+        ? ` Omitted inputs: ${entry.omittedParameters.join(', ')}.`
+        : '';
+      return `- ${entry.feature}: ${entry.reason}${omitted}`;
+    })
+    .join('\n');
+  return `${context}\n\nKnown limitations:\n${limitations}`;
 }
 
 /** MCP advertises tool input as JSON Schema; build it directly from

package/src/imprint/probe-backends.ts

@@ -107,7 +107,7 @@ export async function probeAllBackends(
   return results;
 }
 
-async function probeResolvedTool(
+export async function probeResolvedTool(
   opts: Pick<ProbeBackendsOptions, 'site' | 'paramOverrides'>,
   assetRoot: string,
   tool: ResolvedTool,
@@ -230,7 +230,7 @@ async function probeResolvedTool(
     imprintVersion: VERSION,
     schemaVersion: 2,
     workflowHash: workflowHash(tool.workflow),
-    capabilityHash: capabilityHash(tool.workflow),
+    capabilityHash: workflowCapabilityHash(tool.workflow),
     preferredOrder,
     results,
   };
@@ -323,16 +323,85 @@ function workflowHash(workflow: ResolvedTool['workflow']): string {
     .digest('hex');
 }
 
-function capabilityHash(workflow: ResolvedTool['workflow']): string {
+export function workflowCapabilityHash(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}`),
-    ),
+    prefersCdpReplayFirst: prefersCdpReplayFirst(workflow),
+    requestModes: normalizedUnique(workflow.requests.map((request) => request.mode ?? 'fetch')),
+    captures: normalizedUnique([
+      ...(workflow.bootstrap?.captures ?? []).map(
+        (capture) => `bootstrap:${capture.source}:${capture.capability}:${capture.required}`,
+      ),
+      ...workflow.requests.flatMap((request) =>
+        (request.captures ?? []).map(
+          (capture) => `request:${capture.source}:${capture.capability}:${capture.required}`,
+        ),
+      ),
+    ]),
   };
   return createHash('sha256').update(JSON.stringify(caps)).digest('hex');
 }
 
+function normalizedUnique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
+export function canRebindBackendsCacheToWorkflow(
+  tool: Pick<ResolvedTool, 'workflow'>,
+  cache: BackendsCache,
+): boolean {
+  return (
+    typeof cache.capabilityHash === 'string' &&
+    cache.capabilityHash === workflowCapabilityHash(tool.workflow)
+  );
+}
+
+/** Carry a previously proven backend preference across a compile-time workflow
+ * revision without performing network I/O. Runtime cache loading remains
+ * hash-strict; this adapter deliberately rebinds only after the verifier has
+ * decided the existing preference is still applicable. */
+export function rebindBackendsCacheToWorkflow(
+  tool: Pick<ResolvedTool, 'workflow' | 'dir'>,
+  cache: BackendsCache,
+  outPath = pathResolve(tool.dir, 'backends.json'),
+): BackendsCache {
+  if (!canRebindBackendsCacheToWorkflow(tool, cache)) {
+    throw new Error('backend cache capabilities changed; run a fresh probe instead of rebinding');
+  }
+  const rebound: BackendsCache = {
+    ...cache,
+    workflowHash: workflowHash(tool.workflow),
+    capabilityHash: workflowCapabilityHash(tool.workflow),
+  };
+  BackendsCacheSchema.parse(rebound);
+  writeFileSync(outPath, `${JSON.stringify(rebound, null, 2)}\n`);
+  return rebound;
+}
+
+/** Rebind an already-proven cache after compile-time metadata is stamped onto
+ * workflow.json. This performs no network I/O and intentionally does nothing
+ * for missing/invalid caches. */
+export function rebindExistingBackendsCacheToWorkflow(toolDir: string): BackendsCache | null {
+  const workflowPath = pathResolve(toolDir, 'workflow.json');
+  if (!existsSync(workflowPath)) return null;
+
+  let workflow: ResolvedTool['workflow'];
+  try {
+    workflow = WorkflowSchema.parse(JSON.parse(readFileSync(workflowPath, 'utf8')));
+  } catch {
+    return null;
+  }
+
+  const assetRoot = pathResolve(toolDir, '..', '..');
+  const status = loadBackendsCacheStatus(workflow.site, assetRoot, toolDir, {
+    warn: false,
+    toolName: workflow.toolName,
+  });
+  if (status.status !== 'ok' && status.status !== 'stale') return null;
+  if (!canRebindBackendsCacheToWorkflow({ workflow }, status.cache)) return null;
+  return rebindBackendsCacheToWorkflow({ workflow, dir: toolDir }, status.cache);
+}
+
 export function persistRuntimeBackendsCache(opts: {
   tool: ResolvedTool;
   assetRoot: string;
@@ -343,6 +412,18 @@ export function persistRuntimeBackendsCache(opts: {
     warn: false,
     toolName: opts.tool.workflow.toolName,
   });
+  const soleAttempt = opts.attempts.length === 1 ? opts.attempts[0] : undefined;
+  if (
+    status.status === 'ok' &&
+    status.cache.preferredOrder[0] === opts.usedBackend &&
+    soleAttempt?.backend === opts.usedBackend &&
+    soleAttempt.outcome === 'ok'
+  ) {
+    // A normal call through the already-proven preferred backend is not a
+    // probe or a new backend-learning event. Preserve the original probe time
+    // and its richer cold/warm/ranking diagnostics byte-for-byte on disk.
+    return status.cache;
+  }
   const results: BackendsCache['results'] =
     status.status === 'ok' ? { ...status.cache.results } : {};
 
@@ -408,7 +489,7 @@ export function persistRuntimeBackendsCache(opts: {
     imprintVersion: VERSION,
     schemaVersion: 2,
     workflowHash: workflowHash(opts.tool.workflow),
-    capabilityHash: capabilityHash(opts.tool.workflow),
+    capabilityHash: workflowCapabilityHash(opts.tool.workflow),
     preferredOrder,
     results,
   };

package/src/imprint/runtime.ts

@@ -41,6 +41,44 @@ export interface CredentialStore {
   storage?: StorageRecord[];
 }
 
+type NavigationOptions = NonNullable<WorkflowRequest['navigation']>;
+type RequestTransformResult =
+  | string
+  | {
+      url?: string;
+      body?: string;
+      headers?: Record<string, string>;
+      navigation?: Partial<NavigationOptions>;
+      skip?: boolean;
+    };
+
+function mergeNavigationOptions(
+  base: WorkflowRequest['navigation'],
+  override: Partial<NavigationOptions>,
+): NavigationOptions {
+  if (
+    override.actions !== undefined &&
+    (!Array.isArray(override.actions) ||
+      override.actions.length === 0 ||
+      override.actions.some(
+        (entry) =>
+          !entry ||
+          entry.action !== 'click' ||
+          typeof entry.selector !== 'string' ||
+          entry.selector.length === 0,
+      ))
+  ) {
+    throw new Error('request transform returned invalid navigation click actions');
+  }
+  if (
+    override.resultSelector !== undefined &&
+    (typeof override.resultSelector !== 'string' || override.resultSelector.length === 0)
+  ) {
+    throw new Error('request transform returned an invalid navigation result selector');
+  }
+  return { ...base, ...override } as NavigationOptions;
+}
+
 /** Browser-only workflow operations supplied by cdp-replay. Keeping this
  *  transport generic lets pages mint coupled browser state through their own
  *  JavaScript without adding OAuth-provider or frontend-framework logic here. */
@@ -55,6 +93,9 @@ export interface BrowserNavigationTransport {
       timeoutMs?: number;
       pollIntervalMs?: number;
       urlIncludes?: string;
+      selector?: string;
+      actions?: Array<{ action: 'click'; selector: string }>;
+      resultSelector?: string;
       cookie?: { name: string; domain?: string; path?: string };
     },
   ): Promise<Response>;
@@ -178,16 +219,13 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
   const dependencyPreflight = preflightStateDependencies(opts.workflow, state, stateCapabilities);
   if (!dependencyPreflight.ok) return dependencyPreflight.result;
 
-  type TransformResult =
-    | string
-    | { url?: string; body?: string; headers?: Record<string, string>; skip?: boolean };
   let requestTransform:
     | ((
         method: string,
         url: string,
         responses: unknown[],
         params?: Record<string, string | number | boolean>,
-      ) => TransformResult)
+      ) => RequestTransformResult)
     | null = null;
   if (opts.workflow.requestTransformModule && opts.workflowPath) {
     try {
@@ -217,6 +255,7 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
     });
     if (!subbedResult.ok) return subbedResult.result;
     const subbed = subbedResult.value;
+    let navigation = req.navigation;
 
     if (requestTransform) {
       try {
@@ -237,9 +276,18 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
               subbed.headers[k] = v;
             }
           }
+          if (transformResult.navigation) {
+            navigation = mergeNavigationOptions(navigation, transformResult.navigation);
+          }
         }
-      } catch {
-        // Non-fatal — proceed with the original request.
+      } catch (err) {
+        return {
+          ok: false,
+          error: 'BAD_RESPONSE',
+          message: `request transform failed for request ${i}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        };
       }
     }
 
@@ -258,7 +306,7 @@ export async function executeWorkflow<T = unknown>(opts: ExecuteOptions): Promis
       }
       try {
         resp = await opts.browser.navigate(subbed.url, {
-          ...req.navigation,
+          ...navigation,
           method: subbed.method,
           headers: subbed.headers,
           body: subbed.body,
@@ -469,9 +517,7 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
         url: string,
         responses: unknown[],
         params?: Record<string, string | number | boolean>,
-      ) =>
-        | string
-        | { url?: string; body?: string; headers?: Record<string, string>; skip?: boolean })
+      ) => RequestTransformResult)
     | undefined;
   if (opts.workflow.requestTransformModule && opts.workflowPath) {
     try {
@@ -543,6 +589,7 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
     });
     if (!substituted.ok) return substituted;
     const request = substituted.value;
+    let navigation = req.navigation;
 
     if (requestTransform) {
       try {
@@ -558,6 +605,9 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
           if (transformed.url !== undefined) request.url = transformed.url;
           if (transformed.body !== undefined) request.body = transformed.body;
           if (transformed.headers) Object.assign(request.headers, transformed.headers);
+          if (transformed.navigation) {
+            navigation = mergeNavigationOptions(navigation, transformed.navigation);
+          }
         }
       } catch (err) {
         return {
@@ -592,7 +642,7 @@ async function executeAuthWorkflow(opts: ExecuteOptions): Promise<ToolResult> {
       }
       try {
         response = await opts.browser.navigate(request.url, {
-          ...req.navigation,
+          ...navigation,
           method: request.method,
           headers: request.headers,
           body: request.body,