libretto 0.6.21 → 0.6.23

package/README.md

@@ -1,5 +1,9 @@
 <!-- Generated from packages/libretto/README.template.md by `pnpm sync:mirrors`. Do not edit directly. -->
 
+<p align="center">
+  <img src="assets/readme-banner.png" alt="Libretto" />
+</p>
+
 # Libretto
 
 [![npm version](https://img.shields.io/npm/v/libretto)](https://www.npmjs.com/package/libretto)
@@ -87,7 +91,7 @@ Run `npx libretto help` for the full list of commands.
 
 ## Configuration
 
-All Libretto state lives in a `.libretto/` directory at your project root. See the [configuration docs](https://libretto.sh/docs/configuration) for details on config files, sessions, and profiles.
+All Libretto state lives in a `.libretto/` directory at your project root. See the [configuration docs](https://libretto.sh/docs/understand-libretto/configuration) for details on config files, sessions, and profiles.
 
 ## Join the Community
 

package/README.template.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="{{LIBRETTO_PATH_PREFIX}}assets/readme-banner.png" alt="Libretto" />
+</p>
+
 # Libretto
 
 [![npm version](https://img.shields.io/npm/v/libretto)](https://www.npmjs.com/package/libretto)
@@ -85,7 +89,7 @@ Run `npx libretto help` for the full list of commands.
 
 ## Configuration
 
-All Libretto state lives in a `.libretto/` directory at your project root. See the [configuration docs](https://libretto.sh/docs/configuration) for details on config files, sessions, and profiles.
+All Libretto state lives in a `.libretto/` directory at your project root. See the [configuration docs](https://libretto.sh/docs/understand-libretto/configuration) for details on config files, sessions, and profiles.
 
 ## Join the Community
 

package/dist/cli/commands/execution.js

@@ -476,13 +476,20 @@ async function runIntegrationFromFile(args, logger) {
       viewport: args.viewport,
       stayOpenOnSuccess: args.stayOpenOnSuccess,
       daemonSocketPath,
-      provider: provider ? { name: provider.name, sessionId: provider.sessionId } : void 0
+      provider: provider ? {
+        name: provider.name,
+        sessionId: provider.sessionId,
+        recordingUrl: provider.recordingUrl
+      } : void 0
     },
     logger
   );
   if (provider?.liveViewUrl) {
     console.log(`View live session: ${provider.liveViewUrl}`);
   }
+  if (provider?.recordingUrl) {
+    console.log(`View recording: ${provider.recordingUrl}`);
+  }
   let outcome;
   try {
     outcome = await waitForWorkflowOutcome(pid, workflowOutcome.promise);

package/dist/cli/core/browser.js

@@ -414,11 +414,15 @@ async function runOpenWithProvider(rawUrl, providerName, session, logger, access
     provider: providerName,
     sessionId: providerSession.sessionId,
     cdpEndpoint: providerSession.cdpEndpoint,
-    liveViewUrl: providerSession.liveViewUrl
+    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(
     {
       port: 0,
@@ -431,7 +435,8 @@ async function runOpenWithProvider(rawUrl, providerName, session, logger, access
       daemonSocketPath,
       provider: {
         name: providerName,
-        sessionId: providerSession.sessionId
+        sessionId: providerSession.sessionId,
+        recordingUrl: providerSession.recordingUrl
       }
     },
     logger
@@ -657,7 +662,7 @@ async function closeProviderSessionDirectly(session, providerState, logger) {
       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/dist/cli/core/daemon/daemon.js

@@ -352,12 +352,14 @@ class BrowserDaemon {
           name: config.providerName,
           sessionId: providerSession.sessionId,
           cdpEndpoint: providerSession.cdpEndpoint,
-          liveViewUrl: providerSession.liveViewUrl
+          liveViewUrl: providerSession.liveViewUrl,
+          recordingUrl: providerSession.recordingUrl
         },
         providerSession: {
           provider,
           name: config.providerName,
-          sessionId: providerSession.sessionId
+          sessionId: providerSession.sessionId,
+          recordingUrl: providerSession.recordingUrl
         },
         beforeReady: startupCleanup.dispose
       });
@@ -407,13 +409,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(
@@ -422,7 +424,7 @@ class BrowserDaemon {
             {
               provider: this.providerSession.name,
               sessionId: this.providerSession.sessionId,
-              replayUrl: result.replayUrl
+              replayUrl
             },
             null,
             2

package/dist/cli/core/providers/kernel.js

@@ -1,44 +1,122 @@
-const KERNEL_API_ENDPOINT = "https://api.onkernel.com";
-function createKernelProvider() {
-  const apiKey = process.env.KERNEL_API_KEY;
+function readBooleanEnv(name, defaultValue) {
+  const value = process.env[name]?.trim().toLowerCase();
+  if (!value) return defaultValue;
+  return value === "1" || value === "true" || value === "yes";
+}
+function readTimeoutSeconds(options) {
+  if (options.timeoutSeconds !== void 0) return options.timeoutSeconds;
+  return Number(process.env.KERNEL_TIMEOUT_SECONDS ?? 300);
+}
+async function kernelFetchJson(endpoint, apiKey, path, init) {
+  const resp = await fetch(`${endpoint}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+      ...init.headers
+    }
+  });
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Kernel API error (${resp.status}): ${body}`);
+  }
+  return await resp.json();
+}
+async function kernelFetchNoBody(endpoint, apiKey, path, init) {
+  const resp = await fetch(`${endpoint}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      ...init.headers
+    }
+  });
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(`Kernel API error (${resp.status}): ${body}`);
+  }
+}
+function readEndpoint() {
+  return process.env.KERNEL_API_ENDPOINT?.trim() || process.env.KERNEL_ENDPOINT?.trim() || "https://api.onkernel.com";
+}
+function createKernelProvider(options = {}) {
+  const apiKey = options.apiKey ?? process.env.KERNEL_API_KEY;
   if (!apiKey)
     throw new Error("KERNEL_API_KEY is required for Kernel provider.");
+  const endpoint = readEndpoint();
+  const headless = options.headless ?? process.env.KERNEL_HEADLESS !== "false";
+  const stealth = options.stealth ?? readBooleanEnv("KERNEL_STEALTH", false);
+  const timeoutSeconds = readTimeoutSeconds(options);
+  const enableRecording = options.enableRecording ?? readBooleanEnv("KERNEL_ENABLE_RECORDING", false);
+  const replays = /* @__PURE__ */ new Map();
   return {
     async createSession() {
-      const resp = await fetch(`${KERNEL_API_ENDPOINT}/browsers`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          headless: process.env.KERNEL_HEADLESS !== "false",
-          stealth: process.env.KERNEL_STEALTH === "true",
-          timeout_seconds: Number(process.env.KERNEL_TIMEOUT_SECONDS ?? 300)
-        })
-      });
-      if (!resp.ok) {
-        const body = await resp.text();
-        throw new Error(`Kernel API error (${resp.status}): ${body}`);
+      const json = await kernelFetchJson(
+        endpoint,
+        apiKey,
+        "/browsers",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            headless,
+            stealth,
+            timeout_seconds: timeoutSeconds
+          })
+        }
+      );
+      let replay;
+      if (enableRecording) {
+        try {
+          replay = await kernelFetchJson(
+            endpoint,
+            apiKey,
+            `/browsers/${json.session_id}/replays`,
+            { method: "POST", body: JSON.stringify({}) }
+          );
+          replays.set(json.session_id, {
+            replayId: replay.replay_id,
+            replayViewUrl: replay.replay_view_url ?? void 0
+          });
+        } catch (error) {
+          await kernelFetchNoBody(
+            endpoint,
+            apiKey,
+            `/browsers/${json.session_id}`,
+            { method: "DELETE" }
+          ).catch(() => {
+          });
+          throw error;
+        }
       }
-      const json = await resp.json();
       return {
         sessionId: json.session_id,
-        cdpEndpoint: json.cdp_ws_url
+        cdpEndpoint: json.cdp_ws_url,
+        liveViewUrl: json.browser_live_view_url ?? void 0,
+        recordingUrl: replay?.replay_view_url ?? void 0
       };
     },
     async closeSession(sessionId) {
-      const resp = await fetch(`${KERNEL_API_ENDPOINT}/browsers/${sessionId}`, {
-        method: "DELETE",
-        headers: { Authorization: `Bearer ${apiKey}` }
+      const replay = replays.get(sessionId);
+      let replayStopError;
+      if (replay) {
+        try {
+          await kernelFetchNoBody(
+            endpoint,
+            apiKey,
+            `/browsers/${sessionId}/replays/${replay.replayId}/stop`,
+            { method: "POST" }
+          );
+        } catch (error) {
+          replayStopError = error;
+        }
+      }
+      await kernelFetchNoBody(endpoint, apiKey, `/browsers/${sessionId}`, {
+        method: "DELETE"
       });
-      if (!resp.ok) {
-        const body = await resp.text();
-        throw new Error(
-          `Kernel API error closing session ${sessionId} (${resp.status}): ${body}`
-        );
+      replays.delete(sessionId);
+      if (replayStopError) {
+        throw replayStopError;
       }
-      return {};
+      return { replayUrl: replay?.replayViewUrl };
     }
   };
 }

package/dist/cli/core/providers/steel.js

@@ -1,5 +1,14 @@
 const DEFAULT_STEEL_API_ENDPOINT = "https://api.steel.dev";
 const DEFAULT_STEEL_CONNECT_ENDPOINT = "wss://connect.steel.dev";
+const STEEL_STEALTH_SESSION_OPTIONS = {
+  solveCaptcha: true,
+  useProxy: true,
+  stealthConfig: {
+    humanizeInteractions: true,
+    autoCaptchaSolving: true,
+    skipFingerprintInjection: false
+  }
+};
 function createSteelProvider(options = {}) {
   const apiKey = options.apiKey ?? process.env.STEEL_API_KEY;
   if (!apiKey) throw new Error("STEEL_API_KEY is required for Steel provider.");
@@ -13,7 +22,7 @@ function createSteelProvider(options = {}) {
           "steel-api-key": apiKey,
           "Content-Type": "application/json"
         },
-        body: JSON.stringify({})
+        body: JSON.stringify(STEEL_STEALTH_SESSION_OPTIONS)
       });
       if (!resp.ok) {
         const body = await resp.text();

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { LogOptions, Logger, LoggerApi, LoggerSink, MinimalLogger, defaultLogger } from './shared/logger/logger.js';
 export { createFileLogSink, jsonlConsoleSink, prettyConsoleSink } from './shared/logger/sinks.js';
 export { SESSION_STATE_VERSION, SessionState, SessionStateFile, SessionStateFileSchema, SessionStatus, SessionStatusSchema, parseSessionStateContent, parseSessionStateData, serializeSessionState } from './shared/state/session-state.js';
-export { executeRecoveryAgent } from './runtime/recovery/agent.js';
+export { BrowserAction, RecoveryAgentResult, RecoveryAgentStep, executeRecoveryAgent } from './runtime/recovery/agent.js';
 export { attemptWithRecovery } from './runtime/recovery/recovery.js';
 export { DetectedSubmissionError, KnownSubmissionError, detectSubmissionError } from './runtime/recovery/errors.js';
+export { COMPUTER_USE_RECOVERY_MODELS, ComputerUseRecoveryActionOptions, POPUP_RECOVERY_INSTRUCTION, PopupRecoveryActionOptions, RecoveryAction, RecoveryActionContext, RecoveryActionHandler, RecoveryActionOptions, RecoveryActionResult, RecoveryActionTargetType, computerUseRecoveryAction, createRecoveryPage, popupRecoveryAction } from './runtime/recovery/page-fallbacks.js';
 export { ExtractOptions, extractFromPage } from './runtime/extract/extract.js';
 export { PageRequestOptions, RequestConfig, pageRequest } from './runtime/network/network.js';
 export { DownloadResult, DownloadViaClickOptions, downloadViaClick } from './runtime/download/download.js';
@@ -12,7 +13,7 @@ export { InstrumentationOptions, InstrumentedPage, installInstrumentation, instr
 export { GhostCursorOptions, ensureGhostCursor, ghostClick, hideGhostCursor, moveGhostCursor } from './shared/visualization/ghost-cursor.js';
 export { HighlightOptions, clearHighlights, ensureHighlightLayer, showHighlight } from './shared/visualization/highlight.js';
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './shared/run/browser.js';
-export { ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowInputError, LibrettoWorkflowSchemas, WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow } from './shared/workflow/workflow.js';
+export { ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowInputError, LibrettoWorkflowOptions, WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow } from './shared/workflow/workflow.js';
 import 'zod';
 import 'playwright';
 import 'ai';

package/dist/index.js

@@ -17,11 +17,20 @@ import {
   parseSessionStateContent,
   serializeSessionState
 } from "./shared/state/index.js";
-import { executeRecoveryAgent } from "./runtime/recovery/agent.js";
+import {
+  executeRecoveryAgent
+} from "./runtime/recovery/agent.js";
 import { attemptWithRecovery } from "./runtime/recovery/recovery.js";
 import {
   detectSubmissionError
 } from "./runtime/recovery/errors.js";
+import {
+  COMPUTER_USE_RECOVERY_MODELS,
+  POPUP_RECOVERY_INSTRUCTION,
+  computerUseRecoveryAction,
+  createRecoveryPage,
+  popupRecoveryAction
+} from "./runtime/recovery/page-fallbacks.js";
 import {
   extractFromPage
 } from "./runtime/extract/extract.js";
@@ -78,16 +87,20 @@ if (isDirectExecution()) {
   });
 }
 export {
+  COMPUTER_USE_RECOVERY_MODELS,
   LIBRETTO_WORKFLOW_BRAND,
   LibrettoWorkflow,
   LibrettoWorkflowInputError,
   Logger,
+  POPUP_RECOVERY_INSTRUCTION,
   SESSION_STATE_VERSION,
   SessionStateFileSchema,
   SessionStatusSchema,
   attemptWithRecovery,
   clearHighlights,
+  computerUseRecoveryAction,
   createFileLogSink,
+  createRecoveryPage,
   defaultLogger,
   detectSubmissionError,
   downloadViaClick,
@@ -111,6 +124,7 @@ export {
   parseSessionStateContent,
   parseSessionStateData,
   pause,
+  popupRecoveryAction,
   prettyConsoleSink,
   serializeSessionState,
   showHighlight,

package/dist/runtime/recovery/agent.d.ts

@@ -2,11 +2,59 @@ import { Page } from 'playwright';
 import { MinimalLogger } from '../../shared/logger/logger.js';
 import { LanguageModel } from 'ai';
 
+type BrowserAction = {
+    type: "click";
+    x: number;
+    y: number;
+    button?: string;
+} | {
+    type: "double_click";
+    x: number;
+    y: number;
+} | {
+    type: "scroll";
+    x: number;
+    y: number;
+    scroll_x: number;
+    scroll_y: number;
+} | {
+    type: "keypress";
+    keys: string[];
+} | {
+    type: "type";
+    text: string;
+} | {
+    type: "wait";
+} | {
+    type: "screenshot";
+} | {
+    type: "drag";
+    path: {
+        x: number;
+        y: number;
+    }[];
+} | {
+    type: "move";
+    x: number;
+    y: number;
+} | {
+    type: "done";
+};
+type RecoveryAgentStep = {
+    step: number;
+    reasoning: string;
+    action: BrowserAction;
+};
+type RecoveryAgentStatus = "skipped" | "no-action-needed" | "action-taken" | "incomplete";
+type RecoveryAgentResult = {
+    status: RecoveryAgentStatus;
+    steps: RecoveryAgentStep[];
+};
 /**
  * Executes a vision-based recovery agent to recover from browser automation failures.
  * Takes a screenshot, sends it to the LLM with the instruction, and executes
  * the LLM's suggested browser actions.
  */
-declare function executeRecoveryAgent(page: Page, instruction: string, logger?: MinimalLogger, model?: LanguageModel): Promise<void>;
+declare function executeRecoveryAgent(page: Page, instruction: string, logger?: MinimalLogger, model?: LanguageModel, maxSteps?: number): Promise<RecoveryAgentResult>;
 
-export { executeRecoveryAgent };
+export { type BrowserAction, type RecoveryAgentResult, type RecoveryAgentStatus, type RecoveryAgentStep, executeRecoveryAgent };