libretto 0.6.11 → 0.6.12

package/docs/experiments.md

@@ -0,0 +1,67 @@
+# Experiments Framework
+
+Use this reference when adding or changing Libretto experiment flags, wiring experiment checks through CLI or daemon internals, or debugging `libretto experiments` behavior.
+
+## Purpose and Scope
+
+Experiments are boolean feature flags for Libretto internal machinery. They let maintainers enable in-progress CLI or daemon behavior in a workspace without exposing those flags to user workflow code.
+
+Do not add experiments to `LibrettoWorkflowContext` in `packages/libretto/src/shared/workflow/workflow.ts`. User workflows should not branch on Libretto experiment flags.
+
+## Registry and Workspace State
+
+The experiment registry lives in `packages/libretto/src/cli/core/experiments.ts`.
+
+- Add each flag to `EXPERIMENTS` with a stable hyphenated slug, title, description, and `defaultValue`.
+- Use the exported `ExperimentName` and `Experiments` types instead of duplicating flag shapes.
+- Use `resolveExperiments()` to read the resolved boolean snapshot.
+- Use `setExperimentEnabled()` to persist an override and reject unknown flag names.
+
+Workspace overrides are stored in `.libretto/config.json` under the optional `experiments` record. The config schema is defined in `packages/libretto/src/cli/core/config.ts`; unknown config fields are still passed through.
+
+Example workspace state:
+
+```json
+{
+  "version": 1,
+  "experiments": {
+    "compact-snapshot-format": true
+  }
+}
+```
+
+## CLI Behavior
+
+`libretto experiments` is the CLI surface for inspecting and changing workspace experiment overrides.
+
+```bash
+npx libretto experiments
+npx libretto experiments describe <experiment>
+npx libretto experiments enable <experiment>
+npx libretto experiments disable <experiment>
+```
+
+The command is implemented in `packages/libretto/src/cli/commands/experiments.ts` and registered as a top-level command. Listing prints registered experiments in registry order with their enabled/disabled state and description. `describe` prints the experiment status and full instructions. `enable` persists the override to `.libretto/config.json` and prints the full description with a prelude that the enabled experiment changes expected Libretto usage from the skill. `disable` persists the override and prints deterministic success text.
+
+Invalid actions, missing experiment names, and unknown experiment names should fail with actionable usage that includes the available experiment names.
+
+## CLI and Daemon Plumbing
+
+Use `withExperiments()` from `packages/libretto/src/cli/commands/shared.ts` when a command needs experiment values. It resolves one experiment snapshot for the CLI invocation and adds it to command context as `ctx.experiments`.
+
+Daemon-backed startup paths must serialize that snapshot into `DaemonConfig.experiments` in `packages/libretto/src/cli/core/daemon/config.ts`. This currently applies to:
+
+- daemon-backed `open`
+- `connect`
+- provider-backed `open`
+- `run`
+
+The daemon receives experiments at startup only. Changes made with `libretto experiments enable|disable` apply to new daemon sessions, not already-running sessions.
+
+Inside the daemon, experiments are for Libretto machinery only. Keep them in daemon/controller internals; do not pass them into public workflow context objects.
+
+## Testing Notes
+
+Before adding or changing tests, read `docs/tests-guide.md`.
+
+Prefer user-level CLI behavior tests for `libretto experiments` listing and enable/disable flows. Keep a regression test that an enabled experiment is not visible on `LibrettoWorkflowContext` during `run`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",
@@ -38,7 +38,8 @@
     "check:skills": "pnpm run check:mirrors",
     "build": "tsup --config tsup.config.ts",
     "type-check": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "turbo run test:vitest --filter=libretto --log-order=grouped",
+    "test:vitest": "vitest run",
     "test:watch": "vitest",
     "cli": "node dist/index.js",
     "generate-changelog": "tsx scripts/generate-changelog.ts",
@@ -78,6 +79,7 @@
     "glimpseui": "^0.5.1",
     "google-auth-library": "^10.6.1",
     "openai": "^6.29.0",
+    "outdent": "^0.8.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.5"

package/skills/libretto/SKILL.md

@@ -4,7 +4,7 @@ description: "Browser automation CLI for building, maintaining, and running brow
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.11"
+  version: "0.6.12"
 ---
 
 ## How Libretto Works
