libretto 0.4.1 → 0.4.4

package/dist/cli/commands/execution.js

@@ -292,7 +292,7 @@ async function runResume(session, logger, sessionState) {
   } = getPauseSignalPaths(session);
   if (!existsSync(pausedSignalPath)) {
     throw new Error(
-      `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call pause() first.`
+      `Session "${session}" is not paused. Run "libretto-cli run ... --session ${session}" and call pause("${session}") first.`
     );
   }
   if (!isProcessRunning(sessionState.pid)) {

package/dist/cli/commands/init.js

@@ -1,7 +1,7 @@
 import { createInterface } from "node:readline";
-import { appendFileSync, cpSync, existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readAiConfig } from "../core/ai-config.js";
 import { REPO_ROOT } from "../core/context.js";
@@ -60,6 +60,17 @@ function safeReadAiConfig() {
     return null;
   }
 }
+function printInvalidAiConfigWarning() {
+  try {
+    readAiConfig();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.log("  ! Existing AI config is invalid:");
+    for (const line of message.split("\n")) {
+      console.log(`    ${line}`);
+    }
+  }
+}
 function printSnapshotApiStatus() {
   const config = safeReadAiConfig();
   const selection = resolveSnapshotApiModel(config);
@@ -69,6 +80,7 @@ function printSnapshotApiStatus() {
     "  Libretto uses direct API calls for snapshot analysis when supported credentials are available."
   );
   console.log(`  Credentials are loaded from process env and ${envPath}.`);
+  printInvalidAiConfigWarning();
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  \u2713 Ready: ${selection.model} (${selection.source})`);
     console.log("    Snapshot objectives will use the API analyzer by default.");
@@ -84,7 +96,7 @@ function printSnapshotApiStatus() {
     "      GOOGLE_CLOUD_PROJECT=...  # plus application default credentials for Vertex"
   );
   console.log(
-    "    Or run `npx libretto ai configure <provider>` to set a specific model."
+    "    Or run `npx libretto ai configure openai | anthropic | gemini | vertex` to set a specific model."
   );
   console.log("    Run `npx libretto init` interactively to set up credentials.");
 }
@@ -95,6 +107,7 @@ async function runInteractiveApiSetup() {
   console.log("\nSnapshot analysis setup:");
   console.log("  Libretto uses direct API calls for snapshot analysis.");
   console.log(`  Credentials are loaded from process env and ${envPath}.`);
+  printInvalidAiConfigWarning();
   if (selection && hasProviderCredentials(selection.provider)) {
     console.log(`  \u2713 Ready: ${selection.model} (${selection.source})`);
     console.log("    Snapshot objectives will use the API analyzer by default.");
@@ -119,7 +132,7 @@ async function runInteractiveApiSetup() {
       console.log("    ANTHROPIC_API_KEY=...");
       console.log("    GEMINI_API_KEY=...");
       console.log(
-        "    Or run `npx libretto ai configure <provider>` to set a specific model."
+        "    Or run `npx libretto ai configure openai | anthropic | gemini | vertex` to set a specific model."
       );
       return;
     }
@@ -196,27 +209,21 @@ function getPackageSkillsDir() {
   }
   throw new Error("Could not locate libretto skill files in package");
 }
+function detectAgentDirs(root) {
+  const dirs = [];
+  if (existsSync(join(root, ".agents"))) dirs.push(join(root, ".agents"));
+  if (existsSync(join(root, ".claude"))) dirs.push(join(root, ".claude"));
+  return dirs;
+}
 async function copySkills() {
-  const cwd = process.cwd();
-  const agentDirs = [];
-  if (existsSync(join(cwd, ".agents"))) {
-    agentDirs.push({
-      name: ".agents",
-      skillDest: join(cwd, ".agents", "skills", "libretto")
-    });
-  }
-  if (existsSync(join(cwd, ".claude"))) {
-    agentDirs.push({
-      name: ".claude",
-      skillDest: join(cwd, ".claude", "skills", "libretto")
-    });
-  }
+  const agentDirs = detectAgentDirs(REPO_ROOT);
   if (agentDirs.length === 0) {
-    console.log("\nSkills: No .agents/ or .claude/ directory found \u2014 skipping skill copy.");
+    console.log("\nSkills: No .agents/ or .claude/ directory found in repo root \u2014 skipping.");
     return;
   }
-  const dirNames = agentDirs.map((d) => d.name).join(" and ");
-  const existing = agentDirs.filter((d) => existsSync(d.skillDest));
+  const destinations = agentDirs.map((d) => join(d, "skills", "libretto"));
+  const dirNames = agentDirs.map((d) => basename(d)).join(" and ");
+  const existing = destinations.filter((d) => existsSync(d));
   const verb = existing.length > 0 ? "Overwrite" : "Install";
   const proceed = await askYesNo(`
 ${verb} libretto skills in ${dirNames}?`);
@@ -231,7 +238,12 @@ ${verb} libretto skills in ${dirNames}?`);
     console.error(`  \u2717 ${e instanceof Error ? e.message : String(e)}`);
     return;
   }
