libretto 0.6.11 → 0.6.13

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

@@ -25,30 +25,69 @@ import {
   type Page,
 } from "playwright";
 import { mkdir } from "node:fs/promises";
-import { appendFileSync } from "node:fs";
+import { appendFileSync, existsSync, writeFileSync } from "node:fs";
 import { installSessionTelemetry } from "../session-telemetry.js";
+import {
+  createIpcPeer,
+  type IpcPeer,
+  type IpcPeerHandlers,
+} from "../../../shared/ipc/ipc.js";
+import {
+  createIpcSocketServer,
+  listenOnIpcSocket,
+} from "../../../shared/ipc/socket-transport.js";
 import {
   createLoggerForSession,
   getSessionDir,
   getSessionNetworkLogPath,
   getSessionActionsLogPath,
+  getSessionProviderClosePath,
+  getSessionStatePath,
 } from "../context.js";
 import type { LoggerApi } from "../../../shared/logger/index.js";
+import type { ExportedLibrettoWorkflow } from "../../../shared/workflow/workflow.js";
 import {
-  DaemonServer,
   getDaemonSocketPath,
-  type DaemonRequest,
+  type CliToDaemonApi,
+  type DaemonCloseResult,
+  type DaemonExecOutput,
+  type DaemonExecResult,
+  type DaemonToCliApi,
 } from "./ipc.js";
 import { wrapPageForActionLogging } from "../telemetry.js";
+import {
+  getProfilePath,
+  hasProfile,
+  normalizeDomain,
+  normalizeUrl,
+} from "../browser.js";
 import { handlePages } from "./pages.js";
 import { handleExec, handleReadonlyExec } from "./exec.js";
-import { handleSnapshot } from "./snapshot.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";
+import { diffSnapshots } from "../../../shared/snapshot/diff-snapshots.js";
+import {
+  installPageStabilityWaiter,
+  preparePageStabilityWait,
+  waitForPageStable,
+} from "../../../shared/snapshot/wait-for-page-stable.js";
 import {
-  isConnectConfig,
   type DaemonConfig,
-  type DaemonLaunchConfig,
-  type DaemonConnectConfig,
+  type DaemonBrowserLaunchConfig,
+  type DaemonBrowserConnectConfig,
+  type DaemonBrowserProviderConfig,
+  type DaemonWorkflowConfig,
 } from "./config.js";
+import type { Experiments } from "../experiments.js";
+import { getCloudProviderApi } from "../providers/index.js";
+import type { ProviderApi } from "../providers/types.js";
+import {
+  getAbsoluteIntegrationPath,
+  loadDefaultWorkflow,
+} from "../workflow-runtime.js";
+import { WorkflowController } from "../workflow-runner/runner.js";
 
 function isOperationalPage(page: Page): boolean {
   const url = page.url();
@@ -56,6 +95,63 @@ function isOperationalPage(page: Page): boolean {
 }
 
 type TelemetryEntry = Record<string, unknown>;
+type ErrorWithOutput = Error & { output?: DaemonExecOutput };
+type ShutdownOptions = { keepIpcClientsAlive?: boolean };
+type ShutdownHandler = (options: ShutdownOptions) => Promise<void> | void;
+
+async function waitForSessionState(session: string): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  while (Date.now() < deadline) {
+    if (existsSync(getSessionStatePath(session))) return;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(
+    `Session state was not written before workflow start for "${session}".`,
+  );
+}
+
+class UserFacingStartupError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UserFacingStartupError";
+  }
+}
+
+function getMissingLocalAuthProfileError(args: {
+  normalizedDomain: string;
+  profilePath: string;
+  session: string;
+}): string {
+  return [
+    `Local auth profile not found for domain "${args.normalizedDomain}".`,
+    `Expected profile file: ${args.profilePath}`,
+    "To create it:",
+    `  1. libretto open https://${args.normalizedDomain} --headed --session ${args.session}`,
+    "  2. Log in manually in the browser window.",
+    `  3. libretto save ${args.normalizedDomain} --session ${args.session}`,
+  ].join("\n");
+}
+
+function resolveAuthProfileStorageStatePath(args: {
+  authProfileDomain?: string;
+  session: string;
+}): string | undefined {
+  if (!args.authProfileDomain) return undefined;
+  const normalizedDomain = normalizeDomain(
+    normalizeUrl(args.authProfileDomain),
+  );
+  const profilePath = getProfilePath(normalizedDomain);
+  if (!hasProfile(normalizedDomain)) {
+    throw new UserFacingStartupError(
+      getMissingLocalAuthProfileError({
+        normalizedDomain,
+        profilePath,
+        session: args.session,
+      }),
+    );
+  }
+  return profilePath;
+}
 
 // ── BrowserDaemon ──────────────────────────────────────────────────────
 
