libretto 0.2.3 → 0.2.5

package/README.md

@@ -1,231 +1,125 @@
 # Libretto
 
-A TypeScript library for browser automation with AI-powered recovery and data extraction. Built on Playwright.
-
-## Features
-
-- **AI-powered recovery** — Vision-based agent that automatically detects and dismisses popups or obstacles using an LLM
-- **Structured data extraction** — Extract typed data from web pages using AI vision + Zod schemas
-- **Error detection** — Classify form/submission errors against known patterns
-- **In-browser network requests** — Execute authenticated fetch calls inside the page context with optional Zod validation
-- **File downloads** — Trigger and intercept file downloads via click, with optional save-to-disk
-- **Dry-run mode** — Skip mutations in development without side effects
-- **Pluggable LLM** — Bring your own LLM provider (Claude, GPT, etc.) via a simple interface
-- **Pluggable logging** — All runtime functions accept an optional logger; defaults to console output
+AI-powered browser automation library and CLI built on Playwright.
 
 ## Installation
 
 ```bash
 pnpm add libretto playwright zod
+npx libretto init
 ```
 
-`playwright` and `zod` are peer dependencies.
+> **pnpm users:** add `onlyBuiltDependencies` to your `package.json` to allow
+> Playwright's postinstall script to run:
+>
+> ```jsonc
+> // package.json
+> {
+>   "pnpm": {
+>     "onlyBuiltDependencies": ["playwright"]
+>   }
+> }
+> ```
 
 ## Quick Start
 
-```typescript
-import { chromium } from "playwright";
-import { extractFromPage, attemptWithRecovery } from "libretto";
-
-const browser = await chromium.launch();
-const page = await browser.newPage();
-
-await page.goto("https://example.com/login");
-await page.fill("#email", "user@example.com");
-await page.fill("#password", "secret");
-
-// Automatically retry with AI popup recovery on failure
-await attemptWithRecovery(page, () => page.click('button[type="submit"]'));
-
-await browser.close();
-```
-
-## Runtime Functions
+### 1. Configure your LLM
 
-### Recovery
-
-#### `attemptWithRecovery(page, fn, logger?, llmClient?)`
-
-Executes a function and, if it fails, uses AI vision to detect and dismiss popups before retrying once.
+The easiest way is to use the built-in Vercel AI SDK adapter with any compatible provider:
 
 ```typescript
-import { attemptWithRecovery } from "libretto";
+import { createLLMClientFromModel } from "libretto/llm";
+import { openai } from "@ai-sdk/openai";
 
-await attemptWithRecovery(page, async () => {
-  await page.click('button[type="submit"]');
-}, undefined, llmClient);
+const llmClient = createLLMClientFromModel(openai("gpt-4o"));
 ```
 
-#### `executeRecoveryAgent(page, instruction, logger?, llmClient?)`
-
-Runs a multi-step vision-based recovery agent that takes screenshots and executes browser actions (click, type, scroll, etc.) to resolve obstacles.
+Or use any other provider:
 
 ```typescript
-import { executeRecoveryAgent } from "libretto";
-
-await executeRecoveryAgent(
-  page,
-  "Close the cookie consent banner",
-  undefined,
-  llmClient,
-);
-```
+import { createLLMClientFromModel } from "libretto";
+import { anthropic } from "@ai-sdk/anthropic";
 
-#### `detectSubmissionError(page, error, logContext, llmClient, knownErrors?, logger?)`
-
-Uses a screenshot + LLM vision to detect if an error occurred during a form submission. Matches against provided known error patterns.
-
-```typescript
-import { detectSubmissionError } from "libretto";
-
-try {
-  await page.click("#submit");
-} catch (error) {
-  const result = await detectSubmissionError(page, error, "checkout", llmClient, [
-    { id: "duplicate", errorPatterns: ["already exists"], userMessage: "Duplicate entry" },
-  ]);
-  console.log(result.errorId, result.message);
-}
+const llmClient = createLLMClientFromModel(anthropic("claude-sonnet-4-20250514"));
 ```
 
