libretto 0.6.11 → 0.6.13

package/dist/cli/core/daemon/ipc.js

@@ -1,7 +1,21 @@
 import { createHash } from "node:crypto";
-import { createServer, connect as netConnect } from "node:net";
-import { unlink } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { openSync, closeSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { createIpcPeer } from "../../../shared/ipc/ipc.js";
+import { connectToIpcSocket } from "../../../shared/ipc/socket-transport.js";
 import { REPO_ROOT } from "../context.js";
+function createNoopDaemonToCliHandlers() {
+  return {
+    workflowOutput: () => {
+    },
+    workflowPaused: () => {
+    },
+    workflowFinished: () => {
+    }
+  };
+}
 class DaemonClientError extends Error {
   constructor(message, output) {
     super(message);
@@ -9,163 +23,190 @@ class DaemonClientError extends Error {
     this.name = "DaemonClientError";
   }
 }
+function isDaemonReadyMessage(message) {
+  if (typeof message !== "object" || message === null) return false;
+  const candidate = message;
+  return candidate.type === "ready" && typeof candidate.socketPath === "string";
+}
+function isDaemonStartupErrorMessage(message) {
+  if (typeof message !== "object" || message === null) return false;
+  const candidate = message;
+  return candidate.type === "startup-error" && typeof candidate.message === "string";
+}
 function getDaemonSocketPath(session) {
   const hash = createHash("sha256").update(`${REPO_ROOT}:${session}`).digest("hex").slice(0, 12);
   return `/tmp/libretto-${process.getuid()}-${hash}.sock`;
 }
-class DaemonServer {
-  constructor(socketPath, handler) {
-    this.socketPath = socketPath;
-    this.handler = handler;
+class DaemonClient {
+  constructor(ipc) {
+    this.ipc = ipc;
   }
-  server = null;
-  async listen() {
-    try {
-      await unlink(this.socketPath);
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-    }
-    const server = createServer((socket) => {
-      let buffer = "";
-      socket.on("data", (chunk) => {
-        buffer += chunk.toString();
-        const newlineIndex = buffer.indexOf("\n");
-        if (newlineIndex === -1) return;
-        const line = buffer.slice(0, newlineIndex);
-        buffer = buffer.slice(newlineIndex + 1);
-        void (async () => {
-          let response;
-          try {
-            const request = JSON.parse(line);
-            const data = await this.handler(request);
-            response = { id: request.id, type: "result", data };
-          } catch (err) {
-            const id = (() => {
-              try {
-                return JSON.parse(line).id ?? "unknown";
-              } catch {
-                return "unknown";
-              }
-            })();
-            response = {
-              id,
-              type: "error",
-              message: err instanceof Error ? err.message : String(err),
-              output: err instanceof Error ? err.output : void 0
-            };
-          }
-          socket.end(JSON.stringify(response) + "\n");
-        })();
-      });
-    });
-    this.server = server;
-    await new Promise((resolve, reject) => {
-      server.on("error", reject);
-      server.listen(this.socketPath, () => resolve());
-    });
+  static async connect(socketPath, handlers = createNoopDaemonToCliHandlers()) {
+    const transport = await connectToIpcSocket(socketPath);
+    return new DaemonClient(
+      createIpcPeer(transport, handlers)
+    );
   }
-  async close() {
-    const server = this.server;
-    if (!server) return;
-    this.server = null;
-    await new Promise((resolve, reject) => {
-      server.close((err) => err ? reject(err) : resolve());
+  static async spawn(options) {
+    const { config, logger, logPath, startupTimeoutMs, handlers, onFailure } = options;
+    const { session } = config;
+    const daemonEntryPath = fileURLToPath(
+      new URL("./daemon.js", import.meta.url)
+    );
+    const require2 = createRequire(import.meta.url);
+    const tsxCliPath = require2.resolve("tsx/cli");
+    const childStderrFd = openSync(logPath, "a");
+    const child = spawn(
+      process.execPath,
+      [
+        tsxCliPath,
+        ...config.workflow?.tsconfigPath ? ["--tsconfig", config.workflow.tsconfigPath] : [],
+        daemonEntryPath,
+        JSON.stringify(config)
+      ],
+      {
+        detached: true,
+        stdio: ["ignore", "ignore", childStderrFd, "ipc"]
+      }
+    );
+    closeSync(childStderrFd);
+    const pid = child.pid;
+    logger.info("daemon-spawned", { pid, session });
+    const readyMessage = await DaemonClient.waitForReadyMessage({
+      child,
+      timeoutMs: startupTimeoutMs,
+      formatTimeoutError: () => new Error(
+        `Daemon failed to start within ${Math.ceil(startupTimeoutMs / 1e3)}s. Check logs: ${logPath}`
+      ),
+      formatSpawnError: (error) => {
+        const errWithCode = error;
+        const hint = errWithCode.code === "ENOENT" ? " Ensure Node.js is available in PATH for child processes." : "";
+        return new Error(
+          `Failed to spawn daemon: ${error.message}.${hint} Check logs: ${logPath}`
+        );
+      },
+      formatExitError: (code, signal) => {
+        const status = code ?? signal ?? "unknown";
+        return new Error(
+          `Daemon exited before startup (status: ${status}). Check logs: ${logPath}`
+        );
+      },
+      onReady: (message) => {
+        logger.info("daemon-ready", {
+          session,
+          socketPath: message.socketPath,
+          pid
+        });
+        child.disconnect();
+        child.unref();
+      },
+      onSpawnError: (error) => {
+        logger.error("daemon-spawn-error", { error, session });
+      },
+      onExit: (code, signal, ready) => {
+        logger.warn("daemon-exit", { code, signal, session, pid, ready });
+      }
+    }).catch(async (error) => {
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+      }
+      await onFailure?.();
+      throw error;
     });
-    try {
-      await unlink(this.socketPath);
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-    }
-  }
-}
-class DaemonClient {
-  constructor(socketPath) {
-    this.socketPath = socketPath;
+    const client = await DaemonClient.connect(
+      readyMessage.socketPath,
+      handlers
+    );
+    const socketPath = readyMessage.socketPath;
+    logger.info("daemon-ipc-ready", { session, socketPath });
+    return { pid, socketPath, provider: readyMessage.provider, client };
   }
-  async send(request) {
+  static async waitForReadyMessage(args) {
+    const {
+      child,
+      timeoutMs,
+      formatTimeoutError,
+      formatSpawnError,
+      formatExitError,
+      onReady,
+      onSpawnError,
+      onExit
+    } = args;
     return new Promise((resolve, reject) => {
-      const socket = netConnect(this.socketPath);
-      let buffer = "";
-      socket.on("connect", () => {
-        socket.write(JSON.stringify(request) + "\n");
-      });
-      socket.on("data", (chunk) => {
-        buffer += chunk.toString();
-      });
-      socket.on("end", () => {
-        try {
-          const response = JSON.parse(buffer.trim());
-          resolve(response);
-        } catch (err) {
-          reject(
-            new Error(
-              `Failed to parse daemon response: ${err instanceof Error ? err.message : String(err)}`
-            )
-          );
+      let ready = false;
+      let timeout;
+      const cleanup = () => {
+        clearTimeout(timeout);
+        child.off("message", onMessage);
+        child.off("error", onError);
+        child.off("exit", onChildExit);
+      };
+      const fail = (error) => {
+        cleanup();
+        reject(error);
+      };
+      timeout = setTimeout(() => fail(formatTimeoutError()), timeoutMs);
+      const onMessage = (message) => {
+        if (isDaemonStartupErrorMessage(message)) {
+          fail(new Error(message.message));
+          return;
         }
-      });
-      socket.on("error", (err) => {
-        reject(err);
-      });
-    });
-  }
-  generateId() {
-    return Math.random().toString(36).slice(2, 10);
-  }
-  async sendOrThrow(request) {
-    const response = await this.send(request);
-    if (response.type === "error") {
-      throw new DaemonClientError(response.message, response.output);
-    }
-    return response.data;
-  }
-  async sendResult(request) {
-    const response = await this.send(request);
-    if (response.type === "error") {
-      return {
-        ok: false,
-        message: response.message,
-        output: response.output
+        if (!isDaemonReadyMessage(message)) return;
+        ready = true;
+        cleanup();
+        onReady?.(message);
+        resolve(message);
       };
-    }
-    return { ok: true, data: response.data };
+      const onError = (error) => {
+        onSpawnError?.(error);
+        fail(formatSpawnError(error));
+      };
+      const onChildExit = (code, signal) => {
+        onExit?.(code, signal, ready);
+        if (ready) return;
+        fail(formatExitError(code, signal));
+      };
+      child.on("message", onMessage);
+      child.on("error", onError);
+      child.on("exit", onChildExit);
+    });
   }
   async ping() {
     try {
-      await this.sendOrThrow({ id: this.generateId(), command: "ping" });
+      await this.ipc.call.ping();
       return true;
     } catch {
       return false;
     }
   }
   async pages() {
-    return this.sendOrThrow({ id: this.generateId(), command: "pages" });
+    return this.ipc.call.pages();
   }
   async exec(args) {
-    return this.sendResult({
-      id: this.generateId(),
-      command: "exec",
-      ...args
-    });
+    return this.ipc.call.exec(args);
   }
   async readonlyExec(args) {
-    return this.sendResult({
-      id: this.generateId(),
-      command: "readonly-exec",
-      ...args
-    });
+    return this.ipc.call.readonlyExec(args);
   }
   async snapshot(args = {}) {
-    return this.sendOrThrow({
-      id: this.generateId(),
-      command: "snapshot",
-      ...args
-    });
+    return this.ipc.call.snapshot(args);
+  }
+  async getWorkflowStatus() {
+    return this.ipc.call.getWorkflowStatus();
+  }
+  async resumeWorkflow() {
+    await this.ipc.call.resumeWorkflow();
+  }
+  async close() {
+    return this.ipc.call.close();
+  }
+  destroy() {
+    this.ipc.destroy();
   }
 }
 export {
   DaemonClient,
   DaemonClientError,
-  DaemonServer,
   getDaemonSocketPath
 };

package/dist/cli/core/daemon/snapshot.js

@@ -1,5 +1,10 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { getSessionSnapshotRunDir } from "../context.js";
+import {
+  snapshot
+} from "../../../shared/snapshot/capture-snapshot.js";
+import { waitForPageStable } from "../../../shared/snapshot/wait-for-page-stable.js";
+import { librettoCommand } from "../../../shared/package-manager.js";
 import {
   resolveSnapshotViewport,
   readSnapshotViewportMetrics,
@@ -8,7 +13,46 @@ import {
   forceSnapshotViewport
 } from "../../commands/snapshot.js";
 const RENDER_SETTLE_TIMEOUT_MS = 1e4;
-async function handleSnapshot(targetPage, session, logger, pageId) {
+async function handleCompactSnapshot(targetPage, session, logger, options = {}) {
+  if (options.useCachedSnapshot) {
+    if (!options.cachedSnapshot) {
+      throw new Error(
+        `No compact snapshot is cached for session "${session}". Run ${librettoCommand(`snapshot --session ${session}`)} first.`
+      );
+    }
+    const screenshot2 = await captureSnapshotScreenshot(
+      targetPage,
+      session,
+      logger,
+      options.pageId
+    );
+    return {
+      mode: "compact",
+      pngPath: screenshot2.pngPath,
+      snapshot: options.cachedSnapshot
+    };
+  }
+  const waitResult = await waitForPageStable(targetPage);
+  if (!waitResult.ok) {
+    logger.warn("compact-snapshot-stability-wait-incomplete", {
+      session,
+      pageId: options.pageId,
+      diagnostics: waitResult.diagnostics
+    });
+  }
+  const screenshot = await captureSnapshotScreenshot(
+    targetPage,
+    session,
+    logger,
+    options.pageId
+  );
+  return {
+    mode: "compact",
+    pngPath: screenshot.pngPath,
+    snapshot: await snapshot(targetPage)
+  };
+}
+async function captureSnapshotScreenshot(targetPage, session, logger, pageId) {
   const snapshotRunId = `snapshot-${Date.now()}`;
   const snapshotRunDir = getSessionSnapshotRunDir(session, snapshotRunId);
   mkdirSync(snapshotRunDir, { recursive: true });
@@ -25,7 +69,6 @@ async function handleSnapshot(targetPage, session, logger, pageId) {
     logger.warn("screenshot-url-read-failed", { session, pageId, error });
   }
   const pngPath = `${snapshotRunDir}/page.png`;
-  const htmlPath = `${snapshotRunDir}/page.html`;
   await Promise.race([
     targetPage.waitForLoadState("networkidle").catch(() => {
     }),
@@ -63,24 +106,20 @@ async function handleSnapshot(targetPage, session, logger, pageId) {
     );
     await targetPage.screenshot({ path: pngPath });
   }
-  const htmlContent = await targetPage.content();
-  writeFileSync(htmlPath, htmlContent);
-  logger.info("screenshot-success", {
+  logger.info("screenshot-captured", {
     session,
     pageUrl,
     title,
     pngPath,
-    htmlPath,
     snapshotRunId
   });
   return {
     pngPath,
-    htmlPath,
     snapshotRunId,
     pageUrl: pageUrl ?? "",
     title: title ?? ""
   };
 }
 export {
-  handleSnapshot
+  handleCompactSnapshot
 };

package/dist/cli/core/experiments.js

@@ -0,0 +1,39 @@
+import {
+  readLibrettoConfig,
+  writeLibrettoConfig
+} from "./config.js";
+const EXPERIMENTS = {};
+function isExperimentName(name) {
+  return Object.hasOwn(EXPERIMENTS, name);
+}
+function resolveExperiments(config = readLibrettoConfig()) {
+  return Object.fromEntries(
+    Object.entries(EXPERIMENTS).map(([name, metadata]) => [
+      name,
+      config.experiments?.[name] ?? metadata.defaultValue
+    ])
+  );
+}
+function setExperimentEnabled(name, enabled, configPath) {
+  if (!isExperimentName(name)) {
+    throw new Error(`Unknown experiment "${name}".`);
+  }
+  const config = readLibrettoConfig(configPath);
+  const writtenConfig = writeLibrettoConfig(
+    {
+      ...config,
+      experiments: {
+        ...config.experiments,
+        [name]: enabled
+      }
+    },
+    configPath
+  );
+  return resolveExperiments(writtenConfig);
+}
+export {
+  EXPERIMENTS,
+  isExperimentName,
+  resolveExperiments,
+  setExperimentEnabled
+};

package/dist/cli/core/session.js

@@ -18,6 +18,7 @@ import {
   parseSessionStateContent,
   serializeSessionState
 } from "../../shared/state/index.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 const SESSION_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
 const SESSION_DEV_SERVER = "dev-server";
 const SESSION_BROWSER_AGENT = "browser-agent";
@@ -119,7 +120,7 @@ function throwSessionNotFoundError(session) {
   }
   lines.push("");
   lines.push("Start one with:");
-  lines.push(`  libretto open <url> --session ${session}`);
+  lines.push(`  ${librettoCommand(`open <url> --session ${session}`)}`);
   throw new Error(lines.join("\n"));
 }
 function assertSessionStateExistsOrThrow(session) {
@@ -176,7 +177,7 @@ function assertSessionAllowsCommand(state, commandName, allowedModes) {
   }
   const supportedModes = [...allowedModes].join(", ");
   throw new Error(
-    `Command "${commandName}" is blocked for session "${state.session}" because it is in ${mode} mode. Allowed modes for this command: ${supportedModes}. Run \`libretto session-mode write-access --session ${state.session}\` to unlock the session.`
+    `Command "${commandName}" is blocked for session "${state.session}" because it is in ${mode} mode. Allowed modes for this command: ${supportedModes}. Run \`${librettoCommand(`session-mode write-access --session ${state.session}`)}\` to unlock the session.`
   );
 }
 function clearSessionState(session, logger) {
@@ -213,7 +214,7 @@ function assertSessionAvailableForStart(session, logger) {
   if (!existingState) return;
   if (existingState.provider && existingState.cdpEndpoint) {
     throw new Error(
-      `Session "${session}" is already open via ${existingState.provider.name} provider. Close it first with: libretto close --session ${session}`
+      `Session "${session}" is already open via ${existingState.provider.name} provider. Close it first with: ${librettoCommand(`close --session ${session}`)}`
     );
   }
   if (existingState.pid == null || !isPidRunning(existingState.pid)) {
@@ -222,7 +223,7 @@ function assertSessionAvailableForStart(session, logger) {
   }
   const endpoint = `http://127.0.0.1:${existingState.port}`;
   throw new Error(
-    `Session "${session}" is already open and connected to ${endpoint} (pid ${existingState.pid}). Create a new session or close the current one with: libretto close --session ${session}`
+    `Session "${session}" is already open and connected to ${endpoint} (pid ${existingState.pid}). Create a new session or close the current one with: ${librettoCommand(`close --session ${session}`)}`
   );
 }
 export {

package/dist/cli/core/skill-version.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { REPO_ROOT } from "./context.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 const INSTALLED_SKILL_PATHS = [
   [".agents", "skills", "libretto", "SKILL.md"],
   [".claude", "skills", "libretto", "SKILL.md"]
@@ -63,7 +64,7 @@ function warnIfInstalledSkillOutOfDate() {
       return;
     }
     console.error(
-      `Warning: Your agent skill (${mismatch.installedVersion}) is out of date with your Libretto CLI (${mismatch.cliVersion}). Please run \`npx libretto setup\` to update your skills to the correct version.`
+      `Warning: Your agent skill (${mismatch.installedVersion}) is out of date with your Libretto CLI (${mismatch.cliVersion}). Please run \`${librettoCommand("setup")}\` to update your skills to the correct version.`
     );
   } catch {
   }

package/dist/cli/core/workflow-runner/runner.js

@@ -0,0 +1,147 @@
+import { installPauseHandler } from "../../../shared/debug/pause-handler.js";
+import {
+  getAbsoluteIntegrationPath,
+  installHeadedWorkflowVisualization,
+  loadDefaultWorkflow
+} from "../workflow-runtime.js";
+class WorkflowController {
+  constructor(config) {
+    this.config = config;
+  }
+  status = { state: "idle" };
+  pendingPause;
+  started = false;
+  start(workflowConfig) {
+    if (this.started) {
+      throw new Error("Workflow controller has already started.");
+    }
+    this.started = true;
+    this.status = { state: "running" };
+    void this.run(workflowConfig);
+  }
+  pause(args) {
+    if (this.pendingPause) {
+      throw new Error("Workflow is already paused.");
+    }
+    return new Promise((resolve) => {
+      this.pendingPause = { resolve };
+      this.status = { state: "paused", ...args };
+      this.config.onOutcome?.(this.status);
+    });
+  }
+  resume() {
+    if (!this.pendingPause) {
+      throw new Error("Workflow is not paused.");
+    }
+    const pendingPause = this.pendingPause;
+    this.pendingPause = void 0;
+    this.status = { state: "running" };
+    pendingPause.resolve();
+  }
+  getStatus() {
+    return this.status;
+  }
+  async run(workflowConfig) {
+    const restoreOutput = this.captureProcessOutput();
+    try {
+      const absolutePath = getAbsoluteIntegrationPath(
+        workflowConfig.integrationPath
+      );
+      const workflow = workflowConfig.loadedWorkflow ?? await loadDefaultWorkflow(absolutePath);
+      const workflowLogger = this.config.logger.withScope("integration-run", {
+        integrationPath: absolutePath,
+        workflowName: workflow.name,
+        session: this.config.session
+      });
+      console.log(
+        `Running workflow "${workflow.name}" from ${absolutePath} (${this.config.headed ? "headed" : "headless"})...`
+      );
+      if (this.config.headed && workflowConfig.visualize !== false) {
+        await installHeadedWorkflowVisualization({
+          context: this.config.context,
+          logger: workflowLogger
+        });
+      }
+      await this.config.context.addInitScript(() => {
+        globalThis.__name = (target, value) => Object.defineProperty(target, "name", {
+          value,
+          configurable: true
+        });
+      });
+      const workflowContext = {
+        session: this.config.session,
+        page: this.config.page
+      };
+      const uninstallPauseHandler = installPauseHandler(
+        (pauseArgs) => this.pause({
+          ...pauseArgs,
+          url: this.config.page.isClosed() ? void 0 : this.config.page.url()
+        })
+      );
+      try {
+        await workflow.run(workflowContext, workflowConfig.params ?? {});
+      } catch (error) {
+        this.emitOutcome({
+          state: "finished",
+          result: "failed",
+          message: error instanceof Error ? error.message : String(error),
+          phase: "workflow"
+        });
+        return;
+      } finally {
+        uninstallPauseHandler();
+      }
+      this.emitOutcome({
+        state: "finished",
+        result: "completed",
+        completedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (error) {
+      this.emitOutcome({
+        state: "finished",
+        result: "failed",
+        message: error instanceof Error ? error.message : String(error),
+        phase: "setup"
+      });
+    } finally {
+      restoreOutput();
+    }
+  }
+  emitOutcome(outcome) {
+    this.resolvePendingPause();
+    this.status = outcome;
+    this.config.onOutcome?.(outcome);
+  }
+  resolvePendingPause() {
+    const pendingPause = this.pendingPause;
+    if (!pendingPause) return;
+    this.pendingPause = void 0;
+    pendingPause.resolve();
+  }
+  captureProcessOutput() {
+    const stdout = process.stdout;
+    const stderr = process.stderr;
+    const originalStdoutWrite = stdout.write;
+    const originalStderrWrite = stderr.write;
+    stdout.write = ((...writeArgs) => {
+      const [chunk] = writeArgs;
+      this.config.onLog?.({ stream: "stdout", text: chunkToString(chunk) });
+      return Reflect.apply(originalStdoutWrite, stdout, writeArgs);
+    });
+    stderr.write = ((...writeArgs) => {
+      const [chunk] = writeArgs;
+      this.config.onLog?.({ stream: "stderr", text: chunkToString(chunk) });
+      return Reflect.apply(originalStderrWrite, stderr, writeArgs);
+    });
+    return () => {
+      stdout.write = originalStdoutWrite;
+      stderr.write = originalStderrWrite;
+    };
+  }
+}
+function chunkToString(chunk) {
+  return Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+}
+export {
+  WorkflowController
+};