libretto 0.6.10 → 0.6.12

package/src/shared/debug/pause-handler.ts

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

package/src/shared/debug/pause.ts

@@ -1,32 +1,17 @@
-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(): never {
-  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")}.`,
+  );
 }
 
 /**
  * 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";`
  */
@@ -39,34 +24,15 @@ export async function pause(session: string): Promise<void> {
     throwMissingSessionError();
   }
 
-  const signalPaths = getPauseSignalPaths(session);
-  const { pausedSignalPath, resumeSignalPath } = signalPaths;
-
-  await mkdir(getSessionDir(session), { recursive: true });
-  await removeSignalIfExists(resumeSignalPath);
-
-  const details = {
-    sessionName: session,
-    pausedAt: new Date().toISOString(),
-    url: "unknown",
-  };
-
-  // Try to read the current page URL from the process (best-effort).
-  // The standalone pause doesn't have access to the page object,
-  // so we just record what we can.
-  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: new Date().toISOString(),
+  });
 }

package/src/shared/ipc/AGENTS.md

@@ -0,0 +1,24 @@
+# Shared IPC
+
+This directory contains the generic typed IPC peer used across socket and child-process boundaries. Keep it transport-agnostic and avoid daemon-, workflow-, or CLI-specific behavior here.
+
+## IpcPeer model
+
+`createIpcPeer<Remote, Local>(transport, handlers)` creates one bidirectional peer:
+
+- `Remote` is the API this side can call through `peer.call.*`.
+- `Local` is the API this side exposes through `handlers`.
+- Both peers on a connection use opposite generic ordering.
+- Calls are request/response RPCs over `IpcProtocolMessage`; concurrent calls are supported.
+
+## Transports
+
+Transports implement `IpcTransport<IpcProtocolMessage>` and are responsible only for delivery, framing, close notification, and cleanup. Use `socket-transport.ts` for Unix socket connections and `child-process-transport.ts` for Node child-process IPC.
+
+When adding a transport, filter incoming messages to valid IPC protocol messages before passing them to `createIpcPeer`, and wire close/error events through `onClose` so pending calls reject when the connection dies.
+
+## Error behavior
+
+`createIpcPeer` serializes handler throws into rejected call promises. Callers should usually let those rejections propagate instead of wrapping them in subsystem-specific error adapters.
+
+Use explicit result shapes only when failure is part of the method contract. For example, daemon `exec` and `readonlyExec` return user-code failures as `{ ok: false, message, output }` so CLI callers can preserve captured stdout and stderr.

package/src/shared/ipc/child-process-transport.spec.ts