-### Data Extraction
-
-#### `extractFromPage(options)`
-
-Extract structured data from a page using AI vision + a Zod schema.
-
-```typescript
-import { extractFromPage } from "libretto";
-import { z } from "zod";
-
-const result = await extractFromPage({
-  page,
-  llmClient,
-  instruction: "Extract the product name and price",
-  schema: z.object({
-    name: z.string(),
-    price: z.number(),
-  }),
-  selector: ".product-card", // optional — scopes to a specific element
-});
-// result is typed as { name: string; price: number }
-```
-
-### Network
-
-#### `pageRequest(page, config, options?)`
-
-Executes a fetch call inside the browser context via `page.evaluate()`, inheriting the page's cookies and auth state. Supports optional Zod validation.
-
-```typescript
-import { pageRequest } from "libretto";
-import { z } from "zod";
-
-const data = await pageRequest(
-  page,
-  {
-    url: "https://example.com/api/profile",
-    method: "GET",
-    responseType: "json",
-  },
-  {
-    schema: z.object({ name: z.string(), email: z.string() }),
-  },
-);
-```
-
-### Downloads
-
-#### `downloadViaClick(page, selector, options?)`
-
-Triggers a file download by clicking a DOM element and intercepts the result.
-
-```typescript
-import { downloadViaClick } from "libretto";
-
-const { buffer, filename } = await downloadViaClick(page, "#download-btn");
-```
-
-#### `downloadAndSave(page, selector, options?)`
-
-Same as `downloadViaClick` but also writes the file to disk.
-
-```typescript
-import { downloadAndSave } from "libretto";
-
-const { savedTo } = await downloadAndSave(page, "#export-csv", {
-  savePath: "./exports/report.csv",
-});
-```
-
-## LLM Client Interface
-
-Provide your own implementation backed by any LLM provider:
+You can also implement the `LLMClient` interface directly for full control:
 
 ```typescript
 import type { LLMClient } from "libretto";
 
-const myLLMClient: LLMClient = {
+const llmClient: LLMClient = {
   async generateObject({ prompt, schema, temperature }) {
     // Call your LLM, return parsed + validated result
   },
   async generateObjectFromMessages({ messages, schema, temperature }) {
-    // Call your LLM with message history, return parsed + validated result
+    // Call your LLM with message history (may include images)
   },
 };
 ```
 
-## Logging
-
-All runtime functions accept an optional `logger` parameter. When omitted, output goes to `console.log` with `[INFO]`, `[WARN]`, `[ERROR]` prefixes.
-
-For structured logging, use the built-in `Logger` class:
+### 2. Write a workflow
 
 ```typescript
-import { Logger, createFileLogSink, prettyConsoleSink } from "libretto";
+import { workflow } from "libretto";
+import { z } from "zod";
 
-const logger = new Logger()
-  .withSink(createFileLogSink({ filePath: "./app.log" }))
-  .withSink(prettyConsoleSink);
+export default workflow({
+  name: "extract-product",
+  schema: z.object({ url: z.string() }),
+  handler: async (ctx) => {
+    const page = ctx.page;
+    await page.goto(ctx.params.url);
 
-const scoped = logger.withScope("auth");
-scoped.info("login attempt", { user: "alice" });
-scoped.error("login failed", { reason: "bad password" });
-```
+    const data = await ctx.extract({
+      instruction: "Extract the product name and price",
+      schema: z.object({ name: z.string(), price: z.number() }),
+    });
 
