libretto 0.6.13 → 0.6.15

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

@@ -63,6 +63,7 @@ import {
 } from "../browser.js";
 import { handlePages } from "./pages.js";
 import { handleExec, handleReadonlyExec } from "./exec.js";
+import { DaemonExecRepl } from "./exec-repl.js";
 import { handleCompactSnapshot } from "./snapshot.js";
 import { librettoCommand } from "../../../shared/package-manager.js";
 import type { Snapshot } from "../../../shared/snapshot/types.js";
@@ -82,7 +83,7 @@ import {
 } from "./config.js";
 import type { Experiments } from "../experiments.js";
 import { getCloudProviderApi } from "../providers/index.js";
-import type { ProviderApi } from "../providers/types.js";
+import type { ProviderApi, ProviderSession } from "../providers/types.js";
 import {
   getAbsoluteIntegrationPath,
   loadDefaultWorkflow,
@@ -160,7 +161,7 @@ const REQUEST_TIMEOUT_MS = 60_000;
 
 class BrowserDaemon {
   readonly logger: LoggerApi;
-  private readonly execState: Record<string, unknown> = {};
+  private readonly execRepl: DaemonExecRepl;
   private readonly pageById = new Map<string, Page>();
   private readonly shutdownHandlers: ShutdownHandler[] = [];
   private readonly connectedClis = new Set<IpcPeer<DaemonToCliApi>>();
@@ -183,6 +184,10 @@ class BrowserDaemon {
     },
   ) {
     this.logger = logger.withScope("child");
+    this.execRepl = new DaemonExecRepl({
+      browser: this.browser,
+      context: this.context,
+    });
   }
 
   private trackPage(page: Page): string {
@@ -230,6 +235,7 @@ class BrowserDaemon {
       name: string;
       sessionId: string;
     };
+    beforeReady?: () => void;
   }): Promise<BrowserDaemon> {
     const {
       session,
@@ -242,6 +248,7 @@ class BrowserDaemon {
       navigateUrl,
       readyProvider,
       providerSession,
+      beforeReady,
     } = args;
 
     await mkdir(getSessionDir(session), { recursive: true });
@@ -346,6 +353,7 @@ class BrowserDaemon {
     });
 
     await listenOnIpcSocket(ipcServer, socketPath);
+    beforeReady?.();
     process.send?.({ type: "ready", socketPath, provider: readyProvider });
     daemon.logger.info("ipc-server-listening", { socketPath });
 
@@ -471,8 +479,13 @@ class BrowserDaemon {
   }): Promise<BrowserDaemon> {
     const { session, browser: config } = args;
     const provider = getCloudProviderApi(config.providerName);
-    const providerSession = await provider.createSession();
+    let providerSession: ProviderSession | undefined;
+    const startupCleanup = createProviderStartupCleanup({
+      provider,
+      getProviderSession: () => providerSession,
+    });
     try {
+      providerSession = await provider.createSession();
       const browser = await chromium.connectOverCDP(
         providerSession.cdpEndpoint,
       );
@@ -506,6 +519,7 @@ class BrowserDaemon {
           name: config.providerName,
           sessionId: providerSession.sessionId,
         },
+        beforeReady: startupCleanup.dispose,
       });
 
       daemon.logger.info("child-provider-connected", {
@@ -518,7 +532,10 @@ class BrowserDaemon {
 
       return daemon;
     } catch (error) {
-      await provider.closeSession(providerSession.sessionId);
+      startupCleanup.dispose();
+      if (providerSession) {
+        await provider.closeSession(providerSession.sessionId);
+      }
       throw error;
     }
   }
@@ -713,10 +730,7 @@ class BrowserDaemon {
         const result = await handleExec(
           page,
           args.code,
-          this.context,
-          this.browser,
-          this.execState,
-          this.session,
+          this.execRepl,
           args.visualize,
         );
 
@@ -856,6 +870,62 @@ class BrowserDaemon {
   }
 }
 
+function createProviderStartupCleanup(args: {
+  provider: ProviderApi;
+  getProviderSession: () => ProviderSession | undefined;
+}): { dispose: () => void } {
+  let disposed = false;
+  let fallbackExit: NodeJS.Timeout | undefined;
+
+  const requestClose = (reason: string): void => {
+    if (disposed) return;
+    disposed = true;
+    // Startup cancellation should preserve the signal-style exit code even if
+    // provider.createSession() later rejects through the normal startup path.
+    process.exitCode = reason === "received SIGINT" ? 130 : 1;
+    const providerSession = args.getProviderSession();
+    if (!providerSession) {
+      // If cancellation lands while createSession() is still awaiting provider
+      // capacity, provider-specific signal handlers may still need a tick to
+      // close a queued session id that this daemon has not received yet.
+      fallbackExit = setTimeout(() => {
+        process.exit(process.exitCode);
+      }, 5_000);
+      fallbackExit.unref();
+      return;
+    }
+
+    void args.provider
+      .closeSession(providerSession.sessionId)
+      .catch(() => {})
+      .finally(() => {
+        process.exit(reason === "received SIGINT" ? 130 : 1);
+      });
+  };
+
+  const onDisconnect = (): void => requestClose("parent command disconnected");
+  const onSigint = (): void => requestClose("received SIGINT");
+  const onSigterm = (): void => requestClose("received SIGTERM");
+
+  // These handlers only cover the pre-ready window. Once the daemon is ready,
+  // normal shutdown owns provider cleanup through BrowserDaemon.shutdown().
+  if (typeof process.send === "function") {
+    process.once("disconnect", onDisconnect);
+  }
+  process.once("SIGINT", onSigint);
+  process.once("SIGTERM", onSigterm);
+
+  return {
+    dispose: () => {
+      disposed = true;
+      if (fallbackExit) clearTimeout(fallbackExit);
+      process.off("disconnect", onDisconnect);
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+    },
+  };
+}
+
 // ── Main ───────────────────────────────────────────────────────────────
 
 async function main(): Promise<void> {
@@ -957,7 +1027,9 @@ function reportStartupError(error: unknown): never {
       message: error.message,
     });
   }
