libretto 0.5.5 → 0.6.0

package/skills/libretto/references/code-generation-rules.md

@@ -6,7 +6,7 @@ Follow the user's existing codebase conventions, abstractions, and patterns when
 
 ## Workflow File Structure
 
-Generated files must export a `workflow()` instance so they can be run via `npx libretto run <file> <workflowName>`. Import `workflow` and its types from `"libretto"`:
+Generated files must default-export a `workflow()` instance so they can be run via `npx libretto run <file>`. Import `workflow` and its types from `"libretto"`:
 
 ```typescript
 import { workflow, pause, type LibrettoWorkflowContext } from "libretto";
@@ -22,7 +22,7 @@ type Output = {
   results: Array<{ name: string; value: string }>;
 };
 
-export const myWorkflow = workflow<Input, Output>(
+export default workflow<Input, Output>(
   "myWorkflow",
   async (ctx: LibrettoWorkflowContext, input): Promise<Output> => {
     const { session, page } = ctx;
@@ -39,7 +39,7 @@ export const myWorkflow = workflow<Input, Output>(
 Key points:
 
 - `workflow(name, handler)` takes a unique workflow name and returns the workflow object that Libretto can run.
-- `npx libretto run ./file.ts myWorkflow` resolves `myWorkflow` from the workflows exported by `./file.ts`, so export or re-export the workflow from that file directly or through a `workflows` object, and make sure the run argument matches the name passed to `workflow("myWorkflow", ...)`.
+- `npx libretto run ./file.ts` executes the file's default-exported workflow, so always use `export default workflow(...)`.
 - `ctx` provides `session` and `page`. Use `console.log`/`console.warn`/`console.error` for logging — the runtime wraps these with structured metadata automatically.
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI
 - Use `await pause(ctx.session)` (or `await pause(session)`) to pause the workflow for debugging. It is a no-op in production.

package/skills/libretto/references/configuration-file-reference.md

@@ -12,8 +12,9 @@ Use this reference when you need to inspect or change the workspace configuratio
 
 Libretto reads workspace config from `.libretto/config.json`.
 
-- The file is usually created or updated by `npx libretto ai configure ...`.
+- The file is created by `npx libretto setup` during first-time onboarding (auto-pins the default model for the detected provider) or by `npx libretto ai configure ...` for explicit overrides.
 - API credentials still come from your shell environment or `.env`. The config file stores the selected model, not the secret itself.
+- Use `npx libretto status` to inspect the current AI configuration and open sessions without changing anything.
 - For first-time setup instructions, follow the main `SKILL.md` flow instead of expanding this reference.
 
 ## Supported Settings
@@ -21,6 +22,7 @@ Libretto reads workspace config from `.libretto/config.json`.
 - `ai.model` selects the configured analysis model for `snapshot`.
 - `viewport` is an optional top-level setting used by `open` and `run` when you do not pass `--viewport`.
 - Viewport precedence is: CLI `--viewport`, then `.libretto/config.json`, then the default `1366x768`.
+- `sessionMode` sets the default session access mode for new sessions created by `open`, `connect`, and `run`. Must be `"read-only"` or `"write-access"`. When omitted, defaults to `"write-access"`. Pass `--read-only` or `--write-access` to `open`, `connect`, or `run` to override when creating a session.
 
 Example:
 
@@ -34,20 +36,23 @@ Example:
   "viewport": {
     "width": 1280,
     "height": 800
-  }
+  },
+  "sessionMode": "write-access"
 }
 ```
 
 ## Common Commands
 
 ```bash
-npx libretto init
-npx libretto ai configure openai
+npx libretto setup                                         # first-time onboarding, auto-pins default model
+npx libretto status                                        # inspect AI config and open sessions
+npx libretto ai configure openai                           # explicitly change provider/model
 npx libretto open https://app.example.com --viewport 1440x900
-npx libretto run ./integration.ts main --viewport 1440x900
+npx libretto run ./integration.ts --viewport 1440x900
 ```
 
 ## Notes
 
 - If you want a persistent default viewport for the workspace, add `viewport` to `.libretto/config.json` instead of repeating `--viewport` on every command.