-  for (const { name, skillDest } of agentDirs) {
+  for (let i = 0; i < agentDirs.length; i++) {
+    const skillDest = destinations[i];
+    const name = basename(agentDirs[i]);
+    if (existsSync(skillDest)) {
+      rmSync(skillDest, { recursive: true });
+    }
     cpSync(sourceDir, skillDest, { recursive: true });
     const fileCount = readdirSync(skillDest).length;
     console.log(`  \u2713 Copied ${fileCount} skill files to ${name}/skills/libretto/`);

package/dist/cli/commands/snapshot.js

@@ -13,6 +13,7 @@ import {
 } from "./shared.js";
 import { runApiInterpret } from "../core/api-snapshot-analyzer.js";
 import { readAiConfig } from "../core/ai-config.js";
+import { resolveSnapshotApiModelOrThrow } from "../core/snapshot-api-config.js";
 const DEFAULT_SNAPSHOT_CONTEXT = "No additional user context provided.";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function generateSnapshotRunId() {
@@ -191,6 +192,10 @@ async function runSnapshot(session, logger, pageId, objective, context) {
       "Couldn't run analysis: --objective is required when providing --context."
     );
   }
+  const configuredAi = normalizedObjective ? readAiConfig() : null;
+  if (normalizedObjective) {
+    resolveSnapshotApiModelOrThrow(configuredAi);
+  }
   const { pngPath, htmlPath, condensedHtmlPath } = await captureScreenshot(
     session,
     logger,
@@ -212,7 +217,7 @@ async function runSnapshot(session, logger, pageId, objective, context) {
     htmlPath,
     condensedHtmlPath
   };
-  await runApiInterpret(interpretArgs, logger, readAiConfig());
+  await runApiInterpret(interpretArgs, logger, configuredAi);
 }
 const snapshotInput = SimpleCLI.input({
   positionals: [],

package/dist/cli/core/ai-config.js

@@ -6,7 +6,7 @@ const CURRENT_CONFIG_VERSION = 1;
 const AiConfigSchema = z.object({
   model: z.string().min(1),
   updatedAt: z.string()
-}).strict();
+});
 const ViewportConfigSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1)
@@ -19,22 +19,68 @@ const LibrettoConfigSchema = z.object({
 const DEFAULT_MODELS = {
   openai: "openai/gpt-5.4",
   anthropic: "anthropic/claude-sonnet-4-6",
-  gemini: "google/gemini-2.5-flash",
-  google: "google/gemini-2.5-flash",
+  gemini: "google/gemini-3-flash-preview",
   vertex: "vertex/gemini-2.5-pro"
 };
-const CONFIGURE_PROVIDERS = Object.keys(DEFAULT_MODELS);
-function invalidConfigError(configPath) {
+const PROVIDER_ALIASES = {
+  claude: DEFAULT_MODELS.anthropic,
+  google: DEFAULT_MODELS.gemini
+};
+const CONFIGURE_PROVIDERS = ["openai", "anthropic", "gemini", "vertex"];
+function formatConfigureProviders(separator = " | ") {
+  return CONFIGURE_PROVIDERS.join(separator);
+}
+function formatConfigIssues(error) {
+  return error.issues.map((issue) => `  - ${issue.path.join(".") || "root"}: ${issue.message}`).join("\n");
+}
+function formatExpectedConfigExample() {
+  return JSON.stringify(
+    {
+      version: CURRENT_CONFIG_VERSION,
+      ai: {
+        model: "openai/gpt-5.4",
+        updatedAt: "2026-01-01T00:00:00.000Z"
+      },
+      viewport: {
+        width: 1280,
+        height: 800
+      }
+    },
+    null,
+    2
+  );
+}
+function invalidConfigError(configPath, detail) {
   return new Error(
-    `AI config is invalid at ${configPath}. Fix the file to match the expected schema or delete it.`
+    [
+      `AI config is invalid at ${configPath}.`,
+      detail ? `Problems:
+${detail}` : null,
+      "Expected config example:",
+      formatExpectedConfigExample(),
+      "Notes:",
+      '  - "ai" and "viewport" are optional.',
+      '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
+      "Fix the file to match this shape, or delete it and rerun:",
+      `  npx libretto ai configure ${formatConfigureProviders()}`
+    ].filter(Boolean).join("\n")
   );
 }
 function parseConfig(raw, configPath) {
+  let parsedJson;
   try {
-    return LibrettoConfigSchema.parse(JSON.parse(raw));
-  } catch {
-    throw invalidConfigError(configPath);
+    parsedJson = JSON.parse(raw);
+  } catch (error) {
+    throw invalidConfigError(
+      configPath,
+      `  - root: Invalid JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const parsed = LibrettoConfigSchema.safeParse(parsedJson);
+  if (!parsed.success) {
+    throw invalidConfigError(configPath, formatConfigIssues(parsed.error));
   }
+  return parsed.data;
 }
 function readLibrettoConfig(configPath = LIBRETTO_CONFIG_PATH) {
   if (!existsSync(configPath)) {
@@ -88,7 +134,8 @@ function resolveModelFromInput(input) {
   const trimmed = input.trim();
   if (!trimmed) return null;
   if (trimmed.includes("/")) return trimmed;
-  return DEFAULT_MODELS[trimmed.toLowerCase()] ?? null;
+  const normalized = trimmed.toLowerCase();
+  return DEFAULT_MODELS[normalized] ?? PROVIDER_ALIASES[normalized] ?? null;
 }
 function runAiConfigure(input, options = {}) {
   const configureCommandName = options.configureCommandName ?? "npx libretto ai configure";
@@ -97,7 +144,10 @@ function runAiConfigure(input, options = {}) {
   if (!presetArg && !input.clear) {
     const config2 = readAiConfig(configPath);
     if (!config2) {
-      console.log(`No AI config set. Run '${configureCommandName} openai' to set one.`);
+      console.log(
+        `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`
+      );
+      console.log("Provider credentials still come from your shell or .env file.");
       return;
     }
     printAiConfig(config2, configPath);
@@ -120,7 +170,7 @@ function runAiConfigure(input, options = {}) {
        ${configureCommandName} --clear`
     );
     throw new Error(
-      `Invalid provider or model. Use one of: ${CONFIGURE_PROVIDERS.join(", ")}, or a full model string like "openai/gpt-4o".`
+      `Invalid provider or model. Use one of: ${formatConfigureProviders()}, or a full model string like "openai/gpt-4o".`
     );
   }
   const config = writeAiConfig(model, configPath);

package/dist/cli/core/snapshot-api-config.js

@@ -3,16 +3,15 @@ import { dirname, join, resolve } from "node:path";
 import {
   readAiConfig
 } from "./ai-config.js";
-import { REPO_ROOT } from "./context.js";
+import { LIBRETTO_CONFIG_PATH, REPO_ROOT } from "./context.js";
 import {
   hasProviderCredentials,
-  missingProviderCredentialsMessage,
   parseModel
 } from "../../shared/llm/client.js";
 const DEFAULT_SNAPSHOT_MODELS = {
   openai: "openai/gpt-5.4",
   anthropic: "anthropic/claude-sonnet-4-6",
-  google: "google/gemini-2.5-flash",
+  google: "google/gemini-3-flash-preview",
   vertex: "vertex/gemini-2.5-pro"
 };
 class SnapshotApiUnavailableError extends Error {
@@ -21,6 +20,48 @@ class SnapshotApiUnavailableError extends Error {
     this.name = "SnapshotApiUnavailableError";
   }
 }
+function providerSetupSentence(provider) {
+  switch (provider) {
+    case "openai":
+      return "Add OPENAI_API_KEY to .env or as a shell environment variable.";
+    case "anthropic":
+      return "Add ANTHROPIC_API_KEY to .env or as a shell environment variable.";
+    case "google":
+      return "Add GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY to .env or as a shell environment variable.";
+    case "vertex":
+      return "Add GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT to .env or as a shell environment variable, and make sure application default credentials are configured.";
+  }
+}
+function defaultModelCommandLine() {
+  return "npx libretto ai configure openai | anthropic | gemini | vertex";
+}
+function providerMissingCredentialSummary(provider) {
+  switch (provider) {
+    case "openai":
+      return "OPENAI_API_KEY is missing";
+    case "anthropic":
+      return "ANTHROPIC_API_KEY is missing";
+    case "google":
+      return "GEMINI_API_KEY and GOOGLE_GENERATIVE_AI_API_KEY are missing";
+    case "vertex":
+      return "GOOGLE_CLOUD_PROJECT and GCLOUD_PROJECT are missing";
+  }
+}
+function noSnapshotApiConfiguredMessage() {
+  return [
+    "Failed to analyze snapshot because no snapshot analyzer is configured.",
+    `Add OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_CLOUD_PROJECT to .env or as a shell environment variable, or choose a default model with \`${defaultModelCommandLine()}\`.`,
+    "For more info, run `npx libretto init`."
+  ].join(" ");
+}
+function missingProviderSnapshotMessage(selection) {
+  const configuredSource = selection.source === "config" ? ` in ${LIBRETTO_CONFIG_PATH}` : " from process env or .env";
+  return [
+    `Failed to analyze snapshot because ${selection.provider} is configured${configuredSource}, but ${providerMissingCredentialSummary(selection.provider)}.`,
+    providerSetupSentence(selection.provider),
+    "For more info, run `npx libretto init`."
+  ].join(" ");
+}
 function readWorktreeEnvPath() {
   const gitPath = join(REPO_ROOT, ".git");
   if (!existsSync(gitPath)) return null;
@@ -114,12 +155,12 @@ function resolveSnapshotApiModelOrThrow(config = readAiConfig()) {
   const selection = resolveSnapshotApiModel(config);
   if (!selection) {
     throw new SnapshotApiUnavailableError(
-      "No API snapshot analyzer is available. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY/GOOGLE_GENERATIVE_AI_API_KEY, or GOOGLE_CLOUD_PROJECT, or run `npx libretto ai configure <provider>` to set a default model."
+      noSnapshotApiConfiguredMessage()
     );
   }
   if (!hasProviderCredentials(selection.provider)) {
     throw new SnapshotApiUnavailableError(
-      missingProviderCredentialsMessage(selection.provider)
+      missingProviderSnapshotMessage(selection)
     );
   }
   return selection;

package/dist/cli/workers/run-integration-runtime.js

@@ -6,7 +6,6 @@ import { pathToFileURL } from "node:url";
 import {
   launchBrowser
 } from "../../index.js";
-import { setSessionForPause } from "../../shared/debug/pause.js";
 import { parseSessionStateContent } from "../../shared/state/index.js";
 import { getProfilePath, normalizeDomain } from "../core/browser.js";
 import {
@@ -181,7 +180,6 @@ async function runIntegrationInternal(args, options) {
       appendFileSync(networkLogPath, JSON.stringify(entry) + "\n");
     }
   });
-  setSessionForPause(args.session);
   const workflowContext = {
     logger: integrationLogger,
     page: browserSession.page,

package/dist/shared/debug/index.cjs

@@ -18,13 +18,11 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var debug_exports = {};
 __export(debug_exports, {
-  pause: () => import_pause.pause,
-  setSessionForPause: () => import_pause.setSessionForPause
+  pause: () => import_pause.pause
 });
 module.exports = __toCommonJS(debug_exports);
 var import_pause = require("./pause.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  pause,
-  setSessionForPause
+  pause
 });

package/dist/shared/debug/index.d.cts

@@ -1 +1 @@
-export { pause, setSessionForPause } from './pause.cjs';
+export { pause } from './pause.cjs';

package/dist/shared/debug/index.d.ts

@@ -1 +1 @@
-export { pause, setSessionForPause } from './pause.js';
+export { pause } from './pause.js';

package/dist/shared/debug/index.js

@@ -1,5 +1,4 @@
-import { pause, setSessionForPause } from "./pause.js";
+import { pause } from "./pause.js";
 export {
-  pause,
-  setSessionForPause
+  pause
 };

package/dist/shared/debug/pause.cjs

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,54 +15,53 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var pause_exports = {};
 __export(pause_exports, {
-  pause: () => pause,
-  setSessionForPause: () => setSessionForPause
+  pause: () => pause
 });
 module.exports = __toCommonJS(pause_exports);
 var import_node_fs = require("node:fs");
 var import_promises = require("node:fs/promises");
-let _sessionName;
-function setSessionForPause(session) {
-  _sessionName = session;
-}
-function getSessionFromProcessArgs() {
-  const rawPayload = process.argv[2];
-  if (!rawPayload) return void 0;
+var import_context = require("../../cli/core/context.js");
+var import_pause_signals = require("../../cli/core/pause-signals.js");
+var import_session = require("../../cli/core/session.js");
+function isPidRunning(pid) {
   try {
-    const parsed = JSON.parse(rawPayload);
-    return typeof parsed.session === "string" ? parsed.session : void 0;
+    process.kill(pid, 0);
+    return true;
   } catch {
-    return void 0;
+    return false;
   }
 }
-function resolveSession() {
-  return _sessionName ?? getSessionFromProcessArgs();
+function getRunningSessions() {
+  return (0, import_session.listSessionsWithStateFile)().filter((candidate) => {
+    const state = (0, import_session.readSessionState)(candidate);
+    return state !== null && isPidRunning(state.pid);
+  });
+}
+function throwMissingSessionError() {
+  const runningSessions = getRunningSessions();
+  const lines = ["pause(session) requires a non-empty session ID."];
+  if (runningSessions.length > 0) {
+    lines.push("", "Running sessions:");
+    for (const runningSession of runningSessions) {
+      lines.push(`  ${runningSession}`);
+    }
+  }
+  throw new Error(lines.join("\n"));
 }
-async function pause() {
+async function pause(session) {
   if (process.env.NODE_ENV === "production") {
     return;
   }
-  const session = resolveSession();
-  if (!session) {
-    return;
+  if (typeof session !== "string" || session.trim().length === 0) {
+    throwMissingSessionError();
   }
-  const { getPauseSignalPaths, removeSignalIfExists } = await import("../../cli/core/pause-signals.js");
-  const { getSessionDir } = await import("../../cli/core/context.js");
-  const signalPaths = getPauseSignalPaths(session);
+  const signalPaths = (0, import_pause_signals.getPauseSignalPaths)(session);
   const { pausedSignalPath, resumeSignalPath } = signalPaths;
-  await (0, import_promises.mkdir)(getSessionDir(session), { recursive: true });
-  await removeSignalIfExists(resumeSignalPath);
+  await (0, import_promises.mkdir)((0, import_context.getSessionDir)(session), { recursive: true });
+  await (0, import_pause_signals.removeSignalIfExists)(resumeSignalPath);
   const details = {
     sessionName: session,
     pausedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -79,12 +76,11 @@ async function pause() {
       (resolve) => setTimeout(resolve, RESUME_POLL_INTERVAL_MS)
     );
   }
-  await removeSignalIfExists(resumeSignalPath);
-  await removeSignalIfExists(pausedSignalPath);
+  await (0, import_pause_signals.removeSignalIfExists)(resumeSignalPath);
+  await (0, import_pause_signals.removeSignalIfExists)(pausedSignalPath);
   console.log("[pause] Resume signal received. Continuing workflow...");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  pause,
-  setSessionForPause
+  pause
 });

package/dist/shared/debug/pause.d.cts

@@ -1,7 +1,3 @@
-/**
- * Called by the CLI runtime to make the session name available to `pause()`.
- */
-declare function setSessionForPause(session: string): void;
 /**
  * Standalone pause function.
  *
@@ -11,6 +7,6 @@ declare function setSessionForPause(session: string): void;
  *
  * Import directly: `import { pause } from "libretto";`
  */
-declare function pause(): Promise<void>;
+declare function pause(session: string): Promise<void>;
 
-export { pause, setSessionForPause };
+export { pause };

package/dist/shared/debug/pause.d.ts

@@ -1,7 +1,3 @@
-/**
- * Called by the CLI runtime to make the session name available to `pause()`.
- */
-declare function setSessionForPause(session: string): void;
 /**
  * Standalone pause function.
  *
@@ -11,6 +7,6 @@ declare function setSessionForPause(session: string): void;
  *
  * Import directly: `import { pause } from "libretto";`
  */
-declare function pause(): Promise<void>;
+declare function pause(session: string): Promise<void>;
 
-export { pause, setSessionForPause };
+export { pause };

package/dist/shared/debug/pause.js

@@ -1,32 +1,40 @@
 import { existsSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
-let _sessionName;
-function setSessionForPause(session) {
-  _sessionName = session;
-}
-function getSessionFromProcessArgs() {
-  const rawPayload = process.argv[2];
-  if (!rawPayload) return void 0;
+import { getSessionDir } from "../../cli/core/context.js";
+import { getPauseSignalPaths, removeSignalIfExists } from "../../cli/core/pause-signals.js";
+import { listSessionsWithStateFile, readSessionState } from "../../cli/core/session.js";
+function isPidRunning(pid) {
   try {
-    const parsed = JSON.parse(rawPayload);
-    return typeof parsed.session === "string" ? parsed.session : void 0;
+    process.kill(pid, 0);
+    return true;
   } catch {
-    return void 0;
+    return false;
   }
 }
-function resolveSession() {
-  return _sessionName ?? getSessionFromProcessArgs();
+function getRunningSessions() {
+  return listSessionsWithStateFile().filter((candidate) => {
+    const state = readSessionState(candidate);
+    return state !== null && isPidRunning(state.pid);
+  });
+}
+function throwMissingSessionError() {
+  const runningSessions = getRunningSessions();
+  const lines = ["pause(session) requires a non-empty session ID."];
+  if (runningSessions.length > 0) {
+    lines.push("", "Running sessions:");
+    for (const runningSession of runningSessions) {
+      lines.push(`  ${runningSession}`);
+    }
+  }
+  throw new Error(lines.join("\n"));
 }
-async function pause() {
+async function pause(session) {
   if (process.env.NODE_ENV === "production") {
     return;
   }
-  const session = resolveSession();
-  if (!session) {
-    return;
+  if (typeof session !== "string" || session.trim().length === 0) {
+    throwMissingSessionError();
   }
-  const { getPauseSignalPaths, removeSignalIfExists } = await import("../../cli/core/pause-signals.js");
-  const { getSessionDir } = await import("../../cli/core/context.js");
   const signalPaths = getPauseSignalPaths(session);
   const { pausedSignalPath, resumeSignalPath } = signalPaths;
   await mkdir(getSessionDir(session), { recursive: true });
@@ -50,6 +58,5 @@ async function pause() {
   console.log("[pause] Resume signal received. Continuing workflow...");
 }
 export {
-  pause,
-  setSessionForPause
+  pause
 };

package/dist/shared/llm/client.cjs

@@ -62,7 +62,7 @@ function parseModel(model) {
   const slashIndex = model.indexOf("/");
   if (slashIndex === -1) {
     throw new Error(
-      `Invalid model string "${model}". Expected format: "provider/model-id" (for example "openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "google/gemini-2.5-pro", or "vertex/gemini-2.5-pro").`
+      `Invalid model string "${model}". Expected format: "provider/model-id" (for example "openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "google/gemini-3-flash-preview", or "vertex/gemini-2.5-pro").`
     );
   }
   const providerInput = model.slice(0, slashIndex).toLowerCase();
@@ -90,14 +90,14 @@ function hasProviderCredentials(provider, env = process.env) {
 function missingProviderCredentialsMessage(provider) {
   switch (provider) {
     case "google":
-      return "Missing Gemini API key. Set GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.";
+      return "Gemini API key is missing. Set GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.";
     case "vertex":
-      return "Missing Vertex AI project. Set GOOGLE_CLOUD_PROJECT (or GCLOUD_PROJECT) and ensure application default credentials are configured.";
+      return "Vertex AI project is missing. Set GOOGLE_CLOUD_PROJECT (or GCLOUD_PROJECT) and ensure application default credentials are configured.";
     case "anthropic": {
-      return "Missing Anthropic API key. Set ANTHROPIC_API_KEY.";
+      return "Anthropic API key is missing. Set ANTHROPIC_API_KEY.";
     }
     case "openai": {
-      return "Missing OpenAI API key. Set OPENAI_API_KEY.";
+      return "OpenAI API key is missing. Set OPENAI_API_KEY.";
     }
   }
 }

package/dist/shared/llm/client.js

@@ -26,7 +26,7 @@ function parseModel(model) {
   const slashIndex = model.indexOf("/");
   if (slashIndex === -1) {
     throw new Error(
-      `Invalid model string "${model}". Expected format: "provider/model-id" (for example "openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "google/gemini-2.5-pro", or "vertex/gemini-2.5-pro").`
+      `Invalid model string "${model}". Expected format: "provider/model-id" (for example "openai/gpt-5.4", "anthropic/claude-sonnet-4-6", "google/gemini-3-flash-preview", or "vertex/gemini-2.5-pro").`
     );
   }
   const providerInput = model.slice(0, slashIndex).toLowerCase();
@@ -54,14 +54,14 @@ function hasProviderCredentials(provider, env = process.env) {
 function missingProviderCredentialsMessage(provider) {
   switch (provider) {
     case "google":
-      return "Missing Gemini API key. Set GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.";
+      return "Gemini API key is missing. Set GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.";
     case "vertex":
-      return "Missing Vertex AI project. Set GOOGLE_CLOUD_PROJECT (or GCLOUD_PROJECT) and ensure application default credentials are configured.";
+      return "Vertex AI project is missing. Set GOOGLE_CLOUD_PROJECT (or GCLOUD_PROJECT) and ensure application default credentials are configured.";
     case "anthropic": {
-      return "Missing Anthropic API key. Set ANTHROPIC_API_KEY.";
+      return "Anthropic API key is missing. Set ANTHROPIC_API_KEY.";
     }
     case "openai": {
-      return "Missing OpenAI API key. Set OPENAI_API_KEY.";
+      return "OpenAI API key is missing. Set OPENAI_API_KEY.";
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "dist",
+    "scripts",
     "skills/libretto"
   ],
   "bin": {
@@ -28,7 +29,7 @@
     }
   },
   "scripts": {
-    "postinstall": "playwright install chromium",
+    "postinstall": "node scripts/postinstall.mjs",
     "build": "pnpm run build:runtime && pnpm run build:cli",
     "build:runtime": "tsup --config tsup.config.ts",
     "build:cli": "tsup --config tsup.cli.config.ts",

package/scripts/postinstall.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "..");
+
+// Install Playwright Chromium
+spawnSync("npx", ["playwright", "install", "chromium"], {
+  stdio: "inherit",
+  shell: true,
+});
+
+// Find git repo root
+const gitResult = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+  encoding: "utf-8",
+  stdio: ["pipe", "pipe", "pipe"],
+});
+const repoRoot = gitResult.status === 0 && gitResult.stdout
+  ? gitResult.stdout.trim()
+  : null;
+if (!repoRoot) process.exit(0);
+
+// Sync skills to any agent dirs at repo root
+const sourceDir = join(packageRoot, "skills", "libretto");
+if (!existsSync(sourceDir)) process.exit(0);
+
+const agentDirNames = [".agents", ".claude"];
+for (const name of agentDirNames) {
+  const agentDir = join(repoRoot, name);
+  if (!existsSync(agentDir)) continue;
+  const dest = join(agentDir, "skills", "libretto");
+  if (existsSync(dest)) rmSync(dest, { recursive: true });
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(sourceDir, dest, { recursive: true });
+  const count = readdirSync(dest).length;
+  console.log(`libretto: synced ${count} skill files to ${dest}`);
+}