-  process.exit(1);
+  process.exit(
+    process.exitCode && process.exitCode !== 0 ? process.exitCode : 1,
+  );
 }
 
 try {

package/src/cli/core/daemon/exec-repl.ts

@@ -0,0 +1,189 @@
+import * as repl from "node:repl";
+import { PassThrough } from "node:stream";
+import { format, formatWithOptions, type InspectOptions } from "node:util";
+import { stripTypeScriptExecCode } from "../exec-compiler.js";
+
+const PROMPT = "__LIBRETTO_EXEC_REPL_READY__";
+const TOP_LEVEL_RETURN_HINT =
+  "Hint: top-level return isn't supported because exec is a REPL-style environment. Use the expression value instead, for example: await page.title()";
+const NO_RESULT = Symbol("NO_RESULT");
+
+type ReplOutput = {
+  stdout: string;
+  stderr: string;
+};
+
+export type DaemonExecReplResult = {
+  ok: true;
+  result: unknown;
+  output: ReplOutput;
+};
+
+export type DaemonExecReplFailure = {
+  ok: false;
+  error: Error;
+  output: ReplOutput;
+};
+
+export type DaemonExecReplResponse = DaemonExecReplResult | DaemonExecReplFailure;
+
+type ActiveEval = {
+  output: string;
+  consoleOutput: ReplOutput;
+  resolve: (value: DaemonExecReplResponse) => void;
+};
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof error.message === "string"
+  ) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function isTopLevelReturnError(error: unknown): boolean {
+  const message = getErrorMessage(error);
+  return (
+    message.includes("Illegal return statement") ||
+    message.includes("Return statement is not allowed here")
+  );
+}
+
+function isErrorLike(value: unknown): boolean {
+  return (
+    value instanceof Error ||
+    (typeof value === "object" &&
+      value !== null &&
+      "name" in value &&
+      "message" in value &&
+      typeof value.name === "string" &&
+      typeof value.message === "string")
+  );
+}
+
+function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(getErrorMessage(value));
+}
+
+function appendTopLevelReturnHint(error: unknown): Error {
+  const message = getErrorMessage(error);
+  if (message.includes(TOP_LEVEL_RETURN_HINT)) {
+    return error instanceof Error ? error : new Error(message);
+  }
+  return new SyntaxError(`${message}\n\n${TOP_LEVEL_RETURN_HINT}`);
+}
+
+function createBufferedConsole(): { console: Console; output: ReplOutput } {
+  const output: ReplOutput = { stdout: "", stderr: "" };
+  const writeStdout = (...args: unknown[]) => {
+    output.stdout += `${format(...args)}\n`;
+  };
+  const writeStderr = (...args: unknown[]) => {
+    output.stderr += `${format(...args)}\n`;
+  };
+
+  const bufferedConsole = {
+    ...globalThis.console,
+    log: writeStdout,
+    info: writeStdout,
+    debug: writeStdout,
+    dir: (value?: unknown, options?: InspectOptions) => {
+      output.stdout += `${formatWithOptions(options ?? {}, value)}\n`;
+    },
+    warn: writeStderr,
+    error: writeStderr,
+  } satisfies Console;
+
+  return { console: bufferedConsole, output };
+}
+
+export class DaemonExecRepl {
+  private readonly replServer: repl.REPLServer;
+  private readonly input = new PassThrough();
+  private readonly output = new PassThrough();
+  private readyResolve: (() => void) | undefined;
+  private readonly ready: Promise<void>;
+  private activeEval: ActiveEval | undefined;
+  private lastResult: unknown = NO_RESULT;
+
+  constructor(globals: Record<string, unknown>) {
+    this.ready = new Promise((resolve) => {
+      this.readyResolve = resolve;
+    });
+    this.output.on("data", (chunk: Buffer | string) => {
+      this.handleOutput(String(chunk));
+    });
+    this.replServer = repl.start({
+      prompt: PROMPT,
+      input: this.input,
+      output: this.output,
+      terminal: true,
+      useGlobal: false,
+      writer: (value: unknown) => {
+        this.lastResult = value;
+        return "";
+      },
+    });
+    Object.assign(this.replServer.context, globals);
+  }
+
+  async run(
+    code: string,
+    globals: Record<string, unknown>,
+  ): Promise<DaemonExecReplResponse> {
+    Object.assign(this.replServer.context, globals);
+
+    let jsCode: string;
+    try {
+      jsCode = stripTypeScriptExecCode(code);
+    } catch (error) {
+      return {
+        ok: false,
+        error: isTopLevelReturnError(error)
+          ? appendTopLevelReturnHint(error)
+          : toError(error),
+        output: { stdout: "", stderr: "" },
+      };
+    }
+
+    await this.ready;
+    const buffered = createBufferedConsole();
+    Object.assign(this.replServer.context, { console: buffered.console });
+    return await new Promise<DaemonExecReplResponse>((resolve) => {
+      this.activeEval = { output: "", consoleOutput: buffered.output, resolve };
+      this.lastResult = NO_RESULT;
+      this.input.write(`.editor\n${jsCode}\n\x04`);
+    });
+  }
+
+  private handleOutput(chunk: string): void {
+    const active = this.activeEval;
+    if (!active) {
+      if (chunk.includes(PROMPT)) {
+        this.readyResolve?.();
+        this.readyResolve = undefined;
+      }
+      return;
+    }
+
+    active.output += chunk;
+    if (!active.output.includes(PROMPT)) return;
+
+    this.activeEval = undefined;
+    const result = this.lastResult === NO_RESULT ? undefined : this.lastResult;
+    const output = active.consoleOutput;
+    if (isErrorLike(result)) {
+      const error = isTopLevelReturnError(result)
+        ? appendTopLevelReturnHint(result)
+        : toError(result);
+      active.resolve({ ok: false, error, output });
+      return;
+    }
+    active.resolve({ ok: true, result, output });
+  }
+}

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

