libretto 0.6.19 → 0.6.21

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/providers/libretto-cloud.js

@@ -64,8 +64,11 @@ function createLibrettoCloudProvider() {
       };
     },
     async closeSession(sessionId) {
-      const json = await closeCloudSession(endpoint, apiKey, sessionId);
-      return { replayUrl: json.replay_url ?? void 0 };
+      await closeCloudSession(endpoint, apiKey, sessionId);
+      const replayUrl = await getCloudRecordingUrl(endpoint, apiKey, sessionId).catch(
+        () => void 0
+      );
+      return { replayUrl };
     }
   };
 }
@@ -153,8 +156,24 @@ async function closeCloudSession(endpoint, apiKey, sessionId) {
       `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`
     );
   }
+}
+async function getCloudRecordingUrl(endpoint, apiKey, sessionId) {
+  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();
-  return json;
+  return json.recording_url ?? void 0;
 }
 function createStartupSessionCleanup(endpoint, apiKey, sessionId) {
   let cancelled = false;

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.21",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",