libretto 0.5.4 → 0.5.6

package/src/runtime/recovery/errors.ts

@@ -3,7 +3,7 @@ import {
   type MinimalLogger,
   defaultLogger,
 } from "../../shared/logger/logger.js";
-import type { LLMClient } from "../../shared/llm/types.js";
+import { generateObject, type LanguageModel } from "ai";
 import { z } from "zod";
 
 /**
@@ -47,7 +47,7 @@ export async function detectSubmissionError(
   page: Page,
   error: unknown,
   logContext: string,
-  llmClient: LLMClient,
+  model: LanguageModel,
   knownErrors: KnownSubmissionError[] = [],
   logger?: MinimalLogger,
 ): Promise<DetectedSubmissionError> {
@@ -109,7 +109,8 @@ IMPORTANT:
 
 ${domSnapshot ? `<dom_snapshot>\n${domSnapshot}\n</dom_snapshot>` : ""}`;
 
-  const result = await llmClient.generateObjectFromMessages({
+  const { object: result } = await generateObject({
+    model,
     schema: detectSubmissionErrorSchema,
     messages: [
       {

package/src/runtime/recovery/recovery.ts

@@ -3,7 +3,7 @@ import {
   type MinimalLogger,
   defaultLogger,
 } from "../../shared/logger/logger.js";
-import type { LLMClient } from "../../shared/llm/types.js";
+import type { LanguageModel } from "ai";
 import { executeRecoveryAgent } from "./agent.js";
 
 /**
@@ -14,7 +14,7 @@ export async function attemptWithRecovery<T>(
   page: Page,
   fn: () => Promise<T>,
   logger?: MinimalLogger,
-  llmClient?: LLMClient,
+  model?: LanguageModel,
 ): Promise<T> {
   const log = logger ?? defaultLogger;
   try {
@@ -33,7 +33,7 @@ export async function attemptWithRecovery<T>(
       throw error;
     }
 
-    if (!llmClient) {
+    if (!model) {
       throw error;
     }
 
@@ -45,7 +45,7 @@ export async function attemptWithRecovery<T>(
       page,
       "Look at the page to see if there is a popup blocking the screen. If so, close the popup.",
       log,
-      llmClient,
+      model,
     );
 
     return await fn();

package/src/shared/debug/pause.ts

@@ -5,35 +5,16 @@ import {
   getPauseSignalPaths,
   removeSignalIfExists,
 } from "../../cli/core/pause-signals.js";
-import {
-  listSessionsWithStateFile,
-  readSessionState,
-} from "../../cli/core/session.js";
-
-function isPidRunning(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function getRunningSessions(): string[] {
-  return listSessionsWithStateFile().filter((candidate) => {
-    const state = readSessionState(candidate);
-    return state !== null && state.pid != null && isPidRunning(state.pid);
-  });
-}
+import { listRunningSessions } from "../../cli/core/session.js";
 
 function throwMissingSessionError(): never {
-  const runningSessions = getRunningSessions();
+  const runningSessions = listRunningSessions();
   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}`);
+    for (const s of runningSessions) {
+      lines.push(`  ${s.session}`);
     }
   }
 

package/src/shared/run/browser.ts

@@ -9,9 +9,10 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { ensureLibrettoSessionStatePath } from "../paths/paths.js";
 import {
   SESSION_STATE_VERSION,
+  type SessionAccessMode,
   SessionStateFileSchema,
 } from "../state/session-state.js";
-import { readLibrettoConfig } from "../../cli/core/ai-config.js";
+import { readLibrettoConfig } from "../../cli/core/config.js";
 
 async function pickFreePort(): Promise<number> {
   return await new Promise((resolve, reject) => {
@@ -34,6 +35,7 @@ export type LaunchBrowserArgs = {
   headless?: boolean;
   viewport?: { width: number; height: number };
   storageStatePath?: string;
+  accessMode?: SessionAccessMode;
 };
 
 export type BrowserSession = {
@@ -97,6 +99,7 @@ export async function launchBrowser({
   headless = false,
   viewport = { width: 1366, height: 768 },
   storageStatePath,
+  accessMode = "write-access",
 }: LaunchBrowserArgs): Promise<BrowserSession> {
   const debugPort = await pickFreePort();
   const windowPosition = headless ? undefined : resolveWindowPosition();
@@ -141,6 +144,7 @@ export async function launchBrowser({
         pid: process.pid,
         startedAt: new Date().toISOString(),
         status: "active",
+        mode: accessMode,
       },
       null,
       2,

package/src/shared/state/index.ts

@@ -1,10 +1,12 @@
 export {
+  SessionAccessModeSchema,
   SESSION_STATE_VERSION,
   SessionStatusSchema,
   SessionStateFileSchema,
   parseSessionStateData,
   parseSessionStateContent,
   serializeSessionState,
+  type SessionAccessMode,
   type SessionStatus,
   type SessionState,
   type SessionStateFile,

package/src/shared/state/session-state.ts

@@ -9,6 +9,7 @@ export const SessionStatusSchema = z.enum([
   "failed",
   "exited",
 ]);
+export const SessionAccessModeSchema = z.enum(["read-only", "write-access"]);
 export const SessionViewportSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1),
@@ -22,10 +23,12 @@ export const SessionStateFileSchema = z.object({
   session: z.string().min(1),
   startedAt: z.string().datetime({ offset: true }),
   status: SessionStatusSchema.optional(),
+  mode: SessionAccessModeSchema.default("write-access"),
   viewport: SessionViewportSchema.optional(),
 });
 
 export type SessionStatus = z.infer<typeof SessionStatusSchema>;
+export type SessionAccessMode = z.infer<typeof SessionAccessModeSchema>;
 export type SessionStateFile = z.infer<typeof SessionStateFileSchema>;
 export type SessionState = Omit<SessionStateFile, "version">;
 

package/src/shared/workflow/workflow.ts

@@ -1,12 +1,10 @@
 import type { Page } from "playwright";
-import type { MinimalLogger } from "../logger/logger.js";
 
 export const LIBRETTO_WORKFLOW_BRAND = Symbol.for("libretto.workflow");
 
 export type LibrettoWorkflowContext = {
   session: string;
   page: Page;
-  logger: MinimalLogger;
 };
 
 export type LibrettoWorkflowHandler<Input = unknown, Output = unknown> = (
@@ -19,10 +17,7 @@ export class LibrettoWorkflow<Input = unknown, Output = unknown> {
   public readonly name: string;
   private readonly handler: LibrettoWorkflowHandler<Input, Output>;
 
-  constructor(
-    name: string,
-    handler: LibrettoWorkflowHandler<Input, Output>,
-  ) {
+  constructor(name: string, handler: LibrettoWorkflowHandler<Input, Output>) {
     this.name = name;
     this.handler = handler;
   }
@@ -72,31 +67,45 @@ function addWorkflowOrThrow(
   workflowsByName.set(value.name, value);
 }
 
+function collectWorkflowsOrThrow(
+  values: Iterable<unknown>,
+): ExportedLibrettoWorkflow[] {
+  const workflowsByName = new Map<string, ExportedLibrettoWorkflow>();
+
+  for (const value of values) {
+    addWorkflowOrThrow(workflowsByName, value);
+  }
+
+  return [...workflowsByName.values()];
+}
+
 export function getWorkflowsFromModuleExports(
   moduleExports: WorkflowModuleExports,
 ): ExportedLibrettoWorkflow[] {
-  const workflowsByName = new Map<string, ExportedLibrettoWorkflow>();
+  const discoveredValues: unknown[] = [];
 
   for (const [exportName, value] of Object.entries(moduleExports)) {
     if (exportName === "workflows" && value && typeof value === "object") {
       // Support both `export const workflows = workflow(...)` and
       // `export const workflows = { myWorkflow }`.
       if (isLibrettoWorkflow(value)) {
-        addWorkflowOrThrow(workflowsByName, value);
+        discoveredValues.push(value);
       } else {
-        for (const nestedValue of Object.values(
-          value as Record<string, unknown>,
-        )) {
-          addWorkflowOrThrow(workflowsByName, nestedValue);
-        }
+        discoveredValues.push(...Object.values(value as Record<string, unknown>));
       }
       continue;
     }
 
-    addWorkflowOrThrow(workflowsByName, value);
+    discoveredValues.push(value);
   }
 
-  return [...workflowsByName.values()];
+  return collectWorkflowsOrThrow(discoveredValues);
+}
+
+export function getDefaultWorkflowFromModuleExports(
+  moduleExports: WorkflowModuleExports,
+): ExportedLibrettoWorkflow | null {
+  return isLibrettoWorkflow(moduleExports.default) ? moduleExports.default : null;
 }
 
 export function getWorkflowFromModuleExports(

package/dist/cli/commands/init.js

@@ -1,286 +0,0 @@
-import { createInterface } from "node:readline";
-import {
-  appendFileSync,
-  cpSync,
-  existsSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync
-} from "node:fs";
-import { spawnSync } from "node:child_process";
-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";
-import {
-  loadSnapshotEnv,
-  resolveSnapshotApiModel
-} from "../core/snapshot-api-config.js";
-import { hasProviderCredentials } from "../../shared/llm/client.js";
-import { SimpleCLI } from "../framework/simple-cli.js";
-const PROVIDER_CHOICES = [
-  {
-    key: "1",
-    label: "OpenAI",
-    envVar: "OPENAI_API_KEY",
-    envHint: "Get your key at https://platform.openai.com/api-keys"
-  },
-  {
-    key: "2",
-    label: "Anthropic",
-    envVar: "ANTHROPIC_API_KEY",
-    envHint: "Get your key at https://console.anthropic.com/settings/keys"
-  },
-  {
-    key: "3",
-    label: "Google Gemini",
-    envVar: "GEMINI_API_KEY",
-    envHint: "Get your key at https://aistudio.google.com/apikey"
-  },
-  {
-    key: "4",
-    label: "Google Vertex AI",
-    envVar: "GOOGLE_CLOUD_PROJECT",
-    envHint: "Requires gcloud auth application-default login and a GCP project ID"
-  }
-];
-function promptUser(rl, question) {
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      resolve(answer.trim());
-    });
-  });
-}
-function safeReadAiConfig() {
-  try {
-    return readAiConfig();
-  } catch {
-    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);
-  const envPath = join(REPO_ROOT, ".env");
-  console.log("\nSnapshot analysis:");
-  console.log(
-    "  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."
-    );
-    console.log("    No further action required.");
-    return;
-  }
-  console.log("  \u2717 No snapshot API credentials detected.");
-  console.log("    Add one provider to .env:");
-  console.log("      OPENAI_API_KEY=...");
-  console.log("      ANTHROPIC_API_KEY=...");
-  console.log("      GEMINI_API_KEY=...  # or GOOGLE_GENERATIVE_AI_API_KEY");
-  console.log(
-    "      GOOGLE_CLOUD_PROJECT=...  # plus application default credentials for Vertex"
-  );
-  console.log(
-    "    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."
-  );
-}
-async function runInteractiveApiSetup() {
-  const config = safeReadAiConfig();
-  const selection = resolveSnapshotApiModel(config);
-  const envPath = join(REPO_ROOT, ".env");
-  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."
-    );
-    return;
-  }
-  console.log("  \u2717 No snapshot API credentials detected.\n");
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-  try {
-    console.log(
-      "  Which API provider would you like to use for snapshot analysis?\n"
-    );
-    for (const choice of PROVIDER_CHOICES) {
-      console.log(`    ${choice.key}) ${choice.label}`);
-    }
-    console.log("    s) Skip for now\n");
-    const answer = await promptUser(rl, "  Choice: ");
-    if (answer.toLowerCase() === "s" || !answer) {
-      console.log(
-        "\n  Skipped. You can set up API credentials later by rerunning `npx libretto init`."
-      );
-      console.log("  Or add credentials directly to your .env file:");
-      console.log("    OPENAI_API_KEY=...");
-      console.log("    ANTHROPIC_API_KEY=...");
-      console.log("    GEMINI_API_KEY=...");
-      console.log(
-        "    Or run `npx libretto ai configure openai | anthropic | gemini | vertex` to set a specific model."
-      );
-      return;
-    }
-    const selected = PROVIDER_CHOICES.find((choice) => choice.key === answer);
-    if (!selected) {
-      console.log(`
-  Unknown choice "${answer}". Skipping API setup.`);
-      return;
-    }
-    console.log(`
-  ${selected.label} selected.`);
-    console.log(`  ${selected.envHint}
-`);
-    const apiKeyValue = await promptUser(
-      rl,
-      `  Enter your ${selected.envVar}: `
-    );
-    if (!apiKeyValue) {
-      console.log("\n  No value entered. Skipping API key setup.");
-      return;
-    }
-    let envContent = "";
-    if (existsSync(envPath)) {
-      envContent = readFileSync(envPath, "utf-8");
-    }
-    const envLine = `${selected.envVar}=${apiKeyValue}`;
-    if (envContent.includes(`${selected.envVar}=`)) {
-      const updated = envContent.replace(
-        new RegExp(`^${selected.envVar}=.*$`, "m"),
-        () => envLine
-      );
-      writeFileSync(envPath, updated);
-      console.log(`
-  \u2713 Updated ${selected.envVar} in ${envPath}`);
-    } else {
-      const separator = envContent && !envContent.endsWith("\n") ? "\n" : "";
-      appendFileSync(envPath, `${separator}${envLine}
-`);
-      console.log(`
-  \u2713 Added ${selected.envVar} to ${envPath}`);
-    }
-    loadSnapshotEnv();
-    process.env[selected.envVar] = apiKeyValue;
-    const newSelection = resolveSnapshotApiModel(safeReadAiConfig());
-    if (newSelection && hasProviderCredentials(newSelection.provider)) {
-      console.log(`  \u2713 Snapshot API ready: ${newSelection.model}`);
-    }
-  } finally {
-    rl.close();
-  }
-}
-function installBrowsers() {
-  console.log("\nInstalling Playwright Chromium...");
-  const result = spawnSync("npx", ["playwright", "install", "chromium"], {
-    stdio: "inherit",
-    shell: true
-  });
-  if (result.status === 0) {
-    console.log("  \u2713 Playwright Chromium installed");
-  } else {
-    console.error(
-      "  \u2717 Failed to install Playwright Chromium. Run manually: npx playwright install chromium"
-    );
-  }
-}
-function getPackageSkillsDir() {
-  const thisFile = fileURLToPath(import.meta.url);
-  let dir = dirname(thisFile);
-  while (dir !== dirname(dir)) {
-    if (existsSync(join(dir, "skills", "libretto"))) {
-      return join(dir, "skills", "libretto");
-    }
-    dir = dirname(dir);
-  }
-  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;
-}
-function copySkills() {
-  const agentDirs = detectAgentDirs(REPO_ROOT);
-  if (agentDirs.length === 0) {
-    console.log(
-      "\nSkills: No .agents/ or .claude/ directory found in repo root \u2014 skipping."
-    );
-    return;
-  }
-  const destinations = agentDirs.map((d) => join(d, "skills", "libretto"));
-  let sourceDir;
-  try {
-    sourceDir = getPackageSkillsDir();
-  } catch (e) {
-    console.error(`  \u2717 ${e instanceof Error ? e.message : String(e)}`);
-    return;
-  }
-  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/`
-    );
-  }
-}
-const initInput = SimpleCLI.input({
-  positionals: [],
-  named: {
-    skipBrowsers: SimpleCLI.flag({
-      name: "skip-browsers",
-      help: "Skip Playwright Chromium installation"
-    })
-  }
-});
-const initCommand = SimpleCLI.command({
-  description: "Initialize libretto in the current project"
-}).input(initInput).handle(async ({ input }) => {
-  console.log("Initializing libretto...\n");
-  if (!input.skipBrowsers) {
-    installBrowsers();
-  } else {
-    console.log("\nSkipping browser installation (--skip-browsers)");
-  }
-  copySkills();
-  if (process.stdin.isTTY) {
-    await runInteractiveApiSetup();
-  } else {
-    loadSnapshotEnv();
-    printSnapshotApiStatus();
-  }
-  console.log("\n\u2713 libretto init complete");
-});
-export {
-  initCommand,
-  initInput
-};

package/dist/cli/commands/logs.js

@@ -1,117 +0,0 @@
-import { z } from "zod";
-import { listOpenPages } from "../core/browser.js";
-import { withSessionLogger } from "../core/context.js";
-import {
-  clearActionLog,
-  clearNetworkLog,
-  formatActionEntry,
-  formatNetworkEntry,
-  readActionLog,
-  readNetworkLog
-} from "../core/telemetry.js";
-import { SimpleCLI } from "../framework/simple-cli.js";
-import {
-  integerOption,
-  pageOption,
-  sessionOption,
-  withRequiredSession
-} from "./shared.js";
-async function resolvePageId(session, pageId) {
-  if (!pageId) return void 0;
-  const pages = await withSessionLogger(
-    session,
-    async (logger) => listOpenPages(session, logger)
-  );
-  const foundPage = pages.find((page) => page.id === pageId);
-  if (!foundPage) {
-    throw new Error(
-      `Page "${pageId}" was not found in session "${session}". Run "libretto pages --session ${session}" to list ids.`
-    );
-  }
-  return pageId;
-}
-const networkInput = SimpleCLI.input({
-  positionals: [],
-  named: {
-    session: sessionOption(),
-    last: integerOption(),
-    filter: SimpleCLI.option(z.string().optional()),
-    method: SimpleCLI.option(z.string().optional()),
-    page: pageOption(),
-    clear: SimpleCLI.flag()
-  }
-});
-const networkCommand = SimpleCLI.command({
-  description: "View captured network requests"
-}).input(networkInput).use(withRequiredSession()).handle(async ({ input, ctx }) => {
-  if (input.clear) {
-    clearNetworkLog(ctx.session);
-    console.log("Network log cleared.");
-    return;
-  }
-  const pageId = await resolvePageId(ctx.session, input.page);
-  const entries = readNetworkLog(ctx.session, {
-    last: input.last,
-    filter: input.filter,
-    method: input.method,
-    pageId
-  });
-  if (entries.length === 0) {
-    console.log("No network requests captured.");
-    return;
-  }
-  for (const entry of entries) {
-    console.log(formatNetworkEntry(entry));
-  }
-  console.log(`
-${entries.length} request(s) shown.`);
-});
-const actionsInput = SimpleCLI.input({
-  positionals: [],
-  named: {
-    session: sessionOption(),
-    last: integerOption(),
-    filter: SimpleCLI.option(z.string().optional()),
-    action: SimpleCLI.option(z.string().optional()),
-    source: SimpleCLI.option(z.string().optional()),
-    page: pageOption(),
-    clear: SimpleCLI.flag()
-  }
-});
-const actionsCommand = SimpleCLI.command({
-  description: "View captured actions"
-}).input(actionsInput).use(withRequiredSession()).handle(async ({ input, ctx }) => {
-  if (input.clear) {
-    clearActionLog(ctx.session);
-    console.log("Action log cleared.");
-    return;
-  }
-  const pageId = await resolvePageId(ctx.session, input.page);
-  const entries = readActionLog(ctx.session, {
-    last: input.last,
-    filter: input.filter,
-    action: input.action,
-    source: input.source,
-    pageId
-  });
-  if (entries.length === 0) {
-    console.log("No actions captured.");
-    return;
-  }
-  for (const entry of entries) {
-    console.log(formatActionEntry(entry));
-  }
-  console.log(`
-${entries.length} action(s) shown.`);
-});
-const logCommands = {
-  network: networkCommand,
-  actions: actionsCommand
-};
-export {
-  actionsCommand,
-  actionsInput,
-  logCommands,
-  networkCommand,
-  networkInput
-};

package/dist/shared/llm/ai-sdk-adapter.d.ts

@@ -1,22 +0,0 @@
-import { LanguageModel } from 'ai';
-import { LLMClient } from './types.js';
-import 'zod';
-
-/**
- * Creates a libretto LLMClient from a Vercel AI SDK LanguageModel.
- *
- * This eliminates the need for consumers to write their own adapter
- * when using @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google-vertex,
- * or any other Vercel AI SDK-compatible provider.
- *
- * @example
- * ```typescript
- * import { createLLMClientFromModel } from "libretto/llm";
- * import { openai } from "@ai-sdk/openai";
- *
- * const llmClient = createLLMClientFromModel(openai("gpt-4o"));
- * ```
- */
-declare function createLLMClientFromModel(model: LanguageModel): LLMClient;
-
-export { createLLMClientFromModel };