libretto 0.5.4 → 0.5.6

package/README.md

@@ -22,13 +22,20 @@ https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
 ```bash
 npm install libretto
 
-# Install skill, download Chromium if not already installed, configure snapshot analysis
-npx libretto init
+# First-time onboarding: install skill, download Chromium, and pin the default snapshot model
+npx libretto setup
 
-# Configure or change the snapshot analysis model (see Configuration section below). `npx libretto init` sets this up the first time.
+# Check workspace readiness at any time
+npx libretto status
+
+# Manually change the snapshot analysis model (advanced override)
 npx libretto ai configure <openai | anthropic | gemini | vertex>
 ```
 
+`setup` detects available provider credentials (e.g. `OPENAI_API_KEY`) and automatically pins the default model to `.libretto/config.json`. Re-running `setup` on a healthy workspace shows the current configuration instead of re-prompting. If credentials are missing for a previously configured provider, `setup` offers an interactive repair flow.
+
+Use `ai configure` when you want to explicitly switch providers or set a custom model string.
+
 ## Use cases
 
 Libretto is designed to be used as a skill through your coding agent. Here are some example prompts:
@@ -62,19 +69,19 @@ Agents can use Libretto to reproduce the failure, pause the workflow at any poin
 You can also use Libretto directly from the command line. All commands accept `--session <name>` to target a specific session.
 
 ```bash
-npx libretto init                          # interactive; run yourself, not through an agent
+npx libretto setup                         # interactive first-run onboarding; run yourself, not through an agent
+npx libretto status                        # check AI config health and open sessions
 npx libretto open <url>                    # launch browser and open a URL (headed by default)
 npx libretto snapshot --objective "..." --context "..."  # capture PNG + HTML and analyze with an LLM
 npx libretto exec "<code>"                 # execute Playwright TypeScript against the open page (single quoted argument)
 echo "<code>" | npx libretto exec -        # intentionally read Playwright TypeScript from stdin
-npx libretto run <file> <workflowName>     # run an exported workflow from a file
+npx libretto run <file>                    # run the file's default-exported workflow
 npx libretto resume                        # resume a paused workflow
-npx libretto network                       # view captured network requests
-npx libretto actions                       # view captured user/agent actions
 npx libretto pages                         # list open pages in the session
 npx libretto save <domain>                 # save browser session (cookies, localStorage) for reuse
 npx libretto close                         # close the browser
-npx libretto ai configure <provider>       # configure snapshot analysis model
+npx libretto ai configure <provider>       # manually change snapshot analysis model
+npx libretto status                        # show AI config and open sessions
 ```
 
 ## Configuration
@@ -98,12 +105,18 @@ All Libretto state lives in a `.libretto/` directory at your project root. Confi
 
 The `ai` field configures which model Libretto uses for snapshot analysis — extracting selectors, identifying interactive elements, or diagnosing why a step failed. This keeps heavy visual context out of your coding agent's context window. Snapshot analysis is required.
 
-The easiest way to set the model is through the CLI:
+`npx libretto setup` automatically pins the default model for the first provider whose credentials it finds. To explicitly change the provider or model afterward:
 
 ```bash
 npx libretto ai configure <openai | anthropic | gemini | vertex>
 ```
 
+To inspect the current configuration without changing anything:
+
+```bash
+npx libretto status
+```
+
 Provider credentials are read from environment variables or a `.env` file at your project root: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_CLOUD_PROJECT` for Vertex.
 
 The `viewport` field sets the default browser viewport size. Both fields are optional.
@@ -157,6 +170,6 @@ Source layout:
 - `README.template.md` — source of truth for the repo and package READMEs
 - `skills/libretto/` — source of truth for the Libretto skill
 
-Run `pnpm sync:mirrors` after editing `README.template.md` or anything under `skills/libretto/`. `pnpm i` also resyncs the skill mirrors through `postinstall`.
+Run `pnpm sync:mirrors` after editing `README.template.md` or anything under `skills/libretto/`.
 
 To check that generated READMEs, skill mirrors, and skill version metadata are in sync without fixing them, run `pnpm check:mirrors`. To release, run `pnpm prepare-release`.

package/README.template.md

@@ -20,13 +20,20 @@ https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
 ```bash
 npm install libretto
 
-# Install skill, download Chromium if not already installed, configure snapshot analysis
-npx libretto init
+# First-time onboarding: install skill, download Chromium, and pin the default snapshot model
+npx libretto setup
 
