libretto 0.6.20 → 0.6.22

package/src/cli/core/providers/kernel.ts

@@ -1,51 +1,175 @@
 import type { ProviderApi } from "./types.js";
 
-const KERNEL_API_ENDPOINT = "https://api.onkernel.com";
+export type KernelProviderOptions = {
+  apiKey?: string;
+  headless?: boolean;
+  stealth?: boolean;
+  timeoutSeconds?: number;
+  enableRecording?: boolean;
+};
 
-export function createKernelProvider(): ProviderApi {
-  const apiKey = process.env.KERNEL_API_KEY;
+type KernelBrowserResponse = {
+  session_id: string;
+  cdp_ws_url: string;
+  browser_live_view_url?: string | null;
+};
+
+type KernelReplayResponse = {
+  replay_id: string;
+  replay_view_url?: string | null;
+};
+
+function readBooleanEnv(name: string, defaultValue: boolean): boolean {
+  const value = process.env[name]?.trim().toLowerCase();
+  if (!value) return defaultValue;
+  return value === "1" || value === "true" || value === "yes";
+}
+
+function readTimeoutSeconds(options: KernelProviderOptions): number {
+  if (options.timeoutSeconds !== undefined) return options.timeoutSeconds;
+  return Number(process.env.KERNEL_TIMEOUT_SECONDS ?? 300);
+}
+
+async function kernelFetchJson<T>(
+  endpoint: string,
+  apiKey: string,
+  path: string,
+  init: RequestInit,
+): Promise<T> {
+  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()) as T;
+}
+
+async function kernelFetchNoBody(
+  endpoint: string,
+  apiKey: string,
+  path: string,
+  init: RequestInit,
+): Promise<void> {
+  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(): string {
+  return (
+    process.env.KERNEL_API_ENDPOINT?.trim() ||
+    process.env.KERNEL_ENDPOINT?.trim() ||
+    "https://api.onkernel.com"
+  );
+}
+
+export function createKernelProvider(
+  options: KernelProviderOptions = {},
+): ProviderApi {
+  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 = new Map<
+    string,
+    {
+      replayId: string;
+      replayViewUrl?: string;
+    }
+  >();
 
   return {
     async createSession() {
-      const resp = await fetch(`${KERNEL_API_ENDPOINT}/browsers`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-          "Content-Type": "application/json",
+      const json = await kernelFetchJson<KernelBrowserResponse>(
+        endpoint,
+        apiKey,
+        "/browsers",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            headless,
+            stealth,
+            timeout_seconds: timeoutSeconds,
+          }),
         },
-        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}`);
+      );
+
+      let replay: KernelReplayResponse | undefined;
+      if (enableRecording) {
+        try {
+          replay = await kernelFetchJson<KernelReplayResponse>(
+            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 ?? undefined,
+          });
+        } catch (error) {
+          await kernelFetchNoBody(
+            endpoint,
+            apiKey,
+            `/browsers/${json.session_id}`,
+            { method: "DELETE" },
+          ).catch(() => {});
+          throw error;
+        }
       }
-      const json = (await resp.json()) as {
-        session_id: string;
-        cdp_ws_url: string;
-      };
+
       return {
         sessionId: json.session_id,
         cdpEndpoint: json.cdp_ws_url,
+        liveViewUrl: json.browser_live_view_url ?? undefined,
+        recordingUrl: replay?.replay_view_url ?? undefined,
       };
     },
     async closeSession(sessionId) {
-      const resp = await fetch(`${KERNEL_API_ENDPOINT}/browsers/${sessionId}`, {
+      const replay = replays.get(sessionId);
+      let replayStopError: unknown;
+      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",
-        headers: { Authorization: `Bearer ${apiKey}` },
       });
-      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/src/cli/core/providers/libretto-cloud.ts

@@ -6,7 +6,6 @@ type CloudSessionResponse = {
   status: string;
   cdp_url: string | null;
   live_view_url: string | null;
-  recording_url: string | null;
 };
 
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
@@ -77,8 +76,11 @@ export function createLibrettoCloudProvider(): ProviderApi {
       };
     },
     async closeSession(sessionId) {
-      const json = await closeCloudSession(endpoint, apiKey, sessionId);
-      return { replayUrl: json.replay_url ?? undefined };
+      await closeCloudSession(endpoint, apiKey, sessionId);
+      const replayUrl = await getCloudRecordingUrl(endpoint, apiKey, sessionId).catch(
+        () => undefined,
+      );
+      return { replayUrl };
     },
   };
 }
@@ -172,7 +174,7 @@ async function closeCloudSession(
   endpoint: string,
   apiKey: string,
   sessionId: string,
-): Promise<{ replay_url: string | null }> {
+): Promise<void> {
   const resp = await fetch(`${endpoint}/v1/sessions/close`, {
     method: "POST",
     headers: {
@@ -187,10 +189,31 @@ async function closeCloudSession(
       `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`,
     );
   }
+}
+
+async function getCloudRecordingUrl(
+  endpoint: string,
+  apiKey: string,
+  sessionId: string,
+): Promise<string | undefined> {
+  const resp = await fetch(`${endpoint}/v1/recordings/get`, {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ json: { session_id: sessionId } }),
+  });
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(
+      `Libretto Cloud API error reading recording for session ${sessionId} (${resp.status}): ${body}`,
+    );
+  }
   const { json } = (await resp.json()) as {
-    json: { replay_url: string | null };
+    json: { recording_url: string | null };
   };
-  return json;
+  return json.recording_url ?? undefined;
 }
 
 function createStartupSessionCleanup(

package/src/cli/core/providers/steel.ts

@@ -8,6 +8,16 @@ type SteelSessionResponse = {
   sessionViewerUrl?: string;
 };
 
+const STEEL_STEALTH_SESSION_OPTIONS = {
+  solveCaptcha: true,
+  useProxy: true,
+  stealthConfig: {
+    humanizeInteractions: true,
+    autoCaptchaSolving: true,
+    skipFingerprintInjection: false,
+  },
+};
+
 export type SteelProviderOptions = {
   apiKey?: string;
 };
@@ -30,7 +40,7 @@ export function createSteelProvider(
           "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/src/cli/core/providers/types.ts

@@ -5,6 +5,9 @@ export type ProviderSession = {
   // Only libretto-cloud surfaces this today; direct-SDK providers leave it
   // undefined.
   liveViewUrl?: string;
+  // Provider-hosted URL for watching the recording for this session. It may be
+  // available as soon as recording starts, before the provider has finalized it.
+  recordingUrl?: string;
 };
 
 export type ProviderCloseResult = {

package/src/index.ts

@@ -29,13 +29,33 @@ export {
 } from "./shared/state/index.js";
 
 // Recovery
-export { executeRecoveryAgent } from "./runtime/recovery/agent.js";
+export {
+  executeRecoveryAgent,
+  type BrowserAction,
+  type RecoveryAgentResult,
+  type RecoveryAgentStep,
+} from "./runtime/recovery/agent.js";
 export { attemptWithRecovery } from "./runtime/recovery/recovery.js";
 export {
   detectSubmissionError,
   type KnownSubmissionError,
   type DetectedSubmissionError,
 } from "./runtime/recovery/errors.js";
+export {
+  COMPUTER_USE_RECOVERY_MODELS,
+  POPUP_RECOVERY_INSTRUCTION,
+  computerUseRecoveryAction,
+  createRecoveryPage,
+  popupRecoveryAction,
+  type ComputerUseRecoveryActionOptions,
+  type PopupRecoveryActionOptions,
+  type RecoveryActionContext,
+  type RecoveryAction,
+  type RecoveryActionHandler,
+  type RecoveryActionOptions,
+  type RecoveryActionResult,
+  type RecoveryActionTargetType,
+} from "./runtime/recovery/page-fallbacks.js";
 
 // AI extraction
 export {
@@ -105,7 +125,7 @@ export {
   type ExportedLibrettoWorkflow,
   type LibrettoWorkflowContext,
   type LibrettoWorkflowHandler,
-  type LibrettoWorkflowSchemas,
+  type LibrettoWorkflowOptions,
   type WorkflowInputValidator,
 } from "./shared/workflow/workflow.js";
 const isDirectExecution = (): boolean => {