libretto 0.6.12 → 0.6.14

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

@@ -63,7 +63,8 @@ import {
 } from "../browser.js";
 import { handlePages } from "./pages.js";
 import { handleExec, handleReadonlyExec } from "./exec.js";
-import { handleCompactSnapshot, handleSnapshot } from "./snapshot.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";
 import { snapshot } from "../../../shared/snapshot/capture-snapshot.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 });
@@ -271,9 +278,7 @@ class BrowserDaemon {
       });
     }
 
-    if (experiments["compact-snapshot-format"]) {
-      await context.addInitScript(installPageStabilityWaiter);
-    }
+    await context.addInitScript(installPageStabilityWaiter);
 
     // IPC server — typed handlers are attached per client connection so one
     // daemon lifetime can serve multiple CLI invocations.
@@ -295,19 +300,15 @@ class BrowserDaemon {
       wrapPageForActionLogging(p, session);
       daemon.trackPage(p);
     }
-    if (experiments["compact-snapshot-format"]) {
-      await Promise.all(
-        initialPages.map((initialPage) =>
-          daemon.installCompactSnapshotWaiter(initialPage),
-        ),
-      );
-    }
+    await Promise.all(
+      initialPages.map((initialPage) =>
+        daemon.installCompactSnapshotWaiter(initialPage),
+      ),
+    );
     context.on("page", (newPage) => {
       wrapPageForActionLogging(newPage, session);
       daemon.trackPage(newPage);
-      if (experiments["compact-snapshot-format"]) {
-        void daemon.installCompactSnapshotWaiter(newPage);
-      }
+      void daemon.installCompactSnapshotWaiter(newPage);
     });
 
     // Navigate after telemetry is installed (so we capture the initial
@@ -352,6 +353,7 @@ class BrowserDaemon {
     });
 
     await listenOnIpcSocket(ipcServer, socketPath);
+    beforeReady?.();
     process.send?.({ type: "ready", socketPath, provider: readyProvider });
     daemon.logger.info("ipc-server-listening", { socketPath });
 
@@ -477,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,
       );
@@ -512,6 +519,7 @@ class BrowserDaemon {
           name: config.providerName,
           sessionId: providerSession.sessionId,
         },
+        beforeReady: startupCleanup.dispose,
       });
 
       daemon.logger.info("child-provider-connected", {
@@ -524,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;
     }
   }
@@ -659,40 +670,23 @@ class BrowserDaemon {
   private async runSnapshot(
     args: Parameters<CliToDaemonApi["snapshot"]>[0],
   ): Promise<ReturnType<CliToDaemonApi["snapshot"]>> {
-    if (args.mode === "compact") {
-      if (!this.experiments["compact-snapshot-format"]) {
-        throw new Error(
-          `The compact-snapshot-format experiment is not enabled for session "${this.session}". ` +
-            `Close and reopen the session after running ${librettoCommand("experiments enable compact-snapshot-format")}.`,
-        );
-      }
-      const targetPage = this.resolveTargetPage(args.pageId);
-      const result = await this.withRequestTimeout(() =>
-        handleCompactSnapshot(
-          targetPage,
-          this.session,
-          this.logger,
-          {
-            pageId: args.pageId,
-            cachedSnapshot: this.latestCompactSnapshotByPage.get(targetPage),
-            useCachedSnapshot: args.useCachedSnapshot,
-          },
-        ),
-      );
-      if (!args.useCachedSnapshot) {
-        this.latestCompactSnapshotByPage.set(targetPage, result.snapshot);
-      }
-      return result;
-    }
-
-    return this.withRequestTimeout(() =>
-      handleSnapshot(
-        this.resolveTargetPage(args.pageId),
+    const targetPage = this.resolveTargetPage(args.pageId);
+    const result = await this.withRequestTimeout(() =>
+      handleCompactSnapshot(
+        targetPage,
         this.session,
         this.logger,
-        args.pageId,
+        {
+          pageId: args.pageId,
+          cachedSnapshot: this.latestCompactSnapshotByPage.get(targetPage),
+          useCachedSnapshot: args.useCachedSnapshot,
+        },
       ),
     );
+    if (!args.useCachedSnapshot) {
+      this.latestCompactSnapshotByPage.set(targetPage, result.snapshot);
+    }
+    return result;
   }
 
   private async withRequestTimeout<T>(
@@ -720,26 +714,7 @@ class BrowserDaemon {
   private async runExec(
     args: Parameters<CliToDaemonApi["exec"]>[0],
   ): Promise<DaemonExecResult> {
-    if (this.experiments["compact-snapshot-format"]) {
-      return this.runCompactExec(args);
-    }
-
-    try {
-      const data = await this.withRequestTimeout(() =>
-        handleExec(
-          this.resolveTargetPage(args.pageId),
-          args.code,
-          this.context,
-          this.browser,
-          this.execState,
-          this.session,
-          args.visualize,
-        ),
-      );
-      return { ok: true, data };
-    } catch (error) {
-      return this.createExecErrorResult(error);
-    }
+    return this.runCompactExec(args);
   }
 
   private async runCompactExec(
@@ -755,10 +730,7 @@ class BrowserDaemon {
         const result = await handleExec(
           page,
           args.code,
-          this.context,
-          this.browser,
-          this.execState,
-          this.session,
+          this.execRepl,
           args.visualize,
         );
 
@@ -831,17 +803,17 @@ class BrowserDaemon {
       context: this.context,
       logger: this.logger,
       onLog: (event) => {
-        this.broadcast("workflowOutput", event);
+        void this.broadcast("workflowOutput", event);
       },
       onOutcome: (outcome) => {
         if (outcome.state === "paused") {
-          this.broadcast("workflowPaused", {
+          void this.broadcast("workflowPaused", {
             pausedAt: outcome.pausedAt,
             url: outcome.url,
           });
           return;
         }
-        this.broadcast(
+        void this.broadcast(
           "workflowFinished",
           outcome.result === "completed"
             ? { result: "completed", completedAt: outcome.completedAt }
@@ -898,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> {
@@ -999,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);
+  });
+});