libretto 0.6.12 → 0.6.14

package/src/cli/core/daemon/ipc.ts

@@ -3,6 +3,7 @@ import type { ChildProcess } from "node:child_process";
 import { spawn } from "node:child_process";
 import { openSync, closeSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir, userInfo } from "node:os";
 import { fileURLToPath } from "node:url";
 import { createIpcPeer, type IpcPeer } from "../../../shared/ipc/ipc.js";
 import { connectToIpcSocket } from "../../../shared/ipc/socket-transport.js";
@@ -25,9 +26,10 @@ export type DaemonExecArgs = {
 
 export type DaemonReadonlyExecArgs = { code: string; pageId?: string };
 
-export type DaemonSnapshotArgs =
-  | { mode?: "legacy"; pageId?: string; useCachedSnapshot?: false }
-  | { mode: "compact"; pageId?: string; useCachedSnapshot?: boolean };
+export type DaemonSnapshotArgs = {
+  pageId?: string;
+  useCachedSnapshot?: boolean;
+};
 
 export type DaemonExecSuccess = {
   result: unknown;
@@ -35,24 +37,12 @@ export type DaemonExecSuccess = {
   snapshotDiff?: SnapshotDiff;
 };
 
-export type DaemonLegacySnapshotResult = {
-  pngPath: string;
-  htmlPath: string;
-  snapshotRunId: string;
-  pageUrl: string;
-  title: string;
-};
-
-export type DaemonCompactSnapshotResult = {
+export type DaemonSnapshotResult = {
   mode: "compact";
   pngPath: string;
   snapshot: Snapshot;
 };
 
-export type DaemonSnapshotResult =
-  | DaemonLegacySnapshotResult
-  | DaemonCompactSnapshotResult;
-
 export type DaemonCloseResult = { replayUrl?: string };
 
 export type DaemonCommandResult<T> =
@@ -116,6 +106,11 @@ export type DaemonStartupErrorMessage = {
   message: string;
 };
 
+export type DaemonStartupStatusMessage = {
+  type: "startup-status";
+  message: string;
+};
+
 function isDaemonReadyMessage(message: unknown): message is DaemonReadyMessage {
   if (typeof message !== "object" || message === null) return false;
   const candidate = message as { type?: unknown; socketPath?: unknown };
@@ -132,6 +127,16 @@ function isDaemonStartupErrorMessage(
   );
 }
 
+function isDaemonStartupStatusMessage(
+  message: unknown,
+): message is DaemonStartupStatusMessage {
+  if (typeof message !== "object" || message === null) return false;
+  const candidate = message as { type?: unknown; message?: unknown };
+  return (
+    candidate.type === "startup-status" && typeof candidate.message === "string"
+  );
+}
+
 export type DaemonClientSpawnOptions = {
   config: DaemonConfig;
   logger: LoggerApi;
@@ -153,18 +158,43 @@ export type DaemonClientSpawnResult = {
 // ---------------------------------------------------------------------------
 
 /**
- * Deterministic Unix domain socket path for a given session.
+ * Deterministic IPC endpoint for a given session.
+ *
+ * Unix-like platforms use a socket path in `/tmp` to stay well under the macOS
+ * 104-byte Unix socket path limit. Windows uses a named pipe path because
+ * filesystem Unix domain socket paths are not portable there.
  *
- * The path lives in `/tmp` to stay well under the macOS 104-byte Unix socket
- * path limit. The hash combines `REPO_ROOT` and the session name so different
- * repos (or sessions within the same repo) never collide.
+ * The hash combines `REPO_ROOT`, the session name, and a user key so different
+ * repos, sessions, or local users never collide.
  */
-export function getDaemonSocketPath(session: string): string {
+export function getDaemonSocketPath(
+  session: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const userKey = getDaemonUserKey();
   const hash = createHash("sha256")
-    .update(`${REPO_ROOT}:${session}`)
+    .update(`${REPO_ROOT}:${session}:${userKey}`)
     .digest("hex")
     .slice(0, 12);
-  return `/tmp/libretto-${process.getuid!()}-${hash}.sock`;
+
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\libretto-${hash}`;
+  }
+
+  return `/tmp/libretto-${userKey}-${hash}.sock`;
+}
+
+function getDaemonUserKey(): string {
+  if (typeof process.getuid === "function") return String(process.getuid());
+
+  try {
+    const info = userInfo();
+    if (info.username) return info.username;
+  } catch {
+    // Fall back below.
+  }
+
+  return createHash("sha256").update(homedir()).digest("hex").slice(0, 12);
 }
 
 // ---------------------------------------------------------------------------
@@ -268,6 +298,13 @@ export class DaemonClient {
       onExit: (code, signal, ready) => {
         logger.warn("daemon-exit", { code, signal, session, pid, ready });
       },
+      onStatus: (message) => {
+        logger.info("daemon-startup-status", {
+          session,
+          message: message.message,
+        });
+        console.log(message.message);
+      },
     }).catch(async (error: unknown) => {
       try {
         process.kill(pid, "SIGTERM");
@@ -303,6 +340,7 @@ export class DaemonClient {
       signal: NodeJS.Signals | null,
       ready: boolean,
     ) => void;
+    onStatus?: (message: DaemonStartupStatusMessage) => void;
   }): Promise<DaemonReadyMessage> {
     const {
       child,
@@ -313,6 +351,7 @@ export class DaemonClient {
       onReady,
       onSpawnError,
       onExit,
+      onStatus,
     } = args;
 
     return new Promise<DaemonReadyMessage>((resolve, reject) => {
@@ -324,6 +363,8 @@ export class DaemonClient {
         child.off("message", onMessage);
         child.off("error", onError);
         child.off("exit", onChildExit);
+        process.off("SIGINT", onParentSigint);
+        process.off("SIGTERM", onParentSigterm);
       };
 
       const fail = (error: Error): void => {
@@ -338,6 +379,10 @@ export class DaemonClient {
           fail(new Error(message.message));
           return;
         }
+        if (isDaemonStartupStatusMessage(message)) {
+          onStatus?.(message);
+          return;
+        }
         if (!isDaemonReadyMessage(message)) return;
         ready = true;
         cleanup();
@@ -359,9 +404,22 @@ export class DaemonClient {
         fail(formatExitError(code, signal));
       };
 
+      const forwardSignalToChild = (signal: NodeJS.Signals): void => {
+        try {
+          child.kill(signal);
+        } catch {
+          // Child may have already exited.
+        }
+      };
+
+      const onParentSigint = (): void => forwardSignalToChild("SIGINT");
+      const onParentSigterm = (): void => forwardSignalToChild("SIGTERM");
+
       child.on("message", onMessage);
       child.on("error", onError);
       child.on("exit", onChildExit);
+      process.once("SIGINT", onParentSigint);
+      process.once("SIGTERM", onParentSigterm);
     });
   }
 

package/src/cli/core/daemon/snapshot.ts

@@ -1,5 +1,5 @@
 import type { Page } from "playwright";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import type { LoggerApi } from "../../../shared/logger/index.js";
 import { getSessionSnapshotRunDir } from "../context.js";
 import {
@@ -25,48 +25,6 @@ type SnapshotScreenshot = {
   title: string;
 };
 
-export async function handleSnapshot(
-  targetPage: Page,
-  session: string,
-  logger: LoggerApi,
-  pageId?: string,
-): Promise<{
-  pngPath: string;
-  htmlPath: string;
-  snapshotRunId: string;
-  pageUrl: string;
-  title: string;
-}> {
-  const screenshot = await captureSnapshotScreenshot(
-    targetPage,
-    session,
-    logger,
-    pageId,
-  );
-  const htmlPath = `${getSessionSnapshotRunDir(
-    session,
-    screenshot.snapshotRunId,
-  )}/page.html`;
-
-  // Capture HTML content.
-  const htmlContent = await targetPage.content();
-  writeFileSync(htmlPath, htmlContent);
-
-  logger.info("screenshot-success", {
-    session,
-    pageUrl: screenshot.pageUrl,
-    title: screenshot.title,
-    pngPath: screenshot.pngPath,
-    htmlPath,
-    snapshotRunId: screenshot.snapshotRunId,
-  });
-
-  return {
-    ...screenshot,
-    htmlPath,
-  };
-}
-
 export async function handleCompactSnapshot(
   targetPage: Page,
   session: string,

package/src/cli/core/exec-compiler.ts

@@ -19,6 +19,13 @@ const stripTypeScriptTypes = (
   moduleBuiltin as { stripTypeScriptTypes?: StripTypeScriptTypesFn }
 ).stripTypeScriptTypes;
 
+export function stripTypeScriptExecCode(code: string): string {
+  if (!stripTypeScriptTypes) return code;
+  return withSuppressedStripTypeScriptWarning(() =>
+    stripTypeScriptTypes(code, { mode: "strip" }),
+  );
+}
+
 export function withSuppressedStripTypeScriptWarning<T>(action: () => T): T {
   type EmitWarningFn = (...args: unknown[]) => void;
   const mutableProcess = process as unknown as { emitWarning: EmitWarningFn };
@@ -66,9 +73,7 @@ export function compileTypeScriptExecFunction(
   if (!stripTypeScriptTypes) return null;
 
   const wrappedSource = `(async function __librettoExec(${helperNames.join(", ")}) {\n${code}\n})`;
-  const jsSource = withSuppressedStripTypeScriptWarning(() =>
-    stripTypeScriptTypes(wrappedSource, { mode: "strip" }),
-  );
+  const jsSource = stripTypeScriptExecCode(wrappedSource);
   const createFunction = new Function(
     `return ${jsSource}`,
   ) as () => ExecFunction;

package/src/cli/core/experiments.ts

@@ -4,45 +4,16 @@ import {
   writeLibrettoConfig,
 } from "./config.js";
 
-export const EXPERIMENTS = {
-  "compact-snapshot-format": {
-    title: "Compact snapshot format",
-    oneSentenceDescription:
-      "Use compact accessibility snapshots and exec page-change diffs without an AI sub-agent.",
-    docs: [
-      "Compact snapshot format changes how agents should use snapshot and exec after the experiment is enabled.",
-      "",
-      "Compared with the skill's documented behavior:",
-      "  - Run libretto snapshot --session <name> without --objective or --context.",
-      "  - Snapshot output is a screenshot path plus a compact accessibility tree; it does not use the PNG + HTML + AI analysis path.",
-      "  - Run libretto snapshot <ref> --session <name> to inspect a subtree from the latest full compact snapshot.",
-      "  - Run libretto exec normally; after successful mutations, Libretto prints page-change diffs from compact snapshots without AI analysis.",
-      "  - If a session was already open before enabling the experiment, close and reopen it before relying on this behavior.",
-      "",
-      "Full compact snapshot:",
-      "  libretto snapshot --session <name>",
-      "",
-      "Cached subtree snapshot:",
-      "  libretto snapshot <ref> --session <name>",
-      "",
-      "Run an unscoped snapshot before using refs. Subtree snapshots capture a fresh screenshot but reuse the latest cached tree.",
-      "",
-      "Notes:",
-      "  - Use ref forms printed in the tree, such as l16. Numeric-suffix aliases such as e16 also match l16.",
-    ].join("\n"),
-    defaultValue: false,
-  },
-} as const satisfies Record<
-  string,
-  {
-    title: string;
-    oneSentenceDescription: string;
-    docs?: string;
-    defaultValue: boolean;
-  }
->;
+export type ExperimentMetadata = {
+  title: string;
+  oneSentenceDescription: string;
+  docs?: string;
+  defaultValue: boolean;
+};
+
+export const EXPERIMENTS: Readonly<Record<string, ExperimentMetadata>> = {};
 
-export type ExperimentName = keyof typeof EXPERIMENTS;
+export type ExperimentName = string;
 export type Experiments = Record<ExperimentName, boolean>;
 
 export function isExperimentName(name: string): name is ExperimentName {

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

@@ -4,9 +4,16 @@ 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);
+const VALID_PROVIDERS = new Set([
+  "local",
+  "kernel",
+  "browserbase",
+  "libretto-cloud",
+] as const);
 export type ProviderName =
   typeof VALID_PROVIDERS extends Set<infer T> ? T : never;
+const DEFAULT_PROVIDER_STARTUP_TIMEOUT_MS = 60_000;
+const LIBRETTO_CLOUD_STARTUP_TIMEOUT_MS = 10 * 60_000;
 
 function assertValidProviderName(value: string, source: string): ProviderName {
   if (!VALID_PROVIDERS.has(value as ProviderName)) {
@@ -50,9 +57,7 @@ export function getCloudProviderApi(name: string): ProviderApi {
     case "browserbase":
       return createBrowserbaseProvider();
     case "libretto-cloud":
-      console.warn(
-        "Note: The libretto-cloud provider is in alpha.",
-      );
+      console.warn("Note: The libretto-cloud provider is in alpha.");
       return createLibrettoCloudProvider();
     default:
       throw new Error(
@@ -60,3 +65,11 @@ export function getCloudProviderApi(name: string): ProviderApi {
       );
   }
 }
+
+export function getProviderStartupTimeoutMs(
+  providerName: string | undefined,
+): number {
+  return providerName === "libretto-cloud"
+    ? LIBRETTO_CLOUD_STARTUP_TIMEOUT_MS
+    : DEFAULT_PROVIDER_STARTUP_TIMEOUT_MS;
+}

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));
+}