libretto 0.6.13 → 0.6.15

package/dist/cli/core/providers/libretto-cloud.js

@@ -1,15 +1,19 @@
-import { HOSTED_API_URL } from "../auth-fetch.js";
+import { resolveHostedApiUrl } from "../auth-fetch.js";
+const DEFAULT_POLL_INTERVAL_MS = 2e3;
+const DEFAULT_BROWSER_SESSION_TIMEOUT_SECONDS = 3600;
+const QUEUE_WAIT_TIMEOUT_MS = 10 * 6e4;
 function createLibrettoCloudProvider() {
   const apiKey = process.env.LIBRETTO_API_KEY;
   if (!apiKey)
     throw new Error(
       "LIBRETTO_API_KEY is required for the Libretto Cloud provider."
     );
-  const endpoint = HOSTED_API_URL;
+  const endpoint = resolveHostedApiUrl();
   return {
     async createSession() {
-      const timeoutSeconds = Number(
-        process.env.LIBRETTO_TIMEOUT_SECONDS ?? 7200
+      const browserSessionTimeoutSeconds = readPositiveNumberEnv(
+        "LIBRETTO_TIMEOUT_SECONDS",
+        DEFAULT_BROWSER_SESSION_TIMEOUT_SECONDS
       );
       const resp = await fetch(`${endpoint}/v1/sessions/create`, {
         method: "POST",
@@ -18,42 +22,190 @@ function createLibrettoCloudProvider() {
           "Content-Type": "application/json"
         },
         body: JSON.stringify({
-          json: { timeout_seconds: timeoutSeconds }
+          json: { timeout_seconds: browserSessionTimeoutSeconds }
         })
       });
       if (!resp.ok) {
         const body = await resp.text();
-        throw new Error(
-          `Libretto Cloud API error (${resp.status}): ${body}`
-        );
+        throw new Error(`Libretto Cloud API error (${resp.status}): ${body}`);
       }
       const { json } = await resp.json();
+      const startupCleanup = createStartupSessionCleanup(
+        endpoint,
+        apiKey,
+        json.session_id
+      );
+      let readySession;
+      try {
+        readySession = await waitForCloudSessionReady({
+          endpoint,
+          apiKey,
+          session: json,
+          timeoutMs: QUEUE_WAIT_TIMEOUT_MS,
+          isCancelled: startupCleanup.isCancelled
+        });
+      } catch (error) {
+        if (startupCleanup.isCancelled()) {
+          await startupCleanup.waitForClose();
+        } else {
+          await closeCloudSession(endpoint, apiKey, json.session_id).catch(
+            () => {
+            }
+          );
+        }
+        throw error;
+      } finally {
+        startupCleanup.dispose();
+      }
       return {
-        sessionId: json.session_id,
-        cdpEndpoint: json.cdp_url,
-        liveViewUrl: json.live_view_url ?? void 0
+        sessionId: readySession.session_id,
+        cdpEndpoint: readySession.cdp_url,
+        liveViewUrl: readySession.live_view_url ?? void 0
       };
     },
     async closeSession(sessionId) {
-      const resp = await fetch(`${endpoint}/v1/sessions/close`, {
-        method: "POST",
-        headers: {
-          "x-api-key": apiKey,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({ json: { session_id: sessionId } })
-      });
-      if (!resp.ok) {
-        const body = await resp.text();
-        throw new Error(
-          `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`
-        );
-      }
-      const { json } = await resp.json();
+      const json = await closeCloudSession(endpoint, apiKey, sessionId);
       return { replayUrl: json.replay_url ?? void 0 };
     }
   };
 }
+async function waitForCloudSessionReady(args) {
+  let session = args.session;
+  if (args.isCancelled?.()) {
+    throw new Error(
+      `Libretto Cloud session ${session.session_id} was cancelled before browser capacity was available.`
+    );
+  }
+  if (session.cdp_url) {
+    return { ...session, cdp_url: session.cdp_url };
+  }
+  sendStartupStatus(
+    `Libretto Cloud browser session queued (session: ${session.session_id}). Waiting for browser capacity...`
+  );
+  const pollIntervalMs = readPositiveNumberEnv(
+    "LIBRETTO_CLOUD_SESSION_POLL_INTERVAL_MS",
+    DEFAULT_POLL_INTERVAL_MS
+  );
+  const deadline = Date.now() + args.timeoutMs;
+  while (Date.now() < deadline) {
+    if (args.isCancelled?.()) {
+      throw new Error(
+        `Libretto Cloud session ${session.session_id} was cancelled before browser capacity was available.`
+      );
+    }
+    await sleep(pollIntervalMs);
+    if (args.isCancelled?.()) {
+      throw new Error(
+        `Libretto Cloud session ${session.session_id} was cancelled before browser capacity was available.`
+      );
+    }
+    session = await getCloudSession(
+      args.endpoint,
+      args.apiKey,
+      session.session_id
+    );
+    if (session.cdp_url) {
+      sendStartupStatus(
+        `Libretto Cloud browser capacity available (session: ${session.session_id}). Connecting...`
+      );
+      return { ...session, cdp_url: session.cdp_url };
+    }
+    if (!["queued", "starting"].includes(session.status)) {
+      throw new Error(
+        `Libretto Cloud session ${session.session_id} entered status "${session.status}" before a CDP URL was available.`
+      );
+    }
+  }
+  throw new Error(
+    `Timed out waiting for Libretto Cloud browser capacity after ${Math.ceil(args.timeoutMs / 1e3)}s (session: ${session.session_id}).`
+  );
+}
+async function getCloudSession(endpoint, apiKey, sessionId) {
+  const resp = await fetch(`${endpoint}/v1/sessions/get`, {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ json: { session_id: sessionId } })
+  });
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(
+      `Libretto Cloud API error reading session ${sessionId} (${resp.status}): ${body}`
+    );
+  }
+  const { json } = await resp.json();
+  return json;
+}
+async function closeCloudSession(endpoint, apiKey, sessionId) {
+  const resp = await fetch(`${endpoint}/v1/sessions/close`, {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ json: { session_id: sessionId } })
+  });
+  if (!resp.ok) {
+    const body = await resp.text();
+    throw new Error(
+      `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`
+    );
+  }
+  const { json } = await resp.json();
+  return json;
+}
+function createStartupSessionCleanup(endpoint, apiKey, sessionId) {
+  let cancelled = false;
+  let closePromise = null;
+  const requestClose = (reason) => {
+    if (cancelled) return;
+    cancelled = true;
+    sendStartupStatus(
+      `Libretto Cloud browser session cancelled (${reason}). Cleaning up queued session...`
+    );
+    closePromise = closeCloudSession(endpoint, apiKey, sessionId).then(
+      () => {
+      },
+      () => {
+      }
+    );
+  };
+  const onDisconnect = () => requestClose("parent command disconnected");
+  const onSigint = () => requestClose("received SIGINT");
+  const onSigterm = () => requestClose("received SIGTERM");
+  if (typeof process.send === "function") {
+    process.once("disconnect", onDisconnect);
+  }
+  process.once("SIGINT", onSigint);
+  process.once("SIGTERM", onSigterm);
+  return {
+    isCancelled: () => cancelled,
+    waitForClose: async () => {
+      await closePromise;
+    },
+    dispose: () => {
+      process.off("disconnect", onDisconnect);
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+    }
+  };
+}
+function readPositiveNumberEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function sendStartupStatus(message) {
+  if (typeof process.send === "function") {
+    process.send({ type: "startup-status", message });
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 export {
   createLibrettoCloudProvider
 };

package/dist/cli/router.js

@@ -8,14 +8,19 @@ import { setupCommand } from "./commands/setup.js";
 import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
 import { librettoCommand } from "../shared/package-manager.js";
-import { SimpleCLI } from "./framework/simple-cli.js";
+import { SimpleCLI } from "affordance";
 const cliRoutes = {
   ...browserCommands,
-  deploy: deployCommand,
+  cloud: SimpleCLI.group({
+    description: "Libretto Cloud commands",
+    routes: {
+      deploy: deployCommand,
+      auth: authCommands,
+      billing: billingCommands
+    }
+  }),
   experiments: experimentsCommand,
   ...executionCommands,
-  auth: authCommands,
-  billing: billingCommands,
   setup: setupCommand,
   status: statusCommand,
   snapshot: snapshotCommand

package/dist/shared/ipc/socket-transport.d.ts

@@ -5,5 +5,6 @@ declare function connectToIpcSocket(socketPath: string): Promise<IpcTransport<Ip
 declare function createIpcSocketServer(onConnection: (transport: IpcTransport<IpcProtocolMessage>) => void): Server;
 declare function listenForIpcConnections(socketPath: string, onConnection: (transport: IpcTransport<IpcProtocolMessage>) => void): Promise<Server>;
 declare function listenOnIpcSocket(server: Server, socketPath: string): Promise<void>;
+declare function isWindowsNamedPipePath(socketPath: string): boolean;
 
-export { connectToIpcSocket, createIpcSocketServer, listenForIpcConnections, listenOnIpcSocket };
+export { connectToIpcSocket, createIpcSocketServer, isWindowsNamedPipePath, listenForIpcConnections, listenOnIpcSocket };

package/dist/shared/ipc/socket-transport.js

@@ -1,10 +1,9 @@
-import { rm } from "node:fs/promises";
+import { mkdir, rm } from "node:fs/promises";
 import {
   createServer,
   createConnection
 } from "node:net";
 import { dirname } from "node:path";
-import { mkdir } from "node:fs/promises";
 function createJsonSocketTransport(socket) {
   socket.setEncoding("utf8");
   return {
@@ -82,12 +81,11 @@ async function listenForIpcConnections(socketPath, onConnection) {
   return server;
 }
 async function listenOnIpcSocket(server, socketPath) {
-  await mkdir(dirname(socketPath), { recursive: true });
-  await rm(socketPath, { force: true });
+  await prepareIpcSocketPath(socketPath);
   const originalClose = server.close.bind(server);
   server.close = ((callback) => {
     return originalClose((error) => {
-      void rm(socketPath, { force: true }).finally(() => callback?.(error));
+      void removeStaleSocketFile(socketPath).finally(() => callback?.(error));
     });
   });
   await new Promise((resolve, reject) => {
@@ -104,6 +102,18 @@ async function listenOnIpcSocket(server, socketPath) {
     server.listen(socketPath);
   });
 }
+function isWindowsNamedPipePath(socketPath) {
+  return socketPath.startsWith("\\\\.\\pipe\\");
+}
+async function prepareIpcSocketPath(socketPath) {
+  if (isWindowsNamedPipePath(socketPath)) return;
+  await mkdir(dirname(socketPath), { recursive: true });
+  await removeStaleSocketFile(socketPath);
+}
+async function removeStaleSocketFile(socketPath) {
+  if (isWindowsNamedPipePath(socketPath)) return;
+  await rm(socketPath, { force: true });
+}
 async function connectSocket(socketPath) {
   const socket = createConnection(socketPath);
   return new Promise((resolve, reject) => {
@@ -138,6 +148,7 @@ function isRecord(value) {
 export {
   connectToIpcSocket,
   createIpcSocketServer,
+  isWindowsNamedPipePath,
   listenForIpcConnections,
   listenOnIpcSocket
 };

package/dist/shared/ipc/socket-transport.spec.js

@@ -6,6 +6,7 @@ import { expect, test as base } from "vitest";
 import { createIpcPeer } from "./ipc.js";
 import {
   connectToIpcSocket,
+  isWindowsNamedPipePath,
   listenForIpcConnections
 } from "./socket-transport.js";
 const test = base.extend({
@@ -47,6 +48,10 @@ test("sends concurrent calls over one socket", async ({ socketPath }) => {
   });
   await expect(stat(socketPath)).rejects.toThrow();
 });
+test("recognizes Windows named pipe paths", () => {
+  expect(isWindowsNamedPipePath("\\\\.\\pipe\\libretto-abc123")).toBe(true);
+  expect(isWindowsNamedPipePath("/tmp/libretto-501-abc123.sock")).toBe(false);
+});
 test("rejects pending calls when the socket closes", async ({ socketPath }) => {
   const serverPeers = [];
   const server = await listenForIpcConnections(socketPath, (transport) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.13",
+  "version": "0.6.15",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",
@@ -9,7 +9,6 @@
     "url": "https://github.com/saffron-health/libretto"
   },
   "type": "module",
-  "packageManager": "pnpm@10.33.0",
   "publishConfig": {
     "access": "public"
   },
@@ -86,6 +85,7 @@
     "vitest": "^4.1.5"
   },
   "dependencies": {
+    "affordance": "^0.1.0",
     "ai": "^6.0.116",
     "esbuild": "^0.27.0",
     "playwright": "^1.58.2",

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.13"
+  version: "0.6.15"
 ---
 
 ## How Libretto Works
@@ -19,18 +19,20 @@ The npm package includes `src/` (full TypeScript source) and `docs/` for deeper
 
 Full documentation is published at [libretto.sh](https://libretto.sh). Available pages:
 
-- Get started: [introduction](https://libretto.sh/get-started/introduction), [installation](https://libretto.sh/get-started/installation), [configuration](https://libretto.sh/get-started/configuration)
-- Fundamentals: [core concepts](https://libretto.sh/fundamentals/core-concepts), [how workflow generation works](https://libretto.sh/fundamentals/how-workflow-generation-works), [automation and bot detection](https://libretto.sh/fundamentals/automation-and-bot-detection), [website authentication](https://libretto.sh/fundamentals/website-authentication)
-- Workflow guides: [one-shot generation](https://libretto.sh/workflow-guides/one-shot-workflow-generation), [interactive building](https://libretto.sh/workflow-guides/interactive-workflow-building), [debugging workflows](https://libretto.sh/workflow-guides/debugging-workflows), [convert to network requests](https://libretto.sh/workflow-guides/convert-to-network-requests)
-- CLI reference: [open and connect](https://libretto.sh/cli-reference/open-and-connect), [sessions](https://libretto.sh/cli-reference/sessions), [profiles](https://libretto.sh/cli-reference/profiles), [snapshot](https://libretto.sh/cli-reference/snapshot), [exec](https://libretto.sh/cli-reference/exec), [run and resume](https://libretto.sh/cli-reference/run-and-resume), [session logs](https://libretto.sh/cli-reference/session-logs), [pages](https://libretto.sh/cli-reference/pages)
-- Library API: [workflow](https://libretto.sh/library-api/workflow), [AI extraction](https://libretto.sh/library-api/ai-extraction), [network requests](https://libretto.sh/library-api/network-requests), [file downloads](https://libretto.sh/library-api/file-downloads)
-- Hosting: [introduction](https://libretto.sh/hosting/introduction), [GCP](https://libretto.sh/hosting/gcp), [AWS](https://libretto.sh/hosting/aws)
+- Get started: [quickstart](https://libretto.sh/docs/get-started/quickstart), [first workflow](https://libretto.sh/docs/get-started/first-workflow), [deploying](https://libretto.sh/docs/get-started/deploying)
+- Fundamentals: [core concepts](https://libretto.sh/docs/understand-libretto/core-concepts), [how workflow generation works](https://libretto.sh/docs/understand-libretto/how-workflow-generation-works), [automation and bot detection](https://libretto.sh/docs/understand-libretto/automation-and-bot-detection), [website authentication](https://libretto.sh/docs/understand-libretto/website-authentication)
+- Workflow guides: [one-shot generation](https://libretto.sh/docs/guides/one-shot-workflow-generation), [interactive building](https://libretto.sh/docs/guides/interactive-workflow-building), [debugging workflows](https://libretto.sh/docs/guides/debugging-workflows), [convert to network requests](https://libretto.sh/docs/guides/convert-to-network-requests)
+- CLI reference: [open and connect](https://libretto.sh/docs/reference/cli/open-and-connect), [sessions](https://libretto.sh/docs/reference/cli/sessions), [profiles](https://libretto.sh/docs/reference/cli/profiles), [snapshot](https://libretto.sh/docs/reference/cli/snapshot), [exec](https://libretto.sh/docs/reference/cli/exec), [run and resume](https://libretto.sh/docs/reference/cli/run-and-resume), [session logs](https://libretto.sh/docs/reference/cli/session-logs), [pages](https://libretto.sh/docs/reference/cli/pages)
+- Library API: [workflow](https://libretto.sh/docs/reference/runtime/workflow), [AI extraction](https://libretto.sh/docs/reference/runtime/ai-extraction), [network requests](https://libretto.sh/docs/reference/runtime/network-requests), [file downloads](https://libretto.sh/docs/reference/runtime/file-downloads)
+- Libretto Cloud Hosting: [overview](https://libretto.sh/docs/libretto-cloud-hosting/overview), [authentication](https://libretto.sh/docs/libretto-cloud-hosting/authentication), [deployments](https://libretto.sh/docs/libretto-cloud-hosting/deployments)
+- Alternative providers: [overview](https://libretto.sh/docs/alternative-providers/overview), [Kernel](https://libretto.sh/docs/alternative-providers/kernel), [Browserbase](https://libretto.sh/docs/alternative-providers/browserbase), [GCP](https://libretto.sh/docs/alternative-providers/gcp), [AWS](https://libretto.sh/docs/alternative-providers/aws)
 
 ## Default Integration Approach
 
-- Prefer network requests first for new integrations unless the user explicitly asks for Playwright or UI automation, then do not use the site's internal API.
-- Read `references/site-security-review.md` before committing to a network-first approach on a new site.
-- Fall back to passive interception or Playwright-driven UI automation when the security review rules network requests out, the request path is not workable, or the user explicitly asks for Playwright.
+- Use Playwright for navigation and other non-fetch browser behavior, including document and asset loads.
+- Prefer browser-context `fetch()` for data extraction and form submission when the target is a real site fetch/XHR endpoint and `references/site-security-review.md` says the path is safe and workable.
+- Use passive interception when the UI already triggers useful fetch/XHR requests or active fetch is risky.
+- Fall back to Playwright UI automation when fetch is ruled out, the request path is not workable, or the user explicitly asks for Playwright/UI automation.
 
 ## Setup
 
@@ -48,8 +50,8 @@ Full documentation is published at [libretto.sh](https://libretto.sh). Available
 - Do not treat visibility as interactivity. If an element will not act, inspect blockers before retrying.
 - Defer repo/code review until you begin generating code, unless the user explicitly asks for it earlier.
 - Read and follow guidelines in `references/code-generation-rules.md` before generating or editing production workflow code.
-- Validation requires a successful clean `run --headless` with confirmation of the actual returned output, not just process success. If the user wants to watch the finished workflow, do a final headed `run` after headless validation succeeds.
-- After validation, always show the user: (1) the output/results from the headless validation run, and (2) a headed version of the same command so they can re-run it themselves and watch the browser (e.g. replace `--headless` with `--headed`). Include any `--params` or `--auth-profile` flags the workflow needs.
+- Validation requires a successful clean `run` with confirmation of the actual returned output, not just process success. Use the same headed or headless mode that the workflow run is already using.
+- After validation, always show the user: (1) the output/results from the validation run, and (2) the same command so they can re-run it themselves. Include any `--params`, `--headed`, `--headless`, or `--auth-profile` flags the workflow needs.
 - Treat exploration sessions as disposable unless the user explicitly wants one kept open.
 - Get explicit user confirmation before mutating actions or replaying network requests that may have side effects.
 - Never run multiple `exec` commands at the same time.
@@ -113,17 +115,18 @@ npx libretto snapshot --session debug-example --page <page-id>
 - Use `exec` for focused inspection and short-lived interaction experiments.
 - Use `exec` to validate selectors, inspect data, or prototype a step before you encode it in the workflow file.
 - Use `exec -` to run multi-line scripts from stdin, especially when the code is too long or complex for a command line argument.
-- Available globals: `page`, `context`, `browser`, `state`, `fetch`, `Buffer`.
+- The `exec` REPL is persistent for each browser session. Define helper functions once and reuse them in later `exec` calls.
+- Available globals: `page`, `frame`, `context`, `browser`, `fetch`, `Buffer`.
 - Let failures throw. Do not hide `exec` failures with `try/catch` or `.catch()`.
 - Do not run multiple `exec` commands in parallel.
 - Do not use `exec` in read-only diagnosis flows. Use `readonly-exec` from the `libretto-readonly` skill for those sessions.
 - After successful mutations, `exec` prints page-change diffs from compact snapshots.
 
 ```bash
-npx libretto exec "return await page.url()"
-npx libretto exec "return await page.locator('button').count()"
+npx libretto exec "await page.url()"
 npx libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
-echo "return await page.url()" | npx libretto exec - --session debug-example
+echo "async function textOf(selector) { return await page.locator(selector).textContent(); }" | npx libretto exec - --session debug-example
+npx libretto exec --session debug-example "await textOf('h1')"
 ```
 
 ### `pages`
@@ -133,13 +136,13 @@ echo "return await page.url()" | npx libretto exec - --session debug-example
 
 ```bash
 npx libretto pages --session debug-example
-npx libretto exec --session debug-example --page <page-id> "return await page.url()"
+npx libretto exec --session debug-example --page <page-id> "await page.url()"
 ```
 
 ### `run`
 
-- 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.
+- Use `run` to verify a workflow file after creating it or editing it. Use the same headed or headless mode for validation that the workflow run is already using.
+- Plain `run` defaults to headed mode. Do not use `--headless` unless the user asks for headless mode or the existing workflow run already uses it.
 - 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.
@@ -148,9 +151,9 @@ npx libretto exec --session debug-example --page <page-id> "return await page.ur
 - Re-run the same workflow after each fix to verify the browser behavior end to end.
 
 ```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 --params '{"status":"open"}'
+npx libretto run ./integration.ts --read-only
+npx libretto run ./integration.ts --stay-open-on-success
 npx libretto run ./integration.ts --auth-profile app.example.com
 ```
 
@@ -230,10 +233,10 @@ Assistant: [Uses `snapshot` and `exec` as needed to understand the site and deci
 Assistant: [Reads `references/code-generation-rules.md` before writing production workflow code]
 Assistant: I found the working path. I'll now create the workflow file and verify it.
 Assistant: [Creates or edits `target-workflow.ts` following `references/code-generation-rules.md`]
-Assistant: [Runs `npx libretto run ./target-workflow.ts --headless --params '{"status":"open"}'` to validate]
+Assistant: [Runs `npx libretto run ./target-workflow.ts --params '{"status":"open"}'` to validate]
 Assistant: Validation passed. Here are the results:
-[Shows the output/results from the headless run]
-To watch it yourself in a browser, run: npx libretto run ./target-workflow.ts --headed --params '{"status":"open"}'
+[Shows the output/results from the validation run]
+To run it again, use: npx libretto run ./target-workflow.ts --params '{"status":"open"}'
 </example>
 ```
 
@@ -243,17 +246,17 @@ To watch it yourself in a browser, run: npx libretto run ./target-workflow.ts --
 <example>
 [Context: The user has an existing Libretto workflow that is failing]
 Assistant: I'll reproduce the failure first so we can inspect the exact browser state it leaves behind.
-Assistant: [Runs `npx libretto run ./integration.ts --session debug-flow --headed`]
+Assistant: [Runs `npx libretto run ./integration.ts --session debug-flow`]
 Assistant: The workflow failed and Libretto kept the browser open. I'll inspect the page state before changing code.
 Assistant: [Runs `npx libretto snapshot --session debug-flow`]
 Assistant: [Runs `npx libretto exec --session debug-flow "...focused inspection or prototype..."`]
 Assistant: [Reads `references/code-generation-rules.md` before patching the workflow file]
 Assistant: I found the issue. I'll patch the workflow code and verify.
 Assistant: [Edits `integration.ts` following `references/code-generation-rules.md`]
-Assistant: [Runs `npx libretto run ./integration.ts --headless` to validate the fix]
+Assistant: [Runs `npx libretto run ./integration.ts` to validate the fix]
 Assistant: Fix verified. Here are the results:
-[Shows the output/results from the headless run]
-To watch it yourself in a browser, run: npx libretto run ./integration.ts --headed
+[Shows the output/results from the validation run]
+To run it again, use: npx libretto run ./integration.ts
 </example>
 ```
 
@@ -265,3 +268,4 @@ To watch it yourself in a browser, run: npx libretto run ./integration.ts --head
 - Read `references/auth-profiles.md` when auth-profile behavior is relevant.
 - Read `references/pages-and-page-targeting.md` when a session has multiple open pages or you need `--page`.
 - Read `references/action-logs.md` for full action log field descriptions and user-vs-agent event semantics.
+- If the workflow code is deployed to the Libretto Cloud platform and you need to reference its API docs, fetch [https://libretto.sh/docs/llms.txt](https://libretto.sh/docs/llms.txt) and follow the relevant page links.

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

@@ -117,6 +117,12 @@ Do not rely on broad DOM querying inside `page.evaluate()` for production flows
 
 ## Network Request Methods
 
+Network request methods are for active fetch/XHR endpoints the site already uses. Prefer them for data extraction or form submissions when the security review shows the path is safe and workable.
+
+Before codifying a network request, confirm that the browser primitive matches how the site normally makes that request. Use `page.goto()` or link clicks for document navigation. Use `page.evaluate(fetch)` only for endpoints the site calls with fetch/XHR. Let the DOM load scripts, images, stylesheets, and iframes naturally, or create the corresponding DOM element if you truly need that request type.
+
+Do not use `fetch()` to avoid UI navigation for page HTML or asset URLs. The request still comes from the browser, but the browser marks it as fetch/XHR with different request-context headers than a navigation, script, image, stylesheet, or iframe load. Do not try to fix that by copying headers, because the browser controls the request context. Prefer passive network interception when the site's own UI already triggers the useful request.
+
 When codifying network-based data extraction or form submissions, wrap `page.evaluate(() => fetch(...))` calls in typed methods on a shared API client class:
 
 ```typescript

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

@@ -6,6 +6,7 @@ Use this reference when you need to inspect or change workspace configuration fo
 
 - You want to understand where Libretto stores workspace-level settings.
 - You want a persistent default viewport for `open` or `run`.
+- You want a persistent default browser provider, such as Kernel or Browserbase.
 
 ## File Location
 
@@ -17,6 +18,9 @@ Libretto reads workspace config from `.libretto/config.json`.
 
 ## Supported Settings
 
+- `provider` is an optional top-level setting used by `open` and `run` when you do not pass `--provider` and do not set `LIBRETTO_PROVIDER`. Must be `"local"`, `"kernel"`, `"browserbase"`, or `"libretto-cloud"`.
+- Provider precedence is: CLI `--provider`, then `LIBRETTO_PROVIDER`, then `.libretto/config.json`, then `"local"`.
+- Provider credentials belong in the repo root `.env` file, which Libretto loads automatically before running CLI commands.
 - `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.
@@ -26,6 +30,7 @@ Example:
 ```json
 {
   "version": 1,
+  "provider": "kernel",
   "viewport": {
     "width": 1280,
     "height": 800
@@ -39,11 +44,14 @@ Example:
 ```bash
 npx libretto setup                                         # first-time onboarding
 npx libretto status                                        # inspect open sessions
+npx libretto open https://example.com --provider kernel
+npx libretto run ./integration.ts --provider browserbase
 npx libretto open https://example.com --viewport 1440x900
 npx libretto run ./integration.ts --viewport 1440x900
 ```
 
 ## Notes
 
+- If you want a persistent default provider for the workspace, add `provider` to `.libretto/config.json` instead of repeating `--provider` on every command.
 - If you want a persistent default viewport for the workspace, add `viewport` to `.libretto/config.json` instead of repeating `--viewport` on every command.
 - Run `npx libretto status` at any time to check open sessions.

package/skills/libretto/references/site-security-review.md

@@ -60,10 +60,11 @@ Use the review above to decide what is safe to prioritize. Every integration use
 
 ### Strategy A: Prioritize `page.evaluate(fetch(...))`
 
-Make fetch calls directly from within the browser's JavaScript context. The requests share the browser's TLS fingerprint, cookies, and origin. They look identical to requests the site's own JS would make.
+Make fetch calls directly from within the browser's JavaScript context. Use this only for endpoints the site already calls with fetch/XHR, not for page navigation or asset loads.
 
 When to prioritize this:
 
+- The target endpoint is normally called by the site with fetch/XHR
 - No enterprise bot protection is detected
 - `fetch` is not monkey-patched
 - The API responses are parseable and useful
@@ -71,7 +72,7 @@ When to prioritize this:
 
 Why: maximum control and efficiency. You call exactly the endpoints you want with the parameters you want, skip UI rendering, and get structured JSON back. On sites without aggressive detection, this is the fastest and cleanest approach.
 
-Risk: if the site monitors fetch call stacks, your calls may be flagged because they do not originate from the site's bundled code. This is uncommon but exists on high-security sites.
+Risk: fetch is the wrong primitive for page HTML and asset URLs; use Playwright navigation or DOM-driven loads for those. Sites can also monitor fetch call stacks and flag calls that do not originate from the site's bundled code.
 
 You will still use Playwright for initial navigation, login/auth flows, cookie consent, and any UI interactions needed to establish session state before making fetch calls.
 
@@ -111,10 +112,9 @@ Trade-off: it is slower, more fragile against DOM changes, and you only get data
 
 | Site Profile | Primary Strategy | Supplement With |
 | --- | --- | --- |
-| No bot protection, fetch not patched | A (`page.evaluate(fetch)`) | Playwright for navigation/auth |
-| No bot protection, fetch is patched | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
-| Bot protection detected, fetch not patched | B (`page.on('response', ...)`) | Playwright for navigation; cautious use of `page.evaluate(fetch)` only if needed |
-| Bot protection detected, fetch is patched | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
+| No bot protection, fetch/XHR endpoint, fetch not patched | A (`page.evaluate(fetch)`) | Playwright for navigation/auth |
+| No bot protection, fetch is patched or endpoint is not fetch/XHR | B (`page.on('response', ...)`) | Playwright for navigation; DOM extraction as fallback |
+| Bot protection detected | B (`page.on('response', ...)`) | Playwright for navigation; cautious use of `page.evaluate(fetch)` only if needed |
 | Server-rendered content (no API calls) | C (DOM extraction) | Playwright for all interaction |
 
 ## Output: Site Assessment Summary

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.13"
+  version: "0.6.15"
 ---
 
 ## How Libretto Read-Only Works