libretto 0.6.19 → 0.6.21

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.19"
+  version: "0.6.21"
 ---
 
 ## How Libretto Works
@@ -39,12 +39,13 @@ Prefer to enter sites at a user-facing URL (homepage, login, etc.) on the first
 
 ## Setup
 
-- Use `libretto setup` for first-time workspace onboarding. It installs Chromium and syncs skills.
-- Use `libretto status` to inspect open sessions without triggering setup.
+- 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.
 
 ## Experiments
 
-- Use `libretto experiments` to list internal feature flags and `libretto experiments describe <name>` for usage notes when an experiment is enabled.
+- Use `npx libretto experiments` to list internal feature flags and `npx libretto experiments describe <name>` for usage notes when an experiment is enabled.
 
 ## Working Rules
 
@@ -83,9 +84,9 @@ npx libretto open https://example.com --session debug-example
 - Pass `--read-only` if the connected session must stay inspection-only from the start.
 
 ```bash
-libretto connect http://127.0.0.1:9222 --session my-session
-libretto connect http://127.0.0.1:9222 --read-only --session readonly-session
-libretto connect http://127.0.0.1:9223 --session another-session
+npx libretto connect http://127.0.0.1:9222 --session my-session
+npx libretto connect http://127.0.0.1:9222 --read-only --session readonly-session
+npx libretto connect http://127.0.0.1:9223 --session another-session
 ```
 
 ### `session-mode`
@@ -96,7 +97,7 @@ libretto connect http://127.0.0.1:9223 --session another-session
 - Pass `--read-only` or `--write-access` to override the config default for a single command.
 
 ```bash
-libretto session-mode --session my-session
+npx libretto session-mode --session my-session
 ```
 
 ### `snapshot`
@@ -108,9 +109,9 @@ libretto session-mode --session my-session
 - Use it before guessing at selectors, after workflow failures, and whenever the visible page state is unclear.
 
 ```bash
-libretto snapshot --session debug-example
-libretto snapshot <ref> --session debug-example
-libretto snapshot --session debug-example --page <page-id>
+npx libretto snapshot --session debug-example
+npx libretto snapshot <ref> --session debug-example
+npx libretto snapshot --session debug-example --page <page-id>
 ```
 
 ### `exec`
@@ -126,10 +127,10 @@ libretto snapshot --session debug-example --page <page-id>
 - After successful mutations, `exec` prints page-change diffs from compact snapshots.
 
 ```bash
-libretto exec "await page.url()"
-libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
-echo "async function textOf(selector) { return await page.locator(selector).textContent(); }" | libretto exec - --session debug-example
-libretto exec --session debug-example "await textOf('h1')"
+npx libretto exec "await page.url()"
+npx libretto exec "await page.locator('button:has-text(\"Continue\")').click()"
+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`
@@ -138,8 +139,8 @@ libretto exec --session debug-example "await textOf('h1')"
 - If `exec` or `snapshot` complains about multiple pages, list page ids first and then pass `--page`.
 
 ```bash
-libretto pages --session debug-example
-libretto exec --session debug-example --page <page-id> "await page.url()"
+npx libretto pages --session debug-example
+npx libretto exec --session debug-example --page <page-id> "await page.url()"
 ```
 
 ### `run`
@@ -150,14 +151,14 @@ libretto exec --session debug-example --page <page-id> "await page.url()"
 - Pass `--read-only` if the preserved session should come back locked for follow-up terminal inspection after the workflow run.
 - If the workflow fails, Libretto keeps the browser open. Inspect the failed state with `snapshot` and `exec` before editing code.
 - Insert `await pause(session)` statements in the workflow file when you need to stop at specific states for interactive debugging, like breakpoints in the browser flow.
-- If the workflow pauses, resume it with `libretto resume --session <name>`.
+- If the workflow pauses, resume it with `npx libretto resume --session <name>`.
 - Re-run the same workflow after each fix to verify the browser behavior end to end.
 
 ```bash
-libretto run ./integration.ts --params '{"status":"open"}'
-libretto run ./integration.ts --read-only
-libretto run ./integration.ts --stay-open-on-success
-libretto run ./integration.ts --auth-profile app.example.com
+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
 ```
 
 ### `resume`
@@ -168,7 +169,7 @@ libretto run ./integration.ts --auth-profile app.example.com
 - Keep resuming the same session until the workflow completes or pauses again.
 
 ```bash
-libretto resume --session debug-example
+npx libretto resume --session debug-example
 ```
 
 ### `save`
@@ -176,7 +177,7 @@ libretto resume --session debug-example
 - Use `save` only when the user explicitly asks to save or reuse authenticated browser state.
 
 ```bash
-libretto save app.example.com
+npx libretto save app.example.com
 ```
 
 ### `close`