@@ -142,6 +142,7 @@ npx libretto exec --session debug-example --page <page-id> "return await page.ur
 
 - Use `run` to verify a workflow file after creating it or editing it, preferring `run --headless` for the normal fix/verify loop.
 - Plain `run` defaults to headed mode.
+- Successful runs close the browser by default. Pass `--stay-open-on-success` when you need to inspect the completed state with `pages`, `snapshot`, or `exec`.
 - Pass `--read-only` if the preserved session should come back locked for follow-up terminal inspection after the workflow run.
 - If the workflow fails, Libretto keeps the browser open. Inspect the failed state with `snapshot` and `exec` before editing code.
 - Insert `await pause(session)` statements in the workflow file when you need to stop at specific states for interactive debugging, like breakpoints in the browser flow.
@@ -151,6 +152,7 @@ npx libretto exec --session debug-example --page <page-id> "return await page.ur
 ```bash
 npx libretto run ./integration.ts --headless --params '{"status":"open"}'
 npx libretto run ./integration.ts --headless --read-only
+npx libretto run ./integration.ts --headless --stay-open-on-success
 npx libretto run ./integration.ts --auth-profile app.example.com
 ```
 

package/skills/libretto-readonly/SKILL.md

@@ -4,7 +4,7 @@ description: "Read-only Libretto workflow for diagnosing live browser state with
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.11"
+  version: "0.6.12"
 ---
 
 ## How Libretto Read-Only Works

package/src/cli/AGENTS.md

@@ -0,0 +1,7 @@
+# CLI Source
+
+## Experiments
+
+When adding or changing Libretto experiment flags, read `../../docs/experiments.md` for the registry, CLI command, config, and daemon plumbing conventions.
+
+Experiments are internal Libretto machinery. Do not expose them on `LibrettoWorkflowContext` or user workflow APIs.

package/src/cli/cli.ts

@@ -1,5 +1,6 @@
 import { resolveAiSetupStatus } from "./core/ai-model.js";
 import { ensureLibrettoSetup } from "./core/context.js";
+import { librettoCommand } from "../shared/package-manager.js";
 import { createCLIApp } from "./router.js";
 import { warnIfInstalledSkillOutOfDate } from "./core/skill-version.js";
 import { loadEnv } from "../shared/env/load-env.js";
@@ -24,17 +25,17 @@ function printSetupAudit(): void {
       break;
     case "configured-missing-credentials":
       console.log(
-        `✗ ${status.provider} configured (model: ${status.model}), but credentials are missing. Run \`npx libretto setup\` to repair.`,
+        `✗ ${status.provider} configured (model: ${status.model}), but credentials are missing. Run \`${librettoCommand("setup")}\` to repair.`,
       );
       break;
     case "invalid-config":
       console.log(
-        `✗ AI config is invalid. Run \`npx libretto setup\` to reconfigure.`,
+        `✗ AI config is invalid. Run \`${librettoCommand("setup")}\` to reconfigure.`,
       );
       break;
     case "unconfigured":
       console.log(
-        `✗ No AI model configured. Run \`npx libretto setup\` or \`npx libretto ai configure\` to set up.`,
+        `✗ No AI model configured. Run \`${librettoCommand("setup")}\` or \`${librettoCommand("ai configure")}\` to set up.`,
       );
       break;
   }

package/src/cli/commands/ai.ts

@@ -7,6 +7,7 @@ import {
 } from "../core/config.js";
 import { LIBRETTO_CONFIG_PATH } from "../core/context.js";
 import { DEFAULT_SNAPSHOT_MODELS } from "../core/ai-model.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
 
 const PROVIDER_ALIASES: Record<string, string> = {
@@ -63,7 +64,7 @@ export function runAiConfigure(
   } = {},
 ): void {
   const configureCommandName =
-    options.configureCommandName ?? "npx libretto ai configure";
+    options.configureCommandName ?? librettoCommand("ai configure");
   const configPath = options.configPath ?? LIBRETTO_CONFIG_PATH;
 
   const presetArg = input.preset?.trim();
@@ -135,7 +136,7 @@ export const aiCommands = SimpleCLI.group({
             preset: input.preset,
           },
           {
-            configureCommandName: `libretto ai configure`,
+            configureCommandName: librettoCommand("ai configure"),
           },
         );
       }),

package/src/cli/commands/browser.ts

@@ -9,12 +9,10 @@ import {
   runPages,
   runSave,
 } from "../core/browser.js";