-## Module Exports
+    return data;
+  },
+});
+```
 
-Libretto provides granular imports:
+### 3. Run it
 
-| Import                   | Contents                                                  |
-| ------------------------ | --------------------------------------------------------- |
-| `libretto`               | Everything                                                |
-| `libretto/logger`        | `Logger`, `defaultLogger`, sinks                          |
-| `libretto/recovery`      | `attemptWithRecovery`, `executeRecoveryAgent`, `detectSubmissionError` |
-| `libretto/extract`       | `extractFromPage`                                         |
-| `libretto/network`       | `pageRequest`                                             |
-| `libretto/download`      | `downloadViaClick`, `downloadAndSave`                     |
-| `libretto/debug`         | `debugPause`                                              |
-| `libretto/config`        | `isDryRun`, `isDebugMode`, `shouldPauseBeforeMutation`    |
-| `libretto/instrumentation` | `instrumentPage`, `installInstrumentation`              |
-| `libretto/visualization` | Ghost cursor and highlight helpers                        |
-| `libretto/run`           | `launchBrowser`                                           |
-| `libretto/state`         | Session state serialization and parsing                   |
-| `libretto/llm`           | `LLMClient` type                                          |
+```bash
+npx libretto run ./workflows/extract-product.ts extractProduct \
+  --params '{"url": "https://example.com/product"}'
+```
 
-## Configuration
+## CLI Commands
 
-Runtime flags via environment variables:
+```
+npx libretto init                  # Copy skills, install Playwright Chromium
+npx libretto open <url>            # Launch browser and open URL
+npx libretto run <file> <export>   # Run a workflow
+npx libretto ai configure <preset> # Configure AI runtime (codex, claude, gemini)
+npx libretto snapshot              # Capture page screenshot + HTML
+npx libretto exec <code>           # Execute Playwright code
+```
 
-| Env Variable          | Effect                                              |
-| --------------------- | --------------------------------------------------- |
-| `LIBRETTO_DEBUG`      | Enable debug mode                                   |
-| `LIBRETTO_DRY_RUN`   | Enable dry-run mode (defaults to `true` in development) |
+Run `npx libretto help` for the full list.
 
-## Development
+## Module Exports
 
-```bash
-pnpm install
-pnpm build         # compile to dist/
-pnpm type-check    # typecheck without emitting
-```
+| Import                     | Contents                                                      |
+| -------------------------- | ------------------------------------------------------------- |
+| `libretto`                 | Everything                                                    |
+| `libretto/llm`             | `LLMClient` type, `createLLMClient`, `createLLMClientFromModel` |
+| `libretto/recovery`        | `attemptWithRecovery`, `executeRecoveryAgent`, `detectSubmissionError` |
+| `libretto/extract`         | `extractFromPage`                                             |
+| `libretto/network`         | `pageRequest`                                                 |
+| `libretto/download`        | `downloadViaClick`, `downloadAndSave`                         |
+| `libretto/logger`          | `Logger`, `defaultLogger`, sinks                              |
+| `libretto/debug`           | `debugPause`                                                  |
+| `libretto/config`          | `isDryRun`, `isDebugMode`, `shouldPauseBeforeMutation`        |
+| `libretto/instrumentation` | `instrumentPage`, `installInstrumentation`                    |
+| `libretto/visualization`   | Ghost cursor and highlight helpers                            |
+| `libretto/run`             | `launchBrowser`                                               |
+| `libretto/state`           | Session state serialization and parsing                       |
+
+## Links
+
+- [GitHub](https://github.com/saffron-health/libretto)
+- [Issues](https://github.com/saffron-health/libretto/issues)

package/dist/cli/cli.js

@@ -4,6 +4,7 @@ import { registerAICommands } from "./commands/ai.js";
 import { registerBrowserCommands } from "./commands/browser.js";
 import { registerExecutionCommands } from "./commands/execution.js";
 import { registerLogCommands } from "./commands/logs.js";
+import { registerInitCommand } from "./commands/init.js";
 import { registerSnapshotCommands } from "./commands/snapshot.js";
 import {
   closeLogger,
@@ -26,6 +27,7 @@ const CLI_COMMANDS = /* @__PURE__ */ new Set([
   "pages",
   "resume",
   "close",
+  "init",
   "--help",
   "-h",
   "help"
@@ -34,9 +36,10 @@ function printUsage() {
   console.log(`Usage: libretto-cli <command> [--session <name>]
 
 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)