@@ -66,21 +162,29 @@ class BrowserDaemon {
   readonly logger: LoggerApi;
   private readonly execState: Record<string, unknown> = {};
   private readonly pageById = new Map<string, Page>();
+  private readonly shutdownHandlers: ShutdownHandler[] = [];
+  private readonly connectedClis = new Set<IpcPeer<DaemonToCliApi>>();
+  private workflowController: WorkflowController | undefined;
+  private shutdownPromise: Promise<DaemonCloseResult> | undefined;
+  private readonly latestCompactSnapshotByPage = new WeakMap<Page, Snapshot>();
 
   private constructor(
     private readonly session: string,
+    private readonly experiments: Experiments,
     private readonly externallyManaged: boolean,
     private readonly browser: Browser,
     private readonly context: BrowserContext,
     private readonly page: Page,
-    private readonly ipcServer: DaemonServer,
     logger: LoggerApi,
+    private readonly providerSession?: {
+      provider: ProviderApi;
+      name: string;
+      sessionId: string;
+    },
   ) {
     this.logger = logger.withScope("child");
   }
 
-  private shuttingDown = false;
-
   private trackPage(page: Page): string {
     const id = `page-${Math.random().toString(36).slice(2, 5)}`;
     this.pageById.set(id, page);
@@ -88,6 +192,16 @@ class BrowserDaemon {
     return id;
   }
 
+  private async installCompactSnapshotWaiter(page: Page): Promise<void> {
+    const result = await preparePageStabilityWait(page, { timeoutMs: 1_000 });
+    if (!result.ok) {
+      this.logger.warn("compact-snapshot-waiter-install-incomplete", {
+        session: this.session,
+        diagnostics: result.diagnostics,
+      });
+    }
+  }
+
   // ── Shared initialization ──────────────────────────────────────────
 
   /**
@@ -97,6 +211,7 @@ class BrowserDaemon {
    */
   private static async initialize(args: {
     session: string;
+    experiments: Experiments;
     externallyManaged: boolean;
     browser: Browser;
     context: BrowserContext;
@@ -104,15 +219,29 @@ class BrowserDaemon {
     initialPages: Page[];
     /** If set, navigate to this URL after telemetry but before starting IPC. */
     navigateUrl?: string;
+    readyProvider?: {
+      name: string;
+      sessionId: string;
+      cdpEndpoint: string;
+      liveViewUrl?: string;
+    };
+    providerSession?: {
+      provider: ProviderApi;
+      name: string;
+      sessionId: string;
+    };
   }): Promise<BrowserDaemon> {
     const {
       session,
+      experiments,
       externallyManaged,
       browser,
       context,
       page,
       initialPages,
       navigateUrl,
+      readyProvider,
+      providerSession,
     } = args;
 
     await mkdir(getSessionDir(session), { recursive: true });
@@ -142,21 +271,20 @@ class BrowserDaemon {
       });
     }
 
-    // IPC server — handler is wired after construction to avoid a
-    // circular type inference issue (daemon references itself).
+    await context.addInitScript(installPageStabilityWaiter);
+
+    // IPC server — typed handlers are attached per client connection so one
+    // daemon lifetime can serve multiple CLI invocations.
     const socketPath = getDaemonSocketPath(session);
-    let handler: (request: DaemonRequest) => Promise<unknown>;
-    const ipcServer = new DaemonServer(socketPath, (request) =>
-      handler(request),
-    );
     const daemon = new BrowserDaemon(
       session,
+      experiments,
       externallyManaged,
       browser,
       context,
       page,
-      ipcServer,
       logger,
+      providerSession,
     );
 
     // Action logging and page tracking must be registered before optional
@@ -165,9 +293,15 @@ class BrowserDaemon {
       wrapPageForActionLogging(p, session);
       daemon.trackPage(p);
     }
+    await Promise.all(
+      initialPages.map((initialPage) =>
+        daemon.installCompactSnapshotWaiter(initialPage),
+      ),
+    );
     context.on("page", (newPage) => {
       wrapPageForActionLogging(newPage, session);
       daemon.trackPage(newPage);
+      void daemon.installCompactSnapshotWaiter(newPage);
     });
 
     // Navigate after telemetry is installed (so we capture the initial
@@ -177,8 +311,42 @@ class BrowserDaemon {
       await page.goto(navigateUrl);
     }
 
-    handler = (request) => daemon.handleRequest(request);
-    await ipcServer.listen();
+    const ipcServer = createIpcSocketServer((transport) => {
+      const cli = createIpcPeer<DaemonToCliApi, CliToDaemonApi>(
+        transport,
+        daemon.createIpcHandlers(),
+      );
+      const stopTracking = transport.onClose?.(() => {
+        daemon.connectedClis.delete(cli);
+        stopTracking?.();
+      });
+      daemon.connectedClis.add(cli);
+    });
+    daemon.registerShutdownHandler(async (options) => {
+      if (!options.keepIpcClientsAlive) {
+        for (const cli of daemon.connectedClis) {
+          cli.destroy();
+        }
+        daemon.connectedClis.clear();
+      }
+      if (options.keepIpcClientsAlive) {
+        ipcServer.close((error) => {
+          if (error) {
+            daemon.logger.warn("ipc-server-close-failed", {
+              session,
+              error,
+            });
+          }
+        });
+        return;
+      }
+      await new Promise<void>((resolve, reject) => {
+        ipcServer.close((error) => (error ? reject(error) : resolve()));
+      });
+    });
+
+    await listenOnIpcSocket(ipcServer, socketPath);
+    process.send?.({ type: "ready", socketPath, provider: readyProvider });
     daemon.logger.info("ipc-server-listening", { socketPath });
 
     browser.on("disconnected", () => {
@@ -190,7 +358,13 @@ class BrowserDaemon {
 
   // ── Launch mode ────────────────────────────────────────────────────
 
-  static async launchBrowser(config: DaemonLaunchConfig): Promise<BrowserDaemon> {
+  static async launchBrowser(args: {
+    session: string;
+    experiments: Experiments;
+    browser: DaemonBrowserLaunchConfig;
+    workflow?: DaemonWorkflowConfig;
+  }): Promise<BrowserDaemon> {
+    const { session, browser: config } = args;
     const windowPositionArg = config.windowPosition
       ? `--window-position=${config.windowPosition.x},${config.windowPosition.y}`
       : undefined;
@@ -199,17 +373,24 @@ class BrowserDaemon {
       headless: !config.headed,
       args: [
         "--disable-blink-features=AutomationControlled",
-        `--remote-debugging-port=${config.port}`,
+        ...(config.remoteDebuggingPort
+          ? [`--remote-debugging-port=${config.remoteDebuggingPort}`]
+          : []),
         "--remote-debugging-address=127.0.0.1",
         "--no-focus-on-check",
         ...(windowPositionArg ? [windowPositionArg] : []),
       ],
     });
 
+    const storageStatePath =
+      config.storageStatePath ??
+      resolveAuthProfileStorageStatePath({
+        authProfileDomain: args.workflow?.authProfileDomain,
+        session,
+      });
+
     const context = await browser.newContext({
-      ...(config.storageStatePath
-        ? { storageState: config.storageStatePath }
-        : {}),
+      ...(storageStatePath ? { storageState: storageStatePath } : {}),
       viewport: {
         width: config.viewport.width,
         height: config.viewport.height,
@@ -223,19 +404,20 @@ class BrowserDaemon {
     page.setDefaultNavigationTimeout(45000);
 
     const daemon = await BrowserDaemon.initialize({
-      session: config.session,
+      session,
+      experiments: args.experiments,
       externallyManaged: false,
       browser,
       context,
       page,
       initialPages: [page],
-      navigateUrl: config.url,
+      navigateUrl: config.initialUrl,
     });
 
     daemon.logger.info("child-launched", {
-      port: config.port,
+      port: config.remoteDebuggingPort,
       pid: process.pid,
-      session: config.session,
+      session,
     });
 
     return daemon;
@@ -243,9 +425,12 @@ class BrowserDaemon {
 
   // ── Connect mode ───────────────────────────────────────────────────
 
-  static async connectToEndpoint(
-    config: DaemonConnectConfig,
-  ): Promise<BrowserDaemon> {
+  static async connectToEndpoint(args: {
+    session: string;
+    experiments: Experiments;
+    browser: DaemonBrowserConnectConfig;
+  }): Promise<BrowserDaemon> {
+    const { session, browser: config } = args;
     const browser = await chromium.connectOverCDP(config.cdpEndpoint);
 
     // Discover existing contexts and pages.
@@ -259,47 +444,168 @@ class BrowserDaemon {
         : await context.newPage();
 
     const daemon = await BrowserDaemon.initialize({
-      session: config.session,
+      session,
+      experiments: args.experiments,
       externallyManaged: true,
       browser,
       context,
       page,
-      initialPages:
-        operationalPages.length > 0 ? operationalPages : [page],
-      navigateUrl: config.url,
+      initialPages: operationalPages.length > 0 ? operationalPages : [page],
+      navigateUrl: config.initialUrl,
     });
 
     daemon.logger.info("child-connected", {
       cdpEndpoint: config.cdpEndpoint,
-      url: config.url,
+      url: config.initialUrl,
       pid: process.pid,
-      session: config.session,
+      session,
     });
 
     return daemon;
   }
 
+  static async connectToProvider(args: {
+    session: string;
+    experiments: Experiments;
+    browser: DaemonBrowserProviderConfig;
+  }): Promise<BrowserDaemon> {
+    const { session, browser: config } = args;
+    const provider = getCloudProviderApi(config.providerName);
+    const providerSession = await provider.createSession();
+    try {
+      const browser = await chromium.connectOverCDP(
+        providerSession.cdpEndpoint,
+      );
+
+      const contexts = browser.contexts();
+      const context =
+        contexts.length > 0 ? contexts[0] : await browser.newContext();
+      const operationalPages = context.pages().filter(isOperationalPage);
+      const page =
+        operationalPages.length > 0
+          ? operationalPages[operationalPages.length - 1]
+          : await context.newPage();
+
+      const daemon = await BrowserDaemon.initialize({
+        session,
+        experiments: args.experiments,
+        externallyManaged: true,
+        browser,
+        context,
+        page,
+        initialPages: operationalPages.length > 0 ? operationalPages : [page],
+        navigateUrl: config.initialUrl,
+        readyProvider: {
+          name: config.providerName,
+          sessionId: providerSession.sessionId,
+          cdpEndpoint: providerSession.cdpEndpoint,
+          liveViewUrl: providerSession.liveViewUrl,
+        },
+        providerSession: {
+          provider,
+          name: config.providerName,
+          sessionId: providerSession.sessionId,
+        },
+      });
+
+      daemon.logger.info("child-provider-connected", {
+        provider: config.providerName,
+        sessionId: providerSession.sessionId,
+        url: config.initialUrl,
+        pid: process.pid,
+        session,
+      });
+
+      return daemon;
+    } catch (error) {
+      await provider.closeSession(providerSession.sessionId);
+      throw error;
+    }
+  }
+
   // ── Lifecycle ──────────────────────────────────────────────────────
 
-  async shutdown(reason: string, closeBrowser: boolean): Promise<void> {
-    if (this.shuttingDown) return;
-    this.shuttingDown = true;
-    this.logger.info(reason, { session: this.session });
-    await this.ipcServer.close();
-    if (!closeBrowser) return;
-    if (this.externallyManaged) {
-      // Drop the CDP pipe without killing the external browser.
-      try {
-        (
-          this.browser as unknown as {
-            _connection?: { close(): void };
+  registerShutdownHandler(handler: ShutdownHandler): void {
+    this.shutdownHandlers.push(handler);
+  }
+
+  shutdown(
+    reason: string,
+    closeBrowser: boolean,
+    options: ShutdownOptions = {},
+  ): Promise<DaemonCloseResult> {
+    if (this.shutdownPromise) return this.shutdownPromise;
+    this.shutdownPromise = this.performShutdown(reason, closeBrowser, options);
+    return this.shutdownPromise;
+  }
+
+  private async performShutdown(
+    reason: string,
+    closeBrowser: boolean,
+    options: ShutdownOptions,
+  ): Promise<DaemonCloseResult> {
+    let replayUrl: string | undefined;
+    try {
+      this.logger.info(reason, { session: this.session });
+      for (const handler of this.shutdownHandlers) {
+        await handler(options);
+      }
+      if (closeBrowser) {
+        if (this.externallyManaged) {
+          // Playwright does not expose a public "detach from this CDP browser"
+          // API. Closing the private connection lets the daemon's event loop
+          // drain without asking Playwright to close the externally managed
+          // browser/provider session itself.
+          try {
+            (
+              this.browser as unknown as {
+                _connection?: { close(): void };
+              }
+            )._connection?.close();
+          } catch {
+            // Connection may already be closed.
           }
-        )._connection?.close();
-      } catch {
-        // Connection may already be closed.
+        } else {
+          await this.browser.close();
+        }
+      }
+      if (this.providerSession) {
+        const result = await this.providerSession.provider.closeSession(
+          this.providerSession.sessionId,
+        );
+        replayUrl = result.replayUrl;
+        if (result.replayUrl) {
+          this.logger.info("provider-recording", {
+            session: this.session,
+            provider: this.providerSession.name,
+            sessionId: this.providerSession.sessionId,
+            replayUrl: result.replayUrl,
+          });
+        }
+        writeFileSync(
+          getSessionProviderClosePath(this.session),
+          JSON.stringify(
+            {
+              provider: this.providerSession.name,
+              sessionId: this.providerSession.sessionId,
+              replayUrl: result.replayUrl,
+            },
+            null,
+            2,
+          ),
+          "utf8",
+        );
+      }
+      return replayUrl ? { replayUrl } : {};
+    } finally {
+      if (options.keepIpcClientsAlive) {
+        setImmediate(() => {
+          for (const cli of this.connectedClis) {
+            cli.destroy();
+          }
+          this.connectedClis.clear();
+        });
       }
-    } else {
-      await this.browser.close();
     }
   }
 
@@ -307,82 +613,245 @@ class BrowserDaemon {
 
   private resolveTargetPage(pageId?: string): Page {
     if (!pageId) {
-      if (this.pageById.size > 1) {
+      if (this.page.isClosed()) {
+        const openPages = Array.from(this.pageById.values());
+        if (openPages.length === 1) return openPages[0];
         throw new Error(
-          `Multiple pages are open in session "${this.session}". Pass --page <id> to target a page (run "libretto pages --session ${this.session}" to list ids).`,
+          `The primary page for session "${this.session}" is closed. Run "${librettoCommand(`pages --session ${this.session}`)}" to choose a page id.`,
         );
       }
-      // Return the single tracked page rather than `this.page` — the
-      // initial page may have been closed and replaced by a new one.
-      if (this.pageById.size === 1) {
-        return this.pageById.values().next().value!;
-      }
       return this.page;
     }
     const page = this.pageById.get(pageId);
     if (!page) {
       throw new Error(
-        `Page "${pageId}" was not found in session "${this.session}". Run "libretto pages --session ${this.session}" to list ids.`,
+        `Page "${pageId}" was not found in session "${this.session}". Run "${librettoCommand(`pages --session ${this.session}`)}" to list ids.`,
       );
     }
     return page;
   }
 
-  // ── IPC handler ────────────────────────────────────────────────────
+  // ── IPC handlers ───────────────────────────────────────────────────
+
+  private createIpcHandlers(): IpcPeerHandlers<CliToDaemonApi> {
+    return {
+      ping: () => ({ protocolVersion: PROTOCOL_VERSION }),
+      pages: () =>
+        this.withRequestTimeout(() => handlePages(this.pageById, this.page)),
+      exec: (args) => this.runExec(args),
+      readonlyExec: (args) => this.runReadonlyExec(args),
+      snapshot: (args) => this.runSnapshot(args),
+      getWorkflowStatus: () => this.getWorkflowStatus(),
+      resumeWorkflow: () => this.resumeWorkflow(),
+      close: () =>
+        this.shutdown("ipc-close", true, {
+          keepIpcClientsAlive: true,
+        }),
+    };
+  }
 
-  private async handleRequest(request: DaemonRequest): Promise<unknown> {
-    if (request.command === "ping") {
-      return { protocolVersion: PROTOCOL_VERSION };
+  private async runSnapshot(
+    args: Parameters<CliToDaemonApi["snapshot"]>[0],
+  ): Promise<ReturnType<CliToDaemonApi["snapshot"]>> {
+    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;
+  }
 
+  private async withRequestTimeout<T>(
+    operation: () => Promise<T> | T,
+  ): Promise<T> {
     // All non-ping commands get a timeout guard. The timer is cleared
     // when the command settles to avoid orphaned timers that would
     // keep the event loop alive after shutdown.
-    let timerId: ReturnType<typeof setTimeout>;
-    return Promise.race([
-      this.dispatchCommand(request).finally(() => clearTimeout(timerId)),
-      new Promise<never>((_resolve, reject) => {
-        timerId = setTimeout(
-          () =>
-            reject(
-              new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`),
-            ),
-          REQUEST_TIMEOUT_MS,
-        );
-      }),
-    ]);
+    let timerId: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      timerId = setTimeout(
+        () =>
+          reject(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`)),
+        REQUEST_TIMEOUT_MS,
+      );
+    });
+
+    try {
+      return await Promise.race([operation(), timeout]);
+    } finally {
+      if (timerId) clearTimeout(timerId);
+    }
   }
 
-  private async dispatchCommand(request: DaemonRequest): Promise<unknown> {
-    switch (request.command) {
-      case "pages":
-        return handlePages(this.pageById, this.page);
-      case "exec":
-        return handleExec(
-          this.resolveTargetPage(request.pageId),
-          request.code,
+  private async runExec(
+    args: Parameters<CliToDaemonApi["exec"]>[0],
+  ): Promise<DaemonExecResult> {
+    return this.runCompactExec(args);
+  }
+
+  private async runCompactExec(
+    args: Parameters<CliToDaemonApi["exec"]>[0],
+  ): Promise<DaemonExecResult> {
+    let targetPage: Page | undefined;
+    try {
+      targetPage = this.resolveTargetPage(args.pageId);
+      const page = targetPage;
+      const data = await this.withRequestTimeout(async () => {
+        const before =
+          this.latestCompactSnapshotByPage.get(page) ?? (await snapshot(page));
+        const result = await handleExec(
+          page,
+          args.code,
           this.context,
           this.browser,
           this.execState,
           this.session,
-          request.visualize,
+          args.visualize,
         );
-      case "readonly-exec":
-        return handleReadonlyExec(
-          this.resolveTargetPage(request.pageId),
-          request.code,
-        );
-      case "snapshot":
-        return handleSnapshot(
-          this.resolveTargetPage(request.pageId),
-          this.session,
-          this.logger,
-          request.pageId,
-        );
-      default:
-        throw new Error(
-          `Unknown command: ${(request as { command: string }).command}`,
+
+        try {
+          const waitResult = await waitForPageStable(page);
+          if (!waitResult.ok) {
+            this.logger.warn("compact-exec-stability-wait-incomplete", {
+              session: this.session,
+              pageId: args.pageId,
+              diagnostics: waitResult.diagnostics,
+            });
+          }
+
+          const after = await snapshot(page);
+          const snapshotDiff = diffSnapshots(before, after);
+          this.latestCompactSnapshotByPage.set(page, after);
+          return { ...result, snapshotDiff };
+        } catch (error) {
+          this.latestCompactSnapshotByPage.delete(page);
+          this.logger.warn("compact-exec-diff-failed", {
+            session: this.session,
+            pageId: args.pageId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+          return result;
+        }
+      });
+      return { ok: true, data };
+    } catch (error) {
+      if (targetPage) this.latestCompactSnapshotByPage.delete(targetPage);
+      return this.createExecErrorResult(error);
+    }
+  }
+
+  private async runReadonlyExec(
+    args: Parameters<CliToDaemonApi["readonlyExec"]>[0],
+  ): Promise<DaemonExecResult> {
+    try {
+      const data = await this.withRequestTimeout(() =>
+        handleReadonlyExec(this.resolveTargetPage(args.pageId), args.code),
+      );
+      return { ok: true, data };
+    } catch (error) {
+      return this.createExecErrorResult(error);
+    }
+  }
+
+  private createExecErrorResult(error: unknown): DaemonExecResult {
+    return {
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+      output:
+        error instanceof Error ? (error as ErrorWithOutput).output : undefined,
+    };
+  }
+
+  startWorkflow(args: {
+    workflow: DaemonWorkflowConfig;
+    headed: boolean;
+    loadedWorkflow?: ExportedLibrettoWorkflow;
+  }): void {
+    if (this.workflowController) {
+      throw new Error("Workflow controller has already started.");
+    }
+
+    this.workflowController = new WorkflowController({
+      session: this.session,
+      headed: args.headed,
+      page: this.page,
+      context: this.context,
+      logger: this.logger,
+      onLog: (event) => {
+        void this.broadcast("workflowOutput", event);
+      },
+      onOutcome: (outcome) => {
+        if (outcome.state === "paused") {
+          void this.broadcast("workflowPaused", {
+            pausedAt: outcome.pausedAt,
+            url: outcome.url,
+          });
+          return;
+        }
+        void this.broadcast(
+          "workflowFinished",
+          outcome.result === "completed"
+            ? { result: "completed", completedAt: outcome.completedAt }
+            : {
+                result: "failed",
+                message: outcome.message,
+                phase: outcome.phase,
+              },
         );
+      },
+    });
+    this.workflowController.start({
+      integrationPath: args.workflow.integrationPath,
+      params: args.workflow.params,
+      visualize: args.workflow.visualize,
+      loadedWorkflow: args.loadedWorkflow,
+    });
+  }
+
+  getWorkflowStatus(): ReturnType<WorkflowController["getStatus"]> {
+    return this.workflowController?.getStatus() ?? { state: "idle" };
+  }
+
+  resumeWorkflow(): void {
+    if (!this.workflowController) {
+      throw new Error("Workflow is not paused.");
+    }
+    this.workflowController.resume();
+  }
+
+  async broadcast<Name extends keyof DaemonToCliApi>(
+    name: Name,
+    message: Parameters<DaemonToCliApi[Name]>[0],
+  ): Promise<void> {
+    const results = await Promise.allSettled(
+      Array.from(this.connectedClis, (cli) => {
+        const call = cli.call[name] as (
+          message: Parameters<DaemonToCliApi[Name]>[0],
+        ) => Promise<void>;
+        return call(message);
+      }),
+    );
+    for (const result of results) {
+      if (result.status === "rejected") {
+        this.logger.warn("workflow-event-failed", {
+          event: name,
+          error:
+            result.reason instanceof Error
+              ? result.reason.message
+              : String(result.reason),
+        });
+      }
     }
   }
 }
@@ -391,10 +860,65 @@ class BrowserDaemon {
 
 async function main(): Promise<void> {
   const config = JSON.parse(process.argv[2]) as DaemonConfig;
+  const headed =
+    config.browser.kind === "launch" ? config.browser.headed : false;
 
-  const daemon = isConnectConfig(config)
-    ? await BrowserDaemon.connectToEndpoint(config)
-    : await BrowserDaemon.launchBrowser(config);
+  let loadedWorkflow: ExportedLibrettoWorkflow | undefined;
+  if (config.workflow) {
+    try {
+      loadedWorkflow = await loadDefaultWorkflow(
+        getAbsoluteIntegrationPath(config.workflow.integrationPath),
+      );
+    } catch (error) {
+      throw new UserFacingStartupError(
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
+  const daemon =
+    config.browser.kind === "provider"
+      ? await BrowserDaemon.connectToProvider({
+          session: config.session,
+          experiments: config.experiments,
+          browser: config.browser,
+        })
+      : config.browser.kind === "connect"
+        ? await BrowserDaemon.connectToEndpoint({
+            session: config.session,
+            experiments: config.experiments,
+            browser: config.browser,
+          })
+        : await BrowserDaemon.launchBrowser({
+            session: config.session,
+            experiments: config.experiments,
+            browser: config.browser,
+            workflow: config.workflow,
+          });
+
+  if (config.workflow) {
+    void waitForSessionState(config.session)
+      .then(() =>
+        daemon.startWorkflow({
+          workflow: config.workflow!,
+          headed,
+          loadedWorkflow,
+        }),
+      )
+      .catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        daemon.logger.error("workflow-failed", {
+          error: message,
+        });
+        return daemon
+          .broadcast("workflowFinished", {
+            result: "failed" as const,
+            message,
+            phase: "setup" as const,
+          })
+          .finally(() => daemon.shutdown("workflow-start-failed", true));
+      });
+  }
 
   process.on("SIGTERM", () => {
     void daemon.shutdown("child-sigterm", true);
@@ -426,4 +950,18 @@ async function main(): Promise<void> {
   // letting the process exit naturally.
 }
 
-await main();
+function reportStartupError(error: unknown): never {
+  if (error instanceof UserFacingStartupError) {
+    process.send?.({
+      type: "startup-error",
+      message: error.message,
+    });
+  }
+  process.exit(1);
+}
+
+try {
+  await main();
+} catch (error) {
+  reportStartupError(error);
+}