libretto 0.6.19 → 0.6.20

package/README.md

@@ -28,17 +28,14 @@ https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
 ## Installation
 
 ```bash
-# Install the Libretto command once. Requires Node.js and npm.
-curl -fsSL https://libretto.sh/install.sh | bash
-
-# Add Libretto to your project
+# Add Libretto to your project. Requires Node.js and npm.
 npm install libretto
 
 # First-time onboarding: install skills and download Chromium
-libretto setup
+npx libretto setup
 
 # Check workspace readiness at any time
-libretto status
+npx libretto status
 ```
 
 `setup` creates the `.libretto/` directory, installs agent skills, and downloads Chromium unless you pass `--skip-browsers`.
@@ -76,17 +73,17 @@ Agents can use Libretto to reproduce the failure, pause the workflow at any poin
 You can also use Libretto directly from the command line. All commands accept `--session <name>` to target a specific session.
 
 ```bash
-libretto open <url>                    # launch browser and open a URL
-libretto run ./integration.ts --headless # run a workflow and close on success
-libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
-libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
-libretto exec "<code>"                 # execute Playwright TypeScript against the open page
-libretto close                         # close the browser
+npx libretto open <url>                    # launch browser and open a URL
+npx libretto run ./integration.ts --headless # run a workflow and close on success
+npx libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
+npx libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
+npx libretto exec "<code>"                 # execute Playwright TypeScript against the open page
+npx libretto close                         # close the browser
 ```
 
 `run` sessions are inspectable through the same daemon-backed commands as `open` sessions. Successful runs close the browser by default; pass `--stay-open-on-success` to keep the browser open for `pages`, `snapshot`, and `exec`. Failed or paused workflows keep the browser open so you can inspect the exact page state before fixing or resuming the workflow.
 
-Run `libretto help` for the full list of commands.
+Run `npx libretto help` for the full list of commands.
 
 ## Configuration
 

package/README.template.md

@@ -26,17 +26,14 @@ https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18
 ## Installation
 
 ```bash
-# Install the Libretto command once. Requires Node.js and npm.
-curl -fsSL https://libretto.sh/install.sh | bash
-
-# Add Libretto to your project
+# Add Libretto to your project. Requires Node.js and npm.
 npm install libretto
 
 # First-time onboarding: install skills and download Chromium
-libretto setup
+npx libretto setup
 
 # Check workspace readiness at any time
-libretto status
+npx libretto status
 ```
 
 `setup` creates the `.libretto/` directory, installs agent skills, and downloads Chromium unless you pass `--skip-browsers`.
@@ -74,17 +71,17 @@ Agents can use Libretto to reproduce the failure, pause the workflow at any poin
 You can also use Libretto directly from the command line. All commands accept `--session <name>` to target a specific session.
 
 ```bash
-libretto open <url>                    # launch browser and open a URL
-libretto run ./integration.ts --headless # run a workflow and close on success
-libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
-libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
-libretto exec "<code>"                 # execute Playwright TypeScript against the open page
-libretto close                         # close the browser
+npx libretto open <url>                    # launch browser and open a URL
+npx libretto run ./integration.ts --headless # run a workflow and close on success
+npx libretto run ./integration.ts --headless --stay-open-on-success # keep a successful run inspectable
+npx libretto snapshot --session <name>     # capture a screenshot and compact accessibility tree
+npx libretto exec "<code>"                 # execute Playwright TypeScript against the open page
+npx libretto close                         # close the browser
 ```
 
 `run` sessions are inspectable through the same daemon-backed commands as `open` sessions. Successful runs close the browser by default; pass `--stay-open-on-success` to keep the browser open for `pages`, `snapshot`, and `exec`. Failed or paused workflows keep the browser open so you can inspect the exact page state before fixing or resuming the workflow.
 
-Run `libretto help` for the full list of commands.
+Run `npx libretto help` for the full list of commands.
 
 ## Configuration
 

package/dist/cli/cli.js