@@ -185,8 +186,8 @@ libretto save app.example.com
 - `close --all` is available for workspace cleanup.
 
 ```bash
-libretto close --session debug-example
-libretto close --all
+npx libretto close --session debug-example
+npx libretto close --all
 ```
 
 ## Session Logs
@@ -234,17 +235,17 @@ Key fields: `id` (incrementing request id), `ts` (ISO timestamp), `pageId` (page
 <example>
 [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 `libretto open https://target.example.com --headed`]
+Assistant: [Runs `npx libretto open https://target.example.com --headed`]
 Assistant: [Reads `references/site-security-review.md` before choosing between passive network inspection, direct browser fetch calls, and Playwright-first automation]
-Assistant: [Runs `libretto snapshot --session <session>`]
+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 `libretto run ./target-workflow.ts --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 validation run]
-To run it again, use: libretto run ./target-workflow.ts --params '{"status":"open"}'
+To run it again, use: npx libretto run ./target-workflow.ts --params '{"status":"open"}'
 </example>
 ```
 
@@ -254,17 +255,17 @@ To run it again, use: libretto run ./target-workflow.ts --params '{"status":"ope
 <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 `libretto run ./integration.ts --session debug-flow`]
+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 `libretto snapshot --session debug-flow`]
-Assistant: [Runs `libretto exec --session debug-flow "...focused inspection or prototype..."`]
+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 `libretto run ./integration.ts` 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 validation run]
-To run it again, use: libretto run ./integration.ts
+To run it again, use: npx libretto run ./integration.ts
 </example>
 ```
 

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

@@ -17,9 +17,9 @@ Use this reference only when the user explicitly asks to save or reuse local aut
 ## Commands
 
 ```bash
-libretto open https://app.example.com --headed
-libretto save app.example.com
-libretto run ./integration.ts --auth-profile app.example.com
+npx libretto open https://app.example.com --headed
+npx libretto save app.example.com
+npx libretto run ./integration.ts --auth-profile app.example.com
 ```
 
 ## Notes

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

@@ -6,7 +6,7 @@ Follow the user's existing codebase conventions, abstractions, and patterns when
 
 ## Workflow File Structure
 
-Generated files must default-export a `workflow()` instance so they can be run via `libretto run <file>`. Workflows declare their input and output shapes as Zod schemas, which both type the handler and validate runtime input.
+Generated files must default-export a `workflow()` instance so they can be run via `npx libretto run <file>`. Workflows declare their input and output shapes as Zod schemas, which both type the handler and validate runtime input.
 
 Add `zod` (`^4.0.0`) to the workflow's `package.json` dependencies. Then import `workflow` from `"libretto"` and `z` from `"zod"`:
 
@@ -42,7 +42,7 @@ Key points:
 
 - `workflow(name, { input, output }, handler)` takes a unique workflow name, a pair of Zod schemas describing input and output, and the async handler. The handler's `input` parameter is inferred from the input schema — do not redeclare it with a separate `type Input = ...`.
 - At run time, Libretto validates `input` against `inputSchema` before calling the handler. Invalid input throws a clear error listing each failing field; the workflow handler never sees malformed input.
-- `libretto run ./file.ts` executes the file's default-exported workflow, so always use `export default workflow(...)`.
+- `npx libretto run ./file.ts` executes the file's default-exported workflow, so always use `export default workflow(...)`.
 - `ctx` provides `session` and `page`. Use `console.log`/`console.warn`/`console.error` for logging — the runtime wraps these with structured metadata automatically.
 - `input` comes from `--params '{"query":"foo"}'` or `--params-file params.json` on the CLI, then gets parsed through `inputSchema`.
 - Use `await pause(ctx.session)` (or `await pause(session)`) to pause the workflow for debugging. It is a no-op in production.

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

@@ -12,8 +12,8 @@ Use this reference when you need to inspect or change workspace configuration fo
 
 Libretto reads workspace config from `.libretto/config.json`.
 
-- The file is created by `libretto setup` during first-time onboarding.
-- Use `libretto status` to inspect open sessions without changing anything.
+- The file is created by `npx libretto setup` during first-time onboarding.
+- Use `npx libretto status` to inspect open sessions without changing anything.
 - For first-time setup instructions, follow the main `SKILL.md` flow instead of expanding this reference.
 
 ## Supported Settings
@@ -42,17 +42,17 @@ Example:
 ## Common Commands
 
 ```bash
-libretto setup                                         # first-time onboarding
-libretto status                                        # inspect open sessions
-libretto open https://example.com --provider kernel
-libretto run ./integration.ts --provider browserbase
-libretto open https://example.com --provider steel
-libretto open https://example.com --viewport 1440x900
-libretto run ./integration.ts --viewport 1440x900
+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 --provider steel
+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 `libretto status` at any time to check open sessions.
+- Run `npx libretto status` at any time to check open sessions.

