libretto 0.5.0 → 0.5.2

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

@@ -1,9 +1,11 @@
+import type { BrowserContext } from "playwright";
 import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { cwd } from "node:process";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  instrumentContext,
   launchBrowser,
   type LibrettoWorkflowContext,
 } from "../../index.js";
@@ -16,14 +18,16 @@ import {
   getSessionNetworkLogPath,
   getSessionStatePath,
 } from "../core/context.js";
-import { getPauseSignalPaths, removeSignalIfExists } from "../core/pause-signals.js";
+import {
+  getPauseSignalPaths,
+  removeSignalIfExists,
+} from "../core/pause-signals.js";
 import { installSessionTelemetry } from "../core/session-telemetry.js";
 import type { RunIntegrationWorkerRequest } from "./run-integration-worker-protocol.js";
 
 const LIBRETTO_WORKFLOW_BRAND = Symbol.for("libretto.workflow");
 
 type LoadedLibrettoWorkflow = {
-  metadata: {};
   run: (ctx: LibrettoWorkflowContext, input: unknown) => Promise<unknown>;
 };
 
@@ -71,7 +75,10 @@ function readSessionStatePid(session: string): number | null {
   if (!existsSync(statePath)) return null;
 
   try {
-    return parseSessionStateContent(readFileSync(statePath, "utf8"), statePath).pid;
+    return (
+      parseSessionStateContent(readFileSync(statePath, "utf8"), statePath)
+        .pid ?? null
+    );
   } catch {
     return null;
   }
@@ -101,14 +108,14 @@ async function waitForFailureSessionRelease(args: {
   }
 }
 
-function isLoadedLibrettoWorkflow(value: unknown): value is LoadedLibrettoWorkflow {
+function isLoadedLibrettoWorkflow(
+  value: unknown,
+): value is LoadedLibrettoWorkflow {
   if (!value || typeof value !== "object") return false;
   const candidate = value as Record<PropertyKey, unknown>;
   return (
     candidate[LIBRETTO_WORKFLOW_BRAND] === true &&
-    typeof candidate.run === "function" &&
-    !!candidate.metadata &&
-    typeof candidate.metadata === "object"
+    typeof candidate.run === "function"
   );
 }
 
@@ -182,8 +189,8 @@ async function loadWorkflowExport(
         '  import { workflow } from "libretto";',
         "",
         `  export const ${exportName} = workflow<InputType, OutputType>(`,
-        "    {},",
         "    async (ctx, input) => {",
+        "      // ctx.session  — libretto session name",
         "      // ctx.page     — Playwright Page instance",
         "      // ctx.logger   — MinimalLogger",
         "      // ctx.services — injected dependencies (generic, default {})",
@@ -198,6 +205,17 @@ async function loadWorkflowExport(
   return targetExport;
 }
 
+export async function installHeadedWorkflowVisualization(args: {
+  context: BrowserContext;
+  logger: LoggerApi;
+  instrument?: typeof instrumentContext;
+}): Promise<void> {
+  await (args.instrument ?? instrumentContext)(args.context, {
+    visualize: true,
+    logger: args.logger,
+  });
+}
+
 async function runIntegrationInternal(
   args: RunIntegrationWorkerRequest,
   options: {
@@ -242,7 +260,14 @@ async function runIntegrationInternal(
     sessionName: args.session,
     headless: args.headless,
     storageStatePath,
+    viewport: args.viewport,
   });
+  if (!args.headless && args.visualize !== false) {
+    await installHeadedWorkflowVisualization({
+      context: browserSession.context,
+      logger: integrationLogger,
+    });
+  }
   const actionsLogPath = getSessionActionsLogPath(args.session);
   const networkLogPath = getSessionNetworkLogPath(args.session);
   await installSessionTelemetry({
@@ -258,6 +283,7 @@ async function runIntegrationInternal(
   });
 
   const workflowContext: LibrettoWorkflowContext = {
+    session: args.session,
     logger: integrationLogger,
     page: browserSession.page,
     services: {},
@@ -267,7 +293,8 @@ async function runIntegrationInternal(
     try {
       await workflow.run(workflowContext, args.params ?? {});
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
       await writeFile(
         signalPaths.failedSignalPath,
         JSON.stringify(

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

@@ -6,7 +6,9 @@ export const RunIntegrationWorkerRequestSchema = z.object({
   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(),
 });
 
 export type RunIntegrationWorkerRequest = z.infer<

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

@@ -5,10 +5,7 @@ import {
   type RunIntegrationWorkerRequest,
 } from "./run-integration-worker-protocol.js";
 import { runIntegrationFromFileInWorker } from "./run-integration-runtime.js";
-import {
-  ensureLibrettoSetup,
-  withSessionLogger,
-} from "../core/context.js";
+import { ensureLibrettoSetup, withSessionLogger } from "../core/context.js";
 import { getPauseSignalPaths } from "../core/pause-signals.js";
 
 function parseWorkerRequest(argv: string[]): RunIntegrationWorkerRequest {

package/src/index.ts

@@ -2,119 +2,126 @@ import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // Logger
-export { Logger, defaultLogger, type LoggerApi, type MinimalLogger, type LoggerSink, type LogOptions } from "./shared/logger/logger.js";
 export {
-	createFileLogSink,
-	prettyConsoleSink,
-	jsonlConsoleSink,
+  Logger,
+  defaultLogger,
+  type LoggerApi,
+  type MinimalLogger,
+  type LoggerSink,
+  type LogOptions,
+} from "./shared/logger/logger.js";
+export {
+  createFileLogSink,
+  prettyConsoleSink,
+  jsonlConsoleSink,
 } from "./shared/logger/sinks.js";
 
 // LLM client interface
-export type { LLMClient, Message, MessageContentPart } from "./shared/llm/types.js";
+export type {
+  LLMClient,
+  Message,
+  MessageContentPart,
+} from "./shared/llm/types.js";
 export { createLLMClientFromModel } from "./shared/llm/ai-sdk-adapter.js";
 export {
-	SESSION_STATE_VERSION,
-	SessionStatusSchema,
-	SessionStateFileSchema,
-	parseSessionStateData,
-	parseSessionStateContent,
-	serializeSessionState,
-	type SessionStatus,
-	type SessionState,
-	type SessionStateFile,
+  SESSION_STATE_VERSION,
+  SessionStatusSchema,
+  SessionStateFileSchema,
+  parseSessionStateData,
+  parseSessionStateContent,
+  serializeSessionState,
+  type SessionStatus,
+  type SessionState,
+  type SessionStateFile,
 } from "./shared/state/index.js";
 
 // Recovery
 export { executeRecoveryAgent } from "./runtime/recovery/agent.js";
 export { attemptWithRecovery } from "./runtime/recovery/recovery.js";
 export {
-	detectSubmissionError,
-	type KnownSubmissionError,
-	type DetectedSubmissionError,
+  detectSubmissionError,
+  type KnownSubmissionError,
+  type DetectedSubmissionError,
 } from "./runtime/recovery/errors.js";
 
 // AI extraction
-export { extractFromPage, type ExtractOptions } from "./runtime/extract/extract.js";
+export {
+  extractFromPage,
+  type ExtractOptions,
+} from "./runtime/extract/extract.js";
 
 // Network helpers
 export {
-	pageRequest,
-	type RequestConfig,
-	type PageRequestOptions,
+  pageRequest,
+  type RequestConfig,
+  type PageRequestOptions,
 } from "./runtime/network/network.js";
 
 // Download helpers
 export {
-	downloadViaClick,
-	downloadAndSave,
-	type DownloadResult,
-	type DownloadViaClickOptions,
-	type SaveDownloadOptions,
+  downloadViaClick,
+  downloadAndSave,
+  type DownloadResult,
+  type DownloadViaClickOptions,
+  type SaveDownloadOptions,
 } from "./runtime/download/download.js";
 
 // Debug / Pause
 export { pause } from "./shared/debug/pause.js";
 
-// Config
-export {
-	isDebugMode,
-	isDryRun,
-	shouldPauseBeforeMutation,
-} from "./shared/config/config.js";
-
 // Instrumentation
 export {
-	instrumentPage,
-	installInstrumentation,
-	instrumentContext,
-	type InstrumentationOptions,
-	type InstrumentedPage,
+  instrumentPage,
+  installInstrumentation,
+  instrumentContext,
+  type InstrumentationOptions,
+  type InstrumentedPage,
 } from "./shared/instrumentation/instrument.js";
 
 // Visualization
 export {
-	ensureGhostCursor,
-	moveGhostCursor,
-	ghostClick,
-	hideGhostCursor,
-	type GhostCursorOptions,
+  ensureGhostCursor,
+  moveGhostCursor,
+  ghostClick,
+  hideGhostCursor,
+  type GhostCursorOptions,
 } from "./shared/visualization/ghost-cursor.js";
 export {
-	ensureHighlightLayer,
-	showHighlight,
-	clearHighlights,
-	type HighlightOptions,
+  ensureHighlightLayer,
+  showHighlight,
+  clearHighlights,
+  type HighlightOptions,
 } from "./shared/visualization/highlight.js";
 
 // Run helpers
 export {
-	launchBrowser,
-	type LaunchBrowserArgs,
-	type BrowserSession,
+  launchBrowser,
+  type LaunchBrowserArgs,
+  type BrowserSession,
 } from "./shared/run/api.js";
 
 // Workflow helpers
 export {
-	LibrettoWorkflow,
-	LIBRETTO_WORKFLOW_BRAND,
-	workflow,
-	type LibrettoWorkflowMetadata,
-	type LibrettoWorkflowContext,
-	type LibrettoWorkflowHandler,
+  LibrettoWorkflow,
+  LIBRETTO_WORKFLOW_BRAND,
+  workflow,
+  type LibrettoWorkflowContext,
+  type LibrettoWorkflowHandler,
 } from "./shared/workflow/workflow.js";
 
 const isDirectExecution = (): boolean => {
-	const entryArg = process.argv[1];
-	if (!entryArg) {
-		return false;
-	}
-	return pathToFileURL(resolve(entryArg)).href === import.meta.url;
+  const entryArg = process.argv[1];
+  if (!entryArg) {
+    return false;
+  }
+  return pathToFileURL(resolve(entryArg)).href === import.meta.url;
 };
 
 if (isDirectExecution()) {
-	void import("./cli/index.js").catch((error: unknown) => {
-			const message = error instanceof Error ? error.stack ?? error.message : String(error);
-			process.stderr.write(`${message}\n`);
-			process.exitCode = 1;
-		});
+  void import("./cli/index.js").catch((error: unknown) => {
+    const message =
+      error instanceof Error ? (error.stack ?? error.message) : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+  });
 }

package/src/runtime/download/download.ts

@@ -4,16 +4,16 @@ import type { Page, Download } from "playwright";
 import type { MinimalLogger } from "../../shared/logger/logger.js";
 
 export type DownloadResult = {
-	/** The raw file contents. */
-	buffer: Buffer;
-	/** The filename suggested by the server (Content-Disposition header or URL). */
-	filename: string;
+  /** The raw file contents. */
+  buffer: Buffer;
+  /** The filename suggested by the server (Content-Disposition header or URL). */
+  filename: string;
 };
 
 export type DownloadViaClickOptions = {
-	logger?: MinimalLogger;
-	/** Timeout in milliseconds for waiting on the download event. Defaults to 30 000. */
-	timeout?: number;
+  logger?: MinimalLogger;
+  /** Timeout in milliseconds for waiting on the download event. Defaults to 30 000. */
+  timeout?: number;
 };
 
 /**
@@ -24,55 +24,55 @@ export type DownloadViaClickOptions = {
  * never missed.
  */
 export async function downloadViaClick(
-	page: Page,
-	selector: string,
-	options?: DownloadViaClickOptions,
+  page: Page,
+  selector: string,
+  options?: DownloadViaClickOptions,
 ): Promise<DownloadResult> {
-	const { logger, timeout = 30_000 } = options ?? {};
+  const { logger, timeout = 30_000 } = options ?? {};
 
-	const startTime = Date.now();
+  const startTime = Date.now();
 
-	// 1. Register the download listener BEFORE clicking
-	const downloadPromise = page.waitForEvent("download", { timeout });
+  // 1. Register the download listener BEFORE clicking
+  const downloadPromise = page.waitForEvent("download", { timeout });
 
-	// 2. Click the element that triggers the download
-	await page.locator(selector).click();
+  // 2. Click the element that triggers the download
+  await page.locator(selector).click();
 
-	// 3. Await the download event
-	const download: Download = await downloadPromise;
+  // 3. Await the download event
+  const download: Download = await downloadPromise;
 
-	// 4. Get the suggested filename
-	const filename = download.suggestedFilename();
+  // 4. Get the suggested filename
+  const filename = download.suggestedFilename();
 
-	// 5. Read the downloaded file into a buffer
-	const readStream = await download.createReadStream();
-	if (!readStream) {
-		throw new Error(
-			`Download stream unavailable for "${filename}". The browser may have been closed before the download completed.`,
-		);
-	}
+  // 5. Read the downloaded file into a buffer
+  const readStream = await download.createReadStream();
+  if (!readStream) {
+    throw new Error(
+      `Download stream unavailable for "${filename}". The browser may have been closed before the download completed.`,
+    );
+  }
 
-	const chunks: Buffer[] = [];
-	for await (const chunk of readStream) {
-		chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-	}
-	const buffer = Buffer.concat(chunks);
+  const chunks: Buffer[] = [];
+  for await (const chunk of readStream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const buffer = Buffer.concat(chunks);
 
-	const duration = Date.now() - startTime;
+  const duration = Date.now() - startTime;
 
-	logger?.info("download:click", {
-		selector,
-		filename,
-		size: buffer.length,
-		duration,
-	});
+  logger?.info("download:click", {
+    selector,
+    filename,
+    size: buffer.length,
+    duration,
+  });
 
-	return { buffer, filename };
+  return { buffer, filename };
 }
 
 export type SaveDownloadOptions = DownloadViaClickOptions & {
-	/** Absolute or relative path to save the file to. When omitted the suggested filename is used in the current working directory. */
-	savePath?: string;
+  /** Absolute or relative path to save the file to. When omitted the suggested filename is used in the current working directory. */
+  savePath?: string;
 };
 
 /**
@@ -80,21 +80,25 @@ export type SaveDownloadOptions = DownloadViaClickOptions & {
  * downloaded file to disk.
  */
 export async function downloadAndSave(
-	page: Page,
-	selector: string,
-	options?: SaveDownloadOptions,
+  page: Page,
+  selector: string,
+  options?: SaveDownloadOptions,
 ): Promise<DownloadResult & { savedTo: string }> {
-	const { savePath, ...downloadOpts } = options ?? {};
-	const { buffer, filename } = await downloadViaClick(page, selector, downloadOpts);
-
-	const dest = resolve(savePath ?? filename);
-	await writeFile(dest, buffer);
-
-	options?.logger?.info("download:saved", {
-		filename,
-		savedTo: dest,
-		size: buffer.length,
-	});
-
-	return { buffer, filename, savedTo: dest };
+  const { savePath, ...downloadOpts } = options ?? {};
+  const { buffer, filename } = await downloadViaClick(
+    page,
+    selector,
+    downloadOpts,
+  );
+
+  const dest = resolve(savePath ?? filename);
+  await writeFile(dest, buffer);
+
+  options?.logger?.info("download:saved", {
+    filename,
+    savedTo: dest,
+    size: buffer.length,
+  });
+
+  return { buffer, filename, savedTo: dest };
 }

package/src/runtime/download/index.ts

@@ -1,7 +1,7 @@
 export {
-	downloadViaClick,
-	downloadAndSave,
-	type DownloadResult,
-	type DownloadViaClickOptions,
-	type SaveDownloadOptions,
+  downloadViaClick,
+  downloadAndSave,
+  type DownloadResult,
+  type DownloadViaClickOptions,
+  type SaveDownloadOptions,
 } from "./download.js";

package/src/runtime/extract/extract.ts

@@ -1,16 +1,19 @@
 import type { Page } from "playwright";
 import type z from "zod";
-import { type MinimalLogger, defaultLogger } from "../../shared/logger/logger.js";
+import {
+  type MinimalLogger,
+  defaultLogger,
+} from "../../shared/logger/logger.js";
 import type { LLMClient } from "../../shared/llm/types.js";
 
 export type ExtractOptions<T extends z.ZodType> = {
-	page: Page;
-	instruction: string;
-	schema: T;
-	llmClient: LLMClient;
-	logger?: MinimalLogger;
-	/** Optional CSS selector to scope extraction to a specific element. */
-	selector?: string;
+  page: Page;
+  instruction: string;
+  schema: T;
+  llmClient: LLMClient;
+  logger?: MinimalLogger;
+  /** Optional CSS selector to scope extraction to a specific element. */
+  selector?: string;
 };
 
 /**
@@ -20,48 +23,55 @@ export type ExtractOptions<T extends z.ZodType> = {
  * matching the provided Zod schema.
  */
 export async function extractFromPage<T extends z.ZodType>(
-	options: ExtractOptions<T>,
+  options: ExtractOptions<T>,
 ): Promise<z.infer<T>> {
-	const { page, instruction, schema, selector, logger = defaultLogger, llmClient } = options;
+  const {
+    page,
+    instruction,
+    schema,
+    selector,
+    logger = defaultLogger,
+    llmClient,
+  } = options;
 
-	let screenshot: string;
-	let domContent: string | undefined;
+  let screenshot: string;
+  let domContent: string | undefined;
 
-	if (selector) {
-		const element = page.locator(selector);
-		await element.waitFor({ state: "visible", timeout: 10_000 });
+  if (selector) {
+    const element = page.locator(selector);
+    await element.waitFor({ state: "visible", timeout: 10_000 });
 
-		const screenshotBuffer = await element.screenshot();
-		screenshot = screenshotBuffer.toString("base64");
+    const screenshotBuffer = await element.screenshot();
+    screenshot = screenshotBuffer.toString("base64");
 
-		try {
-			domContent = await element.innerHTML();
-			if (domContent.length > 30000) {
-				domContent = domContent.slice(0, 30000) + "\n... [truncated]";
-			}
-		} catch {
-			domContent = undefined;
-		}
-	} else {
-		const cdpClient = await page.context().newCDPSession(page);
-		await cdpClient.send("Page.enable");
-		const { data } = await cdpClient.send("Page.captureScreenshot", {
-			format: "png",
-		});
-		screenshot = data;
+    try {
+      domContent = await element.innerHTML();
+      if (domContent.length > 30000) {
+        domContent = domContent.slice(0, 30000) + "\n... [truncated]";
+      }
+    } catch {
+      domContent = undefined;
+    }
+  } else {
+    const cdpClient = await page.context().newCDPSession(page);
+    await cdpClient.send("Page.enable");
+    const { data } = await cdpClient.send("Page.captureScreenshot", {
+      format: "png",
+    });
+    screenshot = data;
 
-		try {
-			const htmlContent = await page.content();
-			domContent =
-				htmlContent.length > 50000
-					? htmlContent.slice(0, 50000) + "\n... [truncated]"
-					: htmlContent;
-		} catch {
-			domContent = undefined;
-		}
-	}
+    try {
+      const htmlContent = await page.content();
+      domContent =
+        htmlContent.length > 50000
+          ? htmlContent.slice(0, 50000) + "\n... [truncated]"
+          : htmlContent;
+    } catch {
+      domContent = undefined;
+    }
+  }
 
-	const prompt = `You are analyzing a screenshot${selector ? " of a specific element" : ""} from a web page to extract structured data.
+  const prompt = `You are analyzing a screenshot${selector ? " of a specific element" : ""} from a web page to extract structured data.
 
 Instruction: ${instruction}
 
@@ -69,24 +79,24 @@ ${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({
-		schema,
-		messages: [
-			{
-				role: "user",
-				content: [
-					{ type: "text", text: prompt },
-					{ type: "image", image: `data:image/png;base64,${screenshot}` },
-				],
-			},
-		],
-		temperature: 0,
-	});
+  const result = await llmClient.generateObjectFromMessages({
+    schema,
+    messages: [
+      {
+        role: "user",
+        content: [
+          { type: "text", text: prompt },
+          { type: "image", image: `data:image/png;base64,${screenshot}` },
+        ],
+      },
+    ],
+    temperature: 0,
+  });
 
-	logger.info("extractFromPage completed", {
-		selector,
-		instruction: instruction.slice(0, 100),
-	});
+  logger.info("extractFromPage completed", {
+    selector,
+    instruction: instruction.slice(0, 100),
+  });
 
-	return result;
+  return result;
 }

package/src/runtime/network/index.ts

@@ -1,5 +1,5 @@
 export {
-	pageRequest,
-	type RequestConfig,
-	type PageRequestOptions,
+  pageRequest,
+  type RequestConfig,
+  type PageRequestOptions,
 } from "./network.js";