@@ -11,19 +11,6 @@ function renderVersion() {
 function printSetupAudit() {
   warnIfLibrettoVersionsDiffer();
 }
-function isPackageManagerExec(env = process.env) {
-  return env.npm_command === "exec";
-}
-function warnIfPackageManagerExec() {
-  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) {
   if (rawArgs.length === 0) return true;
   return rawArgs[0] === "help" && rawArgs.length === 1;
@@ -42,7 +29,6 @@ async function runLibrettoCLI() {
   const rawArgs = process.argv.slice(2);
   let exitCode = 0;
   loadEnv();
-  warnIfPackageManagerExec();
   ensureLibrettoSetup();
   const app = createCLIApp();
   try {

package/dist/cli/commands/deploy.js

@@ -93,6 +93,10 @@ 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().optional().transform(
         (value) => value?.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0) ?? []
@@ -120,6 +124,7 @@ 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({
     apiUrl,

package/dist/cli/commands/update.js

@@ -1,8 +1,16 @@
 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
+} from "../../shared/package-manager.js";
+function packageInstallCommand(packageManager, packageSpec) {
+  return `${installCommand(packageManager)} ${packageSpec}`;
+}
 function readCurrentCliVersion() {
   const packageJsonPath = fileURLToPath(
     new URL("../../../package.json", import.meta.url)
@@ -17,6 +25,21 @@ function readCurrentCliVersion() {
   }
   return manifest.version;
 }
+function readPackageVersion(packageJsonPath) {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(packageJsonPath, "utf8")
+    );
+    return manifest.version?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function readLocalPackageVersion() {
+  return readPackageVersion(
+    join(REPO_ROOT, "node_modules", "libretto", "package.json")
+  );
+}
 function readLatestNpmVersion() {
   const result = spawnSync("npm", ["view", "libretto@latest", "version"], {
     encoding: "utf8"
@@ -65,55 +88,61 @@ const updateInput = SimpleCLI.input({
     })
   }
 });
-function formatUpdateFailure(status, signal) {
-  const knownState = status === null ? `installer was interrupted${signal ? ` by ${signal}` : ""}.` : `installer exited with status ${status}.`;
+function formatUpdateFailure(status, signal, updateCommand2) {
+  const knownState = status === null ? `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: ${updateCommand2}`,
     "Help: libretto help update"
   ].join("\n");
 }
 const updateCommand = SimpleCLI.command({
   description: "Update Libretto to the latest version"
 }).input(updateInput).handle(async ({ input }) => {
+  const packageManager = detectProjectPackageManager();
+  const updateCommand2 = packageInstallCommand(packageManager, "libretto@latest");
   if (input.dryRun) {
     console.log("Update command:");
-    console.log(`  ${UPDATE_COMMAND}`);
+    console.log(`  ${updateCommand2}`);
     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(updateCommand2, {
     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: ${updateCommand2}`,
         "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, updateCommand2)
+    );
   }
-  console.log("Libretto updated to latest.");
+  console.log("Local Libretto package updated to latest.");
   console.log("No further action required.");
 });
 export {

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

@@ -47,6 +47,7 @@ import {
   loadDefaultWorkflow
 } from "../workflow-runtime.js";
 import { WorkflowController } from "../workflow-runner/runner.js";
+import { validateWorkflowInput } from "../../../shared/workflow/workflow.js";
 function isOperationalPage(page) {
   const url = page.url();
   return !url.startsWith("devtools://") && !url.startsWith("chrome-error://");
@@ -682,6 +683,7 @@ async function main() {
       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/dist/cli/core/skill-version.js

@@ -68,115 +68,28 @@ function readInstalledSkillVersions() {
   }
   return [...versions];
 }
-function parseVersion(version) {
-  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
-  if (!match) {
-    return null;
-  }
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    prerelease: match[4] ?? null
-  };
-}
-function compareVersions(left, right) {
-  const parsedLeft = parseVersion(left);
-  const parsedRight = parseVersion(right);
-  if (!parsedLeft || !parsedRight) {
-    return left.localeCompare(right);
-  }
-  for (const key of ["major", "minor", "patch"]) {
-    const diff = parsedLeft[key] - parsedRight[key];
-    if (diff !== 0) {
-      return diff;
-    }
-  }
-  if (parsedLeft.prerelease === parsedRight.prerelease) {
-    return 0;
-  }
-  if (parsedLeft.prerelease === null) {
-    return 1;
-  }
-  if (parsedRight.prerelease === null) {
-    return -1;
-  }
-  return parsedLeft.prerelease.localeCompare(parsedRight.prerelease);
-}
-function selectTargetVersion(versions) {
-  const counts = /* @__PURE__ */ new Map();
-  for (const version of versions) {
-    counts.set(version, (counts.get(version) ?? 0) + 1);
-  }
-  const byCountThenVersion = [...counts.entries()].sort(
-    ([leftVersion, leftCount], [rightVersion, rightCount]) => rightCount - leftCount || compareVersions(rightVersion, leftVersion)
-  );
-  return byCountThenVersion[0]?.[0] ?? versions[0] ?? "latest";
-}
-function formatVersion(version, targetVersion) {
-  return version === targetVersion ? version : `${version}  (out of date)`;
-}
-function formatSkillVersions(versions, targetVersion) {
+function formatSkillVersions(versions) {
   if (versions.length === 0) {
     return "not installed";
   }
-  return versions.map((version) => formatVersion(version, targetVersion)).join(", ");
-}
-function formatUpdateInstructions(components) {
-  const instructions = [];
-  if (components.cliVersion !== components.targetVersion) {
-    instructions.push(
-      `  global CLI:    curl -fsSL https://libretto.sh/install.sh | LIBRETTO_VERSION=${components.targetVersion} bash`
-    );
-  }
-  if (components.localPackageVersion && components.localPackageVersion !== components.targetVersion) {
-    instructions.push(
-      `  local package: npm install libretto@${components.targetVersion}`
-    );
-  }
-  if (components.skillVersions.length > 0 && components.skillVersions.some(
-    (skillVersion) => skillVersion !== components.targetVersion
-  )) {
-    instructions.push("  agent skill:   libretto setup");
-  }
-  return instructions;
+  return versions.join(", ");
 }
 function formatVersionWarning(components) {
-  const targetVersion = selectTargetVersion([
-    components.cliVersion,
-    ...components.localPackageVersion ? [components.localPackageVersion] : [],
-    ...components.skillVersions
-  ]);
   const skillLabel = components.skillVersions.length > 1 ? "agent skills" : "agent skill";
-  const updateInstructions = formatUpdateInstructions({
-    ...components,
-    targetVersion
-  });
   return [
-    "WARNING: Libretto version mismatch detected.",
-    "",
-    `  global CLI:    ${formatVersion(components.cliVersion, targetVersion)}`,
-    `  local package: ${components.localPackageVersion ? formatVersion(components.localPackageVersion, targetVersion) : "not installed"}`,
-    `  ${skillLabel}:   ${formatSkillVersions(
-      components.skillVersions,
-      targetVersion
-    )}`,
-    "",
-    "How to update:",
-    ...updateInstructions
+    "WARNING: Libretto skill version does not match the local package.",
+    `  local package: ${components.localPackageVersion ?? `${components.cliVersion}  (current command)`}`,
+    `  ${skillLabel}:   ${formatSkillVersions(components.skillVersions)}`,
+    "Fix: run libretto setup"
   ].join("\n");
 }
 function warnIfLibrettoVersionsDiffer() {
   try {
     const cliVersion = readCurrentCliVersion();
     const localPackageVersion = readLocalPackageVersion();
+    const packageVersion = localPackageVersion ?? cliVersion;
     const skillVersions = readInstalledSkillVersions();
-    const observedVersions = /* @__PURE__ */ new Set([
-      cliVersion,
-      ...localPackageVersion ? [localPackageVersion] : [],
-      ...skillVersions
-    ]);
-    if (observedVersions.size <= 1) {
+    if (skillVersions.length === 0 || skillVersions.every((skillVersion) => skillVersion === packageVersion)) {
       return;
     }
     console.error(

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { InstrumentationOptions, InstrumentedPage, installInstrumentation, instr
 export { GhostCursorOptions, ensureGhostCursor, ghostClick, hideGhostCursor, moveGhostCursor } from './shared/visualization/ghost-cursor.js';
 export { HighlightOptions, clearHighlights, ensureHighlightLayer, showHighlight } from './shared/visualization/highlight.js';
 export { BrowserSession, LaunchBrowserArgs, launchBrowser } from './shared/run/browser.js';
-export { ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowInputError, LibrettoWorkflowSchemas, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, workflow } from './shared/workflow/workflow.js';
+export { ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, LibrettoWorkflowContext, LibrettoWorkflowHandler, LibrettoWorkflowInputError, LibrettoWorkflowSchemas, WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow } from './shared/workflow/workflow.js';
 import 'zod';
 import 'playwright';
 import 'ai';

package/dist/index.js

@@ -59,6 +59,7 @@ import {
   LibrettoWorkflow,
   LibrettoWorkflowInputError,
   LIBRETTO_WORKFLOW_BRAND,
+  validateWorkflowInput,
   workflow
 } from "./shared/workflow/workflow.js";
 const isDirectExecution = () => {
@@ -113,5 +114,6 @@ export {
   prettyConsoleSink,
   serializeSessionState,
   showHighlight,
+  validateWorkflowInput,
   workflow
 };

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

@@ -16,6 +16,11 @@ declare class LibrettoWorkflowInputError extends Error {
     readonly zodError: z.ZodError;
     constructor(workflowName: string, zodError: z.ZodError);
 }
+type WorkflowInputValidator = {
+    readonly name: string;
+    readonly inputSchema?: z.ZodType;
+};
+declare function validateWorkflowInput(workflow: WorkflowInputValidator, input: unknown): void;
 declare class LibrettoWorkflow<InputSchema extends z.ZodType = z.ZodType<unknown>, OutputSchema extends z.ZodType = z.ZodType<unknown>> {
     readonly [LIBRETTO_WORKFLOW_BRAND] = true;
     readonly name: string;
@@ -40,4 +45,4 @@ declare function getWorkflowFromModuleExports(moduleExports: WorkflowModuleExpor
 declare function workflow<InputSchema extends z.ZodType, OutputSchema extends z.ZodType>(name: string, schemas: LibrettoWorkflowSchemas<InputSchema, OutputSchema>, handler: LibrettoWorkflowHandler<z.infer<InputSchema>, z.infer<OutputSchema>>): LibrettoWorkflow<InputSchema, OutputSchema>;
 declare function workflow<Input = unknown, Output = unknown>(name: string, handler: LibrettoWorkflowHandler<Input, Output>): LibrettoWorkflow<z.ZodType<Input>, z.ZodType<Output>>;
 
-export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, LibrettoWorkflowInputError, type LibrettoWorkflowSchemas, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, workflow };
+export { type ExportedLibrettoWorkflow, LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, LibrettoWorkflowInputError, type LibrettoWorkflowSchemas, type WorkflowInputValidator, getDefaultWorkflowFromModuleExports, getWorkflowFromModuleExports, getWorkflowsFromModuleExports, isLibrettoWorkflow, validateWorkflowInput, workflow };

package/dist/shared/workflow/workflow.js

@@ -19,6 +19,17 @@ function formatZodErrorMessage(workflowName, zodError) {
     ...lines
   ].join("\n");
 }
+function parseWorkflowInput(workflowName, inputSchema, input) {
+  if (!inputSchema) return input;
+  const result = inputSchema.safeParse(input);
+  if (!result.success) {
+    throw new LibrettoWorkflowInputError(workflowName, result.error);
+  }
+  return result.data;
+}
+function validateWorkflowInput(workflow2, input) {
+  parseWorkflowInput(workflow2.name, workflow2.inputSchema, input);
+}
 class LibrettoWorkflow {
   [LIBRETTO_WORKFLOW_BRAND] = true;
   name;
@@ -38,16 +49,7 @@ class LibrettoWorkflow {
     this.handler = handler;
   }
   async run(ctx, input) {
-    let parsed;
-    if (this.inputSchema) {
-      const result = this.inputSchema.safeParse(input);
-      if (!result.success) {
-        throw new LibrettoWorkflowInputError(this.name, result.error);
-      }
-      parsed = result.data;
-    } else {
-      parsed = input;
-    }
+    const parsed = parseWorkflowInput(this.name, this.inputSchema, input);
     return this.handler(ctx, parsed);
   }
 }
@@ -118,5 +120,6 @@ export {
   getWorkflowFromModuleExports,
   getWorkflowsFromModuleExports,
   isLibrettoWorkflow,
+  validateWorkflowInput,
   workflow
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.19",
+  "version": "0.6.20",
   "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.19"
+  version: "0.6.20"
 ---
 
 ## 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.20"
 ---
 
 ## 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/skill-version.ts

@@ -89,115 +89,14 @@ function readInstalledSkillVersions(): string[] {
   return [...versions];
 }
 
-function parseVersion(version: string): {
-  major: number;
-  minor: number;
-  patch: number;
-  prerelease: string | null;
-} | null {
-  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
-  if (!match) {
-    return null;
-  }
-
-  return {
-    major: Number(match[1]),
-    minor: Number(match[2]),
-    patch: Number(match[3]),
-    prerelease: match[4] ?? null,
-  };
-}
-
-function compareVersions(left: string, right: string): number {
-  const parsedLeft = parseVersion(left);
-  const parsedRight = parseVersion(right);
-  if (!parsedLeft || !parsedRight) {
-    return left.localeCompare(right);
-  }
-
-  for (const key of ["major", "minor", "patch"] as const) {
-    const diff = parsedLeft[key] - parsedRight[key];
-    if (diff !== 0) {
-      return diff;
-    }
-  }
-
-  if (parsedLeft.prerelease === parsedRight.prerelease) {
-    return 0;
-  }
-  if (parsedLeft.prerelease === null) {
-    return 1;
-  }
-  if (parsedRight.prerelease === null) {
-    return -1;
-  }
-  return parsedLeft.prerelease.localeCompare(parsedRight.prerelease);
-}
-
-function selectTargetVersion(versions: string[]): string {
-  const counts = new Map<string, number>();
-  for (const version of versions) {
-    counts.set(version, (counts.get(version) ?? 0) + 1);
-  }
-
-  const byCountThenVersion = [...counts.entries()].sort(
-    ([leftVersion, leftCount], [rightVersion, rightCount]) =>
-      rightCount - leftCount || compareVersions(rightVersion, leftVersion),
-  );
-
-  return byCountThenVersion[0]?.[0] ?? versions[0] ?? "latest";
-}
-
-function formatVersion(version: string, targetVersion: string): string {
-  return version === targetVersion ? version : `${version}  (out of date)`;
-}
-
 function formatSkillVersions(
   versions: string[],
-  targetVersion: string,
 ): string {
   if (versions.length === 0) {
     return "not installed";
   }
 
-  return versions
-    .map((version) => formatVersion(version, targetVersion))
-    .join(", ");
-}
-
-function formatUpdateInstructions(components: {
-  cliVersion: string;
-  localPackageVersion: string | null;
-  skillVersions: string[];
-  targetVersion: string;
-}): string[] {
-  const instructions: string[] = [];
-
-  if (components.cliVersion !== components.targetVersion) {
-    instructions.push(
-      `  global CLI:    curl -fsSL https://libretto.sh/install.sh | LIBRETTO_VERSION=${components.targetVersion} bash`,
-    );
-  }
-
-  if (
-    components.localPackageVersion &&
-    components.localPackageVersion !== components.targetVersion
-  ) {
-    instructions.push(
-      `  local package: npm install libretto@${components.targetVersion}`,
-    );
-  }
-
-  if (
-    components.skillVersions.length > 0 &&
-    components.skillVersions.some(
-      (skillVersion) => skillVersion !== components.targetVersion,
-    )
-  ) {
-    instructions.push("  agent skill:   libretto setup");
-  }
-
-  return instructions;
+  return versions.join(", ");
 }
 
 function formatVersionWarning(components: {
@@ -205,34 +104,16 @@ function formatVersionWarning(components: {
   localPackageVersion: string | null;
   skillVersions: string[];
 }): string {
-  const targetVersion = selectTargetVersion([
-    components.cliVersion,
-    ...(components.localPackageVersion ? [components.localPackageVersion] : []),
-    ...components.skillVersions,
-  ]);
   const skillLabel =
     components.skillVersions.length > 1 ? "agent skills" : "agent skill";
-  const updateInstructions = formatUpdateInstructions({
-    ...components,
-    targetVersion,
-  });
 
   return [
-    "WARNING: Libretto version mismatch detected.",
-    "",
-    `  global CLI:    ${formatVersion(components.cliVersion, targetVersion)}`,
+    "WARNING: Libretto skill version does not match the local package.",
     `  local package: ${
-      components.localPackageVersion
-        ? formatVersion(components.localPackageVersion, targetVersion)
-        : "not installed"
+      components.localPackageVersion ?? `${components.cliVersion}  (current command)`
     }`,
-    `  ${skillLabel}:   ${formatSkillVersions(
-      components.skillVersions,
-      targetVersion,
-    )}`,
-    "",
-    "How to update:",
-    ...updateInstructions,
+    `  ${skillLabel}:   ${formatSkillVersions(components.skillVersions)}`,
+    "Fix: run libretto setup",
   ].join("\n");
 }
 
@@ -240,14 +121,12 @@ export function warnIfLibrettoVersionsDiffer(): void {
   try {
     const cliVersion = readCurrentCliVersion();
     const localPackageVersion = readLocalPackageVersion();
+    const packageVersion = localPackageVersion ?? cliVersion;
     const skillVersions = readInstalledSkillVersions();
-    const observedVersions = new Set([
-      cliVersion,
-      ...(localPackageVersion ? [localPackageVersion] : []),
-      ...skillVersions,
-    ]);
-
-    if (observedVersions.size <= 1) {
+    if (
+      skillVersions.length === 0 ||
+      skillVersions.every((skillVersion) => skillVersion === packageVersion)
+    ) {
       return;
     }
 

package/src/index.ts

@@ -100,11 +100,13 @@ export {
   LibrettoWorkflow,
   LibrettoWorkflowInputError,
   LIBRETTO_WORKFLOW_BRAND,
+  validateWorkflowInput,
   workflow,
   type ExportedLibrettoWorkflow,
   type LibrettoWorkflowContext,
   type LibrettoWorkflowHandler,
   type LibrettoWorkflowSchemas,
+  type WorkflowInputValidator,
 } from "./shared/workflow/workflow.js";
 const isDirectExecution = (): boolean => {
   const entryArg = process.argv[1];

package/src/shared/workflow/workflow.ts

@@ -49,6 +49,32 @@ function formatZodErrorMessage(
   ].join("\n");
 }
 
+function parseWorkflowInput<InputSchema extends z.ZodType>(
+  workflowName: string,
+  inputSchema: InputSchema | undefined,
+  input: unknown,
+): z.infer<InputSchema> {
+  if (!inputSchema) return input as z.infer<InputSchema>;
+
+  const result = inputSchema.safeParse(input);
+  if (!result.success) {
+    throw new LibrettoWorkflowInputError(workflowName, result.error);
+  }
+  return result.data;
+}
+
+export type WorkflowInputValidator = {
+  readonly name: string;
+  readonly inputSchema?: z.ZodType;
+};
+
+export function validateWorkflowInput(
+  workflow: WorkflowInputValidator,
+  input: unknown,
+): void {
+  parseWorkflowInput(workflow.name, workflow.inputSchema, input);
+}
+
 export class LibrettoWorkflow<
   InputSchema extends z.ZodType = z.ZodType<unknown>,
   OutputSchema extends z.ZodType = z.ZodType<unknown>,
@@ -86,16 +112,7 @@ export class LibrettoWorkflow<
     ctx: LibrettoWorkflowContext,
     input: unknown,
   ): Promise<z.infer<OutputSchema>> {
-    let parsed: z.infer<InputSchema>;
-    if (this.inputSchema) {
-      const result = this.inputSchema.safeParse(input);
-      if (!result.success) {
-        throw new LibrettoWorkflowInputError(this.name, result.error);
-      }
-      parsed = result.data;
-    } else {
-      parsed = input as z.infer<InputSchema>;
-    }
+    const parsed = parseWorkflowInput(this.name, this.inputSchema, input);
     return this.handler(ctx, parsed);
   }
 }