libretto 0.6.11 → 0.6.12

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

@@ -2,6 +2,12 @@ import type { Page } from "playwright";
 import { mkdirSync, writeFileSync } from "node:fs";
 import type { LoggerApi } from "../../../shared/logger/index.js";
 import { getSessionSnapshotRunDir } from "../context.js";
+import {
+  snapshot,
+  type 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,
@@ -12,6 +18,13 @@ import {
 
 const RENDER_SETTLE_TIMEOUT_MS = 10_000;
 
+type SnapshotScreenshot = {
+  pngPath: string;
+  snapshotRunId: string;
+  pageUrl: string;
+  title: string;
+};
+
 export async function handleSnapshot(
   targetPage: Page,
   session: string,
@@ -24,6 +37,98 @@ export async function handleSnapshot(
   pageUrl: string;
   title: string;
 }> {
+  const screenshot = await captureSnapshotScreenshot(
+    targetPage,
+    session,
+    logger,
+    pageId,
+  );
+  const htmlPath = `${getSessionSnapshotRunDir(
+    session,
+    screenshot.snapshotRunId,
+  )}/page.html`;
+
+  // Capture HTML content.
+  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,
+  };
+}
+
+export async function handleCompactSnapshot(
+  targetPage: Page,
+  session: string,
+  logger: LoggerApi,
+  options: {
+    pageId?: string;
+    cachedSnapshot?: Snapshot | null;
+    useCachedSnapshot?: boolean;
+  } = {},
+): Promise<{
+  mode: "compact";
+  pngPath: string;
+  snapshot: Snapshot;
+}> {
+  if (options.useCachedSnapshot) {
+    if (!options.cachedSnapshot) {
+      throw new Error(
+        `No compact snapshot is cached for session "${session}". Run ${librettoCommand(`snapshot --session ${session}`)} first.`,
+      );
+    }
+    const screenshot = await captureSnapshotScreenshot(
+      targetPage,
+      session,
+      logger,
+      options.pageId,
+    );
+    return {
+      mode: "compact",
+      pngPath: screenshot.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: Page,
+  session: string,
+  logger: LoggerApi,
+  pageId?: string,
+): Promise<SnapshotScreenshot> {
   const snapshotRunId = `snapshot-${Date.now()}`;
   const snapshotRunDir = getSessionSnapshotRunDir(session, snapshotRunId);
   mkdirSync(snapshotRunDir, { recursive: true });
@@ -45,7 +150,6 @@ export async function handleSnapshot(
   }
 
   const pngPath = `${snapshotRunDir}/page.png`;
-  const htmlPath = `${snapshotRunDir}/page.html`;
 
   // Wait for network to settle before capturing.
   await Promise.race([
@@ -91,22 +195,16 @@ export async function handleSnapshot(
     await targetPage.screenshot({ path: pngPath });
   }
 
-  // Capture HTML content.
-  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 ?? "",

package/src/cli/core/experiments.ts

@@ -0,0 +1,85 @@
+import {
+  readLibrettoConfig,
+  type LibrettoConfig,
+  writeLibrettoConfig,
+} from "./config.js";
+
+export 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,
+  },
+} as const satisfies Record<
+  string,
+  {
+    title: string;
+    oneSentenceDescription: string;
+    docs?: string;
+    defaultValue: boolean;
+  }
+>;
+
+export type ExperimentName = keyof typeof EXPERIMENTS;
+export type Experiments = Record<ExperimentName, boolean>;
+
+export function isExperimentName(name: string): name is ExperimentName {
+  return Object.hasOwn(EXPERIMENTS, name);
+}
+
+export function resolveExperiments(
+  config: LibrettoConfig = readLibrettoConfig(),
+): Experiments {
+  return Object.fromEntries(
+    Object.entries(EXPERIMENTS).map(([name, metadata]) => [
+      name,
+      config.experiments?.[name] ?? metadata.defaultValue,
+    ]),
+  ) as Experiments;
+}
+
+export function setExperimentEnabled(
+  name: string,
+  enabled: boolean,
+  configPath?: string,
+): Experiments {
+  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);
+}

package/src/cli/core/session.ts

@@ -22,6 +22,7 @@ import {
   type SessionStatus,
   type SessionState,
 } from "../../shared/state/index.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 
 const SESSION_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
 
@@ -154,7 +155,7 @@ function throwSessionNotFoundError(session: string): never {
   }
   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"));
 }
 
@@ -230,7 +231,7 @@ export function assertSessionAllowsCommand(
 
   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.`,
   );
 }
 
@@ -281,7 +282,7 @@ export function assertSessionAvailableForStart(
   // if they have a provider field with a cdpEndpoint.
   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}`)}`,
     );
   }
 
@@ -291,6 +292,6 @@ export function assertSessionAvailableForStart(
   }
   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}`)}`,
   );
 }

package/src/cli/core/skill-version.ts

@@ -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";
 
 type PackageManifest = {
   version?: string;
@@ -85,7 +86,7 @@ export function warnIfInstalledSkillOutOfDate(): void {
     }
 
     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 {
     // Never block command execution on a best-effort skill version check.

package/src/cli/core/snapshot-analyzer.ts

@@ -17,6 +17,7 @@ import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { z } from "zod";
 import type { LoggerApi } from "../../shared/logger/index.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 // Used by the legacy CLI-agent path (UserCodingAgent) which is preserved but
 // not wired into the snapshot command. The active config schema (ai-config.ts)
 // no longer has preset/commandPrefix — this type is kept for the legacy code.
@@ -297,7 +298,7 @@ async function runExternalCommand(
       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;
@@ -830,7 +831,7 @@ export async function runInterpret(
   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.`,
     );
   }
 