-# Configure or change the snapshot analysis model (see Configuration section below). `npx libretto init` sets this up the first time.
+# Check workspace readiness at any time
+npx libretto status
+
+# Manually change the snapshot analysis model (advanced override)
 npx libretto ai configure <openai | anthropic | gemini | vertex>
 ```
 
+`setup` detects available provider credentials (e.g. `OPENAI_API_KEY`) and automatically pins the default model to `.libretto/config.json`. Re-running `setup` on a healthy workspace shows the current configuration instead of re-prompting. If credentials are missing for a previously configured provider, `setup` offers an interactive repair flow.
+
+Use `ai configure` when you want to explicitly switch providers or set a custom model string.
+
 ## Use cases
 
 Libretto is designed to be used as a skill through your coding agent. Here are some example prompts:
@@ -60,19 +67,19 @@ Agents can use Libretto to reproduce the failure, pause the workflow at any poin
 You can also use Libretto directly from the command line. All commands accept `--session <name>` to target a specific session.
 
 ```bash
-npx libretto init                          # interactive; run yourself, not through an agent
+npx libretto setup                         # interactive first-run onboarding; run yourself, not through an agent
+npx libretto status                        # check AI config health and open sessions
 npx libretto open <url>                    # launch browser and open a URL (headed by default)
 npx libretto snapshot --objective "..." --context "..."  # capture PNG + HTML and analyze with an LLM
 npx libretto exec "<code>"                 # execute Playwright TypeScript against the open page (single quoted argument)
 echo "<code>" | npx libretto exec -        # intentionally read Playwright TypeScript from stdin
-npx libretto run <file> <workflowName>     # run an exported workflow from a file
+npx libretto run <file>                    # run the file's default-exported workflow
 npx libretto resume                        # resume a paused workflow
-npx libretto network                       # view captured network requests
-npx libretto actions                       # view captured user/agent actions
 npx libretto pages                         # list open pages in the session
 npx libretto save <domain>                 # save browser session (cookies, localStorage) for reuse
 npx libretto close                         # close the browser
-npx libretto ai configure <provider>       # configure snapshot analysis model
+npx libretto ai configure <provider>       # manually change snapshot analysis model
+npx libretto status                        # show AI config and open sessions
 ```
 
 ## Configuration
@@ -96,12 +103,18 @@ All Libretto state lives in a `.libretto/` directory at your project root. Confi
 
 The `ai` field configures which model Libretto uses for snapshot analysis — extracting selectors, identifying interactive elements, or diagnosing why a step failed. This keeps heavy visual context out of your coding agent's context window. Snapshot analysis is required.
 
-The easiest way to set the model is through the CLI:
+`npx libretto setup` automatically pins the default model for the first provider whose credentials it finds. To explicitly change the provider or model afterward:
 
 ```bash
 npx libretto ai configure <openai | anthropic | gemini | vertex>
 ```
 
+To inspect the current configuration without changing anything:
+
+```bash
+npx libretto status
+```
+
 Provider credentials are read from environment variables or a `.env` file at your project root: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`, or `GOOGLE_CLOUD_PROJECT` for Vertex.
 
 The `viewport` field sets the default browser viewport size. Both fields are optional.
@@ -155,6 +168,6 @@ Source layout:
 - `{{LIBRETTO_PATH_PREFIX}}README.template.md` — source of truth for the repo and package READMEs
 - `{{LIBRETTO_PATH_PREFIX}}skills/libretto/` — source of truth for the Libretto skill
 
-Run `pnpm sync:mirrors` after editing `{{LIBRETTO_PATH_PREFIX}}README.template.md` or anything under `{{LIBRETTO_PATH_PREFIX}}skills/libretto/`. `pnpm i` also resyncs the skill mirrors through `postinstall`.
+Run `pnpm sync:mirrors` after editing `{{LIBRETTO_PATH_PREFIX}}README.template.md` or anything under `{{LIBRETTO_PATH_PREFIX}}skills/libretto/`.
 
 To check that generated READMEs, skill mirrors, and skill version metadata are in sync without fixing them, run `pnpm check:mirrors`. To release, run `pnpm prepare-release`.

package/dist/cli/cli.js

