libretto 0.6.20 → 0.6.22

package/dist/shared/state/session-state.d.ts

@@ -20,6 +20,7 @@ declare const SessionViewportSchema: z.ZodObject<{
 declare const ProviderStateSchema: z.ZodObject<{
     name: z.ZodString;
     sessionId: z.ZodString;
+    recordingUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const SessionStateFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -48,15 +49,17 @@ declare const SessionStateFileSchema: z.ZodObject<{
     provider: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         sessionId: z.ZodString;
+        recordingUrl: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     daemonSocketPath: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type SessionStatus = z.infer<typeof SessionStatusSchema>;
 type SessionAccessMode = z.infer<typeof SessionAccessModeSchema>;
+type ProviderState = z.infer<typeof ProviderStateSchema>;
 type SessionStateFile = z.infer<typeof SessionStateFileSchema>;
 type SessionState = Omit<SessionStateFile, "version">;
 declare function parseSessionStateData(rawState: unknown, source: string): SessionState;
 declare function parseSessionStateContent(content: string, source: string): SessionState;
 declare function serializeSessionState(state: SessionState): SessionStateFile;
 
-export { ProviderStateSchema, SESSION_STATE_VERSION, type SessionAccessMode, SessionAccessModeSchema, type SessionState, type SessionStateFile, SessionStateFileSchema, type SessionStatus, SessionStatusSchema, SessionViewportSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState };
+export { type ProviderState, ProviderStateSchema, SESSION_STATE_VERSION, type SessionAccessMode, SessionAccessModeSchema, type SessionState, type SessionStateFile, SessionStateFileSchema, type SessionStatus, SessionStatusSchema, SessionViewportSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState };

package/dist/shared/state/session-state.js

@@ -15,7 +15,8 @@ const SessionViewportSchema = z.object({
 });
 const ProviderStateSchema = z.object({
   name: z.string(),
-  sessionId: z.string()
+  sessionId: z.string(),
+  recordingUrl: z.string().url().optional()
 });
 const SessionStateFileSchema = z.object({
   version: z.literal(SESSION_STATE_VERSION),

package/dist/shared/workflow/workflow.d.ts

@@ -1,5 +1,7 @@
 import { Page } from 'playwright';
 import { z } from 'zod';
+import { RecoveryAction } from '../../runtime/recovery/page-fallbacks.js';
+import 'ai';
 
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
 type LibrettoWorkflowContext = {
@@ -7,9 +9,13 @@ type LibrettoWorkflowContext = {
     page: Page;
 };
 type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (ctx: LibrettoWorkflowContext, input: Input) => Promise<Output>;
-type LibrettoWorkflowSchemas<InputSchema extends z.ZodType, OutputSchema extends z.ZodType> = {
-    input: InputSchema;
-    output: OutputSchema;
+type LibrettoWorkflowDefinition<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>> = {
+    input?: InputSchema;
+    output?: OutputSchema;
+    recoveryAction?: RecoveryAction;
+};
+type LibrettoWorkflowOptions<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>> = LibrettoWorkflowDefinition<InputSchema, OutputSchema> & {
+    handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>;
 };
 declare class LibrettoWorkflowInputError extends Error {
     readonly workflowName: string;
@@ -26,8 +32,13 @@ declare class LibrettoWorkflow<InputSchema extends z.ZodType = z.ZodType<unknown
     readonly name: string;
     readonly inputSchema?: InputSchema;
     readonly outputSchema?: OutputSchema;
+    readonly recoveryAction?: RecoveryAction;
     private readonly handler;
-    constructor(name: string, schemas: LibrettoWorkflowSchemas<InputSchema, OutputSchema> | undefined, handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>);
+    constructor(name: string, options: {
+        inputSchema?: InputSchema;
+        outputSchema?: OutputSchema;
+        recoveryAction?: RecoveryAction;
+    } | undefined, handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>);
     run(ctx: LibrettoWorkflowContext, input: unknown): Promise<z.infer<OutputSchema>>;
 }
 type ExportedLibrettoWorkflow = {
@@ -35,6 +46,7 @@ type ExportedLibrettoWorkflow = {
     readonly name: string;
     readonly inputSchema?: z.ZodType;
     readonly outputSchema?: z.ZodType;
+    readonly recoveryAction?: RecoveryAction;
     run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
 };
 type WorkflowModuleExports = Record<string, unknown>;
@@ -42,7 +54,8 @@ declare function isLibrettoWorkflow(value: unknown): value is ExportedLibrettoWo
 declare function getWorkflowsFromModuleExports(moduleExports: WorkflowModuleExports): ExportedLibrettoWorkflow[];
 declare function getDefaultWorkflowFromModuleExports(moduleExports: WorkflowModuleExports): ExportedLibrettoWorkflow | null;
 declare function getWorkflowFromModuleExports(moduleExports: WorkflowModuleExports, workflowName: string): ExportedLibrettoWorkflow | null;
-declare function workflow<InputSchema extends z.ZodType, OutputSchema extends z.ZodType>(name: string, schemas: LibrettoWorkflowSchemas<InputSchema, OutputSchema>, handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>): LibrettoWorkflow<InputSchema, OutputSchema>;
+declare function workflow<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>>(name: string, definition: LibrettoWorkflowDefinition<InputSchema, OutputSchema>, handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>): LibrettoWorkflow<InputSchema, OutputSchema>;
+declare function workflow<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>>(name: string, options: LibrettoWorkflowOptions<InputSchema, OutputSchema>): LibrettoWorkflow<InputSchema, OutputSchema>;
 declare function workflow<Input = unknown, Output = unknown>(name: string, handler: LibrettoWorkflowHandler<Input, Output>): LibrettoWorkflow<z.ZodType<Input>, z.ZodType<Output>>;
 
-export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, LibrettoWorkflowInputError, type LibrettoWorkflowSchemas, type WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow };
+export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowDefinition, type LibrettoWorkflowHandler, LibrettoWorkflowInputError, type LibrettoWorkflowOptions, type WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow };

package/dist/shared/workflow/workflow.js

@@ -1,3 +1,6 @@
+import {
+  createRecoveryPage
+} from "../../runtime/recovery/page-fallbacks.js";
 const LIBRETTO_WORKFLOW_BRAND = /* @__PURE__ */ Symbol.for("libretto.workflow");
 class LibrettoWorkflowInputError extends Error {
   workflowName;
@@ -41,16 +44,24 @@ class LibrettoWorkflow {
   // this schema to JSON Schema at build time and exposes it via
   // /v1/workflows/get so API consumers know the workflow's output shape.
   outputSchema;
+  recoveryAction;
   handler;
-  constructor(name, schemas, handler) {
+  constructor(name, options, handler) {
     this.name = name;
-    this.inputSchema = schemas?.input;
-    this.outputSchema = schemas?.output;
+    this.inputSchema = options?.inputSchema;
+    this.outputSchema = options?.outputSchema;
+    this.recoveryAction = options?.recoveryAction;
     this.handler = handler;
   }
   async run(ctx, input) {
     const parsed = parseWorkflowInput(this.name, this.inputSchema, input);
-    return this.handler(ctx, parsed);
+    const workflowContext = !this.recoveryAction ? ctx : {
+      ...ctx,
+      page: createRecoveryPage(ctx.page, {
+        recoveryAction: this.recoveryAction
+      })
+    };
+    return this.handler(workflowContext, parsed);
   }
 }
 function isLibrettoWorkflow(value) {
@@ -101,16 +112,34 @@ function getWorkflowFromModuleExports(moduleExports, workflowName) {
   }
   return null;
 }
-function workflow(name, schemasOrHandler, maybeHandler) {
-  if (typeof schemasOrHandler === "function") {
-    return new LibrettoWorkflow(name, void 0, schemasOrHandler);
+function getWorkflowConstructorOptions(options) {
+  return {
+    inputSchema: options.input,
+    outputSchema: options.output,
+    recoveryAction: options.recoveryAction
+  };
+}
+function workflow(name, definitionOrHandler, maybeHandler) {
+  if (typeof definitionOrHandler === "function") {
+    return new LibrettoWorkflow(name, void 0, definitionOrHandler);
+  }
+  if ("handler" in definitionOrHandler) {
+    return new LibrettoWorkflow(
+      name,
+      getWorkflowConstructorOptions(definitionOrHandler),
+      definitionOrHandler.handler
+    );
   }
   if (!maybeHandler) {
     throw new Error(
-      `workflow("${name}") called with schemas but no handler. Pass the handler as the third argument.`
+      `workflow("${name}") called without a handler. Pass the handler as the third argument or in the options object.`
     );
   }
-  return new LibrettoWorkflow(name, schemasOrHandler, maybeHandler);
+  return new LibrettoWorkflow(
+    name,
+    getWorkflowConstructorOptions(definitionOrHandler),
+    maybeHandler
+  );
 }
 export {
   LIBRETTO_WORKFLOW_BRAND,

package/docs/reference/runtime/page-fallbacks.mdx

@@ -0,0 +1,85 @@
+# Runtime recovery actions
+
+`recoveryAction` lets a workflow recover from a supported Playwright Page or Locator failure. When a supported action fails, Libretto runs the recovery action and retries the original action once.
+
+```typescript
+export default workflow("reviewOrder", {
+  input,
+  output,
+  recoveryAction,
+  handler: async ({ page }, params) => {
+    await page.goto(params.url);
+    await page.locator("#review").click();
+    return { complete: true };
+  },
+});
+```
+
+## computerUseRecoveryAction
+
+`computerUseRecoveryAction()` runs a small vision agent with your instruction. It screenshots the viewport, asks the model for a browser action, executes it with Playwright coordinates, and stops when the model returns `done` or `maxSteps` is reached.
+
+One step is one screenshot, one model decision, and one browser action. The default `maxSteps` is `3`, which covers the common popup flow of close, confirm, then done.
+
+```typescript
+import { computerUseRecoveryAction } from "libretto";
+
+const recoveryAction = computerUseRecoveryAction({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5.5",
+  instruction: "Close any visible blocker that prevents submitting the form.",
+  maxSteps: 3,
+});
+```
+
+Supported provider shortcuts:
+
+```typescript
+{ provider: "openai", apiKey, model?: "gpt-5.5" }
+{ provider: "anthropic", apiKey, model?: "claude-sonnet-4-6" }
+```
+
+Advanced callers can pass a preconfigured AI SDK `LanguageModel` with `languageModel`.
+
+## popupRecoveryAction
+
+`popupRecoveryAction()` is a preset for the common popup case. It uses Libretto's default instruction for closing popups, cookie banners, modals, overlays, and similar blockers.
+
+```typescript
+import { popupRecoveryAction } from "libretto";
+
+const recoveryAction = popupRecoveryAction({
+  provider: "anthropic",
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  model: "claude-sonnet-4-6",
+  maxSteps: 3,
+});
+```
+
+## Custom recovery logic
+
+Use a custom `RecoveryAction` when the site needs deterministic recovery logic, or when it needs to combine `popupRecoveryAction()` with other steps such as reloading the page.
+
+```typescript
+import {
+  popupRecoveryAction,
+  type RecoveryAction,
+} from "libretto";
+
+const popupRecoveryAgent = popupRecoveryAction({
+  provider: "openai",
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5.5",
+});
+
+const recoveryAction: RecoveryAction = async (context) => {
+  const result = await popupRecoveryAgent(context);
+  if (result.status === "incomplete") {
+    await context.page.reload();
+  }
+  return result;
+};
+```
+
+If the recovery action returns without throwing, Libretto retries the original failed method once.

package/docs/understand-libretto/error-handling-and-recovery.mdx

@@ -0,0 +1,45 @@
+# Error recovery
+
+Libretto helps your agent handle failures in two ways: inspect failed runs so it can fix the deterministic workflow, or add a narrow runtime recovery action for expected nondeterminism.
+
+Most workflow failures should be fixed with better selectors, waits, or assertions. Runtime recovery is for cases where the workflow is on the right path but the site sometimes shows unexpected UI that blocks the next action.
+
+## Debugging failed runs
+
+When a workflow fails during development, the Libretto CLI helps your agent debug the code by preserving the browser session. The agent can run headed, add `pause(ctx.session)` at useful checkpoints, inspect the page state, iterate on code, and use `resume` to continue from the pause before redeploying.
+
+For deployed workflows on the hosted platform, a failed run automatically starts an analysis agent. It reviews the error, logs, recording, screenshots, and browser state so it can explain what went wrong and suggest the code change.
+
+## Runtime recovery actions
+
+Add `recoveryAction` to a workflow when you want Libretto to recover after a supported Page or Locator action fails. Libretto calls the recovery action, then retries the original action once.
+
+```typescript
+export default workflow("reviewOrder", {
+  input,
+  output,
+  recoveryAction: popupRecoveryAction({
+    provider: "openai",
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: "gpt-5.5",
+    maxSteps: 3,
+  }),
+  handler: async ({ page }, params) => {
+    await page.goto(params.url);
+    await page.locator("#review").click();
+    return { complete: true };
+  },
+});
+```
+
+## AI vision recovery
+
+The computer use recovery action looks at the current screen and takes one or more browser actions to get back to the expected path. It is useful for nondeterministic blockers such as cookie banners, popups, modals, interstitials, and overlays that intercept clicks.
+
+It uses a viewport screenshot, asks the model for an action, scales the returned screenshot coordinates to Playwright coordinates, and executes the action.
+
+`popupRecoveryAction()` is the built-in preset for closing popups and other blockers. Use `computerUseRecoveryAction()` when you want to provide your own instruction.
+
+Simple sites without nondeterministic UI usually do not need AI vision recovery. For complicated sites automated through the DOM, add it when exploration shows blockers across sessions, accounts, or time. Do not use it to make business decisions that belong in the workflow handler.
+
+Supported provider shortcut models are `gpt-5.5` and `claude-sonnet-4-6`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.20",
+  "version": "0.6.22",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",

package/skills/libretto/SKILL.md

@@ -4,7 +4,7 @@ description: "Browser automation CLI for building, maintaining, and running brow
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.20"
+  version: "0.6.22"
 ---
 
 ## How Libretto Works
@@ -24,7 +24,7 @@ Full documentation is published at [libretto.sh](https://libretto.sh). Available
 - Workflow guides: [one-shot generation](https://libretto.sh/docs/guides/one-shot-workflow-generation), [interactive building](https://libretto.sh/docs/guides/interactive-workflow-building), [debugging workflows](https://libretto.sh/docs/guides/debugging-workflows), [convert to network requests](https://libretto.sh/docs/guides/convert-to-network-requests)
 - CLI reference: [open and connect](https://libretto.sh/docs/reference/cli/open-and-connect), [sessions](https://libretto.sh/docs/reference/cli/sessions), [profiles](https://libretto.sh/docs/reference/cli/profiles), [snapshot](https://libretto.sh/docs/reference/cli/snapshot), [exec](https://libretto.sh/docs/reference/cli/exec), [run and resume](https://libretto.sh/docs/reference/cli/run-and-resume), [session logs](https://libretto.sh/docs/reference/cli/session-logs), [pages](https://libretto.sh/docs/reference/cli/pages)
 - Library API: [workflow](https://libretto.sh/docs/reference/runtime/workflow), [AI extraction](https://libretto.sh/docs/reference/runtime/ai-extraction), [network requests](https://libretto.sh/docs/reference/runtime/network-requests), [file downloads](https://libretto.sh/docs/reference/runtime/file-downloads)
-- Libretto Cloud Hosting: [overview](https://libretto.sh/docs/libretto-cloud-hosting/overview), [authentication](https://libretto.sh/docs/libretto-cloud-hosting/authentication), [deployments](https://libretto.sh/docs/libretto-cloud-hosting/deployments)
+- Libretto Cloud Hosting: [overview](https://libretto.sh/docs/libretto-cloud-hosting/overview), [authentication](https://libretto.sh/docs/libretto-cloud-hosting/authentication), [deployments](https://libretto.sh/docs/libretto-cloud-hosting/deployments), [stealth](https://libretto.sh/docs/libretto-cloud-hosting/stealth)
 - Alternative providers: [overview](https://libretto.sh/docs/alternative-providers/overview), [Kernel](https://libretto.sh/docs/alternative-providers/kernel), [Browserbase](https://libretto.sh/docs/alternative-providers/browserbase), [Steel](https://libretto.sh/docs/alternative-providers/steel), [GCP](https://libretto.sh/docs/alternative-providers/gcp), [AWS](https://libretto.sh/docs/alternative-providers/aws)
 
 ## Default Integration Approach
@@ -37,6 +37,12 @@ Mix strategies freely across steps on a site.
 
 Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first navigation — deep URLs on a cold session are commonly blocked by edge bot protection.
 
+## CAPTCHA Handling
+
+- If a CAPTCHA, Cloudflare challenge, or similar bot check appears in a local Chromium session, try to solve it in the visible browser and continue from the solved state.
+- If the same challenge appears while the session is using a hosted browser provider, wait up to 2 minutes for automatic CAPTCHA handling before deciding the workflow is blocked.
+- When a CAPTCHA was observed during exploration, generated workflow code should include an explicit timeout wait at that point with a short comment linking to the hosted platform stealth docs. Follow `references/code-generation-rules.md` for the code shape.
+
 ## Setup
 
 - Use the package manager convention for the target project. The examples use `npx libretto`; pnpm, yarn, and bun projects should use their equivalent package-manager execution form.

package/skills/libretto/references/code-generation-rules.md

@@ -23,10 +23,10 @@ const outputSchema = z.object({
   results: z.array(z.object({ name: z.string(), value: z.string() })),
 });
 
-export default workflow(
-  "myWorkflow",
-  { input: inputSchema, output: outputSchema },
-  async (ctx: LibrettoWorkflowContext, input) => {
+export default workflow("myWorkflow", {
+  input: inputSchema,
+  output: outputSchema,
+  handler: async (ctx: LibrettoWorkflowContext, input) => {
     const { session, page } = ctx;
 
     console.log("workflow-start", { session, query: input.query });
@@ -35,12 +35,12 @@ export default workflow(
 
     return { results: [] };
   },
-);
+});
 ```
 
 Key points:
 
-- `workflow(name, { input, output }, handler)` takes a unique workflow name, a pair of Zod schemas describing input and output, and the async handler. The handler's `input` parameter is inferred from the input schema — do not redeclare it with a separate `type Input = ...`.
+- `workflow(name, { input, output, recoveryAction, handler })` takes a unique workflow name, optional Zod input/output schemas, an optional recovery action, and the async handler. The handler's `input` parameter is inferred from the input schema — do not redeclare it with a separate `type Input = ...`.
 - At run time, Libretto validates `input` against `inputSchema` before calling the handler. Invalid input throws a clear error listing each failing field; the workflow handler never sees malformed input.
 - `npx libretto run ./file.ts` executes the file's default-exported workflow, so always use `export default workflow(...)`.
 - `ctx` provides `session` and `page`. Use `console.log`/`console.warn`/`console.error` for logging — the runtime wraps these with structured metadata automatically.
@@ -49,6 +49,12 @@ Key points:
 - After validation is complete and the workflow is confirmed working end to end, remove all `pause()` calls and pause-only workflow params unless the user explicitly says to keep them.
 - The browser is launched and closed automatically by the CLI. Do not launch or close it in the handler.
 
+## Workflow Error Handling
+
+Do not add runtime recovery by default. Add `recoveryAction` only when exploration shows nondeterministic blockers such as popups, cookie banners, modals, or overlays.
+
+Use `popupRecoveryAction()` for generic popup and modal dismissal. Use a custom `RecoveryAction` function when the site needs specific recovery steps around the popup recovery agent. Tell the user when you add runtime recovery and keep primary workflow logic in the handler.
+
 ## Playwright DOM Interaction Rules
 
 Generated code must use Playwright locator APIs for all DOM interactions. Do not use `page.evaluate()` with `document.querySelector`, `querySelectorAll`, `textContent`, `click()`, or other DOM APIs when a Playwright locator can do the same thing.
@@ -57,6 +63,17 @@ During the interactive `exec` phase, `page.evaluate` is fine for quick prototypi
 
 Before extracting data (for example text, rows, or field values), wait for the target content itself to be ready, not just its container.
 
+## CAPTCHA Waits
+
+If a CAPTCHA, Cloudflare challenge, or similar bot check appeared during exploration, preserve that recovery point in generated workflow code with an explicit 2 minute timeout wait. Put a short comment immediately above the wait linking to the hosted platform stealth docs:
+
+```typescript
+// Wait for hosted CAPTCHA solving; see https://libretto.sh/docs/libretto-cloud-hosting/stealth.
+await page.waitForTimeout(120_000);
+```
+
+Use the wait only where a challenge was actually observed or is expected from the site's normal flow. After the wait, continue with a concrete locator or URL assertion for the real page state so the workflow fails clearly if the challenge was not solved.
+
 ### Anti-Patterns
 
 These patterns come up frequently during interactive sessions and should not carry over into production code:

package/skills/libretto-readonly/SKILL.md

@@ -4,7 +4,7 @@ description: "Read-only Libretto workflow for diagnosing live browser state with
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.20"
+  version: "0.6.22"
 ---
 
 ## How Libretto Read-Only Works

package/src/cli/commands/execution.ts

@@ -628,7 +628,11 @@ async function runIntegrationFromFile(
       stayOpenOnSuccess: args.stayOpenOnSuccess,
       daemonSocketPath,
       provider: provider
-        ? { name: provider.name, sessionId: provider.sessionId }
+        ? {
+            name: provider.name,
+            sessionId: provider.sessionId,
+            recordingUrl: provider.recordingUrl,
+          }
         : undefined,
     },
     logger,
@@ -636,6 +640,9 @@ async function runIntegrationFromFile(
   if (provider?.liveViewUrl) {
     console.log(`View live session: ${provider.liveViewUrl}`);
   }
+  if (provider?.recordingUrl) {
+    console.log(`View recording: ${provider.recordingUrl}`);
+  }
 
   let outcome: WorkflowOutcome;
   try {

package/src/cli/core/browser.ts

@@ -568,11 +568,15 @@ export async function runOpenWithProvider(
     sessionId: providerSession.sessionId,
     cdpEndpoint: providerSession.cdpEndpoint,
     liveViewUrl: providerSession.liveViewUrl,
+    recordingUrl: providerSession.recordingUrl,
   });
 
   if (providerSession.liveViewUrl) {
     console.log(`View live session: ${providerSession.liveViewUrl}`);
   }
+  if (providerSession.recordingUrl) {
+    console.log(`View recording: ${providerSession.recordingUrl}`);
+  }
 
   writeSessionState(
     {
@@ -587,6 +591,7 @@ export async function runOpenWithProvider(
       provider: {
         name: providerName,
         sessionId: providerSession.sessionId,
+        recordingUrl: providerSession.recordingUrl,
       },
     },
     logger,
@@ -867,7 +872,7 @@ async function waitForCloseAllTargets(
 
 async function closeProviderSessionDirectly(
   session: string,
-  providerState: { name: string; sessionId: string },
+  providerState: { name: string; sessionId: string; recordingUrl?: string },
   logger: LoggerApi,
 ): Promise<string | undefined> {
   try {
@@ -879,7 +884,7 @@ async function closeProviderSessionDirectly(
       sessionId: providerState.sessionId,
       replayUrl: result.replayUrl,
     });
-    return result.replayUrl;
+    return result.replayUrl ?? providerState.recordingUrl;
   } catch (error) {
     logger.warn("close-provider-direct-fallback-failed", {
       session,

package/src/cli/core/daemon/daemon.ts

@@ -182,6 +182,7 @@ class BrowserDaemon {
       provider: ProviderApi;
       name: string;
       sessionId: string;
+      recordingUrl?: string;
     },
   ) {
     this.logger = logger.withScope("child");
@@ -230,11 +231,13 @@ class BrowserDaemon {
       sessionId: string;
       cdpEndpoint: string;
       liveViewUrl?: string;
+      recordingUrl?: string;
     };
     providerSession?: {
       provider: ProviderApi;
       name: string;
       sessionId: string;
+      recordingUrl?: string;
     };
     beforeReady?: () => void;
   }): Promise<BrowserDaemon> {
@@ -516,11 +519,13 @@ class BrowserDaemon {
           sessionId: providerSession.sessionId,
           cdpEndpoint: providerSession.cdpEndpoint,
           liveViewUrl: providerSession.liveViewUrl,
+          recordingUrl: providerSession.recordingUrl,
         },
         providerSession: {
           provider,
           name: config.providerName,
           sessionId: providerSession.sessionId,
+          recordingUrl: providerSession.recordingUrl,
         },
         beforeReady: startupCleanup.dispose,
       });
@@ -593,13 +598,13 @@ class BrowserDaemon {
         const result = await this.providerSession.provider.closeSession(
           this.providerSession.sessionId,
         );
-        replayUrl = result.replayUrl;
-        if (result.replayUrl) {
+        replayUrl = result.replayUrl ?? this.providerSession.recordingUrl;
+        if (replayUrl) {
           this.logger.info("provider-recording", {
             session: this.session,
             provider: this.providerSession.name,
             sessionId: this.providerSession.sessionId,
-            replayUrl: result.replayUrl,
+            replayUrl,
           });
         }
         writeFileSync(
@@ -608,7 +613,7 @@ class BrowserDaemon {
             {
               provider: this.providerSession.name,
               sessionId: this.providerSession.sessionId,
-              replayUrl: result.replayUrl,
+              replayUrl,
             },
             null,
             2,

package/src/cli/core/daemon/ipc.ts

@@ -98,6 +98,7 @@ export type DaemonReadyMessage = {
     sessionId: string;
     cdpEndpoint: string;
     liveViewUrl?: string;
+    recordingUrl?: string;
   };
 };