@@ -840,7 +841,7 @@ export async function runInterpret(
   // re-enabled, the caller must supply a valid provider/model-id string.
   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>`, " +
+      `Update your config to the current format with \`${librettoCommand("ai configure <provider>")}\`, ` +
       "or set API credentials in .env for direct API analysis.",
   );
 

package/src/cli/core/workflow-runner/runner.ts

@@ -0,0 +1,237 @@
+import type { BrowserContext, Page } from "playwright";
+import type { LoggerApi } from "../../../shared/logger/index.js";
+import { installPauseHandler } from "../../../shared/debug/pause-handler.js";
+import type {
+  ExportedLibrettoWorkflow,
+  LibrettoWorkflowContext,
+} from "../../../shared/workflow/workflow.js";
+import {
+  getAbsoluteIntegrationPath,
+  installHeadedWorkflowVisualization,
+  loadDefaultWorkflow,
+} from "../workflow-runtime.js";
+
+type WorkflowPausedState = {
+  state: "paused";
+  session: string;
+  pausedAt: string;
+  url?: string;
+};
+
+export type WorkflowFinishedArgs =
+  | { result: "completed"; completedAt: string }
+  | { result: "failed"; message: string; phase: "setup" | "workflow" };
+
+type WorkflowFinishedState = {
+  state: "finished";
+} & WorkflowFinishedArgs;
+
+export type WorkflowOutcome = WorkflowPausedState | WorkflowFinishedState;
+
+export type WorkflowStatus =
+  | { state: "idle" }
+  | { state: "running" }
+  | WorkflowOutcome;
+
+type WorkflowLogEvent = {
+  stream: "stdout" | "stderr";
+  text: string;
+};
+
+export type WorkflowControllerConfig = {
+  session: string;
+  headed: boolean;
+  page: Page;
+  context: BrowserContext;
+  logger: LoggerApi;
+  onLog?: (event: WorkflowLogEvent) => void;
+  onOutcome?: (outcome: WorkflowOutcome) => void;
+};
+
+export type WorkflowStartConfig = {
+  integrationPath: string;
+  params?: unknown;
+  visualize?: boolean;
+  loadedWorkflow?: ExportedLibrettoWorkflow;
+};
+
+type PendingPause = {
+  resolve(): void;
+};
+
+type WritableStreamWithWrite = NodeJS.WriteStream & {
+  write: NodeJS.WriteStream["write"];
+};
+
+export class WorkflowController {
+  private status: WorkflowStatus = { state: "idle" };
+  private pendingPause: PendingPause | undefined;
+  private started = false;
+
+  constructor(private readonly config: WorkflowControllerConfig) {}
+
+  start(workflowConfig: WorkflowStartConfig): void {
+    if (this.started) {
+      throw new Error("Workflow controller has already started.");
+    }
+
+    this.started = true;
+    this.status = { state: "running" };
+    void this.run(workflowConfig);
+  }
+
+  pause(args: {
+    session: string;
+    pausedAt: string;
+    url?: string;
+  }): Promise<void> {
+    if (this.pendingPause) {
+      throw new Error("Workflow is already paused.");
+    }
+
+    return new Promise<void>((resolve) => {
+      this.pendingPause = { resolve };
+      this.status = { state: "paused", ...args };
+      this.config.onOutcome?.(this.status);
+    });
+  }
+
+  resume(): void {
+    if (!this.pendingPause) {
+      throw new Error("Workflow is not paused.");
+    }
+
+    const pendingPause = this.pendingPause;
+    this.pendingPause = undefined;
+    this.status = { state: "running" };
+    pendingPause.resolve();
+  }
+
+  getStatus(): WorkflowStatus {
+    return this.status;
+  }
+
+  private async run(workflowConfig: WorkflowStartConfig): Promise<void> {
+    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,
+        });
+      }
+
+      // tsx/esbuild can inject __name() wrappers when keepNames is true.
+      // Playwright serializes callbacks via Function#toString() into the browser
+      // context, which lacks __name, causing ReferenceError without this polyfill.
+      await this.config.context.addInitScript(() => {
+        (globalThis as Record<string, unknown>).__name = (
+          target: unknown,
+          value: string,
+        ) =>
+          Object.defineProperty(target as object, "name", {
+            value,
+            configurable: true,
+          });
+      });
+
+      const workflowContext: LibrettoWorkflowContext = {
+        session: this.config.session,
+        page: this.config.page,
+      };
+
+      const uninstallPauseHandler = installPauseHandler((pauseArgs) =>
+        this.pause({
+          ...pauseArgs,
+          url: this.config.page.isClosed() ? undefined : 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: new Date().toISOString(),
+      });
+    } catch (error) {
+      this.emitOutcome({
+        state: "finished",
+        result: "failed",
+        message: error instanceof Error ? error.message : String(error),
+        phase: "setup",
+      });
+    } finally {
+      restoreOutput();
+    }
+  }
+
+  private emitOutcome(outcome: WorkflowOutcome): void {
+    this.resolvePendingPause();
+    this.status = outcome;
+    this.config.onOutcome?.(outcome);
+  }
+
+  private resolvePendingPause(): void {
+    const pendingPause = this.pendingPause;
+    if (!pendingPause) return;
+
+    this.pendingPause = undefined;
+    pendingPause.resolve();
+  }
+
+  private captureProcessOutput(): () => void {
+    const stdout = process.stdout as WritableStreamWithWrite;
+    const stderr = process.stderr as WritableStreamWithWrite;
+    const originalStdoutWrite = stdout.write;
+    const originalStderrWrite = stderr.write;
+
+    stdout.write = ((...writeArgs: Parameters<typeof stdout.write>) => {
+      const [chunk] = writeArgs;
+      this.config.onLog?.({ stream: "stdout", text: chunkToString(chunk) });
+      return Reflect.apply(originalStdoutWrite, stdout, writeArgs) as boolean;
+    }) as typeof stdout.write;
+
+    stderr.write = ((...writeArgs: Parameters<typeof stderr.write>) => {
+      const [chunk] = writeArgs;
+      this.config.onLog?.({ stream: "stderr", text: chunkToString(chunk) });
+      return Reflect.apply(originalStderrWrite, stderr, writeArgs) as boolean;
+    }) as typeof stderr.write;
+
+    return () => {
+      stdout.write = originalStdoutWrite;
+      stderr.write = originalStderrWrite;
+    };
+  }
+}
+
+function chunkToString(chunk: unknown): string {
+  return Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+}

