libretto 0.3.0 → 0.3.2

package/README.md

@@ -1,156 +1,82 @@
 # Libretto
 
-AI-powered browser automation library and CLI built on Playwright.
+Libretto gives your coding agent superpowers for building, debugging, and maintaining browser RPA integrations.
+
+It is designed for engineering teams that automate workflows in web apps and want to move from brittle browser-only scripts to faster, more reliable network-first integrations.
 
 ## Installation
 
 ```bash
-pnpm add libretto playwright zod
-npx libretto init
+npm install --save-dev libretto
 ```
 
-> **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": ["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
-
-### 1. Configure your LLM
-
-The easiest way is to use the built-in Vercel AI SDK adapter with any compatible provider:
-
-```typescript
-import { createLLMClientFromModel } from "libretto/llm";
-import { openai } from "@ai-sdk/openai";
-
-const llmClient = createLLMClientFromModel(openai("gpt-4o"));
-```
+Chromium is downloaded automatically via a `postinstall` script. If postinstall scripts are disabled (e.g. `--ignore-scripts`, common in monorepos), run init manually:
 
-Or use any other provider:
+```bash
+npx libretto init
+```
 
-```typescript
-import { createLLMClientFromModel } from "libretto";
-import { anthropic } from "@ai-sdk/anthropic";
+This installs the Chromium browser binary and optionally configures an AI subagent (Gemini, Claude, or Codex) that can analyze page snapshots without consuming the coding agent's context window.
 
-const llmClient = createLLMClientFromModel(anthropic("claude-sonnet-4-20250514"));
-```
+## Usage
 
-You can also implement the `LLMClient` interface directly for full control:
+Libretto is usually used through prompts with the Libretto skill.
 
-```typescript
-import type { LLMClient } from "libretto";
+### One-shot script generation
 
-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 (may include images)
-  },
-};
+```text
+Use the Libretto skill. Go on LinkedIn and scrape the first 10 posts for content, who posted it, the number of reactions, the first 25 comments, and the first 25 reposts.
 ```
 
-### 2. Write a workflow
+### Interactive script building
 
-```typescript
-import { workflow } from "libretto";
-import { z } from "zod";
+```text
+Use the Libretto skill. Let's interactively build a script to scrape scheduling info from the eClinicalWorks EHR.
+```
 
-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);
+### Convert browser automation to network requests
 
-    const data = await ctx.extract({
-      instruction: "Extract the product name and price",
-      schema: z.object({ name: z.string(), price: z.number() }),
-    });
+```text
+We have a browser script at ./integration.ts that automates going to Hacker News and getting the first 10 posts. Convert it to direct network scripts instead. Use the Libretto skill.
+```
 
-    return data;
-  },
-});
+### Fix broken integrations
+
+```text
+We have a browser script at ./integration.ts that is supposed to go to Availity and perform an eligibility check for a patient. But I'm getting a broken selector error when I run it. Fix it. Use the Libretto skill.
 ```
 
-### 3. Run it
+You can also run workflows directly from the CLI:
 
 ```bash
-npx libretto run ./workflows/extract-product.ts extractProduct \
-  --params '{"url": "https://example.com/product"}'
+npx libretto help
+npx libretto run ./integration.ts main
 ```
 
-## CLI Commands
+## The `.libretto/` directory
 
-```
-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
-```
+Libretto stores local runtime state in a `.libretto/` directory at your project root. Sensitive directories (`sessions/` and `profiles/`) are automatically git-ignored via `.libretto/.gitignore`.
 