@@ -0,0 +1,86 @@
+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);
+
+type ParentApi = {
+  greet(name: string): string;
+};
+
+type ChildApi = {
+  double(value: number): number;
+  askParent(name: string): Promise<string>;
+};
+
+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<ChildApi, ParentApi>(
+    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<void>((resolve) => child.once("exit", () => resolve()));
+});
+
+function getChildFixtureSource(): string {
+  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/src/shared/ipc/child-process-transport.ts

@@ -0,0 +1,96 @@
+import type { ChildProcess } from "node:child_process";
+import type { IpcProtocolMessage, IpcTransport } from "./ipc.js";
+
+type ProcessIpcTarget = {
+  send?: (message: IpcProtocolMessage) => boolean;
+  on(event: "message", listener: (message: unknown) => void): ProcessIpcTarget;
+  off(event: "message", listener: (message: unknown) => void): ProcessIpcTarget;
+  on(event: "disconnect", listener: () => void): ProcessIpcTarget;
+  off(event: "disconnect", listener: () => void): ProcessIpcTarget;
+};
+
+export function createChildProcessIpcTransport(
+  child: ChildProcess,
+): IpcTransport<IpcProtocolMessage> {
+  return createProcessIpcTransport(child, () => {
+    if (child.connected) child.disconnect();
+  });
+}
+
+export function createParentProcessIpcTransport(): IpcTransport<IpcProtocolMessage> {
+  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: ProcessIpcTarget,
+  close: () => void,
+): IpcTransport<IpcProtocolMessage> {
+  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: unknown) => {
+        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: unknown): message is IpcProtocolMessage {
+  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 === undefined || isSerializedError(message.error))
+    );
+  }
+
+  return false;
+}
+
+function isSerializedError(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === "string" &&
+    typeof value.message === "string" &&
+    (value.stack === undefined || typeof value.stack === "string")
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/shared/ipc/ipc.spec.ts

@@ -0,0 +1,161 @@
+import { EventEmitter } from "node:events";
+import { expect, test as base } from "vitest";
+import {
+  createIpcPeer,
+  type IpcPeer,
+  type IpcProtocolMessage,
+} from "./ipc.js";
+
+type ApiA = {
+  greet(name: string): string;
+};
+
+type ApiB = {
+  add(left: number, right: number): Promise<number>;
+  fail(): Promise<void>;
+  failWithCause(): Promise<void>;
+  failWithCode(): Promise<void>;
+  failWithNonError(): Promise<void>;
+  wait(): Promise<string>;
+};
+
+type Peers = {
+  a: IpcPeer<ApiB>;
+  b: IpcPeer<ApiA>;
+};
+
+type Fixtures = Peers & {
+  peers: Peers;
+};
+
+const test = base.extend<Fixtures>({
+  peers: async ({}, use) => {
+    const channel = new EventEmitter<{
+      a: [IpcProtocolMessage];
+      b: [IpcProtocolMessage];
+    }>();
+    const a = createIpcPeer<ApiB, ApiA>({
+      send(message) {
+        channel.emit("b", message);
+      },
+      listen(callback) {
+        channel.on("a", callback);
+        return () => channel.off("a", callback);
+      },
+    }, {
+      greet(name) {
+        return `hello ${name}`;
+      },
+    });
+    const b = createIpcPeer<ApiA, ApiB>({
+      send(message) {
+        channel.emit("a", message);
+      },
+      listen(callback) {
+        channel.on("b", callback);
+        return () => channel.off("b", callback);
+      },
+    }, {
+      async add(left, right) {
+        return left + right;
+      },
+      async fail() {
+        throw new Error("expected failure");
+      },
+      async failWithCause() {
+        throw new Error("outer failure", {
+          cause: new Error("inner failure", {
+            cause: new TypeError("root failure"),
+          }),
+        });
+      },
+      async failWithCode() {
+        const error = new Error("coded failure") as Error & { code: string };
+        error.code = "ERR_EXPECTED";
+        throw error;
+      },
+      async failWithNonError() {
+        throw "plain failure";
+      },
+      async wait() {
+        return new Promise(() => {});
+      },
+    });
+
+    await use({ a, b });
+
+    a.destroy();
+    b.destroy();
+  },
+  a: async ({ peers }, use) => {
+    await use(peers.a);
+  },
+  b: async ({ peers }, use) => {
+    await use(peers.b);
+  },
+});
+
+test("calls handlers on the remote peer", async ({ a, b }) => {
+  await expect(a.call.add(2, 3)).resolves.toBe(5);
+  await expect(b.call.greet("Ada")).resolves.toBe("hello Ada");
+});
+
+test("rejects with the remote handler error", async ({ a }) => {
+  await expect(a.call.fail()).rejects.toThrow("fail > expected failure");
+});
+
+test("rejects with the remote handler error cause chain", async ({ a }) => {
+  const error = await getRejectedError(a.call.failWithCause());
+
+  expect(error.message).toBe("failWithCause > outer failure");
+  expect(error.stack).toContain("outer failure");
+
+  const cause = getErrorCause(error);
+  expect(cause.message).toBe("inner failure");
+
+  const rootCause = getErrorCause(cause);
+  expect(rootCause.name).toBe("TypeError");
+  expect(rootCause.message).toBe("root failure");
+});
+
+test("rejects with the remote handler error code", async ({ a }) => {
+  const error = await getRejectedError(a.call.failWithCode());
+
+  expect(error.message).toBe("failWithCode > coded failure");
+  expect(error.code).toBe("ERR_EXPECTED");
+  expect(error.stack).toContain("coded failure");
+});
+
+test("rejects with a serialized non-error thrown value", async ({ a }) => {
+  const error = await getRejectedError(a.call.failWithNonError());
+
+  expect(error.name).toBe("NonError");
+  expect(error.message).toBe("failWithNonError > plain failure");
+  expect(error.stack).toContain("failWithNonError");
+});
+
+test("rejects pending calls when destroyed", async ({ a }) => {
+  const result = a.call.wait();
+
+  a.destroy();
+
+  await expect(result).rejects.toThrow("IPC peer destroyed");
+});
+
+async function getRejectedError(
+  promise: Promise<unknown>,
+): Promise<Error & { code?: unknown }> {
+  try {
+    await promise;
+  } catch (error) {
+    expect(error).toBeInstanceOf(Error);
+    return error as Error & { code?: unknown };
+  }
+
+  throw new Error("Expected promise to reject");
+}
+
+function getErrorCause(error: Error): Error {
+  expect(error.cause).toBeInstanceOf(Error);
+  return error.cause as Error;
+}