libretto 0.6.21 → 0.6.23

package/dist/runtime/recovery/page-fallbacks.js

@@ -0,0 +1,389 @@
+import { executeRecoveryAgent } from "./agent.js";
+import { defaultLogger } from "../../shared/logger/logger.js";
+const POPUP_RECOVERY_INSTRUCTION = [
+  "Look at the page for any popup, modal, cookie banner, overlay, dialog, or interstitial that blocks interaction.",
+  "If any blocking popup is visible, close it before returning done.",
+  "Prefer obvious close, dismiss, continue, accept, or X buttons.",
+  "Do not return done while a blocking overlay or dialog is still visible."
+].join(" ");
+const COMPUTER_USE_RECOVERY_MODELS = {
+  anthropic: "claude-sonnet-4-6",
+  openai: "gpt-5.5"
+};
+const PAGE_UI_METHODS = /* @__PURE__ */ new Set([
+  "click",
+  "dblclick",
+  "tap",
+  "hover",
+  "fill",
+  "type",
+  "press",
+  "pressSequentially",
+  "check",
+  "uncheck",
+  "setChecked",
+  "selectOption",
+  "setInputFiles",
+  "selectText",
+  "dispatchEvent",
+  "focus",
+  "blur",
+  "dragAndDrop"
+]);
+const PAGE_READ_METHODS = /* @__PURE__ */ new Set([
+  "title",
+  "content",
+  "screenshot",
+  "waitForLoadState",
+  "waitForRequest",
+  "waitForResponse",
+  "waitForURL"
+]);
+const LOCATOR_UI_METHODS = /* @__PURE__ */ new Set([
+  "click",
+  "dblclick",
+  "tap",
+  "hover",
+  "fill",
+  "type",
+  "press",
+  "pressSequentially",
+  "check",
+  "uncheck",
+  "setChecked",
+  "selectOption",
+  "setInputFiles",
+  "selectText",
+  "dispatchEvent",
+  "focus",
+  "blur",
+  "clear",
+  "dragTo",
+  "scrollIntoViewIfNeeded"
+]);
+const LOCATOR_READ_METHODS = /* @__PURE__ */ new Set([
+  "textContent",
+  "innerText",
+  "innerHTML",
+  "allTextContents",
+  "allInnerTexts",
+  "ariaSnapshot",
+  "boundingBox",
+  "count",
+  "getAttribute",
+  "inputValue",
+  "isChecked",
+  "isDisabled",
+  "isEditable",
+  "isEnabled",
+  "isVisible",
+  "isHidden",
+  "screenshot",
+  "waitFor"
+]);
+const PAGE_LOCATOR_FACTORY_METHODS = /* @__PURE__ */ new Set([
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId"
+]);
+const LOCATOR_FACTORY_METHODS = /* @__PURE__ */ new Set([
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "filter",
+  "and",
+  "or",
+  "first",
+  "last",
+  "nth"
+]);
+const FRAME_LOCATOR_FACTORY_METHODS = /* @__PURE__ */ new Set([
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "owner",
+  "first",
+  "last",
+  "nth",
+  "frameLocator"
+]);
+function isUiMethod(targetType, method) {
+  return targetType === "page" ? PAGE_UI_METHODS.has(method) : LOCATOR_UI_METHODS.has(method);
+}
+function isReadMethod(targetType, method) {
+  return targetType === "page" ? PAGE_READ_METHODS.has(method) : LOCATOR_READ_METHODS.has(method);
+}
+function isSupportedMethod(targetType, method) {
+  return isUiMethod(targetType, method) || isReadMethod(targetType, method);
+}
+async function runWithFallback(args) {
+  try {
+    return await args.invoke();
+  } catch (originalError) {
+    const baseContext = {
+      page: args.page,
+      targetType: args.targetType,
+      method: args.method,
+      args: args.methodArgs
+    };
+    if (!isSupportedMethod(baseContext.targetType, baseContext.method)) {
+      throw originalError;
+    }
+    defaultLogger.info("Action failed, attempting recovery", {
+      targetType: baseContext.targetType,
+      method: baseContext.method,
+      argsCount: baseContext.args.length,
+      error: formatErrorForLog(originalError)
+    });
+    let recoveryResult;
+    try {
+      recoveryResult = await args.options.recoveryAction({
+        ...baseContext,
+        error: originalError
+      });
+    } catch (recoveryError) {
+      defaultLogger.warn("Recovery action failed", {
+        targetType: baseContext.targetType,
+        method: baseContext.method,
+        originalError: formatErrorForLog(originalError),
+        recoveryError: formatErrorForLog(recoveryError)
+      });
+      throw new AggregateError(
+        [originalError, recoveryError],
+        "Recovery action failed after the original action failed."
+      );
+    }
+    defaultLogger.info("Recovery action completed, retrying original action", {
+      targetType: baseContext.targetType,
+      method: baseContext.method,
+      recoveryResult
+    });
+    try {
+      const result = await args.invoke();
+      defaultLogger.info("Recovered action retry succeeded", {
+        targetType: baseContext.targetType,
+        method: baseContext.method
+      });
+      return result;
+    } catch (retryError) {
+      defaultLogger.warn("Recovered action retry failed", {
+        targetType: baseContext.targetType,
+        method: baseContext.method,
+        originalError: formatErrorForLog(originalError),
+        retryError: formatErrorForLog(retryError)
+      });
+      throw originalError;
+    }
+  }
+}
+function formatErrorForLog(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+  }
+  return { value: String(error) };
+}
+function bindOrWrapLocatorMethod(locator, rawPage, method, value, options, caches) {
+  if (typeof value !== "function") return value;
+  if (LOCATOR_FACTORY_METHODS.has(method)) {
+    return (...args) => {
+      const nextLocator = value.apply(locator, args);
+      return createFallbackLocator(nextLocator, rawPage, options, caches);
+    };
+  }
+  if (method === "all") {
+    return async (...args) => {
+      const locators = await value.apply(locator, args);
+      return locators.map(
+        (nextLocator) => createFallbackLocator(nextLocator, rawPage, options, caches)
+      );
+    };
+  }
+  if (method === "contentFrame") {
+    return (...args) => {
+      const frameLocator = value.apply(locator, args);
+      return createFallbackFrameLocator(frameLocator, rawPage, options, caches);
+    };
+  }
+  if (!isSupportedMethod("locator", method)) {
+    return value.bind(locator);
+  }
+  return (...args) => runWithFallback({
+    page: rawPage,
+    targetType: "locator",
+    method,
+    methodArgs: args,
+    invoke: () => value.apply(locator, args),
+    options
+  });
+}
+function createFallbackLocator(locator, rawPage, options, caches) {
+  const cached = caches.locators.get(locator);
+  if (cached) return cached;
+  const proxy = new Proxy(locator, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") {
+        return Reflect.get(target, prop, receiver);
+      }
+      return bindOrWrapLocatorMethod(
+        target,
+        rawPage,
+        prop,
+        Reflect.get(target, prop, target),
+        options,
+        caches
+      );
+    }
+  });
+  caches.locators.set(locator, proxy);
+  return proxy;
+}
+function createFallbackFrameLocator(frameLocator, rawPage, options, caches) {
+  const cached = caches.frameLocators.get(frameLocator);
+  if (cached) return cached;
+  const proxy = new Proxy(frameLocator, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") {
+        return Reflect.get(target, prop, receiver);
+      }
+      const value = Reflect.get(target, prop, target);
+      if (typeof value !== "function") return value;
+      if (FRAME_LOCATOR_FACTORY_METHODS.has(prop)) {
+        return (...args) => {
+          const result = value.apply(target, args);
+          if (prop === "first" || prop === "last" || prop === "nth") {
+            return createFallbackFrameLocator(
+              result,
+              rawPage,
+              options,
+              caches
+            );
+          }
+          if (prop === "frameLocator") {
+            return createFallbackFrameLocator(
+              result,
+              rawPage,
+              options,
+              caches
+            );
+          }
+          return createFallbackLocator(
+            result,
+            rawPage,
+            options,
+            caches
+          );
+        };
+      }
+      return value.bind(target);
+    }
+  });
+  caches.frameLocators.set(frameLocator, proxy);
+  return proxy;
+}
+function createRecoveryPage(page, options) {
+  const caches = {
+    locators: /* @__PURE__ */ new WeakMap(),
+    frameLocators: /* @__PURE__ */ new WeakMap()
+  };
+  return new Proxy(page, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") {
+        return Reflect.get(target, prop, receiver);
+      }
+      const value = Reflect.get(target, prop, target);
+      if (typeof value !== "function") return value;
+      if (PAGE_LOCATOR_FACTORY_METHODS.has(prop)) {
+        return (...args) => {
+          const locator = value.apply(target, args);
+          return createFallbackLocator(locator, page, options, caches);
+        };
+      }
+      if (prop === "frameLocator") {
+        return (...args) => {
+          const frameLocator = value.apply(target, args);
+          return createFallbackFrameLocator(frameLocator, page, options, caches);
+        };
+      }
+      if (!isSupportedMethod("page", prop)) {
+        return value.bind(target);
+      }
+      return (...args) => runWithFallback({
+        page,
+        targetType: "page",
+        method: prop,
+        methodArgs: args,
+        invoke: () => value.apply(target, args),
+        options
+      });
+    }
+  });
+}
+async function resolveComputerUseRecoveryModel(options) {
+  if ("provider" in options) {
+    if (options.provider === "openai") {
+      const model2 = options.model ?? COMPUTER_USE_RECOVERY_MODELS.openai;
+      if (model2 !== COMPUTER_USE_RECOVERY_MODELS.openai) {
+        throw new Error(
+          `Unsupported OpenAI computer use recovery model "${model2}". Supported model: ${COMPUTER_USE_RECOVERY_MODELS.openai}.`
+        );
+      }
+      return import("@ai-sdk/openai").then(
+        ({ createOpenAI }) => createOpenAI({ apiKey: options.apiKey })(model2)
+      );
+    }
+    const model = options.model ?? COMPUTER_USE_RECOVERY_MODELS.anthropic;
+    if (model !== COMPUTER_USE_RECOVERY_MODELS.anthropic) {
+      throw new Error(
+        `Unsupported Anthropic computer use recovery model "${model}". Supported model: ${COMPUTER_USE_RECOVERY_MODELS.anthropic}.`
+      );
+    }
+    return import("@ai-sdk/anthropic").then(
+      ({ createAnthropic }) => createAnthropic({ apiKey: options.apiKey })(model)
+    );
+  }
+  return options.languageModel;
+}
+function computerUseRecoveryAction(options) {
+  return async ({ page }) => {
+    const model = await resolveComputerUseRecoveryModel(options);
+    return executeRecoveryAgent(
+      page,
+      options.instruction,
+      void 0,
+      model,
+      options.maxSteps
+    );
+  };
+}
+function popupRecoveryAction(options) {
+  return computerUseRecoveryAction({
+    ...options,
+    instruction: POPUP_RECOVERY_INSTRUCTION
+  });
+}
+export {
+  COMPUTER_USE_RECOVERY_MODELS,
+  POPUP_RECOVERY_INSTRUCTION,
+  computerUseRecoveryAction,
+  createRecoveryPage,
+  popupRecoveryAction
+};

package/dist/shared/state/index.d.ts

@@ -1,2 +1,2 @@
-export { SESSION_STATE_VERSION, SessionAccessMode, SessionAccessModeSchema, SessionState, SessionStateFile, SessionStateFileSchema, SessionStatus, SessionStatusSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState } from './session-state.js';
+export { ProviderState, SESSION_STATE_VERSION, SessionAccessMode, SessionAccessModeSchema, SessionState, SessionStateFile, SessionStateFileSchema, SessionStatus, SessionStatusSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState } from './session-state.js';
 import 'zod';

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.