libretto 0.2.3 → 0.2.5

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.3",
+  "version": "0.2.5",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -105,15 +105,9 @@
     "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,9 +37,10 @@ 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
 
 ## Playwright Locators for DOM Interaction