libretto 0.6.28 → 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,7 +66,7 @@ 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. Checks whether `packages/affordance` changed since the current Libretto release tag. If it 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.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.28",
+  "version": "0.6.29",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",

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.28"
+  version: "0.6.29"
 ---
 
 ## How Libretto Works
@@ -51,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.
@@ -232,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"}'
@@ -270,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/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.28"
+  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`.