libretto 0.6.13 → 0.6.15

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

@@ -1,14 +1,15 @@
 import type { ProviderApi } from "./types.js";
 
+const KERNEL_API_ENDPOINT = "https://api.onkernel.com";
+
 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`, {
+      const resp = await fetch(`${KERNEL_API_ENDPOINT}/browsers`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${apiKey}`,
@@ -34,7 +35,7 @@ export function createKernelProvider(): ProviderApi {
       };
     },
     async closeSession(sessionId) {
-      const resp = await fetch(`${endpoint}/browsers/${sessionId}`, {
+      const resp = await fetch(`${KERNEL_API_ENDPOINT}/browsers/${sessionId}`, {
         method: "DELETE",
         headers: { Authorization: `Bearer ${apiKey}` },
       });

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

@@ -1,20 +1,33 @@
-import { HOSTED_API_URL } from "../auth-fetch.js";
+import { resolveHostedApiUrl } from "../auth-fetch.js";
 import type { ProviderApi } from "./types.js";
 
+type CloudSessionResponse = {
+  session_id: string;
+  status: string;
+  cdp_url: string | null;
+  live_view_url: string | null;
+  recording_url: string | null;
+};
+
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_BROWSER_SESSION_TIMEOUT_SECONDS = 3_600;
+const QUEUE_WAIT_TIMEOUT_MS = 10 * 60_000;
+
 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 endpoint = HOSTED_API_URL;
+  const endpoint = resolveHostedApiUrl();
 
   // The Libretto Cloud API is an oRPC RPCHandler, not plain REST, so inputs
   // must be wrapped as { json: ... } and outputs arrive the same way.
   return {
     async createSession() {
-      const timeoutSeconds = Number(
-        process.env.LIBRETTO_TIMEOUT_SECONDS ?? 7200,
+      const browserSessionTimeoutSeconds = readPositiveNumberEnv(
+        "LIBRETTO_TIMEOUT_SECONDS",
+        DEFAULT_BROWSER_SESSION_TIMEOUT_SECONDS,
       );
       const resp = await fetch(`${endpoint}/v1/sessions/create`, {
         method: "POST",
@@ -23,48 +36,223 @@ export function createLibrettoCloudProvider(): ProviderApi {
           "Content-Type": "application/json",
         },
         body: JSON.stringify({
-          json: { timeout_seconds: timeoutSeconds },
+          json: { timeout_seconds: browserSessionTimeoutSeconds },
         }),
       });
       if (!resp.ok) {
         const body = await resp.text();
-        throw new Error(
-          `Libretto Cloud API error (${resp.status}): ${body}`,
-        );
+        throw new Error(`Libretto Cloud API error (${resp.status}): ${body}`);
+      }
+      const { json } = (await resp.json()) as { json: CloudSessionResponse };
+      const startupCleanup = createStartupSessionCleanup(
+        endpoint,
+        apiKey,
+        json.session_id,
+      );
+      let readySession: CloudSessionResponse & { cdp_url: string };
+      try {
+        readySession = await waitForCloudSessionReady({
+          endpoint,
+          apiKey,
+          session: json,
+          timeoutMs: QUEUE_WAIT_TIMEOUT_MS,
+          isCancelled: startupCleanup.isCancelled,
+        });
+      } catch (error) {
+        if (startupCleanup.isCancelled()) {
+          await startupCleanup.waitForClose();
+        } else {
+          await closeCloudSession(endpoint, apiKey, json.session_id).catch(
+            () => {},
+          );
+        }
+        throw error;
+      } finally {
+        startupCleanup.dispose();
       }
-      const { json } = (await resp.json()) as {
-        json: {
-          session_id: string;
-          cdp_url: string;
-          live_view_url: string | null;
-          recording_url: string | null;
-        };
-      };
       return {
-        sessionId: json.session_id,
-        cdpEndpoint: json.cdp_url,
-        liveViewUrl: json.live_view_url ?? undefined,
+        sessionId: readySession.session_id,
+        cdpEndpoint: readySession.cdp_url,
+        liveViewUrl: readySession.live_view_url ?? undefined,
       };
     },
     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({ json: { session_id: sessionId } }),
-      });
-      if (!resp.ok) {
-        const body = await resp.text();
-        throw new Error(
-          `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`,
-        );
-      }
-      const { json } = (await resp.json()) as {
-        json: { replay_url: string | null };
-      };
+      const json = await closeCloudSession(endpoint, apiKey, sessionId);
       return { replayUrl: json.replay_url ?? undefined };
     },
   };
 }