-import {
-  resolveProviderName,
-  getCloudProviderApi,
-} from "../core/providers/index.js";
+import { resolveProviderName } from "../core/providers/index.js";
 import { readLibrettoConfig } from "../core/config.js";
 import { createLoggerForSession, withSessionLogger } from "../core/context.js";
+import { librettoCommand } from "../../shared/package-manager.js";
 import {
   type SessionAccessMode,
   assertSessionAvailableForStart,
@@ -26,6 +24,7 @@ import { SimpleCLI } from "../framework/simple-cli.js";
 import {
   sessionOption,
   withAutoSession,
+  withExperiments,
   withRequiredSession,
 } from "./shared.js";
 
@@ -95,7 +94,7 @@ export const openInput = SimpleCLI.input({
 })
   .refine(
     (input) => Boolean(input.url),
-    `Usage: libretto open <url> [--headless] [--read-only|--write-access] [--auth-profile <domain>] [--viewport WxH] [--session <name>]`,
+    `Usage: ${librettoCommand("open <url> [--headless] [--read-only|--write-access] [--auth-profile <domain>] [--viewport WxH] [--session <name>]")}`,
   )
   .refine(
     (input) => !(input.headed && input.headless),
@@ -112,6 +111,7 @@ export const openCommand = SimpleCLI.command({
 })
   .input(openInput)
   .use(withAutoSession())
+  .use(withExperiments())
   .handle(async ({ input, ctx }) => {
     warnIfInstalledSkillOutOfDate();
     assertSessionAvailableForStart(ctx.session, ctx.logger);
@@ -126,16 +126,16 @@ export const openCommand = SimpleCLI.command({
           input.writeAccess,
         ),
         authProfileDomain: input.authProfile,
+        experiments: ctx.experiments,
       });
     } else {
-      const provider = getCloudProviderApi(providerName);
       await runOpenWithProvider(
         input.url!,
         providerName,
-        provider,
         ctx.session,
         ctx.logger,
         resolveRequestedSessionMode(input.readOnly, input.writeAccess),
+        ctx.experiments,
       );
     }
   });
@@ -160,7 +160,7 @@ export const connectInput = SimpleCLI.input({
 })
   .refine(
     (input) => Boolean(input.cdpUrl),
-    `Usage: libretto connect <cdp-url> [--read-only|--write-access] --session <name>`,
+    `Usage: ${librettoCommand("connect <cdp-url> [--read-only|--write-access] --session <name>")}`,
   )
   .refine(
     (input) => !(input.readOnly && input.writeAccess),
@@ -172,6 +172,7 @@ export const connectCommand = SimpleCLI.command({
 })
   .input(connectInput)
   .use(withAutoSession())
+  .use(withExperiments())
   .handle(async ({ input, ctx }) => {
     warnIfInstalledSkillOutOfDate();
     await runConnectWithLogger(
@@ -179,6 +180,7 @@ export const connectCommand = SimpleCLI.command({
       ctx.session,
       ctx.logger,
       resolveRequestedSessionMode(input.readOnly, input.writeAccess),
+      ctx.experiments,
     );
   });
 
@@ -193,7 +195,7 @@ export const saveInput = SimpleCLI.input({
   },
 }).refine(
   (input) => Boolean(input.urlOrDomain),
-  `Usage: libretto save <url|domain> --session <name>`,
+  `Usage: ${librettoCommand("save <url|domain> --session <name>")}`,
 );
 
 export const saveCommand = SimpleCLI.command({
@@ -264,7 +266,7 @@ export const closeInput = SimpleCLI.input({
   },
 }).refine(
   (input) => input.all || input.session,
-  `Usage: libretto close <session>\nUsage: libretto close --all [--force]`,
+  `Usage: ${librettoCommand("close <session>")}\nUsage: ${librettoCommand("close --all [--force]")}`,
 );
 
 export const closeCommand = SimpleCLI.command({
@@ -273,7 +275,7 @@ export const closeCommand = SimpleCLI.command({
   .input(closeInput)
   .handle(async ({ input }) => {
     if (input.force && !input.all) {
-      throw new Error(`Usage: libretto close --all [--force]`);
+      throw new Error(`Usage: ${librettoCommand("close --all [--force]")}`);
     }
     if (input.all) {
       const logger = createLoggerForSession("cli");