libretto 0.2.4 → 0.2.6

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

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

package/dist/shared/debug/pause.js

@@ -1,30 +1,55 @@
-class DebugPauseSignal extends Error {
-  details;
-  constructor(details) {
-    super(`Workflow paused at ${details.url}`);
-    this.name = "DebugPauseSignal";
-    this.details = details;
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "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 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 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)
+    );
+  }
+  await removeSignalIfExists(resumeSignalPath);
+  await removeSignalIfExists(pausedSignalPath);
+  console.log("[pause] Resume signal received. Continuing workflow...");
 }
 export {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 };

package/dist/shared/llm/ai-sdk-adapter.cjs

@@ -38,8 +38,14 @@ function createLLMClientFromModel(model) {
         if (typeof msg.content === "string") {
           return { role: msg.role, content: msg.content };
         }
+        if (msg.role === "assistant") {
+          return {
+            role: "assistant",
+            content: msg.content.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }))
+          };
+        }
         return {
-          role: msg.role,
+          role: "user",
           content: msg.content.map(
             (part) => part.type === "text" ? { type: "text", text: part.text } : { type: "image", image: part.image }
           )

package/dist/shared/llm/ai-sdk-adapter.js

@@ -15,8 +15,14 @@ function createLLMClientFromModel(model) {
         if (typeof msg.content === "string") {
           return { role: msg.role, content: msg.content };
         }
+        if (msg.role === "assistant") {
+          return {
+            role: "assistant",
+            content: msg.content.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }))
+          };
+        }
         return {
-          role: msg.role,
+          role: "user",
           content: msg.content.map(
             (part) => part.type === "text" ? { type: "text", text: part.text } : { type: "image", image: part.image }
           )

package/dist/shared/run/api.cjs

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

package/dist/shared/run/api.d.cts

@@ -1,3 +1,2 @@
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './browser.cjs';
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal } from '../debug/pause.cjs';
 import 'playwright';

package/dist/shared/run/api.d.ts

@@ -1,3 +1,2 @@
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './browser.js';
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal } from '../debug/pause.js';
 import 'playwright';

package/dist/shared/run/api.js

@@ -1,12 +1,4 @@
 import { launchBrowser } from "./browser.js";
-import {
-  debugPause,
-  DebugPauseSignal,
-  isDebugPauseSignal
-} from "../debug/pause.js";
 export {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal,
   launchBrowser
 };

package/dist/shared/workflow/workflow.d.cts