@@ -15,6 +15,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
@@ -35,6 +39,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.
@@ -45,6 +52,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.
 `;
 }
 function isRootHelpRequest(rawArgs) {

package/dist/cli/commands/ai.js

@@ -1,6 +1,80 @@
 import { z } from "zod";
-import { runAiConfigure } from "../core/ai-config.js";
+import {
+  readAiConfig,
+  writeAiConfig,
+  clearAiConfig
+} 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 = {
+  claude: DEFAULT_SNAPSHOT_MODELS.anthropic,
+  gemini: DEFAULT_SNAPSHOT_MODELS.google,
+  google: DEFAULT_SNAPSHOT_MODELS.google
+};
+const CONFIGURE_PROVIDERS = [
+  "openai",
+  "anthropic",
+  "gemini",
+  "vertex"
+];
+function formatConfigureProviders(separator = " | ") {
+  return CONFIGURE_PROVIDERS.join(separator);
+}
+function printAiConfig(config, configPath) {
+  console.log(`Model: ${config.model}`);
+  console.log(`Config file: ${configPath}`);
+  console.log(`Updated at: ${config.updatedAt}`);
+}
+function resolveModelFromInput(input) {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+  if (trimmed.includes("/")) return trimmed;
+  const normalized = trimmed.toLowerCase();
+  return DEFAULT_SNAPSHOT_MODELS[normalized] ?? PROVIDER_ALIASES[normalized] ?? null;
+}
+function runAiConfigure(input, options = {}) {
+  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 config2 = readAiConfig(configPath);
+    if (!config2) {
+      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(config2, 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>
+       ${configureCommandName}
+       ${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);
+}
 const aiConfigureInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("preset", z.string().optional(), {
@@ -31,5 +105,6 @@ const aiCommands = SimpleCLI.group({
 });
 export {
   aiCommands,
-  aiConfigureInput
+  aiConfigureInput,
+  runAiConfigure
 };

package/dist/cli/commands/browser.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { SessionAccessModeSchema } from "../../shared/state/index.js";
 import {
   runClose as runCloseWithLogger,
   runCloseAll as runCloseAllWithLogger,
@@ -7,11 +8,14 @@ import {
   runPages,
   runSave
 } from "../core/browser.js";
+import { readLibrettoConfig } from "../core/config.js";
 import { createLoggerForSession, withSessionLogger } from "../core/context.js";
 import {
   assertSessionAvailableForStart,
+  setSessionMode,
   validateSessionName
 } from "../core/session.js";
+import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 import {
   sessionOption,
@@ -35,6 +39,12 @@ function parseViewportArg(viewportArg) {
   }
   return { width, height };
 }
+function resolveRequestedSessionMode(readOnly, writeAccess) {
+  if (readOnly) return "read-only";
+  if (writeAccess) return "write-access";
+  const config = readLibrettoConfig();
+  return config.sessionMode ?? "write-access";
+}
 const openInput = SimpleCLI.input({
   positionals: [
     SimpleCLI.positional("url", z.string().optional(), {
@@ -45,24 +55,39 @@ 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)"
     })
   }
 }).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."
 );
 const openCommand = SimpleCLI.command({
   description: "Launch browser and open URL (headed by default)"
 }).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 });
+  await runOpen(input.url, headed, ctx.session, ctx.logger, {
+    viewport,
+    accessMode: resolveRequestedSessionMode(input.readOnly, input.writeAccess)
+  });
 });
 const connectInput = SimpleCLI.input({
   positionals: [
@@ -71,16 +96,33 @@ const connectInput = SimpleCLI.input({
     })
   ],
   named: {
-    session: sessionOption()
+    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>`
+  `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."
 );
 const connectCommand = SimpleCLI.command({
   description: "Connect to an existing Chrome DevTools Protocol (CDP) endpoint"
 }).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)
+  );
 });
 const saveInput = SimpleCLI.input({
   positionals: [
@@ -111,6 +153,26 @@ const pagesCommand = SimpleCLI.command({
 }).input(pagesInput).use(withRequiredSession()).handle(async ({ ctx }) => {
   await runPages(ctx.session, ctx.logger);
 });
+const sessionModeInput = SimpleCLI.input({
+  positionals: [
+    SimpleCLI.positional("mode", SessionAccessModeSchema.optional(), {
+      help: "Session mode to set"
+    })
+  ],
+  named: {
+    session: sessionOption()
+  }
+});
+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}.`);
+});
 const closeInput = SimpleCLI.input({
   positionals: [],
   named: {
@@ -147,6 +209,7 @@ const browserCommands = {
   connect: connectCommand,
   save: saveCommand,
   pages: pagesCommand,
+  "session-mode": sessionModeCommand,
   close: closeCommand
 };
 async function runClose(session) {
@@ -167,5 +230,7 @@ export {
   parseViewportArg,
   runClose,
   saveCommand,
-  saveInput
+  saveInput,
+  sessionModeCommand,
+  sessionModeInput
 };