@@ -1,9 +1,9 @@
-import type { Browser, BrowserContext, Page } from "playwright";
+import type { Page } from "playwright";
 import { format, formatWithOptions, type InspectOptions } from "node:util";
 import { installInstrumentation } from "../../../shared/instrumentation/index.js";
 import { compileExecFunction } from "../exec-compiler.js";
 import { createReadonlyExecHelpers } from "../readonly-exec.js";
-import { readNetworkLog, readActionLog } from "../telemetry.js";
+import type { DaemonExecRepl } from "./exec-repl.js";
 
 type ExecOutput = {
   stdout: string;
@@ -52,58 +52,23 @@ function createBufferedConsole(): { console: Console; output: ExecOutput } {
 export async function handleExec(
   targetPage: Page,
   code: string,
-  context: BrowserContext,
-  browser: Browser,
-  execState: Record<string, unknown>,
-  session: string,
+  execRepl: DaemonExecRepl,
   visualize?: boolean,
 ): Promise<ExecResponse> {
-  const buffered = createBufferedConsole();
-
   if (visualize) {
     await installInstrumentation(targetPage, { visualize: true });
   }
 
-  const networkLog = (
-    opts: {
-      last?: number;
-      filter?: string;
-      method?: string;
-      pageId?: string;
-    } = {},
-  ) => readNetworkLog(session, opts);
-
-  const actionLog = (
-    opts: {
-      last?: number;
-      filter?: string;
-      action?: string;
-      source?: string;
-      pageId?: string;
-    } = {},
-  ) => readActionLog(session, opts);
-
   const helpers = {
     page: targetPage,
-    context,
-    browser,
-    state: execState,
-    console: buffered.console,
-    networkLog,
-    actionLog,
+    frame: targetPage.mainFrame(),
   };
 
-  const helperNames = Object.keys(helpers);
-  const fn = compileExecFunction(code, helperNames);
-  try {
-    const result = await fn(...Object.values(helpers));
-    return { result, output: buffered.output };
-  } catch (error) {
-    throw new DaemonExecError(
-      error instanceof Error ? error.message : String(error),
-      buffered.output,
-    );
+  const result = await execRepl.run(code, helpers);
+  if (!result.ok) {
+    throw new DaemonExecError(result.error.message, result.output);
   }
+  return { result: result.result, output: result.output };
 }
 
 export async function handleReadonlyExec(

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

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "vitest";
+import { getDaemonSocketPath } from "./ipc.js";
+
+describe("daemon IPC endpoint paths", () => {
+  test("uses a Windows named pipe path on Windows", () => {
+    const socketPath = getDaemonSocketPath("windows-session", "win32");
+
+    expect(socketPath).toMatch(/^\\\\\.\\pipe\\libretto-[a-f0-9]{12}$/);
+    expect(socketPath).not.toContain("/tmp/");
+    expect(socketPath).not.toContain(".sock");
+  });
+
+  test("uses a short Unix socket path on Unix-like platforms", () => {
+    const socketPath = getDaemonSocketPath("unix-session", "linux");
+
+    expect(socketPath).toMatch(/^\/tmp\/libretto-.+-[a-f0-9]{12}\.sock$/);
+  });
+
+  test("keeps daemon IPC endpoints deterministic per session", () => {
+    const firstPath = getDaemonSocketPath("stable-session", "linux");
+    const secondPath = getDaemonSocketPath("stable-session", "linux");
+    const otherPath = getDaemonSocketPath("other-session", "linux");
+
+    expect(secondPath).toBe(firstPath);
+    expect(otherPath).not.toBe(firstPath);
+  });
+});

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";
@@ -105,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 };
@@ -121,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;
@@ -142,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);
 }
 
 // ---------------------------------------------------------------------------
@@ -257,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");
@@ -292,6 +340,7 @@ export class DaemonClient {
       signal: NodeJS.Signals | null,
       ready: boolean,
     ) => void;
+    onStatus?: (message: DaemonStartupStatusMessage) => void;
   }): Promise<DaemonReadyMessage> {
     const {
       child,
@@ -302,6 +351,7 @@ export class DaemonClient {
       onReady,
       onSpawnError,
       onExit,
+      onStatus,
     } = args;
 
     return new Promise<DaemonReadyMessage>((resolve, reject) => {
@@ -313,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 => {
@@ -327,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();
@@ -348,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/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/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;
+}