@@ -1,34 +1,21 @@
-import { Page, BrowserContext, Browser } from 'playwright';
+import { Page } from 'playwright';
 import { MinimalLogger } from '../logger/logger.cjs';
 
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
-type LibrettoAuthProfile = {
-    type: "local";
-    domain: string;
-};
-type LibrettoWorkflowMetadata = {
-    authProfile?: LibrettoAuthProfile;
-};
-type LibrettoWorkflowContext = {
-    logger: MinimalLogger;
+type LibrettoWorkflowMetadata = {};
+type LibrettoWorkflowContext<S = {}> = {
     page: Page;
-    context: BrowserContext;
-    browser: Browser;
-    session: string;
-    integrationPath: string;
-    exportName: string;
-    headless: boolean;
-    debug: boolean;
-    pause: () => Promise<void>;
+    logger: MinimalLogger;
+    services: S;
 };
-type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (ctx: LibrettoWorkflowContext, input: Input) => Promise<Output>;
-declare class LibrettoWorkflow<Input = unknown, Output = unknown> {
+type LibrettoWorkflowHandler<Input = unknown, Output = unknown, S = {}> = (ctx: LibrettoWorkflowContext<S>, input: Input) => Promise<Output>;
+declare class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
     readonly [LIBRETTO_WORKFLOW_BRAND] = true;
     readonly metadata: LibrettoWorkflowMetadata;
     private readonly handler;
-    constructor(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output>);
-    run(ctx: LibrettoWorkflowContext, input: Input): Promise<Output>;
+    constructor(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>);
+    run(ctx: LibrettoWorkflowContext<S>, input: Input): Promise<Output>;
 }
-declare function workflow<Input = unknown, Output = unknown>(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output>): LibrettoWorkflow<Input, Output>;
+declare function workflow<Input = unknown, Output = unknown, S = {}>(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
 
-export { LIBRETTO_WORKFLOW_BRAND, type LibrettoAuthProfile, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, type LibrettoWorkflowMetadata, workflow };
+export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, type LibrettoWorkflowMetadata, workflow };

package/dist/shared/workflow/workflow.d.ts

@@ -1,34 +1,21 @@
-import { Page, BrowserContext, Browser } from 'playwright';
+import { Page } from 'playwright';
 import { MinimalLogger } from '../logger/logger.js';
 
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
-type LibrettoAuthProfile = {
-    type: "local";
-    domain: string;
-};
-type LibrettoWorkflowMetadata = {
-    authProfile?: LibrettoAuthProfile;
-};
-type LibrettoWorkflowContext = {
-    logger: MinimalLogger;
+type LibrettoWorkflowMetadata = {};
+type LibrettoWorkflowContext<S = {}> = {
     page: Page;
-    context: BrowserContext;
-    browser: Browser;
-    session: string;
-    integrationPath: string;
-    exportName: string;
-    headless: boolean;
-    debug: boolean;
-    pause: () => Promise<void>;
+    logger: MinimalLogger;
+    services: S;
 };
-type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (ctx: LibrettoWorkflowContext, input: Input) => Promise<Output>;
-declare class LibrettoWorkflow<Input = unknown, Output = unknown> {
+type LibrettoWorkflowHandler<Input = unknown, Output = unknown, S = {}> = (ctx: LibrettoWorkflowContext<S>, input: Input) => Promise<Output>;
+declare class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
     readonly [LIBRETTO_WORKFLOW_BRAND] = true;
     readonly metadata: LibrettoWorkflowMetadata;
     private readonly handler;
-    constructor(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output>);
-    run(ctx: LibrettoWorkflowContext, input: Input): Promise<Output>;
+    constructor(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>);
+    run(ctx: LibrettoWorkflowContext<S>, input: Input): Promise<Output>;
 }
-declare function workflow<Input = unknown, Output = unknown>(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output>): LibrettoWorkflow<Input, Output>;
+declare function workflow<Input = unknown, Output = unknown, S = {}>(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
 
-export { LIBRETTO_WORKFLOW_BRAND, type LibrettoAuthProfile, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, type LibrettoWorkflowMetadata, workflow };
+export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, type LibrettoWorkflowMetadata, workflow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -105,9 +105,15 @@
     "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "@ai-sdk/anthropic": { "optional": true },
-    "@ai-sdk/google-vertex": { "optional": true },
-    "@ai-sdk/openai": { "optional": true }
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google-vertex": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.53",

package/skill/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: libretto
 description: "Browser automation CLI for building integrations, with a network-first approach.\n\nWHEN TO USE THIS SKILL:\n- When building a new integration or data extraction workflow against a website\n- When you need to interact with a web page (click, fill, navigate) rather than just read it\n- When debugging browser agent job failures (selectors timing out, clicks not working, elements not found)\n- When you need to test or prototype Playwright interactions before codifying them\n- When you need to save or restore login sessions for authenticated pages\n- When you need to understand what's on a page (use the snapshot command)\n- When scraping dynamic content that requires JavaScript execution\n\nWHEN NOT TO USE THIS SKILL:\n- When you only need to read static web content (use read_web_page instead)\n- When you need to modify browser agent source code (edit files directly)\n- When you need to run a full browser agent job end-to-end (use npx browser-agent CLI)"
+license: MIT
+metadata:
+  author: saffron-health
+  version: "0.2.2"
 ---
 
 # Browser Integration with Libretto CLI
@@ -41,16 +45,24 @@ Built-in sessions: `default`, `dev-server`, `browser-agent`.
 
 Add `--visualize` to any `exec` command to show a ghost cursor and element highlight before each action executes. Use it when the user wants to see what will be clicked/filled before it happens.
 
-## Workflow Pause/Resume (`ctx.pause()`)
+## Workflow Pause/Resume (`pause()`)
 
-Workflows pause from inside the workflow function by calling `await ctx.pause()`.
+Workflows pause by calling `await pause()` (imported from `"libretto"`). In production (`NODE_ENV=production`) it is a no-op.
 
 - There are no pause options to pass at call sites. Pause is session-scoped and resolved from the active session.
-- `npx libretto run ...` waits until the workflow either completes or hits the next `ctx.pause()`.
+- `npx libretto run ...` waits until the workflow either completes or hits the next `pause()`.
 - On pause, the workflow process stays alive and keeps browser/session state.
 - `npx libretto resume --session <name>` sends resume signal and then waits until completion or the next pause.
 - For multi-pause workflows, call `resume` repeatedly until the workflow completes.
 
+## Workflow Failures and Reruns
+
+- `npx libretto run` always uses the same failure-inspection behavior; no separate debug flag is needed.
+- On workflow failure, Libretto prints the workflow error and keeps the browser open for inspection.
+- After a failed run, use `npx libretto exec --session <name> "<code>"` to inspect or prototype fixes.
+- Re-running `npx libretto run ... --session <name>` re-runs the workflow for that session.
+- If the same session still has a failed workflow worker, Libretto releases that failed worker process before rerunning.
+
 ## Globals Available in `exec`
 
 `page`, `context`, `state`, `browser`, `networkLog({ last?, filter?, method? })`, `actionLog({ last?, filter?, action?, source? })`, `console`, `fetch`, `Buffer`, `URL`, `setTimeout`
@@ -214,7 +226,8 @@ When the snapshot doesn't give you enough detail — why an element is hidden, w
 
 - **Never use `page.screenshot()` via `exec`.** Use `npx libretto snapshot` instead — it captures the viewport, sends the screenshot + HTML to a vision model, and returns actionable selectors. The `fullPage` option is especially dangerous — it scrolls the entire page to stitch a screenshot, which can crash JavaScript-heavy pages (especially EMR portals like eClinicalWorks).
 - **Never run `exec` commands in parallel.** Always wait for one `exec` to finish before starting the next. Do not use `run_in_background` for `exec` calls. Running simultaneous `exec` calls opens multiple CDP connections to the same page, which corrupts the page state and kills the browser.
-- `open` and `run` require an available session. If the session is already active, Libretto fails fast and asks you to close the existing session or use a different `--session`.
+- `open` requires an available session. If the session is already active, Libretto fails fast and asks you to close the existing session or use a different `--session`.
+- `run` also requires an available session, except for the specific case of a prior failed `run` in the same session; in that case Libretto releases the failed worker and allows rerun.
 - Use `return <value>` in `exec` to print results. Strings print raw; objects print as JSON.
 - For iframe content, access via `page.locator('iframe[name="..."]').contentFrame()`.
 - Multiple sessions allow parallel browser instances: `--session test1`, `--session test2`.
@@ -313,7 +326,7 @@ The browser stays open indefinitely until explicitly closed with `npx libretto c
 
 If the site requires login, ask the user how auth should work in the generated workflow:
 
-1. Save a local profile (recommended for local runs): open in `--headed`, have the user log in manually, run `npx libretto save <domain>`, and generate workflow metadata with `authProfile: { type: "local", domain: "<hostname>" }`.
+1. Save a local profile (recommended for local runs): open in `--headed`, have the user log in manually, run `npx libretto save <domain>`, and pass `--auth-profile <domain>` when running the workflow (e.g. `npx libretto run ./file.ts main --auth-profile example.com`).
 2. Use user-managed credential logic in Playwright code (no local profile dependency).
 
 If local profile is chosen, include this warning in your generated workflow guidance: local profiles are machine-local (other users/environments will not have them), and sessions can expire so re-login/re-save may be required.

package/skill/code-generation-rules.md

@@ -7,7 +7,7 @@ These rules apply when generating production TypeScript files from interactive b
 Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <exportName>`. Import `workflow` and its types from `"libretto"`:
 
 ```typescript
-import { workflow, type LibrettoWorkflowContext } from "libretto";
+import { workflow, pause, type LibrettoWorkflowContext } from "libretto";
 
 type Input = {
   // Define the expected input shape — passed via --params JSON
@@ -21,15 +21,11 @@ type Output = {
 };
 
 export const myWorkflow = workflow<Input, Output>(
-  {
-    // If the site requires a saved login session:
-    authProfile: { type: "local", domain: "example.com" },
-    // Omit authProfile if no login is needed
-  },
-  async (ctx: LibrettoWorkflowContext, input: Input): Promise<Output> => {
+  {},
+  async (ctx, input): Promise<Output> => {
     const { page } = ctx;
 
-    // workflow logic here — use ctx.page, ctx.context, ctx.browser
+    // workflow logic here — use ctx.page, ctx.logger, ctx.services
     await page.goto("https://example.com");
     // ...
 
@@ -41,11 +37,48 @@ export const myWorkflow = workflow<Input, Output>(
 **Key points:**
 
 - The named export (e.g., `myWorkflow`) is what you pass as the second arg to `npx libretto run ./file.ts myWorkflow`
-- `ctx` provides `page`, `context`, `browser`, `session`, `logger`, `headless`, `integrationPath`, `exportName`
+- `ctx` provides `page`, `logger`, and `services` (generic, default `{}`)
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
-- If `authProfile` is set with a domain, libretto loads the saved browser profile for that domain (created via `npx libretto save <domain>`)
+- If the site requires a saved login session, pass `--auth-profile <domain>` to the CLI (created via `npx libretto save <domain>`)
+- Use `await pause()` (imported from `"libretto"`) to pause the workflow for debugging. It is a no-op in production.
 - The browser is launched and closed automatically by the CLI — do not launch or close it in the handler
 
+## Passing Application Dependencies via Services
+
+Use the third generic on `workflow<Input, Output, Services>` to inject
+dependencies that exist in your application but not in libretto's runtime
+(DB transactions, API clients, caches, etc.):
+
+```typescript
+import { type Transaction } from "./db";
+
+type MyServices = { tx?: Transaction };
+
+export const myWorkflow = workflow<Input, Output, MyServices>(
+  {},
+  async (ctx, input) => {
+    if (ctx.services.tx) {
+      await ctx.services.tx.insert(/* ... */);
+    } else {
+      ctx.logger.info("No DB transaction — skipping write");
+    }
+    // ... browser automation ...
+  },
+);
+```
+
+In production, the caller passes services when invoking `.run()`:
+
+```typescript
+await myWorkflow.run(
+  { page, logger, services: { tx } },
+  input,
+);
+```
+
+When running standalone via `npx libretto run`, services defaults to `{}`,
+so mark fields optional for anything unavailable in that context.
+
 ## Playwright Locators for DOM Interaction
 
 Generated code must use Playwright locator APIs for all DOM interactions. Do not use `page.evaluate()` with `document.querySelector`, `querySelectorAll`, `textContent`, `click()`, or other DOM APIs when a Playwright locator can do the same thing.