package/skills/libretto/references/pages-and-page-targeting.md

@@ -17,9 +17,9 @@ Use this reference when a Libretto session has multiple open pages and you need
 ## Commands
 
 ```bash
-libretto pages --session debug-flow
-libretto exec --session debug-flow --page <page-id> "return await page.url()"
-libretto snapshot --session debug-flow --page <page-id>
+npx libretto pages --session debug-flow
+npx libretto exec --session debug-flow --page <page-id> "return await page.url()"
+npx libretto snapshot --session debug-flow --page <page-id>
 ```
 
 ## Notes

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

package/src/cli/cli.ts

@@ -14,22 +14,6 @@ function printSetupAudit(): void {
   warnIfLibrettoVersionsDiffer();
 }
 
-function isPackageManagerExec(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.npm_command === "exec";
-}
-
-function warnIfPackageManagerExec(): void {
-  if (!isPackageManagerExec()) return;
-
-  console.error(
-    [
-      "Warning: running Libretto through a package manager is deprecated and will be removed in a future release.",
-      "Install the native command instead:",
-      "  curl -fsSL https://libretto.sh/install.sh | bash",
-    ].join("\n"),
-  );
-}
-
 function isRootHelpRequest(rawArgs: readonly string[]): boolean {
   if (rawArgs.length === 0) return true;
   return rawArgs[0] === "help" && rawArgs.length === 1;
@@ -55,7 +39,6 @@ export async function runLibrettoCLI(): Promise<void> {
   const rawArgs = process.argv.slice(2);
   let exitCode = 0;
   loadEnv();
-  warnIfPackageManagerExec();
   ensureLibrettoSetup();
   const app = createCLIApp();
 

package/src/cli/commands/deploy.ts

@@ -125,6 +125,10 @@ export const deployInput = SimpleCLI.input({
       name: "entry-point",
       help: "Entry point file (default: index.ts)",
     }),
+    autoRepair: SimpleCLI.flag({
+      name: "auto-repair",
+      help: "Route failed jobs for this deployment to autofix",
+    }),
     external: SimpleCLI.option(
       z
         .string()
@@ -167,6 +171,7 @@ export const deployCommand = SimpleCLI.command({
       entry_point: entryPoint,
     };
     if (input.description) createPayload.description = input.description;
+    if (input.autoRepair) createPayload.auto_repair = true;
 
     console.log("Uploading deployment...");
     const body = await orpcCall<DeploymentResponse["json"]>({

package/src/cli/commands/update.ts

@@ -1,14 +1,26 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SimpleCLI } from "affordance";
-
-const UPDATE_COMMAND = "curl -fsSL https://libretto.sh/install.sh | bash";
+import { REPO_ROOT } from "../core/context.js";
+import {
+  detectProjectPackageManager,
+  installCommand,
+  type PackageManager,
+} from "../../shared/package-manager.js";
 
 type PackageManifest = {
   version?: string;
 };
 
+function packageInstallCommand(
+  packageManager: PackageManager,
+  packageSpec: string,
+): string {
+  return `${installCommand(packageManager)} ${packageSpec}`;
+}
+
 function readCurrentCliVersion(): string {
   const packageJsonPath = fileURLToPath(
     new URL("../../../package.json", import.meta.url),
@@ -26,6 +38,23 @@ function readCurrentCliVersion(): string {
   return manifest.version;
 }
 
+function readPackageVersion(packageJsonPath: string): string | null {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(packageJsonPath, "utf8"),
+    ) as PackageManifest;
+    return manifest.version?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function readLocalPackageVersion(): string | null {
+  return readPackageVersion(
+    join(REPO_ROOT, "node_modules", "libretto", "package.json"),
+  );
+}
+
 function readLatestNpmVersion(): string {
   const result = spawnSync("npm", ["view", "libretto@latest", "version"], {
     encoding: "utf8",
@@ -83,16 +112,17 @@ export const updateInput = SimpleCLI.input({
 function formatUpdateFailure(
   status: number | null,
   signal: string | null,
+  updateCommand: string,
 ): string {
   const knownState =
     status === null
-      ? `installer was interrupted${signal ? ` by ${signal}` : ""}.`
-      : `installer exited with status ${status}.`;
+      ? `package update was interrupted${signal ? ` by ${signal}` : ""}.`
+      : `package update exited with status ${status}.`;
 
   return [
     "Error: failed to update Libretto to the latest version.",
     `Known state: ${knownState}`,
-    `Try: ${UPDATE_COMMAND}`,
+    `Try: ${updateCommand}`,
     "Help: libretto help update",
   ].join("\n");
 }
@@ -102,48 +132,56 @@ export const updateCommand = SimpleCLI.command({
 })
   .input(updateInput)
   .handle(async ({ input }) => {
+    const packageManager = detectProjectPackageManager();
+    const updateCommand = packageInstallCommand(packageManager, "libretto@latest");
+
     if (input.dryRun) {
       console.log("Update command:");
-      console.log(`  ${UPDATE_COMMAND}`);
+      console.log(`  ${updateCommand}`);
       console.log("No changes made.");
       return;
     }
 
     const currentVersion = readCurrentCliVersion();
+    const localPackageVersion = readLocalPackageVersion();
+    const installedVersion = localPackageVersion ?? currentVersion;
     const latestVersion = readLatestNpmVersion();
-    console.log(`Current version: ${currentVersion}`);
+    console.log(`Current version: ${installedVersion}`);
     console.log(`Latest version: ${latestVersion}`);
 
-    if (currentVersion === latestVersion) {
-      console.log(`Libretto is already up to date (${currentVersion}).`);
+    if (localPackageVersion && installedVersion === latestVersion) {
+      console.log(`Libretto is already up to date (${installedVersion}).`);
       console.log("No further action required.");
       return;
     }
 
-    console.log("Updating Libretto to latest...");
-    const result = spawnSync("bash", ["-lc", UPDATE_COMMAND], {
+    if (!localPackageVersion) {
+      console.log("Local package: not installed");
+    }
+
+    console.log("Updating local Libretto package to latest...");
+    const result = spawnSync(updateCommand, {
       stdio: "inherit",
-      env: {
-        ...process.env,
-        LIBRETTO_VERSION: "latest",
-      },
+      shell: true,
     });
 
     if (result.error) {
       throw new Error(
         [
-          "Error: failed to start the Libretto installer.",
+          "Error: failed to start the Libretto package update.",
           `Known state: ${result.error.message}`,
-          `Try: ${UPDATE_COMMAND}`,
+          `Try: ${updateCommand}`,
           "Help: libretto help update",
         ].join("\n"),
       );
     }
 
     if (result.status !== 0) {
-      throw new Error(formatUpdateFailure(result.status, result.signal));
+      throw new Error(
+        formatUpdateFailure(result.status, result.signal, updateCommand),
+      );
     }
 
-    console.log("Libretto updated to latest.");
+    console.log("Local Libretto package updated to latest.");
     console.log("No further action required.");
   });

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

@@ -89,6 +89,7 @@ import {
   loadDefaultWorkflow,
 } from "../workflow-runtime.js";
 import { WorkflowController } from "../workflow-runner/runner.js";
+import { validateWorkflowInput } from "../../../shared/workflow/workflow.js";
 
 function isOperationalPage(page: Page): boolean {
   const url = page.url();
@@ -941,6 +942,7 @@ async function main(): Promise<void> {
       loadedWorkflow = await loadDefaultWorkflow(
         getAbsoluteIntegrationPath(config.workflow.integrationPath),
       );
+      validateWorkflowInput(loadedWorkflow, config.workflow.params ?? {});
     } catch (error) {
       throw new UserFacingStartupError(
         error instanceof Error ? error.message : String(error),

package/src/cli/core/providers/libretto-cloud.ts

@@ -6,7 +6,6 @@ type CloudSessionResponse = {
   status: string;
   cdp_url: string | null;
   live_view_url: string | null;
-  recording_url: string | null;
 };
 
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
@@ -77,8 +76,11 @@ export function createLibrettoCloudProvider(): ProviderApi {
       };
     },
     async closeSession(sessionId) {
-      const json = await closeCloudSession(endpoint, apiKey, sessionId);
-      return { replayUrl: json.replay_url ?? undefined };
+      await closeCloudSession(endpoint, apiKey, sessionId);
+      const replayUrl = await getCloudRecordingUrl(endpoint, apiKey, sessionId).catch(
+        () => undefined,
+      );
+      return { replayUrl };
     },
   };
 }
@@ -172,7 +174,7 @@ async function closeCloudSession(
   endpoint: string,
   apiKey: string,
   sessionId: string,
-): Promise<{ replay_url: string | null }> {
+): Promise<void> {
   const resp = await fetch(`${endpoint}/v1/sessions/close`, {
     method: "POST",
     headers: {
@@ -187,10 +189,31 @@ async function closeCloudSession(
       `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`,
     );
   }
+}
+
+async function getCloudRecordingUrl(
+  endpoint: string,
+  apiKey: string,
+  sessionId: string,
+): Promise<string | undefined> {
+  const resp = await fetch(`${endpoint}/v1/recordings/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 recording for session ${sessionId} (${resp.status}): ${body}`,
+    );
+  }
   const { json } = (await resp.json()) as {
-    json: { replay_url: string | null };
+    json: { recording_url: string | null };
   };
-  return json;
+  return json.recording_url ?? undefined;
 }
 
 function createStartupSessionCleanup(