libretto 0.5.6 → 0.6.0

package/src/cli/core/browser.ts

@@ -37,6 +37,8 @@ import {
   readSessionState,
   writeSessionState,
 } from "./session.js";
+import type { ProviderApi } from "./providers/types.js";
+import { getCloudProviderApi } from "./providers/index.js";
 import { installSessionTelemetry } from "./session-telemetry.js";
 
 const CLOSE_WAIT_MS = 1_500;
@@ -258,6 +260,16 @@ export async function connect(
       endpoint,
       pid: state.pid,
     });
+    // Provider sessions have no local PID to check liveness.
+    // Don't destroy the remote session on a transient failure —
+    // let the user retry or explicitly close.
+    if (state.provider) {
+      throw new Error(
+        `Could not connect to ${state.provider.name} session for "${session}" at ${endpoint}. ` +
+          `The remote session may still be active. Try again, or close with: libretto close --session ${session}`,
+      );
+    }
+
     if (state.pid == null || !isPidRunning(state.pid)) {
       clearSessionState(session, logger);
       throw new Error(
@@ -717,6 +729,106 @@ await new Promise(() => {});
   );
 }
 
+export async function runOpenWithProvider(
+  rawUrl: string,
+  providerName: string,
+  provider: ProviderApi,
+  session: string,
+  logger: LoggerApi,
+  accessMode: SessionAccessMode = "write-access",
+): Promise<void> {
+  const parsedUrl = normalizeUrl(rawUrl);
+  const url = parsedUrl.href;
+  logger.info("open-provider-start", { url, provider: providerName, session });
+
+  console.log(
+    `Creating ${providerName} browser session (session: ${session})...`,
+  );
+
+  const providerSession = await provider.createSession();
+  logger.info("open-provider-session-created", {
+    provider: providerName,
+    sessionId: providerSession.sessionId,
+    cdpEndpoint: providerSession.cdpEndpoint,
+  });
+
+  console.log(`Connecting to ${providerName} browser...`);
+
+  let browser: Browser | null = null;
+  try {
+    browser = await tryConnectToCDP(
+      providerSession.cdpEndpoint,
+      logger,
+      30_000,
+    );
+    if (!browser) {
+      throw new Error(
+        `Could not connect to ${providerName} browser at ${providerSession.cdpEndpoint}. The remote session was created but CDP connection failed.`,
+      );
+    }
+
+    const contexts = browser.contexts();
+    let page: Page;
+    if (contexts.length > 0 && contexts[0].pages().length > 0) {
+      page = contexts[0].pages()[0];
+    } else {
+      const context =
+        contexts.length > 0 ? contexts[0] : await browser.newContext();
+      page = await context.newPage();
+    }
+
+    await page.goto(url);
+    logger.info("open-provider-navigated", { url, session });
+
+    // Cloud sessions have no local port. Reconnection uses cdpEndpoint directly.
+    writeSessionState(
+      {
+        port: 0,
+        cdpEndpoint: providerSession.cdpEndpoint,
+        session,
+        startedAt: new Date().toISOString(),
+        status: "active",
+        mode: accessMode,
+        provider: {
+          name: providerName,
+          sessionId: providerSession.sessionId,
+        },
+      },
+      logger,
+    );
+
+    disconnectBrowser(browser, logger, session);
+  } catch (err) {
+    if (browser) {
+      disconnectBrowser(browser, logger, session);
+    }
+    // Clean up the remote session so it doesn't leak
+    logger.warn("open-provider-cleanup-after-error", {
+      provider: providerName,
+      sessionId: providerSession.sessionId,
+      error: err,
+    });
+    try {
+      await provider.closeSession(providerSession.sessionId);
+    } catch (cleanupErr) {
+      logger.warn("open-provider-cleanup-failed", {
+        provider: providerName,
+        sessionId: providerSession.sessionId,
+        error: cleanupErr,
+      });
+    }
+    throw err;
+  }
+
+  logger.info("open-provider-success", {
+    url,
+    provider: providerName,
+    session,
+    sessionId: providerSession.sessionId,
+  });
+  console.log(`Browser open (${providerName}): ${url}`);
+}
+
 export async function runSave(
   urlOrDomain: string,
   session: string,
@@ -811,11 +923,37 @@ export async function runClose(
     return;
   }
 
-  logger.info("close-killing", { session, pid: state.pid, port: state.port });
-
-  if (state.pid != null) {
-    sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
-    await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+  if (state.provider) {
+    // Cloud provider session — close via provider API, no local pid to kill
+    logger.info("close-provider", {
+      session,
+      provider: state.provider.name,
+      sessionId: state.provider.sessionId,
+    });
+    try {
+      const provider = getCloudProviderApi(state.provider.name);
+      await provider.closeSession(state.provider.sessionId);
+    } catch (err) {
+      logger.warn("close-provider-error", {
+        session,
+        provider: state.provider.name,
+        sessionId: state.provider.sessionId,
+        error: err,
+      });
+      // Preserve state with cleanup-failed status so the user can retry.
+      // The provider.sessionId is retained for manual or future cleanup.
+      writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+      throw new Error(
+        `Failed to close remote ${state.provider.name} session "${state.provider.sessionId}" for session "${session}". ` +
+          `State preserved with status "cleanup-failed". Retry with: libretto close --session ${session}`,
+      );
+    }
+  } else {
+    logger.info("close-killing", { session, pid: state.pid, port: state.port });
+    if (state.pid != null) {
+      sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
+      await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+    }
   }
 
   clearSessionState(session, logger);
@@ -827,6 +965,7 @@ type ClosableSession = {
   session: string;
   pid?: number;
   port: number;
+  provider?: { name: string; sessionId: string };
 };
 
 function waitForCloseSignalWindow(ms: number): Promise<void> {
@@ -879,6 +1018,7 @@ function resolveClosableSessions(logger: LoggerApi): {
       session,
       pid: state.pid,
       port: state.port,
+      provider: state.provider,
     });
   }
 
@@ -888,9 +1028,11 @@ function resolveClosableSessions(logger: LoggerApi): {
 function clearStoppedSessionStates(
   sessions: ReadonlyArray<ClosableSession>,
   logger: LoggerApi,
+  skip?: ReadonlySet<string>,
 ): number {
   let cleared = 0;
   for (const session of sessions) {
+    if (skip?.has(session.session)) continue;
     if (session.pid == null || !isPidRunning(session.pid)) {
       clearSessionState(session.session, logger);
       cleared += 1;
@@ -916,7 +1058,38 @@ export async function runCloseAll(
     return;
   }
 
+  // Close provider sessions via their APIs
+  const failedProviderSessions = new Set<string>();
+  for (const target of closable) {
+    if (target.provider) {
+      logger.info("close-all-provider", {
+        session: target.session,
+        provider: target.provider.name,
+        sessionId: target.provider.sessionId,
+      });
+      try {
+        const provider = getCloudProviderApi(target.provider.name);
+        await provider.closeSession(target.provider.sessionId);
+      } catch (err) {
+        logger.warn("close-all-provider-error", {
+          session: target.session,
+          provider: target.provider.name,
+          sessionId: target.provider.sessionId,
+          error: err,
+        });
+        failedProviderSessions.add(target.session);
+        // Mark as cleanup-failed, preserving provider.sessionId for retry
+        const state = readSessionState(target.session, logger);
+        if (state) {
+          writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+        }
+      }
+    }
+  }
+
+  // Send SIGTERM to local sessions
   for (const target of closable) {
+    if (target.provider) continue; // already handled above
     logger.info("close-all-sigterm", {
       session: target.session,
       pid: target.pid,
@@ -938,7 +1111,11 @@ export async function runCloseAll(
     (target) => target.pid != null && isPidRunning(target.pid),
   );
   if (survivors.length > 0 && !force) {
-    const closed = clearStoppedSessionStates(closable, logger);
+    const closed = clearStoppedSessionStates(
+      closable,
+      logger,
+      failedProviderSessions,
+    );
 
     throw new Error(
       [
@@ -971,7 +1148,11 @@ export async function runCloseAll(
       (target) => target.pid != null && isPidRunning(target.pid),
     );
     if (survivors.length > 0) {
-      const closed = clearStoppedSessionStates(closable, logger);
+      const closed = clearStoppedSessionStates(
+        closable,
+        logger,
+        failedProviderSessions,
+      );
       throw new Error(
         [
           `Failed to force-close ${survivors.length} session(s): ${formatSessionList(survivors)}.`,
@@ -981,14 +1162,21 @@ export async function runCloseAll(
     }
   }
 
-  clearStoppedSessionStates(closable, logger);
+  clearStoppedSessionStates(closable, logger, failedProviderSessions);
+
+  if (failedProviderSessions.size > 0) {
+    console.log(
+      `Warning: ${failedProviderSessions.size} provider session(s) failed remote cleanup and were preserved with status "cleanup-failed".`,
+    );
+  }
 
   if (clearedUnreadableStates > 0) {
     console.log(
       `Cleared ${clearedUnreadableStates} unreadable session state file(s).`,
     );
   }
-  console.log(`Closed ${closable.length} session(s).`);
+  const closedCount = closable.length - failedProviderSessions.size;
+  console.log(`Closed ${closedCount} session(s).`);
   if (forceKilled > 0) {
     console.log(`Force-killed ${forceKilled} session(s).`);
   }

package/src/cli/core/config.ts

@@ -42,6 +42,7 @@ export const LibrettoConfigSchema = z
     ai: AiConfigSchema.optional(),
     viewport: ViewportConfigSchema.optional(),
     windowPosition: WindowPositionConfigSchema.optional(),
+    provider: z.string().optional(),
     sessionMode: SessionAccessModeSchema.optional(),
   })
   .passthrough();

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

@@ -0,0 +1,57 @@
+import type { ProviderApi } from "./types.js";
+
+export function createBrowserbaseProvider(): ProviderApi {
+  const apiKey = process.env.BROWSERBASE_API_KEY;
+  if (!apiKey)
+    throw new Error(
+      "BROWSERBASE_API_KEY is required for Browserbase provider.",
+    );
+  const projectId = process.env.BROWSERBASE_PROJECT_ID;
+  if (!projectId)
+    throw new Error(
+      "BROWSERBASE_PROJECT_ID is required for Browserbase provider.",
+    );
+  const endpoint =
+    process.env.BROWSERBASE_ENDPOINT ?? "https://api.browserbase.com";
+
+  return {
+    async createSession() {
+      const resp = await fetch(`${endpoint}/v1/sessions`, {
+        method: "POST",
+        headers: {
+          "X-BB-API-Key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ projectId }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Browserbase API error (${resp.status}): ${body}`);
+      }
+      const json = (await resp.json()) as {
+        id: string;
+        connectUrl: string;
+      };
+      return {
+        sessionId: json.id,
+        cdpEndpoint: json.connectUrl,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/v1/sessions/${sessionId}`, {
+        method: "POST",
+        headers: {
+          "X-BB-API-Key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ status: "REQUEST_RELEASE" }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Browserbase API error closing session ${sessionId} (${resp.status}): ${body}`,
+        );
+      }
+    },
+  };
+}

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

@@ -0,0 +1,62 @@
+import { readLibrettoConfig } from "../config.js";
+import { createBrowserbaseProvider } from "./browserbase.js";
+import { createKernelProvider } from "./kernel.js";
+import { createLibrettoCloudProvider } from "./libretto-cloud.js";
+import type { ProviderApi } from "./types.js";
+
+const VALID_PROVIDERS = new Set(["local", "kernel", "browserbase", "libretto-cloud"] as const);
+export type ProviderName =
+  typeof VALID_PROVIDERS extends Set<infer T> ? T : never;
+
+function assertValidProviderName(value: string, source: string): ProviderName {
+  if (!VALID_PROVIDERS.has(value as ProviderName)) {
+    throw new Error(
+      `Invalid provider "${value}" from ${source}. Valid providers: ${[...VALID_PROVIDERS].join(", ")}`,
+    );
+  }
+  return value as ProviderName;
+}
+
+/**
+ * Resolve which provider to use.
+ * Precedence: CLI flag > LIBRETTO_PROVIDER env var > config file > "local" default.
+ */
+export function resolveProviderName(cliFlag?: string): ProviderName {
+  if (cliFlag) {
+    return assertValidProviderName(cliFlag, "--provider flag");
+  }
+
+  const envVar = process.env.LIBRETTO_PROVIDER;
+  if (envVar) {
+    return assertValidProviderName(envVar, "LIBRETTO_PROVIDER env var");
+  }
+
+  const config = readLibrettoConfig();
+  if (config.provider) {
+    return assertValidProviderName(config.provider, "config file");
+  }
+
+  return "local";
+}
+
+/**
+ * Get a ProviderApi instance for a cloud provider.
+ * Only call this for non-"local" providers.
+ */
+export function getCloudProviderApi(name: string): ProviderApi {
+  switch (name) {
+    case "kernel":
+      return createKernelProvider();
+    case "browserbase":
+      return createBrowserbaseProvider();
+    case "libretto-cloud":
+      console.warn(
+        "Note: The libretto-cloud provider is in alpha.",
+      );
+      return createLibrettoCloudProvider();
+    default:
+      throw new Error(
+        `Unknown provider "${name}". Valid cloud providers: kernel, browserbase`,
+      );
+  }
+}

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

@@ -0,0 +1,49 @@
+import type { ProviderApi } from "./types.js";
+
+export function createKernelProvider(): ProviderApi {
+  const apiKey = process.env.KERNEL_API_KEY;
+  if (!apiKey)
+    throw new Error("KERNEL_API_KEY is required for Kernel provider.");
+  const endpoint = process.env.KERNEL_ENDPOINT ?? "https://api.onkernel.com";
+
+  return {
+    async createSession() {
+      const resp = await fetch(`${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 resp.json()) as {
+        session_id: string;
+        cdp_ws_url: string;
+      };
+      return {
+        sessionId: json.session_id,
+        cdpEndpoint: json.cdp_ws_url,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/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}`,
+        );
+      }
+    },
+  };
+}

package/src/cli/core/providers/libretto-cloud.ts

@@ -0,0 +1,61 @@
+import type { ProviderApi } from "./types.js";
+
+export function createLibrettoCloudProvider(): ProviderApi {
+  const apiKey = process.env.LIBRETTO_API_KEY;
+  if (!apiKey)
+    throw new Error(
+      "LIBRETTO_API_KEY is required for the Libretto Cloud provider.",
+    );
+  const apiUrl = process.env.LIBRETTO_API_URL;
+  if (!apiUrl)
+    throw new Error(
+      "LIBRETTO_API_URL is required for the Libretto Cloud provider.",
+    );
+  const endpoint = apiUrl.replace(/\/$/, "");
+
+  return {
+    async createSession() {
+      const timeoutSeconds = Number(
+        process.env.LIBRETTO_TIMEOUT_SECONDS ?? 7200,
+      );
+      const resp = await fetch(`${endpoint}/v1/sessions/create`, {
+        method: "POST",
+        headers: {
+          "x-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ timeout_seconds: timeoutSeconds }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Libretto Cloud API error (${resp.status}): ${body}`,
+        );
+      }
+      const json = (await resp.json()) as {
+        session_id: string;
+        cdp_url: string;
+      };
+      return {
+        sessionId: json.session_id,
+        cdpEndpoint: json.cdp_url,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/v1/sessions/close`, {
+        method: "POST",
+        headers: {
+          "x-api-key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ session_id: sessionId }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`,
+        );
+      }
+    },
+  };
+}

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

@@ -0,0 +1,9 @@
+export type ProviderSession = {
+  sessionId: string; // remote session id for cleanup
+  cdpEndpoint: string; // CDP WebSocket URL
+};
+
+export type ProviderApi = {
+  createSession(): Promise<ProviderSession>;
+  closeSession(sessionId: string): Promise<void>;
+};

package/src/cli/core/session.ts

@@ -129,6 +129,10 @@ export function listRunningSessions(): SessionState[] {
   for (const name of sessions) {
     const state = readSessionState(name);
     if (!state) continue;
+    if (state.provider) {
+      running.push(state);
+      continue;
+    }
     if (state.pid == null || !isPidRunning(state.pid)) continue;
     running.push(state);
   }
@@ -272,6 +276,15 @@ export function assertSessionAvailableForStart(
 ): void {
   const existingState = readSessionState(session, logger);
   if (!existingState) return;
+
+  // Cloud provider sessions have no local PID — treat them as active
+  // if they have a provider field with a cdpEndpoint.
+  if (existingState.provider && existingState.cdpEndpoint) {
+    throw new Error(
+      `Session "${session}" is already open via ${existingState.provider.name} provider. Close it first with: libretto close --session ${session}`,
+    );
+  }
+
   if (existingState.pid == null || !isPidRunning(existingState.pid)) {
     setSessionStatus(session, "exited", logger);
     return;

package/src/cli/workers/run-integration-runtime.ts

@@ -239,6 +239,8 @@ async function runIntegrationInternal(
     storageStatePath,
     viewport: args.viewport,
     accessMode: args.accessMode,
+    cdpEndpoint: args.cdpEndpoint,
+    provider: args.provider,
   });
   if (!args.headless && args.visualize !== false) {
     await installHeadedWorkflowVisualization({

package/src/cli/workers/run-integration-worker-protocol.ts

@@ -10,6 +10,8 @@ export const RunIntegrationWorkerRequestSchema = z.object({
   authProfileDomain: z.string().optional(),
   viewport: z.object({ width: z.number(), height: z.number() }).optional(),
   accessMode: SessionAccessModeSchema.default("write-access"),
+  cdpEndpoint: z.string().optional(),
+  provider: z.object({ name: z.string(), sessionId: z.string() }).optional(),
 });
 
 export type RunIntegrationWorkerRequest = z.infer<

package/src/shared/run/browser.ts

@@ -36,6 +36,8 @@ export type LaunchBrowserArgs = {
   viewport?: { width: number; height: number };
   storageStatePath?: string;
   accessMode?: SessionAccessMode;
+  cdpEndpoint?: string;
+  provider?: { name: string; sessionId: string };
 };
 
 export type BrowserSession = {
@@ -100,7 +102,50 @@ export async function launchBrowser({
   viewport = { width: 1366, height: 768 },
   storageStatePath,
   accessMode = "write-access",
+  cdpEndpoint,
+  provider,
 }: LaunchBrowserArgs): Promise<BrowserSession> {
+  // Cloud/remote mode: connect to an existing CDP endpoint instead of launching locally
+  if (cdpEndpoint) {
+    const browser = await chromium.connectOverCDP(cdpEndpoint);
+    const context =
+      browser.contexts()[0] ?? (await browser.newContext({ viewport }));
+    const page = context.pages()[0] ?? (await context.newPage());
+    page.setDefaultTimeout(30_000);
+    page.setDefaultNavigationTimeout(45_000);
+
+    const metadataPath = ensureLibrettoSessionStatePath(sessionName);
+    writeFileSync(
+      metadataPath,
+      JSON.stringify(
+        {
+          version: SESSION_STATE_VERSION,
+          session: sessionName,
+          port: 0,
+          cdpEndpoint,
+          pid: process.pid,
+          startedAt: new Date().toISOString(),
+          status: "active",
+          mode: accessMode,
+          ...(provider ? { provider } : {}),
+        },
+        null,
+        2,
+      ),
+    );
+
+    return {
+      browser,
+      context,
+      page,
+      debugPort: 0,
+      metadataPath,
+      close: async () => {
+        await browser.close();
+      },
+    };
+  }
+
   const debugPort = await pickFreePort();
   const windowPosition = headless ? undefined : resolveWindowPosition();
   const browser = await chromium.launch({

package/src/shared/state/session-state.ts

@@ -8,6 +8,7 @@ export const SessionStatusSchema = z.enum([
   "completed",
   "failed",
   "exited",
+  "cleanup-failed",
 ]);
 export const SessionAccessModeSchema = z.enum(["read-only", "write-access"]);
 export const SessionViewportSchema = z.object({
@@ -15,6 +16,11 @@ export const SessionViewportSchema = z.object({
   height: z.number().int().min(1),
 });
 
+export const ProviderStateSchema = z.object({
+  name: z.string(),
+  sessionId: z.string(),
+});
+
 export const SessionStateFileSchema = z.object({
   version: z.literal(SESSION_STATE_VERSION),
   port: z.number().int().min(0).max(65535),
@@ -25,6 +31,7 @@ export const SessionStateFileSchema = z.object({
   status: SessionStatusSchema.optional(),
   mode: SessionAccessModeSchema.default("write-access"),
   viewport: SessionViewportSchema.optional(),
+  provider: ProviderStateSchema.optional(),
 });
 
 export type SessionStatus = z.infer<typeof SessionStatusSchema>;