package/src/cli/core/workflow-runtime.ts

@@ -0,0 +1,85 @@
+import type { BrowserContext } from "playwright";
+import { existsSync } from "node:fs";
+import { cwd } from "node:process";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { instrumentContext } from "../../index.js";
+import {
+  getDefaultWorkflowFromModuleExports,
+  getWorkflowsFromModuleExports,
+  type ExportedLibrettoWorkflow,
+} from "../../shared/workflow/workflow.js";
+import type { LoggerApi } from "../../shared/logger/index.js";
+
+const TSCONFIG_HINT =
+  "TypeScript compilation failed. Pass --tsconfig <path> to run against a specific tsconfig.";
+
+function isTsxCompileError(error: unknown): error is Error {
+  return (
+    error instanceof Error &&
+    (error.name === "TransformError" ||
+      error.message.startsWith("Cannot resolve tsconfig at path:"))
+  );
+}
+
+export function getAbsoluteIntegrationPath(integrationPath: string): string {
+  const absolutePath = isAbsolute(integrationPath)
+    ? integrationPath
+    : resolve(cwd(), integrationPath);
+  if (!existsSync(absolutePath)) {
+    throw new Error(`Integration file does not exist: ${absolutePath}`);
+  }
+  return absolutePath;
+}
+
+export async function loadDefaultWorkflow(
+  absolutePath: string,
+): Promise<ExportedLibrettoWorkflow> {
+  let loadedModule: Record<string, unknown>;
+  try {
+    loadedModule = (await import(pathToFileURL(absolutePath).href)) as Record<
+      string,
+      unknown
+    >;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const compileHint = isTsxCompileError(error)
+      ? `\n${TSCONFIG_HINT}`
+      : absolutePath.endsWith(".ts") || absolutePath.endsWith(".tsx")
+        ? `\n${TSCONFIG_HINT}`
+        : "";
+    throw new Error(
+      `Failed to import integration module at ${absolutePath}: ${message}${compileHint}`,
+    );
+  }
+
+  const defaultWorkflow = getDefaultWorkflowFromModuleExports(loadedModule);
+  if (defaultWorkflow) {
+    return defaultWorkflow;
+  }
+
+  const availableWorkflowNames = getWorkflowsFromModuleExports(loadedModule).map(
+    (candidate) => candidate.name,
+  );
+
+  if (availableWorkflowNames.length === 0) {
+    throw new Error(
+      `No default-exported workflow found in ${absolutePath}. Export the workflow with \`export default workflow("name", handler)\`.`,
+    );
+  }
+
+  throw new Error(
+    `No default-exported workflow found in ${absolutePath}. libretto run only uses the file's default export. Available named workflows: ${availableWorkflowNames.join(", ")}`,
+  );
+}
+
+export async function installHeadedWorkflowVisualization(args: {
+  context: BrowserContext;
+  logger: LoggerApi;
+  instrument?: typeof instrumentContext;
+}): Promise<void> {
+  await (args.instrument ?? instrumentContext)(args.context, {
+    visualize: true,
+    logger: args.logger,
+  });
+}

package/src/cli/router.ts

@@ -4,14 +4,17 @@ import { billingCommands } from "./commands/billing.js";
 import { browserCommands } from "./commands/browser.js";
 import { deployCommand } from "./commands/deploy.js";
 import { executionCommands } from "./commands/execution.js";
+import { experimentsCommand } from "./commands/experiments.js";
 import { setupCommand } from "./commands/setup.js";
 import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
+import { librettoCommand } from "../shared/package-manager.js";
 import { SimpleCLI } from "./framework/simple-cli.js";
 
 export const cliRoutes = {
   ...browserCommands,
   deploy: deployCommand,
+  experiments: experimentsCommand,
   ...executionCommands,
   ai: aiCommands,
   auth: authCommands,
@@ -22,5 +25,5 @@ export const cliRoutes = {
 };
 
 export function createCLIApp() {
-  return SimpleCLI.define("libretto", cliRoutes);
+  return SimpleCLI.define(librettoCommand(), cliRoutes);
 }