-- If `snapshot` analysis is not configured yet, return to the setup steps in the main `SKILL.md` flow.
+- If `snapshot` analysis is not configured yet, run `npx libretto setup` to auto-configure, or see the main `SKILL.md` flow.
+- Run `npx libretto status` at any time to check which model is active and whether credentials are present.

package/skills/libretto-readonly/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: libretto-readonly
+description: "Read-only Libretto workflow for diagnosing live browser state without clicks, typing, navigation, or mutation requests."
+license: MIT
+metadata:
+  author: saffron-health
+  version: "0.5.6"
+---
+
+## How Libretto Read-Only Works
+
+- Use this skill when the browser session must stay strictly read-only.
+- Libretto stores read-only vs write-access on the session itself.
+- The primary inspection tools are `snapshot` and `readonly-exec`.
+- `readonly-exec` reuses Libretto's normal execution pipeline, but it only exposes read-only helpers and denies mutating Playwright methods.
+- Only a user can change the session mode for an existing session. Never change a session's mode on your own — the user must change it themselves manually.
+
+## Working Rules
+
+- Announce which session you are using and what page you are inspecting.
+- Do not use `exec`, `run`, or any direct Playwright action that could change browser or application state.
+- Do not click, type, submit forms, navigate, upload files, dispatch DOM events, or send non-GET requests.
+- Prefer `snapshot` first when the visible page state is unclear.
+- Use `readonly-exec` for focused inspection: titles, HTML, locator text, counts, visibility checks, and GET requests.
+- Keep snippets small and purpose-built. Do not run multiple `readonly-exec` commands at the same time.
+- End with diagnosis and handoff guidance, not an attempted in-browser repair.
+
+## Commands
+
+### `connect`
+
+- Use `connect` to attach to an existing CDP endpoint for a preserved browser session.
+- Use `--read-only` when creating the Libretto session handle for a preserved browser session.
+- Libretto read-only mode is enforced through Libretto commands; direct CDP clients that skip Libretto are outside this boundary.
+
+```bash
+npx libretto connect http://127.0.0.1:9222 --read-only --session failed-job-debug
+```
+
+### `pages`
+
+- Use `pages` when a popup, new tab, or second page exists.
+- If `readonly-exec` or `snapshot` complains about multiple pages, list ids first and then pass `--page`.
+
+```bash
+npx libretto pages --session failed-job-debug
+```
+
+### `snapshot`
+
+- Use `snapshot` as the first high-level observation tool.
+- Always provide both `--objective` and `--context`.
+
+```bash
+npx libretto snapshot \
+  --session failed-job-debug \
+  --objective "Identify the visible failure state and likely blocking UI condition" \
+  --context "The workflow already failed and the preserved browser must remain read-only."
+```
+
+### `readonly-exec`
+
+- Use `readonly-exec` for narrow inspection code only.
+- Denied operations fail with `ReadonlyExecDenied: ...`.
+
+#### Helpers
+
+- `page` — a read-only Playwright `Page` proxy. Standard Playwright read methods work normally (`url()`, `title()`, `content()`, `getByRole()`, `locator()`, `textContent()`, `isVisible()`, `count()`, `scrollIntoViewIfNeeded()`, etc.). Anything that mutates the page (`click`, `fill`, `goto`, `evaluate`, `keyboard`, `mouse`) is blocked.
+- `state` — the current Libretto session state object.
+- `get(url, options?)` — HTTP client restricted to **GET and HEAD** requests. Replaces `fetch`, which is blocked in readonly mode. Any request with a body or a non-GET/HEAD method throws `ReadonlyExecDenied`.
+- `scrollBy(deltaX, deltaY)` — scroll the viewport by pixel offset. Use this to inspect content below the fold without targeting a specific element.
+
+Standard JS globals `console`, `URL`, `Buffer`, `setTimeout`, and `setInterval` are also available.
+
+#### Examples
+
+```bash
+npx libretto readonly-exec "return page.url()" --session failed-job-debug
+npx libretto readonly-exec "return await page.getByRole('heading').first().textContent()" --session failed-job-debug
+
+# HTTP GET inspection
+echo "const r = await get('https://api.example.com/status'); return await r.json()" \
+  | npx libretto readonly-exec - --session failed-job-debug
+
+# Scroll down to inspect below-the-fold content
+npx libretto readonly-exec "await scrollBy(0, 500)" --session failed-job-debug
+```
+
+### `close`
+
+- Use `close` when the inspection session is no longer needed.
+
+```bash
+npx libretto close --session failed-job-debug
+```

