libretto 0.5.5 → 0.6.0

package/src/cli/core/telemetry.ts

@@ -2,7 +2,6 @@ import {
   appendFileSync,
   existsSync,
   readFileSync,
-  writeFileSync,
 } from "node:fs";
 import type { Page } from "playwright";
 import {
@@ -65,31 +64,6 @@ export function readNetworkLog(
   return entries;
 }
 
-export function formatNetworkEntry(e: NetworkLogEntry): string {
-  const time = e.ts.replace(/.*T/, "").replace(/\.\d+Z$/, "");
-  const duration = e.durationMs != null ? `${e.durationMs}ms` : "?ms";
-  const size = e.size != null ? `${e.size}B` : "";
-  const parts = [
-    `[${time}]`,
-    `${e.status}`,
-    `${e.method.padEnd(6)}`,
-    e.url,
-    duration,
-    size,
-  ].filter(Boolean);
-  let line = parts.join(" ");
-  if (e.postData) {
-    line += `\n         body: ${e.postData.substring(0, 120)}${e.postData.length > 120 ? "..." : ""}`;
-  }
-  return line;
-}
-
-export function clearNetworkLog(session: string): void {
-  assertSessionStateExistsOrThrow(session);
-  const logPath = getSessionNetworkLogPath(session);
-  writeFileSync(logPath, "");
-}
-
 export type ActionLogEntry = {
   ts: string;
   pageId?: string;
@@ -182,32 +156,6 @@ export function readActionLog(
   return entries;
 }
 
-export function formatActionEntry(e: ActionLogEntry): string {
-  const time = e.ts.replace(/.*T/, "").replace(/\.\d+Z$/, "");
-  const src = e.source.toUpperCase().padEnd(5);
-  const displaySelector = e.bestSemanticSelector || e.selector;
-  const parts = [`[${time}]`, `[${src}]`, e.action];
-  if (displaySelector) parts.push(displaySelector);
-  if (e.targetSelector && e.targetSelector !== displaySelector) {
-    parts.push(`target=${e.targetSelector}`);
-  }
-  if (e.nearbyText) parts.push(`text="${e.nearbyText}"`);
-  if (e.coordinates) {
-    parts.push(`@(${e.coordinates.x},${e.coordinates.y})`);
-  }
-  if (e.value) parts.push(`"${e.value}"`);
-  if (e.url) parts.push(e.url);
-  if (e.duration != null) parts.push(`${e.duration}ms`);
-  if (!e.success) parts.push(`ERROR: ${e.error || "unknown"}`);
-  return parts.join(" ");
-}
-
-export function clearActionLog(session: string): void {
-  assertSessionStateExistsOrThrow(session);
-  const logPath = getSessionActionsLogPath(session);
-  writeFileSync(logPath, "");
-}
-
 const LOCATOR_ACTION_METHODS = [
   "click",
   "dblclick",

package/src/cli/index.ts

@@ -1,13 +1,7 @@
 #!/usr/bin/env node
 import { runLibrettoCLI } from "./cli.js";
-import {
-  maybeConfigureLLMClientFactoryFromEnv,
-  setLLMClientFactory,
-} from "./core/context.js";
 
-export { setLLMClientFactory };
 export { runClose } from "./commands/browser.js";
 export { runLibrettoCLI };
 
-maybeConfigureLLMClientFactoryFromEnv();
 void runLibrettoCLI();

package/src/cli/router.ts

@@ -2,8 +2,8 @@ import { aiCommands } from "./commands/ai.js";
 import { browserCommands } from "./commands/browser.js";
 import { deployCommand } from "./commands/deploy.js";
 import { executionCommands } from "./commands/execution.js";
-import { initCommand } from "./commands/init.js";
-import { logCommands } from "./commands/logs.js";
+import { setupCommand } from "./commands/setup.js";
+import { statusCommand } from "./commands/status.js";
 import { snapshotCommand } from "./commands/snapshot.js";
 import { SimpleCLI } from "./framework/simple-cli.js";
 
@@ -11,9 +11,9 @@ export const cliRoutes = {
   ...browserCommands,
   deploy: deployCommand,
   ...executionCommands,
-  ...logCommands,
   ai: aiCommands,
-  init: initCommand,
+  setup: setupCommand,
+  status: statusCommand,
   snapshot: snapshotCommand,
 };
 

package/src/cli/workers/run-integration-runtime.ts

@@ -5,7 +5,7 @@ import { cwd } from "node:process";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
-  getWorkflowFromModuleExports,
+  getDefaultWorkflowFromModuleExports,
   getWorkflowsFromModuleExports,
   instrumentContext,
   launchBrowser,
@@ -138,9 +138,8 @@ function getAbsoluteIntegrationPath(integrationPath: string): string {
   return absolutePath;
 }
 
-async function loadWorkflowByName(
+async function loadDefaultWorkflow(
   absolutePath: string,
-  workflowName: string,
 ): Promise<LoadedLibrettoWorkflow> {
   let loadedModule: Record<string, unknown>;
   try {
@@ -156,22 +155,23 @@ async function loadWorkflowByName(
     );
   }
 
-  const workflow = getWorkflowFromModuleExports(loadedModule, workflowName);
-  if (workflow) {
-    return workflow as LoadedLibrettoWorkflow;
+  const defaultWorkflow = getDefaultWorkflowFromModuleExports(loadedModule);
+  if (defaultWorkflow) {
+    return defaultWorkflow as LoadedLibrettoWorkflow;
   }
 
-  const availableWorkflows = getWorkflowsFromModuleExports(loadedModule).map(
+  const availableWorkflowNames = getWorkflowsFromModuleExports(loadedModule).map(
     (candidate) => candidate.name,
   );
 
-  const detail =
-    availableWorkflows.length > 0
-      ? ` Available workflows: ${availableWorkflows.join(", ")}`
-      : ' No workflows found in this file. Export a workflow() instance from "libretto" directly or via `export const workflows = { ... }`.';
+  if (availableWorkflowNames.length === 0) {
+    throw new Error(
+      `No default-exported workflow found in ${absolutePath}. Export the workflow with \`export default workflow("name", handler)\`.`,
+    );
+  }
 
   throw new Error(
-    `Workflow "${workflowName}" not found in ${absolutePath}.${detail}`,
+    `No default-exported workflow found in ${absolutePath}. libretto run only uses the file's default export. Available named workflows: ${availableWorkflowNames.join(", ")}`,
   );
 }
 
@@ -194,7 +194,7 @@ async function runIntegrationInternal(
 ): Promise<RunIntegrationOutcome> {
   const { logger } = options;
   const absolutePath = getAbsoluteIntegrationPath(args.integrationPath);
-  const workflow = await loadWorkflowByName(absolutePath, args.workflowName);
+  const workflow = await loadDefaultWorkflow(absolutePath);
   const signalPaths = getPauseSignalPaths(args.session);
   await removeSignalIfExists(signalPaths.pausedSignalPath);
   await removeSignalIfExists(signalPaths.resumeSignalPath);
@@ -203,12 +203,12 @@ async function runIntegrationInternal(
   const restoreStdout = mirrorStdoutToFile(signalPaths.outputSignalPath);
 
   console.log(
-    `Running workflow "${args.workflowName}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
+    `Running workflow "${workflow.name}" from ${absolutePath} (${args.headless ? "headless" : "headed"})...`,
   );
 
   const integrationLogger = logger.withScope("integration-run", {
     integrationPath: absolutePath,
-    workflowName: args.workflowName,
+    workflowName: workflow.name,
     session: args.session,
   });
 
@@ -238,6 +238,9 @@ async function runIntegrationInternal(
     headless: args.headless,
     storageStatePath,
     viewport: args.viewport,
+    accessMode: args.accessMode,
+    cdpEndpoint: args.cdpEndpoint,
+    provider: args.provider,
   });
   if (!args.headless && args.visualize !== false) {
     await installHeadedWorkflowVisualization({
@@ -295,7 +298,6 @@ async function runIntegrationInternal(
       JSON.stringify({ completedAt: new Date().toISOString() }, null, 2),
       "utf8",
     );
-    console.log("Integration completed.");
     return { status: "completed" };
   } finally {
     restoreStdout();

package/src/cli/workers/run-integration-worker-protocol.ts

@@ -1,14 +1,17 @@
 import { z } from "zod";
+import { SessionAccessModeSchema } from "../../shared/state/index.js";
 
 export const RunIntegrationWorkerRequestSchema = z.object({
   integrationPath: z.string().min(1),
-  workflowName: z.string().min(1),
   session: z.string().min(1),
   params: z.unknown(),
   headless: z.boolean(),
   visualize: z.boolean().default(true),
   authProfileDomain: z.string().optional(),
   viewport: z.object({ width: z.number(), height: z.number() }).optional(),
+  accessMode: SessionAccessModeSchema.default("write-access"),
+  cdpEndpoint: z.string().optional(),
+  provider: z.object({ name: z.string(), sessionId: z.string() }).optional(),
 });
 
 export type RunIntegrationWorkerRequest = z.infer<

package/src/index.ts

@@ -16,13 +16,6 @@ export {
   jsonlConsoleSink,
 } from "./shared/logger/sinks.js";
 
-// LLM client interface
-export type {
-  LLMClient,
-  Message,
-  MessageContentPart,
-} from "./shared/llm/types.js";
-export { createLLMClientFromModel } from "./shared/llm/ai-sdk-adapter.js";
 export {
   SESSION_STATE_VERSION,
   SessionStatusSchema,
@@ -102,6 +95,7 @@ export {
 
 // Workflow helpers
 export {
+  getDefaultWorkflowFromModuleExports,
   getWorkflowFromModuleExports,
   getWorkflowsFromModuleExports,
   isLibrettoWorkflow,

package/src/runtime/extract/extract.ts

@@ -4,13 +4,13 @@ import {
   type MinimalLogger,
   defaultLogger,
 } from "../../shared/logger/logger.js";
-import type { LLMClient } from "../../shared/llm/types.js";
+import { generateObject, type LanguageModel } from "ai";
 
 export type ExtractOptions<T extends z.ZodType> = {
   page: Page;
   instruction: string;
   schema: T;
-  llmClient: LLMClient;
+  model: LanguageModel;
   logger?: MinimalLogger;
   /** Optional CSS selector to scope extraction to a specific element. */
   selector?: string;
@@ -31,7 +31,7 @@ export async function extractFromPage<T extends z.ZodType>(
     schema,
     selector,
     logger = defaultLogger,
-    llmClient,
+    model,
   } = options;
 
   let screenshot: string;
@@ -79,7 +79,8 @@ ${domContent ? `Here is the HTML content for additional context:\n<html>\n${domC
 
 Extract the requested information from the screenshot and return it in the specified format. Be precise and only extract what is visible.`;
 
-  const result = await llmClient.generateObjectFromMessages({
+  const { object: result } = await generateObject({
+    model,
     schema,
     messages: [
       {
@@ -98,5 +99,5 @@ Extract the requested information from the screenshot and return it in the speci
     instruction: instruction.slice(0, 100),
   });
 
-  return result;
+  return result as z.infer<T>;
 }

package/src/runtime/recovery/agent.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";
 
 type BrowserAction =
   | { type: "click"; x: number; y: number; button?: string }
@@ -183,9 +183,9 @@ export async function executeRecoveryAgent(
   page: Page,
   instruction: string,
   logger?: MinimalLogger,
-  llmClient?: LLMClient,
+  model?: LanguageModel,
 ): Promise<void> {
-  if (!llmClient) {
+  if (!model) {
     return;
   }
   const log = logger ?? defaultLogger;
@@ -213,7 +213,8 @@ export async function executeRecoveryAgent(
 
   const maxSteps = 3;
   for (let step = 1; step <= maxSteps; step++) {
-    const result = await llmClient.generateObjectFromMessages({
+    const { object: result } = await generateObject({
+      model,
       schema: recoveryActionSchema,
       messages: [
         {

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,9 @@ export type LaunchBrowserArgs = {
   headless?: boolean;
   viewport?: { width: number; height: number };
   storageStatePath?: string;
+  accessMode?: SessionAccessMode;
+  cdpEndpoint?: string;
+  provider?: { name: string; sessionId: string };
 };
 
 export type BrowserSession = {
@@ -97,7 +101,51 @@ export async function launchBrowser({
   headless = false,
   viewport = { width: 1366, height: 768 },
   storageStatePath,
+  accessMode = "write-access",
+  cdpEndpoint,
+  provider,
 }: LaunchBrowserArgs): Promise<BrowserSession> {
+  // Cloud/remote mode: connect to an existing CDP endpoint instead of launching locally
+  if (cdpEndpoint) {
+    const browser = await chromium.connectOverCDP(cdpEndpoint);
+    const context =
+      browser.contexts()[0] ?? (await browser.newContext({ viewport }));
+    const page = context.pages()[0] ?? (await context.newPage());
+    page.setDefaultTimeout(30_000);
+    page.setDefaultNavigationTimeout(45_000);
+
+    const metadataPath = ensureLibrettoSessionStatePath(sessionName);
+    writeFileSync(
+      metadataPath,
+      JSON.stringify(
+        {
+          version: SESSION_STATE_VERSION,
+          session: sessionName,
+          port: 0,
+          cdpEndpoint,
+          pid: process.pid,
+          startedAt: new Date().toISOString(),
+          status: "active",
+          mode: accessMode,
+          ...(provider ? { provider } : {}),
+        },
+        null,
+        2,
+      ),
+    );
+
+    return {
+      browser,
+      context,
+      page,
+      debugPort: 0,
+      metadataPath,
+      close: async () => {
+        await browser.close();
+      },
+    };
+  }
+
   const debugPort = await pickFreePort();
   const windowPosition = headless ? undefined : resolveWindowPosition();
   const browser = await chromium.launch({
@@ -141,6 +189,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

@@ -8,12 +8,19 @@ export const SessionStatusSchema = z.enum([
   "completed",
   "failed",
   "exited",
+  "cleanup-failed",
 ]);
+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),
 });
 
+export const ProviderStateSchema = z.object({
+  name: z.string(),
+  sessionId: z.string(),
+});
+
 export const SessionStateFileSchema = z.object({
   version: z.literal(SESSION_STATE_VERSION),
   port: z.number().int().min(0).max(65535),
@@ -22,10 +29,13 @@ 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(),
+  provider: ProviderStateSchema.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(