libretto 0.2.4 → 0.2.6

package/README.md

@@ -9,17 +9,21 @@ pnpm add libretto playwright zod
 npx libretto init
 ```
 
-> **pnpm users:** add `onlyBuiltDependencies` to your `package.json` to allow
-> Playwright's postinstall script to run:
+> **pnpm users:** if your workspace uses `onlyBuiltDependencies`, add both
+> `libretto` and `playwright` to allow their postinstall scripts to run
+> (libretto's postinstall copies skill files and installs Playwright Chromium):
 >
 > ```jsonc
 > // package.json
 > {
 >   "pnpm": {
->     "onlyBuiltDependencies": ["playwright"]
+>     "onlyBuiltDependencies": ["libretto", "playwright"]
 >   }
 > }
 > ```
+>
+> If the postinstall was skipped (e.g., `libretto` wasn't in the allowlist),
+> run `npx libretto init` manually after install to complete setup.
 
 ## Quick Start
 
@@ -119,6 +123,33 @@ Run `npx libretto help` for the full list.
 | `libretto/run`             | `launchBrowser`                                               |
 | `libretto/state`           | Session state serialization and parsing                       |
 
+## Using Recovery Helpers
+
+The recovery module (`libretto/recovery`) provides `detectSubmissionError` and
+`executeRecoveryAgent` for handling form submission errors. Both accept an
+`LLMClient` — create one with `createLLMClientFromModel` and pass it directly:
+
+```typescript
+import { detectSubmissionError, executeRecoveryAgent } from "libretto/recovery";
+import { createLLMClientFromModel } from "libretto/llm";
+import { openai } from "@ai-sdk/openai";
+
+const llmClient = createLLMClientFromModel(openai("gpt-4o"));
+
+// Detect if a submission produced an error
+const error = await detectSubmissionError(
+  page, submissionError, "eligibility check failed", llmClient, knownErrors, logger,
+);
+
+// Or run the full recovery agent to retry with corrections
+const result = await executeRecoveryAgent(
+  page, error, llmClient, recoveryOptions, logger,
+);
+```
+
+No need to write custom wrappers — `createLLMClientFromModel` bridges any
+Vercel AI SDK provider into the `LLMClient` interface that recovery helpers expect.
+
 ## Links
 
 - [GitHub](https://github.com/saffron-health/libretto)

package/dist/cli/cli.js

@@ -39,7 +39,7 @@ Commands:
   init [--skip-browsers] Initialize libretto (copy skills, install browsers)
   open <url> [--headless] Launch browser and open URL (headed by default)
                           Automatically loads saved profile if available
-  run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--headed|--headless] [--debug]  Run an exported Libretto workflow from a file; pass --debug to enable pause-on-failure debugging (or --no-debug to disable)
+  run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--headed|--headless]  Run an exported Libretto workflow from a file
   ai configure [preset] [-- <command prefix...>]  Configure AI runtime for analysis commands
   save <url|domain>       Save current browser session (cookies, localStorage, etc.)
   exec <code> [--visualize]  Execute Playwright typescript code (--visualize enables ghost cursor + highlight)
@@ -48,7 +48,7 @@ Commands:
   actions [--last N] [--filter regex] [--action TYPE] [--source SOURCE] [--clear]  View captured actions
   pages                   List open pages in the active session
   resume                  Resume a paused workflow in the active session
-  close                   Close the browser
+  close [--all] [--force]  Close the browser for the session, or all tracked sessions with --all
 
 Options:
   --session <name>        Use a named session (default: "default")
@@ -71,6 +71,8 @@ Examples:
   libretto-cli snapshot --objective "Find the submit button" --context "Submitting a referral form, already filled in patient details"
   libretto-cli resume --session default
   libretto-cli close
+  libretto-cli close --all
+  libretto-cli close --all --force
 
   # Multiple sessions
   libretto-cli open https://site1.com --session test1

package/dist/cli/commands/browser.js

@@ -1,5 +1,6 @@
 import {
   runClose as runCloseWithLogger,
+  runCloseAll as runCloseAllWithLogger,
   runOpen,
   runPages,
   runSave
@@ -44,9 +45,31 @@ function registerBrowserCommands(yargs, logger) {
     }
   ).command("pages", "List open pages in the session", (cmd) => cmd, async (argv) => {
     await runPages(String(argv.session), logger);
-  }).command("close", "Close the browser", (cmd) => cmd, async (argv) => {
-    await runCloseWithLogger(String(argv.session), logger);
-  });
+  }).command(
+    "close",
+    "Close the browser",
+    (cmd) => cmd.option("all", {
+      type: "boolean",
+      default: false,
+      describe: "Close all tracked sessions in this workspace"
+    }).option("force", {
+      type: "boolean",
+      default: false,
+      describe: "Force kill sessions that ignore SIGTERM (requires --all)"
+    }),
+    async (argv) => {
+      const closeAll = Boolean(argv.all);
+      const force = Boolean(argv.force);
+      if (force && !closeAll) {
+        throw new Error("Usage: libretto-cli close --all [--force]");
+      }
+      if (closeAll) {
+        await runCloseAllWithLogger(logger, { force });
+        return;
+      }
+      await runCloseWithLogger(String(argv.session), logger);
+    }
+  );
 }
 async function runClose(session) {
   await withSessionLogger(session, async (logger) => {

package/dist/cli/commands/execution.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { fork } from "node:child_process";
+import { spawn } from "node:child_process";
 import * as moduleBuiltin from "node:module";
 import { fileURLToPath } from "node:url";
 import { installInstrumentation } from "../../shared/instrumentation/index.js";
@@ -10,6 +10,8 @@ import {
 import { getPauseSignalPaths } from "../core/pause-signals.js";
 import {
   assertSessionAvailableForStart,
+  clearSessionState,
+  readSessionState,
   readSessionStateOrThrow,
   setSessionStatus
 } from "../core/session.js";
@@ -170,6 +172,35 @@ function isProcessRunning(pid) {
     return false;
   }
 }
+async function stopExistingFailedRunSession(session, logger) {
+  const existingState = readSessionState(session, logger);
+  if (!existingState || existingState.status !== "failed") {
+    return;
+  }
+  logger.info("run-release-existing-failed-session", {
+    session,
+    pid: existingState.pid,
+    port: existingState.port
+  });
+  clearSessionState(session, logger);
+  const stopDeadline = Date.now() + 3e3;
+  while (isProcessRunning(existingState.pid) && Date.now() < stopDeadline) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+  }
+  if (isProcessRunning(existingState.pid)) {
+    logger.warn("run-release-existing-failed-session-timeout", {
+      session,
+      pid: existingState.pid
+    });
+    console.warn(
+      `Existing failed workflow process for session "${session}" (pid ${existingState.pid}) is still shutting down; continuing.`
+    );
+    return;
+  }
+  console.log(
+    `Closed existing failed workflow process for session "${session}" (pid ${existingState.pid}).`
+  );
+}
 function readJsonFileIfExists(path) {
   if (!existsSync(path)) return null;
   try {
@@ -246,7 +277,7 @@ async function runResume(session, logger) {
   } = getPauseSignalPaths(session);
   if (!existsSync(pausedSignalPath)) {
     throw new Error(
-      `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call ctx.pause() first.`
+      `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call pause() first.`
     );
   }
   if (!isProcessRunning(state.pid)) {
@@ -297,6 +328,7 @@ async function runResume(session, logger) {
   console.log("Workflow paused.");
 }
 async function runIntegrationFromFile(args, logger) {
+  await stopExistingFailedRunSession(args.session, logger);
   assertSessionAvailableForStart(args.session, logger);
   const signalPaths = getPauseSignalPaths(args.session);
   clearSignalIfExists(signalPaths.pausedSignalPath);
@@ -308,12 +340,11 @@ async function runIntegrationFromFile(args, logger) {
     new URL("../workers/run-integration-worker.js", import.meta.url)
   );
   const payload = JSON.stringify(args);
-  const worker = fork(workerEntryPath, [payload], {
+  const worker = spawn(process.execPath, [workerEntryPath, payload], {
     detached: true,
-    stdio: ["ignore", "ignore", "ignore", "ipc"],
+    stdio: "ignore",
     env: process.env
   });
-  worker.disconnect();
   worker.unref();
   const outcome = await waitForWorkflowOutcome({
     session: args.session,
@@ -326,7 +357,10 @@ async function runIntegrationFromFile(args, logger) {
   }
   if (outcome.status === "failed") {
     setSessionStatus(args.session, "failed", logger);
-    throw new Error(outcome.message ?? "Workflow failed during run.");
+    throw new Error(
+      `${outcome.message ?? "Workflow failed during run."}
+Browser is still open. You can use \`exec\` to inspect it. Call \`run\` to re-run the workflow.`
+    );
   }
   if (outcome.status === "exited") {
     setSessionStatus(args.session, "exited", logger);
@@ -360,11 +394,17 @@ function registerExecutionCommands(yargs, logger) {
   ).command(
     "run [integrationFile] [integrationExport]",
     "Run an exported Libretto workflow from a file",
-    (cmd) => cmd.option("params", { type: "string" }).option("params-file", { type: "string" }).option("headed", { type: "boolean", default: false }).option("headless", { type: "boolean", default: false }).option("debug", { type: "boolean" }),
+    (cmd) => cmd.option("params", { type: "string" }).option("params-file", { type: "string" }).option("headed", { type: "boolean", default: false }).option("headless", { type: "boolean", default: false }).option("auth-profile", { type: "string", describe: "Domain for local auth profile (e.g. apps.example.com)" }),
     async (argv) => {
-      const usage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--headed|--headless] [--debug]";
+      const usage = "Usage: libretto-cli run <integrationFile> <integrationExport> [--params <json> | --params-file <path>] [--headed|--headless]";
       const integrationPath = argv.integrationFile;
       const exportName = argv.integrationExport;
+      const legacyDebug = argv.debug;
+      if (legacyDebug !== void 0) {
+        throw new Error(
+          "The --debug flag has been removed. Run the command without --debug."
+        );
+      }
       if (!integrationPath || !exportName) {
         throw new Error(usage);
       }
@@ -397,15 +437,14 @@ function registerExecutionCommands(yargs, logger) {
         throw new Error("Cannot pass both --headed and --headless.");
       }
       const headlessMode = hasHeadedFlag ? false : hasHeadlessFlag ? true : void 0;
-      const debugFlag = argv.debug;
-      const debugMode = debugFlag !== void 0 ? debugFlag : process.env.LIBRETTO_DEBUG === "true";
+      const authProfileDomain = argv["auth-profile"];
       await runIntegrationFromFile({
         integrationPath,
         exportName,
         session,
         params,
         headless: headlessMode ?? false,
-        debug: debugMode
+        authProfileDomain
       }, logger);
     }
   ).command(

package/dist/cli/core/browser.js

@@ -12,12 +12,15 @@ import {
 import {
   assertSessionAvailableForStart,
   clearSessionState,
+  listSessionsWithStateFile,
   readSessionStateOrThrow,
   logFileForSession,
   readSessionState,
   writeSessionState
 } from "./session.js";
 import { installSessionTelemetry } from "./session-telemetry.js";
+const CLOSE_WAIT_MS = 1500;
+const FORCE_CLOSE_WAIT_MS = 300;
 async function pickFreePort() {
   return await new Promise((resolve2, reject) => {
     const server = createServer();
@@ -488,16 +491,137 @@ async function runClose(session, logger) {
     return;
   }
   logger.info("close-killing", { session, pid: state.pid, port: state.port });
-  try {
-    process.kill(state.pid, "SIGTERM");
-  } catch (err) {
-    logger.warn("close-kill-failed", { error: err, session, pid: state.pid });
-  }
-  await new Promise((r) => setTimeout(r, 1500));
+  sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
+  await waitForCloseSignalWindow(CLOSE_WAIT_MS);
   clearSessionState(session, logger);
   logger.info("close-success", { session });
   console.log(`Browser closed (session: ${session}).`);
 }
+function waitForCloseSignalWindow(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function isPidRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function sendSignalToProcessGroupOrPid(pid, signal, logger, session) {
+  try {
+    process.kill(pid, signal);
+    logger.info("close-signal-pid", { session, pid, signal });
+  } catch (pidErr) {
+    const pidCode = pidErr.code;
+    if (pidCode !== "ESRCH") {
+      logger.warn("close-signal-pid-failed", {
+        session,
+        pid,
+        signal,
+        error: pidErr
+      });
+    }
+  }
+}
+function formatSessionList(targets) {
+  return targets.map((target) => `"${target.session}"`).join(", ");
+}
+function resolveClosableSessions(logger) {
+  const sessions = listSessionsWithStateFile();
+  const closable = [];
+  let clearedUnreadableStates = 0;
+  for (const session of sessions) {
+    const state = readSessionState(session, logger);
+    if (!state) {
+      clearSessionState(session, logger);
+      clearedUnreadableStates += 1;
+      continue;
+    }
+    closable.push({
+      session,
+      pid: state.pid,
+      port: state.port
+    });
+  }
+  return { closable, clearedUnreadableStates };
+}
+function clearStoppedSessionStates(sessions, logger) {
+  let cleared = 0;
+  for (const session of sessions) {
+    if (!isPidRunning(session.pid)) {
+      clearSessionState(session.session, logger);
+      cleared += 1;
+    }
+  }
+  return cleared;
+}
+async function runCloseAll(logger, options) {
+  const force = Boolean(options?.force);
+  logger.info("close-all-start", { force });
+  const { closable, clearedUnreadableStates } = resolveClosableSessions(logger);
+  if (closable.length === 0) {
+    if (clearedUnreadableStates > 0) {
+      console.log(
+        `Cleared ${clearedUnreadableStates} unreadable session state file(s).`
+      );
+    }
+    console.log("No browser sessions found.");
+    return;
+  }
+  for (const target of closable) {
+    logger.info("close-all-sigterm", {
+      session: target.session,
+      pid: target.pid,
+      port: target.port
+    });
+    sendSignalToProcessGroupOrPid(target.pid, "SIGTERM", logger, target.session);
+  }
+  await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+  let survivors = closable.filter((target) => isPidRunning(target.pid));
+  if (survivors.length > 0 && !force) {
+    const closed = clearStoppedSessionStates(closable, logger);
+    throw new Error(
+      [
+        `Failed to close ${survivors.length} session(s) gracefully: ${formatSessionList(survivors)}.`,
+        `Closed ${closed} session(s).`,
+        "Retry with: libretto-cli close --all --force"
+      ].join("\n")
+    );
+  }
+  let forceKilled = 0;
+  if (survivors.length > 0) {
+    for (const survivor of survivors) {
+      logger.warn("close-all-sigkill", {
+        session: survivor.session,
+        pid: survivor.pid
+      });
+      sendSignalToProcessGroupOrPid(survivor.pid, "SIGKILL", logger, survivor.session);
+      forceKilled += 1;
+    }
+    await waitForCloseSignalWindow(FORCE_CLOSE_WAIT_MS);
+    survivors = survivors.filter((target) => isPidRunning(target.pid));
+    if (survivors.length > 0) {
+      const closed = clearStoppedSessionStates(closable, logger);
+      throw new Error(
+        [
+          `Failed to force-close ${survivors.length} session(s): ${formatSessionList(survivors)}.`,
+          `Closed ${closed} session(s).`
+        ].join("\n")
+      );
+    }
+  }
+  clearStoppedSessionStates(closable, logger);
+  if (clearedUnreadableStates > 0) {
+    console.log(
+      `Cleared ${clearedUnreadableStates} unreadable session state file(s).`
+    );
+  }
+  console.log(`Closed ${closable.length} session(s).`);
+  if (forceKilled > 0) {
+    console.log(`Force-killed ${forceKilled} session(s).`);
+  }
+}
 function resolvePath(filePath) {
   return join(process.cwd(), filePath);
 }
@@ -517,6 +641,7 @@ export {
   normalizeUrl,
   resolvePath,
   runClose,
+  runCloseAll,
   runOpen,
   runPages,
   runSave

package/dist/cli/core/session.js

@@ -14,7 +14,6 @@ import {
 } from "./context.js";
 import {
   SESSION_STATE_VERSION,
-  SessionStatusSchema,
   parseSessionStateContent,
   serializeSessionState
 } from "../../shared/state/index.js";
@@ -65,11 +64,19 @@ function readSessionState(session, logger) {
     return null;
   }
 }
-function listActiveSessions() {
+function listSessionsWithStateFile() {
   if (!existsSync(LIBRETTO_SESSIONS_DIR)) return [];
-  return readdirSync(LIBRETTO_SESSIONS_DIR).filter(
-    (session) => existsSync(getSessionStatePath(session))
-  );
+  return readdirSync(LIBRETTO_SESSIONS_DIR).filter((session) => {
+    try {
+      validateSessionName(session);
+    } catch {
+      return false;
+    }
+    return existsSync(getSessionStatePath(session));
+  }).sort();
+}
+function listActiveSessions() {
+  return listSessionsWithStateFile();
 }
 function throwSessionNotFoundError(session) {
   const active = listActiveSessions();
@@ -128,9 +135,6 @@ function clearSessionState(session, logger) {
   unlinkSync(stateFile);
   logger?.info("session-state-cleared", { session, stateFile });
 }
-function isSessionStatus(value) {
-  return SessionStatusSchema.safeParse(value).success;
-}
 function isPidRunning(pid) {
   try {
     process.kill(pid, 0);
@@ -151,11 +155,6 @@ function setSessionStatus(session, status, logger) {
 function assertSessionAvailableForStart(session, logger) {
   const existingState = readSessionState(session, logger);
   if (!existingState) return;
-  if (isSessionStatus(existingState.status)) {
-    if (existingState.status === "completed" || existingState.status === "failed" || existingState.status === "exited") {
-      return;
-    }
-  }
   if (!isPidRunning(existingState.pid)) {
     setSessionStatus(session, "exited", logger);
     return;
@@ -174,6 +173,7 @@ export {
   assertSessionStateExistsOrThrow,
   clearSessionState,
   getStateFilePath,
+  listSessionsWithStateFile,
   logFileForSession,
   readSessionState,
   readSessionStateOrThrow,