libretto 0.2.4 → 0.2.6

package/dist/cli/workers/run-integration-runtime.js

@@ -1,21 +1,23 @@
-import { appendFileSync, existsSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import { cwd } from "node:process";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
   launchBrowser
 } from "../../index.js";
+import { setSessionForPause } from "../../shared/debug/pause.js";
+import { parseSessionStateContent } from "../../shared/state/index.js";
 import { getProfilePath, normalizeDomain } from "../core/browser.js";
 import {
   getSessionActionsLogPath,
-  getSessionDir,
-  getSessionNetworkLogPath
+  getSessionNetworkLogPath,
+  getSessionStatePath
 } from "../core/context.js";
 import { getPauseSignalPaths, removeSignalIfExists } from "../core/pause-signals.js";
 import { installSessionTelemetry } from "../core/session-telemetry.js";
 const LIBRETTO_WORKFLOW_BRAND = /* @__PURE__ */ Symbol.for("libretto.workflow");
-const RESUME_POLL_INTERVAL_MS = 250;
+const FAILURE_HOLD_POLL_INTERVAL_MS = 250;
 function mirrorStdoutToFile(filePath) {
   const stdout = process.stdout;
   const originalWrite = stdout.write.bind(stdout);
@@ -31,23 +33,32 @@ function mirrorStdoutToFile(filePath) {
     stdout.write = originalWrite;
   };
 }
