libretto 0.6.11 → 0.6.12

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
+};

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

@@ -0,0 +1,60 @@
+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
+} from "../../shared/workflow/workflow.js";
+const TSCONFIG_HINT = "TypeScript compilation failed. Pass --tsconfig <path> to run against a specific tsconfig.";
+function isTsxCompileError(error) {
+  return error instanceof Error && (error.name === "TransformError" || error.message.startsWith("Cannot resolve tsconfig at path:"));
+}
+function getAbsoluteIntegrationPath(integrationPath) {
+  const absolutePath = isAbsolute(integrationPath) ? integrationPath : resolve(cwd(), integrationPath);
+  if (!existsSync(absolutePath)) {
+    throw new Error(`Integration file does not exist: ${absolutePath}`);
+  }
+  return absolutePath;
+}
+async function loadDefaultWorkflow(absolutePath) {
+  let loadedModule;
+  try {
+    loadedModule = await import(pathToFileURL(absolutePath).href);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const compileHint = isTsxCompileError(error) ? `
+${TSCONFIG_HINT}` : absolutePath.endsWith(".ts") || absolutePath.endsWith(".tsx") ? `
+${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(", ")}`
+  );
+}
+async function installHeadedWorkflowVisualization(args) {
+  await (args.instrument ?? instrumentContext)(args.context, {
+    visualize: true,
+    logger: args.logger
+  });
+}
+export {
+  getAbsoluteIntegrationPath,
+  installHeadedWorkflowVisualization,
+  loadDefaultWorkflow
+};

package/dist/cli/router.js