-Run `npx libretto help` for the full list.
-
-## Module Exports
-
-| 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                       |
-
-## 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,
-);
-```
+- **`profiles/<domain>.json`** — Saved browser sessions (cookies, localStorage) for authenticated sites. Created via `npx libretto save <domain>`. Machine-local and never committed.
+- **`sessions/<name>/`** — Per-session runtime state:
+  - `state.json` — Session metadata (debug port, PID, status)
+  - `logs.jsonl` — Structured session logs
+  - `network.jsonl` — Captured network requests (URLs, methods, headers, response status)
+  - `actions.jsonl` — Recorded user actions (clicks, fills, navigations)
+  - `snapshots/` — Screenshot PNGs and HTML snapshots captured via `npx libretto snapshot`
+- **`ai.json`** — AI runtime configuration set via `npx libretto ai configure`.
 
-No need to write custom wrappers — `createLLMClientFromModel` bridges any
-Vercel AI SDK provider into the `LLMClient` interface that recovery helpers expect.
+## Authors
 
-## Links
+Maintained by the team at [Saffron Health](https://saffron.health).
 
-- [GitHub](https://github.com/saffron-health/libretto)
-- [Issues](https://github.com/saffron-health/libretto/issues)
+## Development
+
+For local development in this repository:
+
+```bash
+pnpm i
+pnpm build
+pnpm type-check
+pnpm test
+```

package/dist/cli/cli.js

@@ -0,0 +1,298 @@
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+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,
+  createLoggerForSession,
+  ensureLibrettoSetup
+} from "./core/context.js";
+import {
+  listSessionsWithStateFile,
+  validateSessionName
+} from "./core/session.js";
+const AUTO_SESSION_COMMANDS = /* @__PURE__ */ new Set(["open", "run"]);
+const SESSION_OPTIONAL_COMMANDS = /* @__PURE__ */ new Set(["help", "--help", "-h", "init", "ai"]);
+const CLI_COMMANDS = /* @__PURE__ */ new Set([
+  "open",
+  "run",
+  "ai",
+  "save",
+  "exec",
+  "snapshot",
+  "network",
+  "actions",
+  "pages",
+  "resume",
+  "close",
+  "init",
+  "--help",
+  "-h",
+  "help"
+]);
+function printUsage() {
+  console.log(`Usage: libretto-cli <command> [--session <name>]
+
+Commands:
+  init [--skip-browsers] Initialize libretto (install browsers, check AI setup)
+  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>] [--tsconfig <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)
+  snapshot [--objective <text> --context <text>]  Capture PNG + HTML; analyze when objective is provided (context optional)
+  network [--last N] [--filter regex] [--method M] [--clear]  View captured network requests
+  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 [--all] [--force]  Close the browser for the session, or all tracked sessions with --all
+
+Options:
+  --session <name>        Use a named session
+                          If omitted for open/run, a session id is auto-generated
+                          All other stateful commands require --session
+                          Built-in sessions: default, dev-server, browser-agent
+
+Examples:
+  libretto-cli open https://linkedin.com
+
+  # ... manually log in ...
+  libretto-cli save linkedin.com
+  # Next time you open linkedin.com, you'll be logged in automatically
+
+  libretto-cli exec "await page.locator('button:has-text(\\"Sign in\\")').click()"
+  libretto-cli exec "await page.fill('input[name=\\"email\\"]', 'test@example.com')"
+  libretto-cli ai configure codex
+  libretto-cli ai configure claude
+  libretto-cli ai configure gemini
+  libretto-cli ai configure <codex|claude|gemini> -- <command prefix...>
+  libretto-cli snapshot
+  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
+  libretto-cli open https://site2.com --session test2
+  libretto-cli exec "return await page.title()" --session test1
+
+Available in exec:
+  page, context, state, browser, networkLog, actionLog
+
+Profiles:
+  Profiles are saved to .libretto/profiles/<domain>.json (git-ignored)
+  They persist cookies, localStorage, and session data across browser launches.
+  Local profiles are machine-local and are not shared with other users/environments.
+  Sessions can expire; if run fails auth, log in again and re-save the profile.
+
+Sessions:
+  Session state is stored in .libretto/sessions/<session>/state.json
+  CLI logs are stored in .libretto/sessions/<session>/logs.jsonl
+  Each session runs an isolated browser instance on a dynamic port.
+`);
+}
+function filterSessionArgs(args) {
+  const result = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--session") {
+      i++;
+    } else {
+      result.push(args[i]);
+    }
+  }
+  return result;
+}
+function parseSessionForLog(rawArgs) {
+  const idx = rawArgs.indexOf("--session");
+  if (idx < 0) return null;
+  const value = rawArgs[idx + 1];
+  if (!value || value.startsWith("--") || CLI_COMMANDS.has(value)) {
+    return null;
+  }
+  try {
+    validateSessionName(value);
+    return value;
+  } catch {
+    return null;
+  }
+}
+function hasExplicitSession(rawArgs) {
+  return rawArgs.includes("--session");
+}
+function randomSessionId() {
+  const digits = Math.floor(Math.random() * 1e4).toString().padStart(4, "0");
+  return `ses-${digits}`;
+}
+function generateSessionId() {
+  const activeSessions = new Set(listSessionsWithStateFile());
+  for (let attempt = 0; attempt < 1e4; attempt += 1) {
+    const candidate = randomSessionId();
+    if (!activeSessions.has(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    "Could not generate an available session id. Close an existing session and try again."
+  );
+}
+function hasExecCodeArg(filteredArgs) {
+  for (let i = 1; i < filteredArgs.length; i += 1) {
+    const token = filteredArgs[i];
+    if (!token) continue;
+    if (token === "--") {
+      return filteredArgs.length > i + 1;
+    }
+    if (token === "--visualize") {
+      continue;
+    }
+    if (token === "--page") {
+      const maybeValue = filteredArgs[i + 1];
+      if (maybeValue && !maybeValue.startsWith("--")) {
+        i += 1;
+      }
+      continue;
+    }
+    if (token.startsWith("--page=")) {
+      continue;
+    }
+    if (token.startsWith("-")) {
+      continue;
+    }
+    return true;
+  }
+  return false;
+}
+function commandNeedsSession(command, rawArgs, filteredArgs) {
+  if (AUTO_SESSION_COMMANDS.has(command)) return false;
+  if (SESSION_OPTIONAL_COMMANDS.has(command)) return false;
+  if (command === "close" && rawArgs.includes("--all")) return false;
+  if (command === "close" && rawArgs.includes("--force")) return false;
+  if (command === "exec" && !hasExecCodeArg(filteredArgs)) return false;
+  if (command === "save" && filteredArgs.length <= 1) return false;
+  if (!CLI_COMMANDS.has(command)) return false;
+  return true;
+}
+function resolveSessionArgs(rawArgs) {
+  const filtered = filterSessionArgs(rawArgs);
+  const command = filtered[0];
+  const explicitSession = parseSessionForLog(rawArgs);
+  if (!command) {
+    return {
+      args: rawArgs,
+      generatedSession: null,
+      resolvedSession: explicitSession
+    };
+  }
+  if (hasExplicitSession(rawArgs)) {
+    return {
+      args: rawArgs,
+      generatedSession: null,
+      resolvedSession: explicitSession
+    };
+  }
+  if (!AUTO_SESSION_COMMANDS.has(command)) {
+    return {
+      args: rawArgs,
+      generatedSession: null,
+      resolvedSession: null
+    };
+  }
+  const generatedSession = generateSessionId();
+  return {
+    args: [...rawArgs, "--session", generatedSession],
+    generatedSession,
+    resolvedSession: generatedSession
+  };
+}
+function createParser(logger) {
+  let parser = yargs(hideBin(process.argv)).scriptName("libretto-cli").parserConfiguration({ "populate--": true }).option("session", {
+    type: "string",
+    describe: "Use a named session",
+    global: true,
+    requiresArg: true
+  }).middleware((argv) => {
+    if (argv.session !== void 0) {
+      validateSessionName(String(argv.session));
+    }
+  }).exitProcess(false).help(false).version(false).fail((msg, err) => {
+    if (err) throw err;
+    throw new Error(msg || "Command failed");
+  });
+  parser = registerBrowserCommands(parser, logger);
+  parser = registerExecutionCommands(parser, logger);
+  parser = registerLogCommands(parser);
+  parser = registerAICommands(parser);
+  parser = registerSnapshotCommands(parser, logger);
+  parser = registerInitCommand(parser);
+  parser = parser.command("help", "Show usage", () => {
+  }, () => {
+    printUsage();
+  });
+  return parser;
+}
+async function runLibrettoCLI() {
+  const rawArgs = process.argv.slice(2);
+  let exitCode = 0;
+  let effectiveArgs = rawArgs;
+  let generatedSession = null;
+  let resolvedSession = null;
+  ({
+    args: effectiveArgs,
+    generatedSession,
+    resolvedSession
+  } = resolveSessionArgs(rawArgs));
+  ensureLibrettoSetup();
+  const args = filterSessionArgs(effectiveArgs);
+  const command = args[0];
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    printUsage();
+    process.exit(exitCode);
+    return;
+  }
+  if (!CLI_COMMANDS.has(command)) {
+    console.error(`Unknown command: ${command}
+`);
+    printUsage();
+    process.exit(1);
+    return;
+  }
+  if (!hasExplicitSession(effectiveArgs) && commandNeedsSession(command, effectiveArgs, args)) {
+    console.error(
+      [
+        `Missing required --session for "${command}".`,
+        "Pass --session <name>, or use open/run without --session to auto-create one."
+      ].join("\n")
+    );
+    process.exit(1);
+    return;
+  }
+  const sessionForLogger = resolvedSession ?? "cli";
+  const logger = createLoggerForSession(sessionForLogger);
+  try {
+    const parser = createParser(logger);
+    await parser.parseAsync(effectiveArgs);
+  } catch (err) {
+    logger.error("cli-error", {
+      error: err,
+      args: rawArgs,
+      effectiveArgs,
+      generatedSession
+    });
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    exitCode = 1;
+  } finally {
+    await closeLogger(logger);
+  }
+  process.exit(exitCode);
+}
+export {
+  runLibrettoCLI
+};

package/dist/cli/commands/ai.js

@@ -0,0 +1,21 @@
+import { runAiConfigure } from "../core/ai-config.js";
+function registerAICommands(yargs) {
+  return yargs.command(
+    "ai configure [preset]",
+    "Configure AI runtime",
+    (cmd) => cmd.option("clear", { type: "boolean", default: false }),
+    (argv) => {
+      const customPrefix = Array.isArray(argv["--"]) ? argv["--"] : [];
+      runAiConfigure({
+        clear: Boolean(argv.clear),
+        preset: argv.preset,
+        customPrefix
+      }, {
+        configureCommandName: "libretto-cli ai configure"
+      });
+    }
+  );
+}
+export {
+  registerAICommands
+};

package/dist/cli/commands/browser.js

@@ -0,0 +1,103 @@
+import {
+  runClose as runCloseWithLogger,
+  runCloseAll as runCloseAllWithLogger,
+  runOpen,
+  runPages,
+  runSave
+} from "../core/browser.js";
+import { withSessionLogger } from "../core/context.js";
+function registerBrowserCommands(yargs, logger) {
+  return yargs.command(
+    "open [url]",
+    "Launch browser and open URL (headed by default)",
+    (cmd) => cmd.option("headed", {
+      type: "boolean",
+      default: false
+    }).option("headless", {
+      type: "boolean",
+      default: false
+    }).option("viewport", {
+      type: "string",
+      describe: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)"
+    }),
+    async (argv) => {
+      const hasHeadedFlag = Boolean(argv.headed);
+      const hasHeadlessFlag = Boolean(argv.headless);
+      if (hasHeadedFlag && hasHeadlessFlag) {
+        throw new Error("Cannot pass both --headed and --headless.");
+      }
+      const headed = hasHeadedFlag || !hasHeadlessFlag;
+      const url = argv.url;
+      if (!url) {
+        throw new Error(
+          "Usage: libretto-cli open <url> [--headless] [--viewport WxH] [--session <name>]"
+        );
+      }
+      const viewportArg = argv.viewport;
+      let viewport;
+      if (viewportArg) {
+        const match = viewportArg.match(/^(\d+)x(\d+)$/i);
+        if (!match) {
+          throw new Error(
+            "Invalid --viewport format. Expected WIDTHxHEIGHT (e.g. 1920x1080)."
+          );
+        }
+        const w = Number(match[1]);
+        const h = Number(match[2]);
+        if (w < 1 || h < 1) {
+          throw new Error(
+            "Invalid --viewport dimensions. Width and height must be at least 1."
+          );
+        }
+        viewport = { width: w, height: h };
+      }
+      await runOpen(url, headed, String(argv.session), logger, { viewport });
+    }
+  ).command(
+    "save [urlOrDomain]",
+    "Save current browser session",
+    (cmd) => cmd,
+    async (argv) => {
+      const urlOrDomain = argv.urlOrDomain;
+      if (!urlOrDomain) {
+        throw new Error("Usage: libretto-cli save <url|domain> [--session <name>]");
+      }
+      await runSave(urlOrDomain, String(argv.session), 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.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) => {
+    await runCloseWithLogger(session, logger);
+  });
+}
+export {
+  registerBrowserCommands,
+  runClose
+};