-async function waitForResumeSignal(args) {
-  const { pausedSignalPath, resumeSignalPath } = args.signalPaths;
-  await mkdir(getSessionDir(args.session), { recursive: true });
-  await removeSignalIfExists(resumeSignalPath);
-  await writeFile(
-    pausedSignalPath,
-    JSON.stringify(args.details, null, 2),
-    "utf8"
-  );
-  await args.onPaused?.(args.details);
-  while (!existsSync(resumeSignalPath)) {
+function readSessionStatePid(session) {
+  const statePath = getSessionStatePath(session);
+  if (!existsSync(statePath)) return null;
+  try {
+    return parseSessionStateContent(readFileSync(statePath, "utf8"), statePath).pid;
+  } catch {
+    return null;
+  }
+}
+async function waitForFailureSessionRelease(args) {
+  const { session, expectedPid, logger } = args;
+  logger.info("run-failure-session-hold", { session, expectedPid });
+  while (true) {
+    const currentPid = readSessionStatePid(session);
+    if (currentPid !== expectedPid) {
+      logger.info("run-failure-session-released", {
+        session,
+        expectedPid,
+        currentPid
+      });
+      return;
+    }
     await new Promise(
-      (resolveWait) => setTimeout(resolveWait, RESUME_POLL_INTERVAL_MS)
+      (resolveWait) => setTimeout(resolveWait, FAILURE_HOLD_POLL_INTERVAL_MS)
     );
   }
-  await removeSignalIfExists(resumeSignalPath);
-  await removeSignalIfExists(pausedSignalPath);
 }
 function isLoadedLibrettoWorkflow(value) {
   if (!value || typeof value !== "object") return false;
@@ -57,13 +68,6 @@ function isLoadedLibrettoWorkflow(value) {
 function resolveLocalAuthProfilePath(domain) {
   return getProfilePath(normalizeDomain(domain));
 }
-function resolveWorkflowStorageStatePath(workflow) {
-  const authProfile = workflow.metadata.authProfile;
-  if (authProfile?.type !== "local") {
-    return void 0;
-  }
-  return resolveLocalAuthProfilePath(authProfile.domain);
-}
 function getMissingLocalAuthProfileError(args) {
   const normalizedDomain = normalizeDomain(args.domain);
   return [
@@ -101,7 +105,24 @@ async function loadWorkflowExport(absolutePath, exportName) {
   }
   if (!isLoadedLibrettoWorkflow(targetExport)) {
     throw new Error(
-      `Export "${exportName}" in ${absolutePath} must be a Libretto workflow instance. Use workflow(...) from "libretto".`
+      [
+        `Export "${exportName}" in ${absolutePath} is not a valid Libretto workflow.`,
+        "",
+        'A workflow must be created using the workflow() function from "libretto":',
+        "",
+        '  import { workflow } from "libretto";',
+        "",
+        `  export const ${exportName} = workflow<InputType, OutputType>(`,
+        "    {},",
+        "    async (ctx, input) => {",
+        "      // ctx.page     \u2014 Playwright Page instance",
+        "      // ctx.logger   \u2014 MinimalLogger",
+        "      // ctx.services \u2014 injected dependencies (generic, default {})",
+        "      // input        \u2014 JSON-serializable input matching InputType",
+        "      return output; // must match OutputType",
+        "    },",
+        "  );"
+      ].join("\n")
     );
   }
   return targetExport;
@@ -125,12 +146,12 @@ async function runIntegrationInternal(args, options) {
     integrationExport: args.exportName,
     session: args.session
   });
-  const authProfile = workflow.metadata.authProfile;
-  const storageStatePath = resolveWorkflowStorageStatePath(workflow);
-  if (authProfile?.type === "local" && storageStatePath && !existsSync(storageStatePath)) {
+  const authProfileDomain = args.authProfileDomain;
+  const storageStatePath = authProfileDomain ? resolveLocalAuthProfilePath(authProfileDomain) : void 0;
+  if (authProfileDomain && storageStatePath && !existsSync(storageStatePath)) {
     throw new Error(
       getMissingLocalAuthProfileError({
-        domain: authProfile.domain,
+        domain: authProfileDomain,
         profilePath: storageStatePath,
         session: args.session
       })
@@ -154,50 +175,35 @@ async function runIntegrationInternal(args, options) {
       appendFileSync(networkLogPath, JSON.stringify(entry) + "\n");
     }
   });
+  setSessionForPause(args.session);
   const workflowContext = {
     logger: integrationLogger,
     page: browserSession.page,
-    context: browserSession.context,
-    browser: browserSession.browser,
-    session: args.session,
-    integrationPath: absolutePath,
-    exportName: args.exportName,
-    headless: args.headless,
-    debug: args.debug,
-    pause: async () => {
-      const details = {
-        sessionName: args.session,
-        pausedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        url: browserSession.page.url()
-      };
-      console.log(`[pause] Paused at ${details.url}`);
-      console.log("[pause] Waiting for resume signal...");
-      await waitForResumeSignal({
-        signalPaths,
-        session: args.session,
-        details,
-        onPaused: options.onPaused
-      });
-      console.log("[pause] Resume signal received. Continuing workflow...");
-    }
+    services: {}
   };
   try {
     try {
       await workflow.run(workflowContext, args.params ?? {});
     } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
       await writeFile(
         signalPaths.failedSignalPath,
         JSON.stringify(
           {
             failedAt: (/* @__PURE__ */ new Date()).toISOString(),
-            message: error instanceof Error ? error.message : String(error)
+            message: errorMessage
           },
           null,
           2
         ),
         "utf8"
       );
-      throw error;
+      await waitForFailureSessionRelease({
+        session: args.session,
+        expectedPid: process.pid,
+        logger
+      });
+      return { status: "failed-held" };
     }
     await writeFile(
       signalPaths.completedSignalPath,
@@ -211,10 +217,9 @@ async function runIntegrationInternal(args, options) {
     await browserSession.close();
   }
 }
-async function runIntegrationFromFileInWorker(args, logger, onPaused) {
+async function runIntegrationFromFileInWorker(args, logger) {
   return await runIntegrationInternal(args, {
-    logger,
-    onPaused
+    logger
   });
 }
 export {

package/dist/cli/workers/run-integration-worker-protocol.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+const RunIntegrationWorkerRequestSchema = z.object({
+  integrationPath: z.string().min(1),
+  exportName: z.string().min(1),
+  session: z.string().min(1),
+  params: z.unknown(),
+  headless: z.boolean(),
+  authProfileDomain: z.string().optional()
+});
+export {
+  RunIntegrationWorkerRequestSchema
+};

package/dist/cli/workers/run-integration-worker.js

@@ -1,17 +1,14 @@
 import { writeFile } from "node:fs/promises";
+import { ZodError } from "zod";
+import {
+  RunIntegrationWorkerRequestSchema
+} from "./run-integration-worker-protocol.js";
 import { runIntegrationFromFileInWorker } from "./run-integration-runtime.js";
 import {
   ensureLibrettoSetup,
   withSessionLogger
 } from "../core/context.js";
 import { getPauseSignalPaths } from "../core/pause-signals.js";
-function sendMessage(message) {
-  if (typeof process.send !== "function" || !process.connected) return;
-  try {
-    process.send(message);
-  } catch {
-  }
-}
 function parseWorkerRequest(argv) {
   const rawPayload = argv[2];
   if (!rawPayload) {
@@ -25,21 +22,15 @@ function parseWorkerRequest(argv) {
       `Invalid worker payload JSON: ${error instanceof Error ? error.message : String(error)}`
     );
   }
-  if (!parsed || typeof parsed !== "object") {
-    throw new Error("Worker payload must be an object.");
-  }
-  const candidate = parsed;
-  if (typeof candidate.integrationPath !== "string" || typeof candidate.exportName !== "string" || typeof candidate.session !== "string" || typeof candidate.headless !== "boolean" || typeof candidate.debug !== "boolean" || !("params" in candidate)) {
-    throw new Error("Worker payload is missing required fields.");
+  try {
+    return RunIntegrationWorkerRequestSchema.parse(parsed);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const details = error.issues.map((issue) => `${issue.path.join(".") || "root"}: ${issue.message}`).join("; ");
+      throw new Error(`Worker payload is invalid: ${details}`);
+    }
+    throw error;
   }
-  return {
-    integrationPath: candidate.integrationPath,
-    exportName: candidate.exportName,
-    session: candidate.session,
-    headless: candidate.headless,
-    debug: candidate.debug,
-    params: candidate.params
-  };
 }
 async function main() {
   let request = null;
@@ -49,15 +40,8 @@ async function main() {
     const workerRequest = request;
     ensureLibrettoSetup();
     await withSessionLogger(workerRequest.session, async (logger) => {
-      await runIntegrationFromFileInWorker(
-        workerRequest,
-        logger,
-        async (details) => {
-          sendMessage({ type: "paused", details });
-        }
-      );
+      await runIntegrationFromFileInWorker(workerRequest, logger);
     });
-    sendMessage({ type: "completed" });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     if (request) {
@@ -75,7 +59,6 @@ async function main() {
         "utf8"
       );
     }
-    sendMessage({ type: "failed", message });
     exitCode = 1;
   }
   process.exit(exitCode);

package/dist/index.cjs

@@ -18,11 +18,9 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var index_exports = {};
 __export(index_exports, {
-  DebugPauseSignal: () => import_pause.DebugPauseSignal,
   LIBRETTO_WORKFLOW_BRAND: () => import_workflow.LIBRETTO_WORKFLOW_BRAND,
   LibrettoWorkflow: () => import_workflow.LibrettoWorkflow,
   Logger: () => import_logger.Logger,
-  RunDebugPauseSignal: () => import_api.DebugPauseSignal,
   SESSION_STATE_VERSION: () => import_state.SESSION_STATE_VERSION,
   SessionStateFileSchema: () => import_state.SessionStateFileSchema,
   SessionStatusSchema: () => import_state.SessionStatusSchema,
@@ -30,7 +28,6 @@ __export(index_exports, {
   clearHighlights: () => import_highlight.clearHighlights,
   createFileLogSink: () => import_sinks.createFileLogSink,
   createLLMClientFromModel: () => import_ai_sdk_adapter.createLLMClientFromModel,
-  debugPause: () => import_pause.debugPause,
   defaultLogger: () => import_logger.defaultLogger,
   detectSubmissionError: () => import_errors.detectSubmissionError,
   downloadAndSave: () => import_download.downloadAndSave,
@@ -45,17 +42,15 @@ __export(index_exports, {
   instrumentContext: () => import_instrument.instrumentContext,
   instrumentPage: () => import_instrument.instrumentPage,
   isDebugMode: () => import_config.isDebugMode,
-  isDebugPauseSignal: () => import_pause.isDebugPauseSignal,
   isDryRun: () => import_config.isDryRun,
-  isRunDebugPauseSignal: () => import_api.isDebugPauseSignal,
   jsonlConsoleSink: () => import_sinks.jsonlConsoleSink,
   launchBrowser: () => import_api.launchBrowser,
   moveGhostCursor: () => import_ghost_cursor.moveGhostCursor,
   pageRequest: () => import_network.pageRequest,
   parseSessionStateContent: () => import_state.parseSessionStateContent,
   parseSessionStateData: () => import_state.parseSessionStateData,
+  pause: () => import_pause.pause,
   prettyConsoleSink: () => import_sinks.prettyConsoleSink,
-  runDebugPause: () => import_api.debugPause,
   serializeSessionState: () => import_state.serializeSessionState,
   shouldPauseBeforeMutation: () => import_config.shouldPauseBeforeMutation,
   showHighlight: () => import_highlight.showHighlight,
@@ -81,11 +76,9 @@ var import_api = require("./shared/run/api.js");
 var import_workflow = require("./shared/workflow/workflow.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DebugPauseSignal,
   LIBRETTO_WORKFLOW_BRAND,
   LibrettoWorkflow,
   Logger,
-  RunDebugPauseSignal,
   SESSION_STATE_VERSION,
   SessionStateFileSchema,
   SessionStatusSchema,
@@ -93,7 +86,6 @@ var import_workflow = require("./shared/workflow/workflow.js");
   clearHighlights,
   createFileLogSink,
   createLLMClientFromModel,
-  debugPause,
   defaultLogger,
   detectSubmissionError,
   downloadAndSave,
@@ -108,17 +100,15 @@ var import_workflow = require("./shared/workflow/workflow.js");
   instrumentContext,
   instrumentPage,
   isDebugMode,
-  isDebugPauseSignal,
   isDryRun,
-  isRunDebugPauseSignal,
   jsonlConsoleSink,
   launchBrowser,
   moveGhostCursor,
   pageRequest,
   parseSessionStateContent,
   parseSessionStateData,
+  pause,
   prettyConsoleSink,
-  runDebugPause,
   serializeSessionState,
   shouldPauseBeforeMutation,
   showHighlight,

package/dist/index.d.cts

@@ -9,13 +9,13 @@ export { DetectedSubmissionError, KnownSubmissionError, detectSubmissionError }
 export { ExtractOptions, extractFromPage } from './runtime/extract/extract.cjs';
 export { PageRequestOptions, RequestConfig, pageRequest } from './runtime/network/network.cjs';
 export { DownloadResult, DownloadViaClickOptions, SaveDownloadOptions, downloadAndSave, downloadViaClick } from './runtime/download/download.cjs';
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, DebugPauseContext as RunDebugPauseContext, DebugPauseDetails as RunDebugPauseDetails, DebugPauseSignal as RunDebugPauseSignal, debugPause, isDebugPauseSignal, isDebugPauseSignal as isRunDebugPauseSignal, debugPause as runDebugPause } from './shared/debug/pause.cjs';
+export { pause } from './shared/debug/pause.cjs';
 export { isDebugMode, isDryRun, shouldPauseBeforeMutation } from './shared/config/config.cjs';
 export { InstrumentationOptions, InstrumentedPage, installInstrumentation, instrumentContext, instrumentPage } from './shared/instrumentation/instrument.cjs';
 export { GhostCursorOptions, ensureGhostCursor, ghostClick, hideGhostCursor, moveGhostCursor } from './shared/visualization/ghost-cursor.cjs';
 export { HighlightOptions, clearHighlights, ensureHighlightLayer, showHighlight } from './shared/visualization/highlight.cjs';
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './shared/run/browser.cjs';
-export { LIBRETTO_WORKFLOW_BRAND, LibrettoAuthProfile, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowMetadata, workflow } from './shared/workflow/workflow.cjs';
+export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowMetadata, workflow } from './shared/workflow/workflow.cjs';
 import 'zod';
 import 'ai';
 import 'playwright';

package/dist/index.d.ts

@@ -9,13 +9,13 @@ export { DetectedSubmissionError, KnownSubmissionError, detectSubmissionError }
 export { ExtractOptions, extractFromPage } from './runtime/extract/extract.js';
 export { PageRequestOptions, RequestConfig, pageRequest } from './runtime/network/network.js';
 export { DownloadResult, DownloadViaClickOptions, SaveDownloadOptions, downloadAndSave, downloadViaClick } from './runtime/download/download.js';
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, DebugPauseContext as RunDebugPauseContext, DebugPauseDetails as RunDebugPauseDetails, DebugPauseSignal as RunDebugPauseSignal, debugPause, isDebugPauseSignal, isDebugPauseSignal as isRunDebugPauseSignal, debugPause as runDebugPause } from './shared/debug/pause.js';
+export { pause } from './shared/debug/pause.js';
 export { isDebugMode, isDryRun, shouldPauseBeforeMutation } from './shared/config/config.js';
 export { InstrumentationOptions, InstrumentedPage, installInstrumentation, instrumentContext, instrumentPage } from './shared/instrumentation/instrument.js';
 export { GhostCursorOptions, ensureGhostCursor, ghostClick, hideGhostCursor, moveGhostCursor } from './shared/visualization/ghost-cursor.js';
 export { HighlightOptions, clearHighlights, ensureHighlightLayer, showHighlight } from './shared/visualization/highlight.js';
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './shared/run/browser.js';
-export { LIBRETTO_WORKFLOW_BRAND, LibrettoAuthProfile, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowMetadata, workflow } from './shared/workflow/workflow.js';
+export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowMetadata, workflow } from './shared/workflow/workflow.js';
 import 'zod';
 import 'ai';
 import 'playwright';

package/dist/index.js

@@ -26,11 +26,7 @@ import {
   downloadViaClick,
   downloadAndSave
 } from "./runtime/download/download.js";
-import {
-  debugPause,
-  DebugPauseSignal,
-  isDebugPauseSignal
-} from "./shared/debug/pause.js";
+import { pause } from "./shared/debug/pause.js";
 import {
   isDebugMode,
   isDryRun,
@@ -53,10 +49,7 @@ import {
   clearHighlights
 } from "./shared/visualization/highlight.js";
 import {
-  launchBrowser,
-  debugPause as debugPause2,
-  DebugPauseSignal as DebugPauseSignal2,
-  isDebugPauseSignal as isDebugPauseSignal2
+  launchBrowser
 } from "./shared/run/api.js";
 import {
   LibrettoWorkflow,
@@ -64,11 +57,9 @@ import {
   workflow
 } from "./shared/workflow/workflow.js";
 export {
-  DebugPauseSignal,
   LIBRETTO_WORKFLOW_BRAND,
   LibrettoWorkflow,
   Logger,
-  DebugPauseSignal2 as RunDebugPauseSignal,
   SESSION_STATE_VERSION,
   SessionStateFileSchema,
   SessionStatusSchema,
@@ -76,7 +67,6 @@ export {
   clearHighlights,
   createFileLogSink,
   createLLMClientFromModel,
-  debugPause,
   defaultLogger,
   detectSubmissionError,
   downloadAndSave,
@@ -91,17 +81,15 @@ export {
   instrumentContext,
   instrumentPage,
   isDebugMode,
-  isDebugPauseSignal,
   isDryRun,
-  isDebugPauseSignal2 as isRunDebugPauseSignal,
   jsonlConsoleSink,
   launchBrowser,
   moveGhostCursor,
   pageRequest,
   parseSessionStateContent,
   parseSessionStateData,
+  pause,
   prettyConsoleSink,
-  debugPause2 as runDebugPause,
   serializeSessionState,
   shouldPauseBeforeMutation,
   showHighlight,

package/dist/shared/debug/index.cjs

@@ -18,15 +18,13 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var debug_exports = {};
 __export(debug_exports, {
-  DebugPauseSignal: () => import_pause.DebugPauseSignal,
-  debugPause: () => import_pause.debugPause,
-  isDebugPauseSignal: () => import_pause.isDebugPauseSignal
+  pause: () => import_pause.pause,
+  setSessionForPause: () => import_pause.setSessionForPause
 });
 module.exports = __toCommonJS(debug_exports);
 var import_pause = require("./pause.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 });

package/dist/shared/debug/index.d.cts

@@ -1,2 +1 @@
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal } from './pause.cjs';
-import 'playwright';
+export { pause, setSessionForPause } from './pause.cjs';

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

@@ -1,2 +1 @@
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal } from './pause.js';
-import 'playwright';
+export { pause, setSessionForPause } from './pause.js';

package/dist/shared/debug/index.js

@@ -1,10 +1,5 @@
-import {
-  debugPause,
-  DebugPauseSignal,
-  isDebugPauseSignal
-} from "./pause.js";
+import { pause, setSessionForPause } from "./pause.js";
 export {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 };

package/dist/shared/debug/pause.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,42 +17,74 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var pause_exports = {};
 __export(pause_exports, {
-  DebugPauseSignal: () => DebugPauseSignal,
-  debugPause: () => debugPause,
-  isDebugPauseSignal: () => isDebugPauseSignal
+  pause: () => pause,
+  setSessionForPause: () => setSessionForPause
 });
 module.exports = __toCommonJS(pause_exports);
-class DebugPauseSignal extends Error {
-  details;
-  constructor(details) {
-    super(`Workflow paused at ${details.url}`);
-    this.name = "DebugPauseSignal";
-    this.details = details;
+var import_node_fs = require("node:fs");
+var import_promises = require("node:fs/promises");
+let _sessionName;
+function setSessionForPause(session) {
+  _sessionName = session;
+}
+function getSessionFromProcessArgs() {
+  const rawPayload = process.argv[2];
+  if (!rawPayload) return void 0;
+  try {
+    const parsed = JSON.parse(rawPayload);
+    return typeof parsed.session === "string" ? parsed.session : void 0;
+  } catch {
+    return void 0;
   }
 }
-function isDebugPauseSignal(error) {
-  if (!error || typeof error !== "object") return false;
-  const candidate = error;
-  if (candidate.name !== "DebugPauseSignal") return false;
-  return typeof candidate.details?.sessionName === "string" && typeof candidate.details?.pausedAt === "string" && typeof candidate.details?.url === "string";
+function resolveSession() {
+  return _sessionName ?? getSessionFromProcessArgs();
 }
-async function debugPause(context) {
-  const url = context.page.url();
+async function pause() {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  const session = resolveSession();
+  if (!session) {
+    return;
+  }
+  const { getPauseSignalPaths, removeSignalIfExists } = await import("../../cli/core/pause-signals.js");
+  const { getSessionDir } = await import("../../cli/core/context.js");
+  const signalPaths = getPauseSignalPaths(session);
+  const { pausedSignalPath, resumeSignalPath } = signalPaths;
+  await (0, import_promises.mkdir)(getSessionDir(session), { recursive: true });
+  await removeSignalIfExists(resumeSignalPath);
   const details = {
-    sessionName: context.session,
+    sessionName: session,
     pausedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    url
+    url: "unknown"
   };
-  console.log(`[debugPause] Paused at ${url}`);
-  console.log("[debugPause] Signaling pause to supervisor...");
-  throw new DebugPauseSignal(details);
+  await (0, import_promises.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 (!(0, import_node_fs.existsSync)(resumeSignalPath)) {
+    await new Promise(
+      (resolve) => setTimeout(resolve, RESUME_POLL_INTERVAL_MS)
+    );
+  }
+  await removeSignalIfExists(resumeSignalPath);
+  await removeSignalIfExists(pausedSignalPath);
+  console.log("[pause] Resume signal received. Continuing workflow...");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 });

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

@@ -1,23 +1,16 @@
-import { Page } from 'playwright';
-
-type DebugPauseContext = {
-    page: Page;
-    session: string;
-};
-type DebugPauseDetails = {
-    sessionName: string;
-    pausedAt: string;
-    url: string;
-};
-declare class DebugPauseSignal extends Error {
-    readonly details: DebugPauseDetails;
-    constructor(details: DebugPauseDetails);
-}
-declare function isDebugPauseSignal(error: unknown): error is DebugPauseSignal;
 /**
- * Signals a workflow pause to the caller.
- * This always throws a typed signal that supervisors can intercept.
+ * Called by the CLI runtime to make the session name available to `pause()`.
+ */
+declare function setSessionForPause(session: string): void;
+/**
+ * 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.
+ *
+ * Import directly: `import { pause } from "libretto";`
  */
-declare function debugPause(context: DebugPauseContext): Promise<never>;
+declare function pause(): Promise<void>;
 
-export { type DebugPauseContext, type DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal };
+export { pause, setSessionForPause };