@@ -4,13 +4,16 @@ 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";
 const cliRoutes = {
   ...browserCommands,
   deploy: deployCommand,
+  experiments: experimentsCommand,
   ...executionCommands,
   ai: aiCommands,
   auth: authCommands,
@@ -20,7 +23,7 @@ const cliRoutes = {
   snapshot: snapshotCommand
 };
 function createCLIApp() {
-  return SimpleCLI.define("libretto", cliRoutes);
+  return SimpleCLI.define(librettoCommand(), cliRoutes);
 }
 export {
   cliRoutes,

package/dist/shared/debug/pause-handler.d.ts

@@ -0,0 +1,9 @@
+type ActivePauseHandler = (args: {
+    session: string;
+    pausedAt: string;
+    url?: string;
+}) => Promise<void>;
+declare function installPauseHandler(handler: ActivePauseHandler): () => void;
+declare function getActivePauseHandler(): ActivePauseHandler | undefined;
+
+export { type ActivePauseHandler, getActivePauseHandler, installPauseHandler };

package/dist/shared/debug/pause-handler.js

@@ -0,0 +1,15 @@
+let activePauseHandler;
+function installPauseHandler(handler) {
+  const previousHandler = activePauseHandler;
+  activePauseHandler = handler;
+  return () => {
+    activePauseHandler = previousHandler;
+  };
+}
+function getActivePauseHandler() {
+  return activePauseHandler;
+}
+export {
+  getActivePauseHandler,
+  installPauseHandler
+};

package/dist/shared/debug/pause.d.ts

@@ -2,8 +2,7 @@
  * Standalone pause function.
  *
  * - In production (`NODE_ENV === "production"`), returns immediately (no-op).
- * - Otherwise, writes a `.paused` signal file and polls for a `.resume` signal,
- *   using the same file-based mechanism as the CLI runner.
+ * - Otherwise, delegates to the active Libretto workflow runtime pause handler.
  *
  * Import directly: `import { pause } from "libretto";`
  */

package/dist/shared/debug/pause.js

@@ -1,21 +1,9 @@
-import { existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
-import { getSessionDir } from "../../cli/core/context.js";
-import {
-  getPauseSignalPaths,
-  removeSignalIfExists
-} from "../../cli/core/pause-signals.js";
-import { listRunningSessions } from "../../cli/core/session.js";
+import { getActivePauseHandler } from "./pause-handler.js";
+import { librettoCommand } from "../package-manager.js";
 function throwMissingSessionError() {
-  const runningSessions = listRunningSessions();
-  const lines = ["pause(session) requires a non-empty session ID."];
-  if (runningSessions.length > 0) {
-    lines.push("", "Running sessions:");
-    for (const s of runningSessions) {
-      lines.push(`  ${s.session}`);
-    }
-  }
-  throw new Error(lines.join("\n"));
+  throw new Error(
+    `pause(session) requires a non-empty session ID. Pass ctx.session from inside your workflow: await pause(ctx.session). To list running sessions, run: ${librettoCommand("status")}.`
+  );
 }
 async function pause(session) {
   if (process.env.NODE_ENV === "production") {
@@ -24,27 +12,16 @@ async function pause(session) {
   if (typeof session !== "string" || session.trim().length === 0) {
     throwMissingSessionError();
   }
-  const signalPaths = getPauseSignalPaths(session);
-  const { pausedSignalPath, resumeSignalPath } = signalPaths;
-  await mkdir(getSessionDir(session), { recursive: true });
-  await removeSignalIfExists(resumeSignalPath);
-  const details = {
-    sessionName: session,
-    pausedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    url: "unknown"
-  };
-  await writeFile(pausedSignalPath, JSON.stringify(details, null, 2), "utf8");
-  console.log(`[pause] Paused (session: ${session})`);
-  console.log("[pause] Waiting for resume signal...");
-  const RESUME_POLL_INTERVAL_MS = 250;
-  while (!existsSync(resumeSignalPath)) {
-    await new Promise(
-      (resolve) => setTimeout(resolve, RESUME_POLL_INTERVAL_MS)
+  const handler = getActivePauseHandler();
+  if (!handler) {
+    throw new Error(
+      `pause(session) can only suspend an active Libretto workflow. Run the workflow with ${librettoCommand("run <integrationFile>")} and call pause(ctx.session) from inside the workflow.`
     );
   }
-  await removeSignalIfExists(resumeSignalPath);
-  await removeSignalIfExists(pausedSignalPath);
-  console.log("[pause] Resume signal received. Continuing workflow...");
+  await handler({
+    session,
+    pausedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
 }
 export {
   pause

package/dist/shared/ipc/child-process-transport.d.ts

@@ -0,0 +1,7 @@
+import { ChildProcess } from 'node:child_process';
+import { IpcTransport, IpcProtocolMessage } from './ipc.js';
+
+declare function createChildProcessIpcTransport(child: ChildProcess): IpcTransport<IpcProtocolMessage>;
+declare function createParentProcessIpcTransport(): IpcTransport<IpcProtocolMessage>;
+
+export { createChildProcessIpcTransport, createParentProcessIpcTransport };

package/dist/shared/ipc/child-process-transport.js

@@ -0,0 +1,60 @@
+function createChildProcessIpcTransport(child) {
+  return createProcessIpcTransport(child, () => {
+    if (child.connected) child.disconnect();
+  });
+}
+function createParentProcessIpcTransport() {
+  if (!process.send) {
+    throw new Error(
+      "Cannot create child-process IPC transport: process.send is not available. Start the process with an IPC channel."
+    );
+  }
+  return createProcessIpcTransport(process, () => {
+    if (process.connected) process.disconnect?.();
+  });
+}
+function createProcessIpcTransport(target, close) {
+  return {
+    send(message) {
+      if (!target.send) {
+        throw new Error(
+          "Cannot send IPC message: process IPC channel is closed."
+        );
+      }
+      target.send(message);
+    },
+    listen(callback) {
+      const onMessage = (message) => {
+        if (isIpcProtocolMessage(message)) callback(message);
+      };
+      target.on("message", onMessage);
+      return () => target.off("message", onMessage);
+    },
+    onClose(callback) {
+      const onDisconnect = () => callback();
+      target.on("disconnect", onDisconnect);
+      return () => target.off("disconnect", onDisconnect);
+    },
+    close
+  };
+}
+function isIpcProtocolMessage(message) {
+  if (!isRecord(message)) return false;
+  if (message.type === "ipc-request") {
+    return typeof message.id === "string" && typeof message.method === "string" && Array.isArray(message.args);
+  }
+  if (message.type === "ipc-response") {
+    return typeof message.id === "string" && typeof message.method === "string" && (message.error === void 0 || isSerializedError(message.error));
+  }
+  return false;
+}
+function isSerializedError(value) {
+  return isRecord(value) && typeof value.name === "string" && typeof value.message === "string" && (value.stack === void 0 || typeof value.stack === "string");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export {
+  createChildProcessIpcTransport,
+  createParentProcessIpcTransport
+};

package/dist/shared/ipc/child-process-transport.spec.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/shared/ipc/child-process-transport.spec.js

@@ -0,0 +1,68 @@
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { expect, test } from "vitest";
+import { createIpcPeer } from "./ipc.js";
+import { createChildProcessIpcTransport } from "./child-process-transport.js";
+const execFileAsync = promisify(execFile);
+test("throws a clear error without a child-process IPC channel", async () => {
+  const modulePath = fileURLToPath(
+    new URL("./child-process-transport.ts", import.meta.url)
+  );
+  await expect(
+    execFileAsync(
+      process.execPath,
+      [
+        "--import",
+        "tsx",
+        "-e",
+        `import { createParentProcessIpcTransport } from ${JSON.stringify(modulePath)}; createParentProcessIpcTransport();`
+      ],
+      { cwd: process.cwd() }
+    )
+  ).rejects.toMatchObject({
+    stderr: expect.stringContaining("process.send is not available")
+  });
+});
+test("lets parent and child process call each other", async () => {
+  const child = spawn(
+    process.execPath,
+    ["--import", "tsx", "--input-type=module", "-e", getChildFixtureSource()],
+    { stdio: ["ignore", "ignore", "ignore", "ipc"] }
+  );
+  child.send({ type: "not-an-ipc-protocol-message" });
+  const peer = createIpcPeer(
+    createChildProcessIpcTransport(child),
+    {
+      greet(name) {
+        return `hello ${name}`;
+      }
+    }
+  );
+  await expect(peer.call.double(21)).resolves.toBe(42);
+  await expect(peer.call.askParent("Ada")).resolves.toBe("hello Ada");
+  peer.destroy();
+  await new Promise((resolve) => child.once("exit", () => resolve()));
+});
+function getChildFixtureSource() {
+  const ipcModule = new URL("./ipc.ts", import.meta.url).href;
+  const transportModule = new URL(
+    "./child-process-transport.ts",
+    import.meta.url
+  ).href;
+  return `
+    import { createIpcPeer } from ${JSON.stringify(ipcModule)};
+    import { createParentProcessIpcTransport } from ${JSON.stringify(transportModule)};
+
+    const peer = createIpcPeer(createParentProcessIpcTransport(), {
+      double(value) {
+        return value * 2;
+      },
+      async askParent(name) {
+        return peer.call.greet(name);
+      },
+    });
+
+    process.on("disconnect", () => peer.destroy());
+  `;
+}

package/dist/shared/ipc/ipc.d.ts

@@ -0,0 +1,46 @@
+type IpcTransport<T = unknown> = {
+    send(message: T): void | Promise<void>;
+    listen(callback: (message: T) => void): () => void;
+    onClose?(callback: (error?: Error) => void): () => void;
+    close?(): void;
+};
+type FunctionMap<T> = {
+    [K in keyof T]: (...args: never[]) => unknown;
+};
+type UnwrapPromise<T> = T extends Promise<infer Result> ? Result : T;
+type MaybeAsync<T extends (...args: never[]) => unknown> = T extends (...args: infer Args) => infer Result ? (...args: Args) => UnwrapPromise<Result> | Promise<UnwrapPromise<Result>> : never;
+type IpcPeerHandlers<Local extends FunctionMap<Local>> = {
+    [K in keyof Local]: MaybeAsync<Local[K]>;
+};
+type IpcPeerCalls<Remote extends FunctionMap<Remote>> = {
+    [K in keyof Remote]: Remote[K] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<UnwrapPromise<Result>> : never;
+};
+type IpcPeer<Remote extends FunctionMap<Remote>> = {
+    call: IpcPeerCalls<Remote>;
+    destroy(): void;
+};
+type IpcRequestMessage = {
+    type: "ipc-request";
+    id: string;
+    method: string;
+    args: unknown[];
+};
+type SerializedError = {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string | number;
+    cause?: SerializedError;
+    errors?: SerializedError[];
+};
+type IpcResponseMessage = {
+    type: "ipc-response";
+    id: string;
+    method: string;
+    data?: unknown;
+    error?: SerializedError;
+};
+type IpcProtocolMessage = IpcRequestMessage | IpcResponseMessage;
+declare function createIpcPeer<Remote extends FunctionMap<Remote>, Local extends FunctionMap<Local>>(transport: IpcTransport<IpcProtocolMessage>, handlers: IpcPeerHandlers<Local>): IpcPeer<Remote>;
+
+export { type IpcPeer, type IpcPeerCalls, type IpcPeerHandlers, type IpcProtocolMessage, type IpcTransport, createIpcPeer };

package/dist/shared/ipc/ipc.js

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+function createIpcPeer(transport, handlers) {
+  const pending = /* @__PURE__ */ new Map();
+  let destroyed = false;
+  const stopListening = transport.listen((message) => {
+    if (message.type === "ipc-request") {
+      void handleRequest(message);
+      return;
+    }
+    handleResponse(message);
+  });
+  const stopCloseListener = transport.onClose?.((error) => {
+    destroy(error ?? new Error("IPC transport closed"));
+  });
+  async function handleRequest(message) {
+    if (destroyed) return;
+    const handler = handlers[message.method];
+    if (!handler) {
+      await sendResponse({
+        type: "ipc-response",
+        id: message.id,
+        method: message.method,
+        error: serializeError(
+          new Error(`No handler registered for method: ${message.method}`)
+        )
+      });
+      return;
+    }
+    try {
+      const data = await Promise.resolve(handler(...message.args));
+      await sendResponse({
+        type: "ipc-response",
+        id: message.id,
+        method: message.method,
+        data
+      });
+    } catch (error) {
+      await sendResponse({
+        type: "ipc-response",
+        id: message.id,
+        method: message.method,
+        error: serializeError(error)
+      });
+    }
+  }
+  async function sendResponse(message) {
+    try {
+      await transport.send(message);
+    } catch {
+    }
+  }
+  function handleResponse(message) {
+    const request = pending.get(message.id);
+    if (!request) return;
+    pending.delete(message.id);
+    if (message.error) {
+      request.reject(deserializeRemoteError(request.method, message.error));
+      return;
+    }
+    request.resolve(message.data);
+  }
+  const call = new Proxy({}, {
+    get: (_target, method) => {
+      if (typeof method !== "string") return void 0;
+      return (...args) => {
+        if (destroyed) {
+          return Promise.reject(new Error("IPC peer destroyed"));
+        }
+        const id = `${method}-${randomUUID()}`;
+        const promise = new Promise((resolve, reject) => {
+          pending.set(id, { method, resolve, reject });
+        });
+        void Promise.resolve(
+          transport.send({
+            type: "ipc-request",
+            id,
+            method,
+            args
+          })
+        ).catch((error) => {
+          const request = pending.get(id);
+          if (!request) return;
+          pending.delete(id);
+          request.reject(error);
+        });
+        return promise;
+      };
+    }
+  });
+  function destroy(error = new Error("IPC peer destroyed")) {
+    if (destroyed) return;
+    destroyed = true;
+    stopListening();
+    stopCloseListener?.();
+    transport.close?.();
+    for (const request of pending.values()) {
+      request.reject(error);
+    }
+    pending.clear();
+  }
+  return { call, destroy };
+}
+function serializeError(error, seen = /* @__PURE__ */ new WeakSet()) {
+  if (typeof error === "object" && error !== null) {
+    if (seen.has(error)) {
+      return {
+        name: "Error",
+        message: "[Circular]"
+      };
+    }
+    seen.add(error);
+  }
+  if (error instanceof Error) {
+    const serialized = {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+    const errorWithCode = error;
+    if (typeof errorWithCode.code === "string" || typeof errorWithCode.code === "number") {
+      serialized.code = errorWithCode.code;
+    }
+    if (error.cause !== void 0) {
+      serialized.cause = serializeError(error.cause, seen);
+    }
+    if (error instanceof AggregateError) {
+      serialized.errors = error.errors.map(
+        (aggregateError) => serializeError(aggregateError, seen)
+      );
+    }
+    return serialized;
+  }
+  return {
+    name: "NonError",
+    message: String(error)
+  };
+}
+function deserializeRemoteError(method, remoteError) {
+  const error = deserializeSerializedError(
+    remoteError,
+    `${method} > ${remoteError.message}`
+  );
+  error.stack = [new Error(method).stack, remoteError.stack].filter((stack) => typeof stack === "string").join("\n");
+  return error;
+}
+function deserializeSerializedError(serialized, message = serialized.message) {
+  const cause = serialized.cause ? deserializeSerializedError(serialized.cause) : void 0;
+  const error = serialized.name === "AggregateError" && serialized.errors ? new AggregateError(
+    serialized.errors.map(
+      (aggregateError) => deserializeSerializedError(aggregateError)
+    ),
+    message,
+    { cause }
+  ) : new Error(message, { cause });
+  error.name = serialized.name;
+  error.stack = serialized.stack;
+  const errorWithCode = error;
+  if (serialized.code !== void 0) {
+    errorWithCode.code = serialized.code;
+  }
+  return error;
+}
+export {
+  createIpcPeer
+};