@@ -45,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")
@@ -68,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
@@ -160,6 +165,7 @@ function createParser(logger) {
   parser = registerLogCommands(parser);
   parser = registerAICommands(parser);
   parser = registerSnapshotCommands(parser, logger);
+  parser = registerInitCommand(parser);
   parser = parser.command("help", "Show usage", () => {
   }, () => {
     printUsage();

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/commands/init.js

@@ -0,0 +1,95 @@
+import { existsSync, mkdirSync, cpSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { REPO_ROOT } from "../core/context.js";
+function getSkillSourceDir() {
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = join(thisDir, "..", "..", "..");
+  const skillDir = join(pkgRoot, "skill");
+  if (existsSync(skillDir)) return skillDir;
+  const skillsDir = join(pkgRoot, "skills");
+  if (existsSync(skillsDir)) return skillsDir;
+  throw new Error(
+    "Could not find skill/ or skills/ directory in the libretto package."
+  );
+}
+function copySkills() {
+  const src = getSkillSourceDir();
+  const files = readdirSync(src);
+  if (files.length === 0) {
+    console.log("  No skill files found to copy.");
+    return;
+  }
+  const targets = [
+    join(REPO_ROOT, ".agents", "skills", "libretto"),
+    join(REPO_ROOT, ".claude", "skills", "libretto")
+  ];
+  for (const target of targets) {
+    mkdirSync(target, { recursive: true });
+    cpSync(src, target, { recursive: true });
+    console.log(`  \u2713 Copied skill files to ${target}`);
+  }
+}
+function installBrowsers() {
+  console.log("\nInstalling Playwright Chromium...");
+  const result = spawnSync("npx", ["playwright", "install", "chromium"], {
+    stdio: "inherit",
+    shell: true
+  });
+  if (result.status === 0) {
+    console.log("  \u2713 Playwright Chromium installed");
+  } else {
+    console.error(
+      "  \u2717 Failed to install Playwright Chromium. Run manually: npx playwright install chromium"
+    );
+  }
+}
+function checkSnapshotLLM() {
+  const hasAnyCreds = process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY;
+  console.log("\nSnapshot LLM configuration:");
+  if (hasAnyCreds) {
+    console.log("  \u2713 LLM credentials detected");
+  } else {
+    console.log("  \u2717 No LLM credentials found.");
+    console.log("    Set one of the following environment variables:");
+    console.log("      GOOGLE_CLOUD_PROJECT  (for Vertex AI / Gemini)");
+    console.log("      ANTHROPIC_API_KEY     (for Claude)");
+    console.log("      OPENAI_API_KEY        (for GPT)");
+    console.log(
+      "    Then configure via: npx libretto ai configure <preset>"
+    );
+  }
+}
+function registerInitCommand(yargs) {
+  return yargs.command(
+    "init",
+    "Initialize libretto in the current project",
+    (cmd) => cmd.option("skip-browsers", {
+      type: "boolean",
+      default: false,
+      describe: "Skip Playwright Chromium installation"
+    }),
+    (argv) => {
+      console.log("Initializing libretto...\n");
+      console.log("Copying skill files...");
+      try {
+        copySkills();
+      } catch (err) {
+        console.error(
+          `  \u2717 ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+      if (!argv["skip-browsers"]) {
+        installBrowsers();
+      } else {
+        console.log("\nSkipping browser installation (--skip-browsers)");
+      }
+      checkSnapshotLLM();
+      console.log("\n\u2713 libretto init complete");
+    }
+  );
+}
+export {
+  registerInitCommand
+};