package/src/cli/cli.ts

@@ -16,6 +16,10 @@ Examples:
 
   libretto exec "await page.locator('button:has-text(\\"Sign in\\")').click()"
   libretto exec "await page.fill('input[name=\\"email\\"]', 'test@example.com')"
+  libretto readonly-exec "return await page.title()" --session test1
+  libretto connect http://127.0.0.1:9222 --read-only --session test1
+  libretto run ./integration.ts --read-only --session test1
+  libretto status
   libretto ai configure openai
   libretto ai configure anthropic
   libretto ai configure gemini
@@ -36,6 +40,9 @@ Examples:
 Available in exec:
   page, context, state, browser, networkLog, actionLog
 
+Available in readonly-exec:
+  page, state, snapshot, scrollBy, get
+
 Profiles:
   Profiles are saved to .libretto/profiles/<domain>.json (git-ignored)
   They persist cookies, localStorage, and session data across browser launches.
@@ -46,6 +53,9 @@ 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.
+  Session mode is stored per session as read-only or write-access.
+  Use --read-only on open, connect, or run to create a read-only session.
+  Session mode is enforced by Libretto commands, not by raw CDP clients outside Libretto.
 `;
 }
 

package/src/cli/commands/ai.ts

@@ -1,7 +1,117 @@
 import { z } from "zod";
-import { runAiConfigure } from "../core/ai-config.js";
+import {
+  CURRENT_CONFIG_VERSION,
+  readAiConfig,
+  writeAiConfig,
+  clearAiConfig,
+  type AiConfig,
+} from "../core/config.js";
+import { LIBRETTO_CONFIG_PATH } from "../core/context.js";
+import { DEFAULT_SNAPSHOT_MODELS } from "../core/ai-model.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 
+const PROVIDER_ALIASES: Record<string, string> = {
+  claude: DEFAULT_SNAPSHOT_MODELS.anthropic,
+  gemini: DEFAULT_SNAPSHOT_MODELS.google,
+  google: DEFAULT_SNAPSHOT_MODELS.google,
+};
+
+const CONFIGURE_PROVIDERS = [
+  "openai",
+  "anthropic",
+  "gemini",
+  "vertex",
+] as const;
+
+function formatConfigureProviders(separator = " | "): string {
+  return CONFIGURE_PROVIDERS.join(separator);
+}
+
+function printAiConfig(config: AiConfig, configPath: string): void {
+  console.log(`Model: ${config.model}`);
+  console.log(`Config file: ${configPath}`);
+  console.log(`Updated at: ${config.updatedAt}`);
+}
+
+/**
+ * Resolve the model string from a `ai configure` argument.
+ * Accepts a provider shorthand ("openai", "anthropic", "gemini", "vertex")
+ * or a full provider/model-id string ("openai/gpt-4o", "anthropic/claude-sonnet-4-6").
+ */
+function resolveModelFromInput(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  // Full model string (contains a slash)
+  if (trimmed.includes("/")) return trimmed;
+
+  // Provider shorthand
+  const normalized = trimmed.toLowerCase();
+  return (
+    (DEFAULT_SNAPSHOT_MODELS as Record<string, string>)[normalized] ??
+    PROVIDER_ALIASES[normalized] ??
+    null
+  );
+}
+
+export function runAiConfigure(
+  input: {
+    preset?: string;
+    clear?: boolean;
+  },
+  options: {
+    configureCommandName?: string;
+    configPath?: string;
+  } = {},
+): void {
+  const configureCommandName =
+    options.configureCommandName ?? "npx libretto ai configure";
+  const configPath = options.configPath ?? LIBRETTO_CONFIG_PATH;
+
+  const presetArg = input.preset?.trim();
+
+  if (!presetArg && !input.clear) {
+    const config = readAiConfig(configPath);
+    if (!config) {
+      console.log(
+        `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`,
+      );
+      console.log(
+        "Provider credentials still come from your shell or .env file.",
+      );
+      return;
+    }
+    printAiConfig(config, configPath);
+    return;
+  }
+
+  if (input.clear) {
+    const removed = clearAiConfig(configPath);
+    if (removed) {
+      console.log(`Cleared AI config: ${configPath}`);
+    } else {
+      console.log("No AI config was set.");
+    }
+    return;
+  }
+
+  const model = resolveModelFromInput(presetArg!);
+  if (!model) {
+    console.log(
+      `Usage: ${configureCommandName} <${CONFIGURE_PROVIDERS.join("|")}|provider/model-id>\n` +
+        `       ${configureCommandName}\n` +
+        `       ${configureCommandName} --clear`,
+    );
+    throw new Error(
+      `Invalid provider or model. Use one of: ${formatConfigureProviders()}, or a full model string like "openai/gpt-4o".`,
+    );
+  }
+
+  const config = writeAiConfig(model, configPath);
+  console.log("AI config saved.");
+  printAiConfig(config, configPath);
+}
+
 export const aiConfigureInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("preset", z.string().optional(), {

package/src/cli/commands/browser.ts

@@ -1,17 +1,27 @@
 import { z } from "zod";
+import { SessionAccessModeSchema } from "../../shared/state/index.js";
 import {
   runClose as runCloseWithLogger,
   runCloseAll as runCloseAllWithLogger,
   runConnect as runConnectWithLogger,
   runOpen,
+  runOpenWithProvider,
   runPages,
   runSave,
 } from "../core/browser.js";
+import {
+  resolveProviderName,
+  getCloudProviderApi,
+} from "../core/providers/index.js";
+import { readLibrettoConfig } from "../core/config.js";
 import { createLoggerForSession, withSessionLogger } from "../core/context.js";
 import {
+  type SessionAccessMode,
   assertSessionAvailableForStart,
+  setSessionMode,
   validateSessionName,
 } from "../core/session.js";
+import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
   sessionOption,
@@ -42,6 +52,16 @@ export function parseViewportArg(
   return { width, height };
 }
 
+function resolveRequestedSessionMode(
+  readOnly: boolean | undefined,
+  writeAccess: boolean | undefined,
+): SessionAccessMode {
+  if (readOnly) return "read-only";
+  if (writeAccess) return "write-access";
+  const config = readLibrettoConfig();
+  return config.sessionMode ?? "write-access";
+}
+
 export const openInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("url", z.string().optional(), {
@@ -52,18 +72,34 @@ export const openInput = SimpleCLI.input({
     session: sessionOption(),
     headed: SimpleCLI.flag({ help: "Run browser in headed mode" }),
     headless: SimpleCLI.flag({ help: "Run browser in headless mode" }),
+    readOnly: SimpleCLI.flag({
+      name: "read-only",
+      help: "Create the session in read-only mode",
+    }),
+    writeAccess: SimpleCLI.flag({
+      name: "write-access",
+      help: "Create the session in write-access mode (overrides config default)",
+    }),
     viewport: SimpleCLI.option(z.string().optional(), {
       help: "Viewport size as WIDTHxHEIGHT (e.g. 1920x1080)",
     }),
+    provider: SimpleCLI.option(z.string().optional(), {
+      help: "Browser provider (local, kernel, browserbase)",
+      aliases: ["-p"],
+    }),
   },
 })
   .refine(
     (input) => Boolean(input.url),
-    `Usage: libretto open <url> [--headless] [--viewport WxH] [--session <name>]`,
+    `Usage: libretto open <url> [--headless] [--read-only|--write-access] [--viewport WxH] [--session <name>]`,
   )
   .refine(
     (input) => !(input.headed && input.headless),
     "Cannot pass both --headed and --headless.",
+  )
+  .refine(
+    (input) => !(input.readOnly && input.writeAccess),
+    "Cannot pass both --read-only and --write-access.",
   );
 
 export const openCommand = SimpleCLI.command({
@@ -72,10 +108,30 @@ export const openCommand = SimpleCLI.command({
   .input(openInput)
   .use(withAutoSession())
   .handle(async ({ input, ctx }) => {
+    warnIfInstalledSkillOutOfDate();
     assertSessionAvailableForStart(ctx.session, ctx.logger);
-    const headed = input.headed || !input.headless;
-    const viewport = parseViewportArg(input.viewport);
-    await runOpen(input.url!, headed, ctx.session, ctx.logger, { viewport });
+    const providerName = resolveProviderName(input.provider);
+    if (providerName === "local") {
+      const headed = input.headed || !input.headless;
+      const viewport = parseViewportArg(input.viewport);
+      await runOpen(input.url!, headed, ctx.session, ctx.logger, {
+        viewport,
+        accessMode: resolveRequestedSessionMode(
+          input.readOnly,
+          input.writeAccess,
+        ),
+      });
+    } else {
+      const provider = getCloudProviderApi(providerName);
+      await runOpenWithProvider(
+        input.url!,
+        providerName,
+        provider,
+        ctx.session,
+        ctx.logger,
+        resolveRequestedSessionMode(input.readOnly, input.writeAccess),
+      );
+    }
   });
 
 export const connectInput = SimpleCLI.input({
@@ -86,11 +142,24 @@ export const connectInput = SimpleCLI.input({
   ],
   named: {
     session: sessionOption(),
+    readOnly: SimpleCLI.flag({
+      name: "read-only",
+      help: "Create the session in read-only mode",
+    }),
+    writeAccess: SimpleCLI.flag({
+      name: "write-access",
+      help: "Create the session in write-access mode (overrides config default)",
+    }),
   },
-}).refine(
-  (input) => Boolean(input.cdpUrl),
-  `Usage: libretto connect <cdp-url> --session <name>`,
-);
+})
+  .refine(
+    (input) => Boolean(input.cdpUrl),
+    `Usage: libretto connect <cdp-url> [--read-only|--write-access] --session <name>`,
+  )
+  .refine(
+    (input) => !(input.readOnly && input.writeAccess),
+    "Cannot pass both --read-only and --write-access.",
+  );
 
 export const connectCommand = SimpleCLI.command({
   description: "Connect to an existing Chrome DevTools Protocol (CDP) endpoint",
@@ -98,7 +167,13 @@ export const connectCommand = SimpleCLI.command({
   .input(connectInput)
   .use(withAutoSession())
   .handle(async ({ input, ctx }) => {
-    await runConnectWithLogger(input.cdpUrl!, ctx.session, ctx.logger);
+    warnIfInstalledSkillOutOfDate();
+    await runConnectWithLogger(
+      input.cdpUrl!,
+      ctx.session,
+      ctx.logger,
+      resolveRequestedSessionMode(input.readOnly, input.writeAccess),
+    );
   });
 
 export const saveInput = SimpleCLI.input({
@@ -140,6 +215,32 @@ export const pagesCommand = SimpleCLI.command({
     await runPages(ctx.session, ctx.logger);
   });
 
+export const sessionModeInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("mode", SessionAccessModeSchema.optional(), {
+      help: "Session mode to set",
+    }),
+  ],
+  named: {
+    session: sessionOption(),
+  },
+});
+
+export const sessionModeCommand = SimpleCLI.command({
+  description: "View or set the session access mode",
+})
+  .input(sessionModeInput)
+  .use(withRequiredSession())
+  .handle(async ({ input, ctx }) => {
+    if (!input.mode) {
+      console.log(`Session "${ctx.session}" mode: ${ctx.sessionState.mode}`);
+      return;
+    }
+
+    const nextState = setSessionMode(ctx.session, input.mode, ctx.logger);
+    console.log(`Session "${ctx.session}" mode set to ${nextState.mode}.`);
+  });
+
 export const closeInput = SimpleCLI.input({
   positionals: [],
   named: {
@@ -179,6 +280,7 @@ export const browserCommands = {
   connect: connectCommand,
   save: saveCommand,
   pages: pagesCommand,
+  "session-mode": sessionModeCommand,
   close: closeCommand,
 };