+
+async function waitForCloudSessionReady(args: {
+  endpoint: string;
+  apiKey: string;
+  session: CloudSessionResponse;
+  timeoutMs: number;
+  isCancelled?: () => boolean;
+}): Promise<CloudSessionResponse & { cdp_url: string }> {
+  let session = args.session;
+  if (args.isCancelled?.()) {
+    throw new Error(
+      `Libretto Cloud session ${session.session_id} was cancelled before browser capacity was available.`,
+    );
+  }
+  if (session.cdp_url) {
+    return { ...session, cdp_url: session.cdp_url };
+  }
+
+  sendStartupStatus(
+    `Libretto Cloud browser session queued (session: ${session.session_id}). Waiting for browser capacity...`,
+  );
+
+  const pollIntervalMs = readPositiveNumberEnv(
+    "LIBRETTO_CLOUD_SESSION_POLL_INTERVAL_MS",
+    DEFAULT_POLL_INTERVAL_MS,
+  );
+  const deadline = Date.now() + args.timeoutMs;
+
+  while (Date.now() < deadline) {
+    if (args.isCancelled?.()) {
+      throw new Error(
+        `Libretto Cloud session ${session.session_id} was cancelled before browser capacity was available.`,
+      );
+    }
+    await sleep(pollIntervalMs);
+    if (args.isCancelled?.()) {
+      throw new Error(
+        `Libretto Cloud session ${session.session_id} was cancelled before browser capacity was available.`,
+      );
+    }
+    session = await getCloudSession(
+      args.endpoint,
+      args.apiKey,
+      session.session_id,
+    );
+    if (session.cdp_url) {
+      sendStartupStatus(
+        `Libretto Cloud browser capacity available (session: ${session.session_id}). Connecting...`,
+      );
+      return { ...session, cdp_url: session.cdp_url };
+    }
+    if (!["queued", "starting"].includes(session.status)) {
+      throw new Error(
+        `Libretto Cloud session ${session.session_id} entered status "${session.status}" before a CDP URL was available.`,
+      );
+    }
+  }
+
+  throw new Error(
+    `Timed out waiting for Libretto Cloud browser capacity after ${Math.ceil(args.timeoutMs / 1_000)}s (session: ${session.session_id}).`,
+  );
+}
+
+async function getCloudSession(
+  endpoint: string,
+  apiKey: string,
+  sessionId: string,
+): Promise<CloudSessionResponse> {
+  const resp = await fetch(`${endpoint}/v1/sessions/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 session ${sessionId} (${resp.status}): ${body}`,
+    );
+  }
+  const { json } = (await resp.json()) as { json: CloudSessionResponse };
+  return json;
+}
+
+async function closeCloudSession(
+  endpoint: string,
+  apiKey: string,
+  sessionId: string,
+): Promise<{ replay_url: string | null }> {
+  const resp = await fetch(`${endpoint}/v1/sessions/close`, {
+    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 closing session ${sessionId} (${resp.status}): ${body}`,
+    );
+  }
+  const { json } = (await resp.json()) as {
+    json: { replay_url: string | null };
+  };
+  return json;
+}
+
+function createStartupSessionCleanup(
+  endpoint: string,
+  apiKey: string,
+  sessionId: string,
+): {
+  isCancelled: () => boolean;
+  waitForClose: () => Promise<void>;
+  dispose: () => void;
+} {
+  let cancelled = false;
+  let closePromise: Promise<void> | null = null;
+
+  const requestClose = (reason: string): void => {
+    if (cancelled) return;
+    cancelled = true;
+    sendStartupStatus(
+      `Libretto Cloud browser session cancelled (${reason}). Cleaning up queued session...`,
+    );
+    closePromise = closeCloudSession(endpoint, apiKey, sessionId).then(
+      () => {},
+      () => {},
+    );
+  };
+
+  const onDisconnect = (): void => requestClose("parent command disconnected");
+  const onSigint = (): void => requestClose("received SIGINT");
+  const onSigterm = (): void => requestClose("received SIGTERM");
+
+  if (typeof process.send === "function") {
+    process.once("disconnect", onDisconnect);
+  }
+  process.once("SIGINT", onSigint);
+  process.once("SIGTERM", onSigterm);
+
+  return {
+    isCancelled: () => cancelled,
+    waitForClose: async () => {
+      await closePromise;
+    },
+    dispose: () => {
+      process.off("disconnect", onDisconnect);
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+    },
+  };
+}
+
+function readPositiveNumberEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function sendStartupStatus(message: string): void {
+  if (typeof process.send === "function") {
+    process.send({ type: "startup-status", message });
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/cli/router.ts

@@ -8,15 +8,20 @@ import { setupCommand } from "./commands/setup.js";
 import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
 import { librettoCommand } from "../shared/package-manager.js";
-import { SimpleCLI } from "./framework/simple-cli.js";
+import { SimpleCLI } from "affordance";
 
 export const cliRoutes = {
   ...browserCommands,
-  deploy: deployCommand,
+  cloud: SimpleCLI.group({
+    description: "Libretto Cloud commands",
+    routes: {
+      deploy: deployCommand,
+      auth: authCommands,
+      billing: billingCommands,
+    },
+  }),
   experiments: experimentsCommand,
   ...executionCommands,
-  auth: authCommands,
-  billing: billingCommands,
   setup: setupCommand,
   status: statusCommand,
   snapshot: snapshotCommand,

package/src/shared/ipc/socket-transport.spec.ts

@@ -6,6 +6,7 @@ import { expect, test as base } from "vitest";
 import { createIpcPeer, type IpcPeer } from "./ipc.js";
 import {
   connectToIpcSocket,
+  isWindowsNamedPipePath,
   listenForIpcConnections,
 } from "./socket-transport.js";
 
@@ -64,6 +65,11 @@ test("sends concurrent calls over one socket", async ({ socketPath }) => {
   await expect(stat(socketPath)).rejects.toThrow();
 });
 
+test("recognizes Windows named pipe paths", () => {
+  expect(isWindowsNamedPipePath("\\\\.\\pipe\\libretto-abc123")).toBe(true);
+  expect(isWindowsNamedPipePath("/tmp/libretto-501-abc123.sock")).toBe(false);
+});
+
 test("rejects pending calls when the socket closes", async ({ socketPath }) => {
   const serverPeers: Array<IpcPeer<ClientApi>> = [];
   const server = await listenForIpcConnections(socketPath, (transport) => {

package/src/shared/ipc/socket-transport.ts

@@ -1,4 +1,4 @@
-import { rm } from "node:fs/promises";
+import { mkdir, rm } from "node:fs/promises";
 import {
   createServer,
   createConnection,
@@ -6,7 +6,6 @@ import {
   type Socket,
 } from "node:net";
 import { dirname } from "node:path";
-import { mkdir } from "node:fs/promises";
 import type { IpcProtocolMessage, IpcTransport } from "./ipc.js";
 
 function createJsonSocketTransport(
@@ -109,13 +108,12 @@ export async function listenOnIpcSocket(
   server: Server,
   socketPath: string,
 ): Promise<void> {
-  await mkdir(dirname(socketPath), { recursive: true });
-  await rm(socketPath, { force: true });
+  await prepareIpcSocketPath(socketPath);
 
   const originalClose = server.close.bind(server);
   server.close = ((callback?: (error?: Error) => void) => {
     return originalClose((error?: Error) => {
-      void rm(socketPath, { force: true }).finally(() => callback?.(error));
+      void removeStaleSocketFile(socketPath).finally(() => callback?.(error));
     });
   }) as Server["close"];
 
@@ -135,6 +133,23 @@ export async function listenOnIpcSocket(
   });
 }
 
+export function isWindowsNamedPipePath(socketPath: string): boolean {
+  return socketPath.startsWith("\\\\.\\pipe\\");
+}
+
+async function prepareIpcSocketPath(socketPath: string): Promise<void> {
+  if (isWindowsNamedPipePath(socketPath)) return;
+
+  await mkdir(dirname(socketPath), { recursive: true });
+  await removeStaleSocketFile(socketPath);
+}
+
+async function removeStaleSocketFile(socketPath: string): Promise<void> {
+  if (isWindowsNamedPipePath(socketPath)) return;
+
+  await rm(socketPath, { force: true });
+}
+
 async function connectSocket(socketPath: string): Promise<Socket> {
   const socket = createConnection(socketPath);