libretto 0.6.11 → 0.6.12

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 { 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,
@@ -9,6 +14,71 @@ import {
 } from "../../commands/snapshot.js";
 const RENDER_SETTLE_TIMEOUT_MS = 1e4;
 async function handleSnapshot(targetPage, session, logger, pageId) {
+  const screenshot = await captureSnapshotScreenshot(
+    targetPage,
+    session,
+    logger,
+    pageId
+  );
+  const htmlPath = `${getSessionSnapshotRunDir(
+    session,
+    screenshot.snapshotRunId
+  )}/page.html`;
+  const htmlContent = await targetPage.content();
+  writeFileSync(htmlPath, htmlContent);
+  logger.info("screenshot-success", {
+    session,
+    pageUrl: screenshot.pageUrl,
+    title: screenshot.title,
+    pngPath: screenshot.pngPath,
+    htmlPath,
+    snapshotRunId: screenshot.snapshotRunId
+  });
+  return {
+    ...screenshot,
+    htmlPath
+  };
+}
+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 +95,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 +132,21 @@ 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 {
+  handleCompactSnapshot,
   handleSnapshot
 };

package/dist/cli/core/experiments.js

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

@@ -3,6 +3,7 @@ import { extname, isAbsolute, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { z } from "zod";
+import { librettoCommand } from "../../shared/package-manager.js";
 const InterpretResultSchema = z.object({
   answer: z.string(),
   selectors: z.array(
@@ -171,7 +172,7 @@ async function runExternalCommand(command, args, logger, stdinText) {
       if (error.code === "ENOENT") {
         reject(
           new Error(
-            `Command not found: ${command}. Configure AI with 'libretto ai configure'.`
+            `Command not found: ${command}. Configure AI with '${librettoCommand("ai configure")}'.`
           )
         );
         return;
@@ -645,12 +646,12 @@ async function runInterpret(args, logger) {
   const configuredAgent = UserCodingAgent.getConfigured();
   if (!configuredAgent) {
     throw new Error(
-      "No AI config set. Run 'npx libretto ai configure codex' (or claude/gemini), or set API credentials in your .env file for direct API analysis."
+      `No AI config set. Run '${librettoCommand("ai configure codex")}' (or claude/gemini), or set API credentials in your .env file for direct API analysis.`
     );
   }
   const configuredAnalyzer = configuredAgent.snapshotAnalyzerConfig;
   throw new Error(
-    "The CLI-agent snapshot analysis path is not active. Update your config to the current format with `npx libretto ai configure <provider>`, or set API credentials in .env for direct API analysis."
+    `The CLI-agent snapshot analysis path is not active. Update your config to the current format with \`${librettoCommand("ai configure <provider>")}\`, or set API credentials in .env for direct API analysis.`
   );
 }
 function canAnalyzeSnapshots() {