libretto 0.6.27 → 0.6.29

package/dist/cli/commands/execution.js

@@ -6,6 +6,7 @@ import {
   connect,
   disconnectBrowser,
   runClose,
+  resolveWindowPosition,
   resolveViewport
 } from "../core/browser.js";
 import { parseViewportArg } from "./browser.js";
@@ -20,7 +21,9 @@ import {
   writeSessionState
 } from "../core/session.js";
 import { warnIfLibrettoVersionsDiffer } from "../core/skill-version.js";
-import { readLibrettoConfig } from "../core/config.js";
+import {
+  readLibrettoConfig
+} from "../core/config.js";
 import { renderSnapshotDiff } from "../../shared/snapshot/diff-snapshots.js";
 import {
   getProviderStartupTimeoutMs,
@@ -51,6 +54,20 @@ import {
   withRequiredSession
 } from "./shared.js";
 const require2 = moduleBuiltin.createRequire(import.meta.url);
+function createRunBrowserConfig(args) {
+  if (args.providerName) {
+    return {
+      kind: "provider",
+      providerName: args.providerName
+    };
+  }
+  return {
+    kind: "launch",
+    headed: !args.headless,
+    viewport: args.viewport ?? { width: 1366, height: 768 },
+    ...!args.headless && args.windowPosition ? { windowPosition: args.windowPosition } : {}
+  };
+}
 function writeDaemonExecOutput(output) {
   if (output?.stdout) {
     process.stdout.write(output.stdout);
@@ -427,14 +444,7 @@ async function runIntegrationFromFile(args, logger) {
     config: {
       session: args.session,
       experiments: args.experiments,
-      browser: args.providerName ? {
-        kind: "provider",
-        providerName: args.providerName
-      } : {
-        kind: "launch",
-        headed: !args.headless,
-        viewport: args.viewport ?? { width: 1366, height: 768 }
-      },
+      browser: createRunBrowserConfig(args),
       workflow: {
         integrationPath: absoluteIntegrationPath,
         params: args.params,
@@ -690,15 +700,18 @@ const runCommand = SimpleCLI.command({
     });
     console.log(`Connecting to ${providerName} browser...`);
   }
+  const headless = daemonProviderName ? true : headlessMode ?? false;
+  const windowPosition = headless ? void 0 : resolveWindowPosition(ctx.logger);
   await runIntegrationFromFile(
     {
       integrationPath: input.integrationFile,
       session: ctx.session,
       params,
       tsconfigPath: input.tsconfig,
-      headless: daemonProviderName ? true : headlessMode ?? false,
+      headless,
       visualize,
       viewport,
+      windowPosition,
       accessMode: input.readOnly ? "read-only" : input.writeAccess ? "write-access" : readLibrettoConfig().sessionMode ?? "write-access",
       providerName: daemonProviderName,
       stayOpenOnSuccess: input.stayOpenOnSuccess,
@@ -725,6 +738,7 @@ const executionCommands = {
   resume: resumeCommand
 };
 export {
+  createRunBrowserConfig,
   execCommand,
   execInput,
   executionCommands,

package/dist/cli/core/browser.js

@@ -1027,6 +1027,7 @@ export {
   normalizeUrl,
   resolvePath,
   resolveViewport,
+  resolveWindowPosition,
   runClose,
   runCloseAll,
   runConnect,

package/dist/cli/core/daemon/daemon.js

@@ -49,6 +49,7 @@ import {
 import { WorkflowController } from "../workflow-runner/runner.js";
 import { validateWorkflowInput } from "../../../shared/workflow/workflow.js";
 import { captureAuthProfileStorageState } from "../../../shared/workflow/auth-profile-state.js";
+import { applyWindowPosition } from "../../../shared/run/window-position.js";
 function isOperationalPage(page) {
   const url = page.url();
   return !url.startsWith("devtools://") && !url.startsWith("chrome-error://");
@@ -266,6 +267,7 @@ class BrowserDaemon {
       userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
     });
     const page = await context.newPage();
+    await applyWindowPosition(browser, context, page, config.windowPosition);
     page.setDefaultTimeout(3e4);
     page.setDefaultNavigationTimeout(45e3);
     const daemon = await BrowserDaemon.initialize({

package/dist/shared/run/browser.js

@@ -9,6 +9,9 @@ import {
   SessionStateFileSchema
 } from "../state/session-state.js";
 import { readLibrettoConfig } from "../../cli/core/config.js";
+import {
+  applyWindowPosition
+} from "./window-position.js";
 async function pickFreePort() {
   return await new Promise((resolve, reject) => {
     const server = createServer();
@@ -27,38 +30,6 @@ async function pickFreePort() {
 function resolveWindowPosition() {
   return readLibrettoConfig().windowPosition;
 }
-async function applyWindowPosition(browser, context, page, windowPosition) {
-  if (!windowPosition) {
-    return;
-  }
-  const requestedBounds = {
-    left: windowPosition.x,
-    top: windowPosition.y,
-    windowState: "normal"
-  };
-  const pageCdp = await context.newCDPSession(page);
-  let browserCdp;
-  try {
-    const targetInfo = await pageCdp.send("Target.getTargetInfo");
-    const targetId = targetInfo.targetInfo?.targetId;
-    browserCdp = await browser.newBrowserCDPSession();
-    const windowResult = await browserCdp.send(
-      "Browser.getWindowForTarget",
-      targetId ? { targetId } : {}
-    );
-    await browserCdp.send("Browser.setWindowBounds", {
-      windowId: windowResult.windowId,
-      bounds: requestedBounds
-    });
-    await new Promise((resolve) => setTimeout(resolve, 250));
-  } catch {
-  } finally {
-    await pageCdp.detach().catch(() => {
-    });
-    await browserCdp?.detach().catch(() => {
-    });
-  }
-}
 async function launchBrowser({
   sessionName,
   headless = false,

package/dist/shared/run/window-position.d.ts

@@ -0,0 +1,9 @@
+import { Browser, BrowserContext, Page } from 'playwright';
+
+type WindowPosition = {
+    x: number;
+    y: number;
+};
+declare function applyWindowPosition(browser: Browser, context: BrowserContext, page: Page, windowPosition: WindowPosition | undefined): Promise<void>;
+
+export { type WindowPosition, applyWindowPosition };

package/dist/shared/run/window-position.js

@@ -0,0 +1,36 @@
+async function applyWindowPosition(browser, context, page, windowPosition) {
+  if (!windowPosition) {
+    return;
+  }
+  const requestedBounds = {
+    left: windowPosition.x,
+    top: windowPosition.y,
+    windowState: "normal"
+  };
+  let pageCdp;
+  let browserCdp;
+  try {
+    pageCdp = await context.newCDPSession(page);
+    const targetInfo = await pageCdp.send("Target.getTargetInfo");
+    const targetId = targetInfo.targetInfo?.targetId;
+    browserCdp = await browser.newBrowserCDPSession();
+    const windowResult = await browserCdp.send(
+      "Browser.getWindowForTarget",
+      targetId ? { targetId } : {}
+    );
+    await browserCdp.send("Browser.setWindowBounds", {
+      windowId: windowResult.windowId,
+      bounds: requestedBounds
+    });
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  } catch {
+  } finally {
+    await pageCdp?.detach().catch(() => {
+    });
+    await browserCdp?.detach().catch(() => {
+    });
+  }
+}
+export {
+  applyWindowPosition
+};

package/dist/shared/workflow/authenticate.d.ts

@@ -5,8 +5,8 @@ import '../../runtime/recovery/page-fallbacks.js';
 import 'ai';
 
 type LibrettoAuthenticateOptions = {
-    validate: (ctx: LibrettoWorkflowContext) => Promise<boolean> | boolean;
-    fallback: (ctx: LibrettoWorkflowContext, credentials: Record<string, string>) => Promise<void> | void;
+    isSignedIn: (ctx: LibrettoWorkflowContext) => Promise<boolean> | boolean;
+    signIn: (ctx: LibrettoWorkflowContext, credentials: Record<string, string>) => Promise<void> | void;
     credentials?: Record<string, unknown>;
     envPrefix?: string;
 };

package/dist/shared/workflow/authenticate.js

@@ -1,13 +1,13 @@
 async function librettoAuthenticate(ctx, options) {
-  if (await options.validate(ctx)) {
+  if (await options.isSignedIn(ctx)) {
     return { usedProfile: true };
   }
   const credentials = normalizeCredentials(
     options.credentials ?? readCredentialsFromEnv(options.envPrefix)
   );
-  await options.fallback(ctx, credentials);
-  if (!await options.validate(ctx)) {
-    throw new Error("Authentication fallback completed, but validation still failed.");
+  await options.signIn(ctx, credentials);
+  if (!await options.isSignedIn(ctx)) {
+    throw new Error("Sign-in completed, but the session is still not signed in.");
   }
   return { usedProfile: false };
 }

package/docs/releasing.md

@@ -66,10 +66,13 @@ The root `scripts/prepare-release.sh` script does the following:
 1. Checks that the working tree is clean.
 2. Updates local `main` from `origin/main`.
 3. Runs `pnpm install --frozen-lockfile`, `pnpm --filter libretto type-check`, and `pnpm --filter libretto test`.
-4. Bumps the version in `packages/libretto/package.json`.
-5. Creates a release branch.
-6. Commits the version bump.
-7. Pushes the branch and opens a PR to `main` with the `release` label.
+4. Checks whether `packages/affordance` changed since the current Libretto release tag, excluding `packages/affordance/package.json` version-only changes. If source/package contents changed, the script runs Affordance type-check/tests and bumps `packages/affordance/package.json` by one patch version when the current Affordance version is already published to npm.
+5. Bumps the version in `packages/libretto/package.json`.
+6. Creates a release branch.
+7. Commits the version bump.
+8. Pushes the branch and opens a PR to `main` with the `release` label.
+
+Affordance is published before Libretto in `.github/workflows/release.yml`. Keeping this automatic patch bump in the release PR prevents Libretto from depending on unpublished Affordance APIs while still avoiding unnecessary Affordance releases when its package contents did not change.
 
 Release PRs also run the eval workflow. That workflow records score, duration, token, cost, and tool-call metrics for review. Scores are informational: low scores do not fail the workflow, but setup/runtime failures and zero completed records do.
 
@@ -80,12 +83,12 @@ After the release PR merges, `.github/workflows/release.yml` runs on `main`.
 The workflow:
 
 1. Reads the version from `packages/libretto/package.json`.
-2. Checks whether that version already exists on npm and in GitHub Releases.
+2. Checks whether that version already exists on npm and in GitHub Releases. It also checks whether the current `packages/affordance/package.json` version and matching `create-libretto` version already exist on npm.
 3. Runs install, type-check, and tests for the `libretto` package in a verification job.
 4. Publishes `affordance` first, then `libretto@X.Y.Z`, then `create-libretto@X.Y.Z` with trusted publishing.
 5. Creates GitHub release `vX.Y.Z` with generated release notes if it does not already exist.
 
-This makes the workflow safe to re-run after partial failures. For example, if npm publish succeeds but GitHub release creation fails, a re-run will skip npm and only create the missing release.
+This makes the workflow safe to re-run after partial failures. For example, if npm publish succeeds but GitHub release creation fails, a re-run will skip npm and only create the missing release. It also means Affordance can still be published if its version is missing even when the Libretto npm package and GitHub release for the current Libretto version already exist.
 
 ## Eval gating on release PRs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.27",
+  "version": "0.6.29",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",
@@ -8,6 +8,9 @@
     "type": "git",
     "url": "https://github.com/saffron-health/libretto"
   },
+  "bugs": {
+    "url": "https://github.com/saffron-health/libretto/issues"
+  },
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -67,7 +70,7 @@
     "playwright": "^1.58.2",
     "tsx": "^4.21.0",
     "zod": "^4.3.6",
-    "affordance": "^0.2.0"
+    "affordance": "^0.2.1"
   },
   "scripts": {
     "sync:mirrors": "node ../dev-tools/scripts/sync-mirrors.mjs",

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.27"
+  version: "0.6.29"
 ---
 
 ## How Libretto Works
@@ -15,17 +15,7 @@ metadata:
 
 ## Shipped Source & Documentation
 
-The npm package includes `src/` (full TypeScript source) and `docs/` for deeper understanding of internals and design decisions. Read these when you need implementation context beyond what this skill file covers. Resolve paths from the package root (e.g. `node_modules/libretto/`).
-
-Full documentation is published at [libretto.sh](https://libretto.sh). Available pages:
-
-- 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), [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), [stealth](https://libretto.sh/docs/libretto-cloud-hosting/stealth)
-- 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), [Steel](https://libretto.sh/docs/alternative-providers/steel), [GCP](https://libretto.sh/docs/alternative-providers/gcp), [AWS](https://libretto.sh/docs/alternative-providers/aws)
+Read `references/shipped-source-and-documentation.md` for shipped source details, published documentation links, and implementation context beyond what this skill file covers.
 
 ## Default Integration Approach
 
@@ -48,6 +38,7 @@ Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first
 - Use the package manager convention for the target project. The examples use `npx libretto`; pnpm, yarn, and bun projects should use their equivalent package-manager execution form.
 - Use `npx libretto setup` for first-time workspace onboarding. It installs Chromium and syncs skills.
 - Use `npx libretto status` to inspect open sessions without triggering setup.
+- Use `npx libretto update` to upgrade the project-local Libretto package. Use `npx libretto update --dry-run` to preview the package-manager command first.
 
 ## Experiments
 
@@ -60,7 +51,11 @@ Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first
 - 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` 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.
+- For authenticated workflows, manual login is discovery only. After the user logs in, read only the sign-in action logs and identify the required credentials; if credentials are unclear, ask before writing code.
+- Add missing blank `LIBRETTO_CLOUD_<secret_name>=` entries without overwriting populated values. If any required credential is blank, stop and ask the user to fill it; until then, do not inspect logged-in pages, read authenticated network bodies, write workflow code, open validation sessions, or continue discovery.
+- Authenticated workflows must implement `librettoAuthenticate` with declared credentials before validation. Use a reusable `*_totp_secret` credential for authenticator-app MFA, not a one-time `otp_code`; text and email verification codes are not supported for fully automated sign-in.
+- Read `references/website-authentication.md` when you need `librettoAuthenticate` examples or auth-profile details.
+- Validation requires a successful clean `run` on a fresh, unauthenticated session 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`, or `--headless` 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.
@@ -241,13 +236,15 @@ Key fields: `id` (incrementing request id), `ts` (ISO timestamp), `pageId` (page
 [Context: The user wants to build a new browser workflow and does not yet know the page structure]
 Assistant: I'll inspect the real site first if needed, but before I finish I'll create `target-workflow.ts` so the task produces reusable automation code.
 Assistant: [Runs `npx libretto open https://target.example.com --headed`]
+Assistant: [If sign-in is required, follows the authenticated workflow rules before continuing]
 Assistant: [Reads `references/site-security-review.md` before choosing between passive network inspection, direct browser fetch calls, and Playwright-first automation]
 Assistant: [Runs `npx libretto snapshot --session <session>`]
 Assistant: [Uses `snapshot` and `exec` as needed to understand the site and decide the implementation path]
 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 --params '{"status":"open"}'` to validate]
+Assistant: [Runs `npx libretto run ./target-workflow.ts --params '{"status":"open"}'` on a fresh, unauthenticated session to verify both sign-in and workflow behavior]
+Assistant: [If sign-in validation passes and a reusable session is useful, adds an auth profile and reruns validation]
 Assistant: Validation passed. Here are the results:
 [Shows the output/results from the validation run]
 To run it again, use: npx libretto run ./target-workflow.ts --params '{"status":"open"}'
@@ -279,7 +276,7 @@ To run it again, use: npx libretto run ./integration.ts
 - Read `references/configuration-file-reference.md` when you need to inspect or change `.libretto/config.json` for viewport or session defaults.
 - Read `references/site-security-review.md` before reviewing the site's security posture and deciding whether to lead with network requests, passive interception, or Playwright DOM automation on a new site.
 - Read `references/code-generation-rules.md` before writing or editing production workflow files.
-- Read `references/auth-profiles.md` when auth-profile behavior is relevant.
+- Read `references/website-authentication.md` when website sign-in implementation or 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

@@ -49,7 +49,7 @@ Key points:
 - After validation is complete and the workflow is confirmed working end to end, remove all `pause()` calls and pause-only workflow params unless the user explicitly says to keep them.
 - The browser is launched and closed automatically by the CLI. Do not launch or close it in the handler.
 
-## Workflow Credentials And Auth Profiles
+## Workflow Credentials And Authentication
 
 Declare `credentials` for runtime secrets instead of putting them in the Zod input schema or `--params`. Only declared names are injected into `input.credentials`; local runs read matching `LIBRETTO_CLOUD_` variables from `.env`, and hosted runs read matching Libretto Cloud credentials. For example, `LIBRETTO_CLOUD_OPENAI_API_KEY` becomes `input.credentials.openai_api_key`.
 
@@ -70,14 +70,7 @@ export default workflow("sentimentWorkflow", {
 });
 ```
 
-For logged-in website workflows, unless the user says otherwise, generate both:
-
-- `authProfile: { name, refresh: true }`
-- `librettoAuthenticate(...)` fallback login logic using declared credentials such as `credentials: ["username", "password"]`
-
-After generating or validating a credentialed workflow, include the local `.env` variable names the user must set, and never print secret values.
-
-The fallback should validate the signed-in state, log in when validation fails, and validate again before continuing. Follow `references/auth-profiles.md` for profile naming, refresh behavior, hosted profile behavior, and the fallback-login pattern.
+For website workflows that require signing in, build working sign-in logic with `librettoAuthenticate` and verify it from a clean signed-out browser before adding an auth profile. Follow `references/website-authentication.md`.
 
 ## Workflow Error Handling
 

package/skills/libretto/references/shipped-source-and-documentation.md

@@ -0,0 +1,13 @@
+# Shipped Source & Documentation
+
+The npm package includes `src/` (full TypeScript source) and `docs/` for deeper understanding of internals and design decisions. Resolve paths from the package root, such as `node_modules/libretto/`.
+
+Full documentation is published at [libretto.sh](https://libretto.sh). Available pages:
+
+- 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), [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), [stealth](https://libretto.sh/docs/libretto-cloud-hosting/stealth)
+- 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), [Steel](https://libretto.sh/docs/alternative-providers/steel), [GCP](https://libretto.sh/docs/alternative-providers/gcp), [AWS](https://libretto.sh/docs/alternative-providers/aws)

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

@@ -43,7 +43,7 @@ General guidance: determine whether the site has bot protection and roughly how
 
 ### Probe 2: Fetch and XHR Interception
 
-Check whether the site has monkey-patched `window.fetch` or `XMLHttpRequest`. If it has, making your own fetch calls from `page.evaluate()` is risky because the site can inspect call stacks and detect calls that do not originate from its own code.
+Check whether the site has monkey-patched `window.fetch` or `XMLHttpRequest`. Patching is a caution signal, not an automatic blocker. Browser-context network requests are usually fine when the target endpoint is already called by the site with fetch/XHR and there is no strong bot-protection evidence.
 
 ```js
 window.fetch.toString()
@@ -52,7 +52,7 @@ Object.getOwnPropertyDescriptor(window, 'fetch')
 window.fetch.hasOwnProperty('prototype')
 ```
 
-Important: some sites use `Proxy` to wrap fetch, which makes `toString()` still return `"[native code]"`. The prototype check is a heuristic, not definitive. If you see any sign of fetch interception, treat it as patched.
+Important: ordinary app instrumentation and Libretto's own page-stability tracking can also wrap fetch/XHR. Treat browser fetch as risky only when the wrapper appears security-related, obfuscated, tied to bot-protection scripts, or likely to inspect call stacks. Some `Proxy` wrappers still stringify as `"[native code]"`, so these checks are only heuristics.
 
 ## Choosing a Data Capture Strategy
 
@@ -66,7 +66,7 @@ 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
+- No security-related fetch/XHR interception is detected, or the observed wrapper appears to be ordinary app instrumentation
 - The API responses are parseable and useful
 - You need data that requires many API calls (deep pagination, bulk queries) where driving the UI would be slow
 
@@ -83,7 +83,7 @@ Listen to network responses that the browser naturally makes as you navigate. Yo
 When to prioritize this:
 
 - Enterprise bot protection is detected
-- `fetch` is monkey-patched
+- Security-related fetch/XHR interception is detected
 - The site's normal UI flow triggers API calls that return the data you need
 - You want to minimize detection risk as much as possible
 
@@ -112,8 +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/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 |
+| No bot protection, fetch/XHR endpoint, no security-related interception | A (`page.evaluate(fetch)`) | Playwright for navigation/auth |
+| No bot protection, harmless app instrumentation, fetch/XHR endpoint | A (`page.evaluate(fetch)`) | B (`page.on('response', ...)`) if requests fail |
+| No bot protection, security-related interception 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 |
 

package/skills/libretto/references/website-authentication.md

@@ -0,0 +1,73 @@
+# Website Authentication
+
+Use this reference when a workflow needs a logged-in website session. The Working Rules in `../SKILL.md` define the required auth workflow; this file explains how to implement sign-in logic with `librettoAuthenticate`, and how auth profiles save signed-in state for later runs.
+
+Build and verify working sign-in logic first. The sign-in code takes priority; an auth profile is added only after the sign-in logic is verified, never as a substitute for it.
+
+## Sign-In Logic
+
+Use `librettoAuthenticate` so the workflow can sign in from a fresh browser. Declare each required secret in the workflow credentials array and use those credentials inside `signIn`.
+
+```typescript
+import { librettoAuthenticate, workflow } from "libretto";
+
+export default workflow("accountWorkflow", {
+  credentials: ["portal_username", "portal_password"],
+  async handler(ctx, input) {
+    const { page } = ctx;
+
+    await page.goto("https://app.example.com/dashboard");
+
+    // Sign in when the session is not already authenticated.
+    await librettoAuthenticate(ctx, {
+      credentials: input.credentials,
+      isSignedIn: async () =>
+        await page
+          .getByRole("heading", { name: "Dashboard" })
+          .isVisible()
+          .catch(() => false),
+      signIn: async (_ctx, credentials) => {
+        await page.goto("https://app.example.com/login");
+        await page.getByLabel("Email").fill(credentials.portal_username);
+        await page.getByLabel("Password").fill(credentials.portal_password);
+        await page.getByRole("button", { name: "Sign in" }).click();
+        await page.getByRole("heading", { name: "Dashboard" }).waitFor();
+      },
+    });
+
+    // Continue with the signed-in workflow steps.
+  },
+});
+```
+
+## Auth Profiles
+
+Auth profiles save the signed-in browser state (cookies, localStorage, IndexedDB) so later runs can reuse a logged-in session instead of signing in from scratch. The sign-in logic still takes priority: do not add a profile until the `librettoAuthenticate` sign-in step has been verified from a signed-out browser with no profile present. If you add a profile first, validation passes on the saved session while the untested sign-in logic fails the first time that session expires.
+
+A profile only holds whatever a signed-in session wrote into it, so it does nothing until a run has signed in at least once. With `refresh: true`, a successful run writes updated browser state back to the profile, so a fresh sign-in repairs an expired one. Local runs load `.libretto/profiles/<name>.json`; hosted runs use the provider-native profile with the same name.
+
+Add the profile to the workflow you already verified:
+
+```typescript
+export default workflow("accountWorkflow", {
+  // Added only after the signIn step above is verified standalone.
+  authProfile: { name: "example-account", refresh: true },
+  credentials: ["portal_username", "portal_password"],
+  // ...same handler and librettoAuthenticate call as above.
+});
+```
+
+## Commands
+
+```bash
+# Save the current signed-in session as a named, site-scoped profile.
+npx libretto save example-app --session login --sites app.example.com,auth.example.com
+
+# List or delete hosted auth profile names.
+npx libretto cloud profiles list
+npx libretto cloud profiles delete example-app
+```
+
+`save` captures cookies, localStorage, and IndexedDB only for the comma-separated `--sites` list.
+
+To reuse an existing signed-in Chrome profile instead of signing in, use `npx libretto import-chrome-profiles`. Get the user's consent first, since attaching can close or relaunch their Chrome window.

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

package/src/cli/commands/execution.ts

@@ -7,6 +7,7 @@ import {
   connect,
   disconnectBrowser,
   runClose,
+  resolveWindowPosition,
   resolveViewport,
 } from "../core/browser.js";
 import { parseViewportArg } from "./browser.js";
@@ -22,7 +23,10 @@ import {
   type SessionState,
 } from "../core/session.js";
 import { warnIfLibrettoVersionsDiffer } from "../core/skill-version.js";
-import { readLibrettoConfig } from "../core/config.js";
+import {
+  readLibrettoConfig,
+  type WindowPositionConfig,
+} from "../core/config.js";
 import { renderSnapshotDiff } from "../../shared/snapshot/diff-snapshots.js";
 import {
   getProviderStartupTimeoutMs,
@@ -41,6 +45,7 @@ import {
   type DaemonExecResult,
   type DaemonToCliApi,
 } from "../core/daemon/ipc.js";
+import type { DaemonConfig } from "../core/daemon/config.js";
 import { createReadonlyExecHelpers } from "../core/readonly-exec.js";
 import {
   readActionLog,
@@ -66,6 +71,7 @@ type RunIntegrationCommandRequest = {
   headless: boolean;
   visualize: boolean;
   viewport?: { width: number; height: number };
+  windowPosition?: WindowPositionConfig;
   accessMode: SessionAccessMode;
   providerName?: string;
   stayOpenOnSuccess: boolean;
@@ -76,6 +82,29 @@ type ExecMode = "exec" | "readonly-exec";
 
 const require = moduleBuiltin.createRequire(import.meta.url);
 
+export function createRunBrowserConfig(args: {
+  providerName?: string;
+  headless: boolean;
+  viewport?: { width: number; height: number };
+  windowPosition?: WindowPositionConfig;
+}): DaemonConfig["browser"] {
+  if (args.providerName) {
+    return {
+      kind: "provider",
+      providerName: args.providerName,
+    };
+  }
+
+  return {
+    kind: "launch",
+    headed: !args.headless,
+    viewport: args.viewport ?? { width: 1366, height: 768 },
+    ...(!args.headless && args.windowPosition
+      ? { windowPosition: args.windowPosition }
+      : {}),
+  };
+}
+
 function writeDaemonExecOutput(output?: { stdout: string; stderr: string }) {
   if (output?.stdout) {
     process.stdout.write(output.stdout);
@@ -575,16 +604,7 @@ async function runIntegrationFromFile(
     config: {
       session: args.session,
       experiments: args.experiments,
-      browser: args.providerName
-        ? {
-            kind: "provider",
-            providerName: args.providerName,
-          }
-        : {
-            kind: "launch",
-            headed: !args.headless,
-            viewport: args.viewport ?? { width: 1366, height: 768 },
-      },
+      browser: createRunBrowserConfig(args),
       workflow: {
         integrationPath: absoluteIntegrationPath,
         params: args.params,
@@ -875,15 +895,21 @@ export const runCommand = SimpleCLI.command({
       console.log(`Connecting to ${providerName} browser...`);
     }
 
+    const headless = daemonProviderName ? true : (headlessMode ?? false);
+    const windowPosition = headless
+      ? undefined
+      : resolveWindowPosition(ctx.logger);
+
     await runIntegrationFromFile(
       {
         integrationPath: input.integrationFile!,
         session: ctx.session,
         params,
         tsconfigPath: input.tsconfig,
-        headless: daemonProviderName ? true : (headlessMode ?? false),
+        headless,
         visualize,
         viewport,
+        windowPosition,
         accessMode: input.readOnly ? "read-only" : input.writeAccess ? "write-access" : (readLibrettoConfig().sessionMode ?? "write-access"),
         providerName: daemonProviderName,
         stayOpenOnSuccess: input.stayOpenOnSuccess,

package/src/cli/core/browser.ts

@@ -388,7 +388,7 @@ export function resolveViewport(
   return DEFAULT_VIEWPORT;
 }
 
-function resolveWindowPosition(
+export function resolveWindowPosition(
   logger: LoggerApi,
 ): { x: number; y: number } | undefined {
   const config = readLibrettoConfig();

package/src/cli/core/daemon/daemon.ts

@@ -91,6 +91,7 @@ import {
 import { WorkflowController } from "../workflow-runner/runner.js";
 import { validateWorkflowInput } from "../../../shared/workflow/workflow.js";
 import { captureAuthProfileStorageState } from "../../../shared/workflow/auth-profile-state.js";
+import { applyWindowPosition } from "../../../shared/run/window-position.js";
 
 function isOperationalPage(page: Page): boolean {
   const url = page.url();
@@ -397,6 +398,7 @@ class BrowserDaemon {
     });
 
     const page = await context.newPage();
+    await applyWindowPosition(browser, context, page, config.windowPosition);
     page.setDefaultTimeout(30000);
     page.setDefaultNavigationTimeout(45000);
 

package/src/shared/run/browser.ts

@@ -13,6 +13,10 @@ import {
   SessionStateFileSchema,
 } from "../state/session-state.js";
 import { readLibrettoConfig } from "../../cli/core/config.js";
+import {
+  applyWindowPosition,
+  type WindowPosition,
+} from "./window-position.js";
 
 async function pickFreePort(): Promise<number> {
   return await new Promise((resolve, reject) => {
@@ -49,53 +53,10 @@ export type BrowserSession = {
   close: () => Promise<void>;
 };
 
-function resolveWindowPosition(): { x: number; y: number } | undefined {
+function resolveWindowPosition(): WindowPosition | undefined {
   return readLibrettoConfig().windowPosition;
 }
 
-async function applyWindowPosition(
-  browser: Browser,
-  context: BrowserContext,
-  page: Page,
-  windowPosition: { x: number; y: number } | undefined,
-): Promise<void> {
-  if (!windowPosition) {
-    return;
-  }
-
-  const requestedBounds = {
-    left: windowPosition.x,
-    top: windowPosition.y,
-    windowState: "normal" as const,
-  };
-
-  const pageCdp = await context.newCDPSession(page);
-  let browserCdp:
-    | Awaited<ReturnType<Browser["newBrowserCDPSession"]>>
-    | undefined;
-  try {
-    const targetInfo = await pageCdp.send("Target.getTargetInfo");
-    const targetId = (
-      targetInfo as { targetInfo?: { targetId?: string } }
-    ).targetInfo?.targetId;
-    browserCdp = await browser.newBrowserCDPSession();
-    const windowResult = await browserCdp.send(
-      "Browser.getWindowForTarget",
-      targetId ? { targetId } : {},
-    );
-    await browserCdp.send("Browser.setWindowBounds", {
-      windowId: windowResult.windowId,
-      bounds: requestedBounds,
-    });
-    await new Promise((resolve) => setTimeout(resolve, 250));
-  } catch {
-    // Best-effort: window positioning should not prevent browser launch.
-  } finally {
-    await pageCdp.detach().catch(() => {});
-    await browserCdp?.detach().catch(() => {});
-  }
-}
-
 export async function launchBrowser({
   sessionName,
   headless = false,

package/src/shared/run/window-position.ts

@@ -0,0 +1,49 @@
+import type { Browser, BrowserContext, Page } from "playwright";
+
+export type WindowPosition = { x: number; y: number };
+
+export async function applyWindowPosition(
+  browser: Browser,
+  context: BrowserContext,
+  page: Page,
+  windowPosition: WindowPosition | undefined,
+): Promise<void> {
+  if (!windowPosition) {
+    return;
+  }
+
+  const requestedBounds = {
+    left: windowPosition.x,
+    top: windowPosition.y,
+    windowState: "normal" as const,
+  };
+
+  let pageCdp:
+    | Awaited<ReturnType<BrowserContext["newCDPSession"]>>
+    | undefined;
+  let browserCdp:
+    | Awaited<ReturnType<Browser["newBrowserCDPSession"]>>
+    | undefined;
+  try {
+    pageCdp = await context.newCDPSession(page);
+    const targetInfo = await pageCdp.send("Target.getTargetInfo");
+    const targetId = (
+      targetInfo as { targetInfo?: { targetId?: string } }
+    ).targetInfo?.targetId;
+    browserCdp = await browser.newBrowserCDPSession();
+    const windowResult = await browserCdp.send(
+      "Browser.getWindowForTarget",
+      targetId ? { targetId } : {},
+    );
+    await browserCdp.send("Browser.setWindowBounds", {
+      windowId: windowResult.windowId,
+      bounds: requestedBounds,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  } catch {
+    // Best-effort: window positioning should not prevent browser launch.
+  } finally {
+    await pageCdp?.detach().catch(() => {});
+    await browserCdp?.detach().catch(() => {});
+  }
+}

package/src/shared/workflow/authenticate.ts

@@ -1,8 +1,8 @@
 import type { LibrettoWorkflowContext } from "./workflow.js";
 
 export type LibrettoAuthenticateOptions = {
-  validate: (ctx: LibrettoWorkflowContext) => Promise<boolean> | boolean;
-  fallback: (
+  isSignedIn: (ctx: LibrettoWorkflowContext) => Promise<boolean> | boolean;
+  signIn: (
     ctx: LibrettoWorkflowContext,
     credentials: Record<string, string>,
   ) => Promise<void> | void;
@@ -14,17 +14,17 @@ export async function librettoAuthenticate(
   ctx: LibrettoWorkflowContext,
   options: LibrettoAuthenticateOptions,
 ): Promise<{ usedProfile: boolean }> {
-  if (await options.validate(ctx)) {
+  if (await options.isSignedIn(ctx)) {
     return { usedProfile: true };
   }
 
   const credentials = normalizeCredentials(
     options.credentials ?? readCredentialsFromEnv(options.envPrefix),
   );
-  await options.fallback(ctx, credentials);
+  await options.signIn(ctx, credentials);
 
-  if (!(await options.validate(ctx))) {
-    throw new Error("Authentication fallback completed, but validation still failed.");
+  if (!(await options.isSignedIn(ctx))) {
+    throw new Error("Sign-in completed, but the session is still not signed in.");
   }
 
   return { usedProfile: false };

package/skills/libretto/references/auth-profiles.md

@@ -1,79 +0,0 @@
-# Auth Profiles
-
-Use this reference when generating or maintaining workflows that need a logged-in website session.
-
-## When to Use This
-
-- The user wants to persist authentication across runs.
-- The workflow should recover when saved login state is stale.
-
-## Workflow
-
-- Open the site in headed mode.
-- Ask the user to log in manually.
-- Save the current session as a named, site-scoped profile.
-- Run a workflow that declares the profile and includes fallback login logic.
-
-## Commands
-
-```bash
-# Save scoped auth state from the current Libretto session.
-npx libretto save example-app --session login --sites app.example.com,auth.example.com
-
-# List or delete hosted auth profile names.
-npx libretto cloud profiles list
-npx libretto cloud profiles delete example-app
-```
-
-## Workflow Definition
-
-Use `authProfile` to reuse a named login profile: local runs load
-`.libretto/profiles/<name>.json`, while hosted runs use provider-native profiles
-that `libretto cloud deploy` registers by name without uploading local files.
-Use `{ name, refresh: true }` when successful runs should persist updated
-browser state back to the profile. Pair profile use with `librettoAuthenticate`
-so stale local or hosted sessions can fall back to login with declared
-credentials before the workflow continues.
-
-```typescript
-import { librettoAuthenticate, workflow } from "libretto";
-
-export default workflow("accountWorkflow", {
-  authProfile: {
-    name: "example-account",
-    refresh: true,
-  },
-  credentials: ["username", "password"],
-  async handler(ctx, input) {
-    const { page } = ctx;
-
-    await page.goto("https://app.example.com/dashboard");
-
-    await librettoAuthenticate(ctx, {
-      credentials: input.credentials,
-      validate: async ({ page }) =>
-        await page.getByRole("heading", { name: "Dashboard" })
-          .isVisible()
-          .catch(() => false),
-      fallback: async ({ page }, credentials) => {
-        await page.goto("https://app.example.com/login");
-        await page.getByLabel("Email").fill(credentials.username);
-        await page.getByLabel("Password").fill(credentials.password);
-        await page.getByRole("button", { name: "Sign in" }).click();
-        await page.getByRole("heading", { name: "Dashboard" }).waitFor();
-      },
-    });
-
-    // Continue with the signed-in workflow steps.
-  },
-});
-```
-
-## Notes
-
-- Saving a profile captures cookies, localStorage, and IndexedDB only for the comma-separated `--sites` list.
-- If the user explicitly wants to import from Chrome, ask which Chrome/profile
-  to launch or attach to and get consent before attaching because disconnecting
-  can close or relaunch that Chrome window. Chrome may require copying the
-  selected profile to a temporary user-data directory before running
-  `npx libretto import-chrome-profiles example-app --cdp-url http://127.0.0.1:9222 --sites app.example.com`.