libretto 0.5.5 → 0.5.6

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

@@ -17,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;
   }
@@ -70,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 };

package/dist/shared/llm/ai-sdk-adapter.js

@@ -1,49 +0,0 @@
-import { generateObject } from "ai";
-function createLLMClientFromModel(model) {
-  return {
-    async generateObject(opts) {
-      const { object } = await generateObject({
-        model,
-        schema: opts.schema,
-        prompt: opts.prompt,
-        temperature: opts.temperature ?? 0
-      });
-      return object;
-    },
-    async generateObjectFromMessages(opts) {
-      const messages = opts.messages.map((msg) => {
-        if (typeof msg.content === "string") {
-          return { role: msg.role, content: msg.content };
-        }
-        if (msg.role === "assistant") {
-          return {
-            role: "assistant",
-            content: msg.content.filter(
-              (part) => part.type === "text"
-            ).map((part) => ({ type: "text", text: part.text }))
-          };
-        }
-        return {
-          role: "user",
-          content: msg.content.map(
-            (part) => part.type === "text" ? { type: "text", text: part.text } : {
-              type: "image",
-              image: part.image,
-              ...part.mediaType ? { mediaType: part.mediaType } : {}
-            }
-          )
-        };
-      });
-      const { object } = await generateObject({
-        model,
-        schema: opts.schema,
-        messages,
-        temperature: opts.temperature ?? 0
-      });
-      return object;
-    }
-  };
-}
-export {
-  createLLMClientFromModel
-};

package/dist/shared/llm/client.d.ts

@@ -1,13 +0,0 @@
-import { LLMClient } from './types.js';
-import 'zod';
-
-type Provider = "google" | "vertex" | "anthropic" | "openai";
-declare function parseModel(model: string): {
-    provider: Provider;
-    modelId: string;
-};
-declare function hasProviderCredentials(provider: Provider, env?: NodeJS.ProcessEnv): boolean;
-declare function missingProviderCredentialsMessage(provider: Provider): string;
-declare function createLLMClient(model: string): LLMClient;
-
-export { type Provider, createLLMClient, hasProviderCredentials, missingProviderCredentialsMessage, parseModel };

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

@@ -1,5 +0,0 @@
-export { LLMClient, Message, MessageContentPart } from './types.js';
-export { createLLMClient } from './client.js';
-export { createLLMClientFromModel } from './ai-sdk-adapter.js';
-import 'zod';
-import 'ai';

package/dist/shared/llm/index.js

@@ -1,6 +0,0 @@
-import { createLLMClient } from "./client.js";
-import { createLLMClientFromModel } from "./ai-sdk-adapter.js";
-export {
-  createLLMClient,
-  createLLMClientFromModel
-};

package/dist/shared/llm/types.d.ts

@@ -1,67 +0,0 @@
-import z from 'zod';
-
-type MessageContentPart = {
-    type: "text";
-    text: string;
-} | {
-    type: "image";
-    image: string | Uint8Array;
-    mediaType?: string;
-};
-type Message = {
-    role: "user" | "assistant";
-    content: string | MessageContentPart[];
-};
-/**
- * Pluggable LLM client interface.
- *
- * Users provide their own implementation backed by any LLM provider
- * (OpenAI, Anthropic, etc.). Libretto uses this interface for AI extraction,
- * recovery agents, and error detection.
- *
- * **Error handling:** implementations should throw on failure rather than
- * returning sentinel values (e.g. `null` or `undefined`). Libretto relies
- * on exceptions to trigger retry/recovery logic.
- *
- * A ready-made adapter for the Vercel AI SDK is available via
- * {@link createLLMClientFromModel} in `libretto/llm`.
- */
-interface LLMClient {
-    /**
-     * Generate a structured object from a single text prompt.
-     *
-     * The underlying model **must** support structured / JSON output so that
-     * the response can be parsed and validated against the provided Zod schema.
-     *
-     * @param opts.prompt - The text prompt sent to the model.
-     * @param opts.schema - A Zod schema describing the expected response shape.
-     * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
-     * @returns The parsed object matching the schema.
-     * @throws On LLM or parsing failure.
-     */
-    generateObject<T extends z.ZodType>(opts: {
-        prompt: string;
-        schema: T;
-        temperature?: number;
-    }): Promise<z.output<T>>;
-    /**
-     * Generate a structured object from a conversation-style message array.
-     *
-     * Messages may contain **image content** (base64 data URIs via
-     * {@link MessageContentPart}), so the backing model must support
-     * vision / multimodal input when images are present.
-     *
-     * @param opts.messages - Ordered list of user/assistant messages, potentially multimodal.
-     * @param opts.schema - A Zod schema describing the expected response shape.
-     * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
-     * @returns The parsed object matching the schema.
-     * @throws On LLM or parsing failure.
-     */
-    generateObjectFromMessages<T extends z.ZodType>(opts: {
-        messages: Message[];
-        schema: T;
-        temperature?: number;
-    }): Promise<z.output<T>>;
-}
-
-export type { LLMClient, Message, MessageContentPart };