libretto 0.6.7 → 0.6.9

package/src/cli/core/ai-model.ts

@@ -17,6 +17,7 @@ export const DEFAULT_SNAPSHOT_MODELS = {
   anthropic: "anthropic/claude-sonnet-4-6",
   google: "google/gemini-3-flash-preview",
   vertex: "vertex/gemini-2.5-flash",
+  openrouter: "openrouter/free",
 } as const satisfies Record<Provider, string>;
 
 // ── Source detection ────────────────────────────────────────────────────────
@@ -44,6 +45,8 @@ function detectProviderEnvVar(
       if (env.GOOGLE_CLOUD_PROJECT?.trim()) return "GOOGLE_CLOUD_PROJECT";
       if (env.GCLOUD_PROJECT?.trim()) return "GCLOUD_PROJECT";
       return null;
+    case "openrouter":
+      return env.OPENROUTER_API_KEY?.trim() ? "OPENROUTER_API_KEY" : null;
   }
 }
 
@@ -72,11 +75,13 @@ function providerSetupSentence(provider: Provider): string {
       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.";
+    case "openrouter":
+      return "Add OPENROUTER_API_KEY to .env or as a shell environment variable.";
   }
 }
 
 function defaultModelCommandLine(): string {
-  return "npx libretto ai configure openai | anthropic | gemini | vertex";
+  return "npx libretto ai configure openai | anthropic | gemini | vertex | openrouter";
 }
 
 function providerMissingCredentialSummary(provider: Provider): string {
@@ -89,13 +94,15 @@ function providerMissingCredentialSummary(provider: Provider): string {
       return "GEMINI_API_KEY and GOOGLE_GENERATIVE_AI_API_KEY are missing";
     case "vertex":
       return "GOOGLE_CLOUD_PROJECT and GCLOUD_PROJECT are missing";
+    case "openrouter":
+      return "OPENROUTER_API_KEY is missing";
   }
 }
 
 function noSnapshotApiConfiguredMessage(): string {
   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()}\`.`,
+    `Add OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY, GOOGLE_CLOUD_PROJECT, or OPENROUTER_API_KEY to .env or as a shell environment variable, or choose a default model with \`${defaultModelCommandLine()}\`.`,
     "For more info, run `npx libretto setup`.",
   ].join(" ");
 }
@@ -122,6 +129,7 @@ function inferAutoSnapshotModel(): SnapshotApiModelSelection | null {
     "anthropic",
     "google",
     "vertex",
+    "openrouter",
   ];
 
   for (const provider of providersInPriorityOrder) {

package/src/cli/core/browser-daemon.ts

@@ -0,0 +1,198 @@
+/**
+ * Browser daemon process.
+ *
+ * Launched as a detached child process by `runOpen()` in `browser.ts`.
+ * Receives configuration as a JSON string in `process.argv[2]`.
+ *
+ * Responsibilities:
+ * - Launch Chromium with the specified settings
+ * - Create a browser context and page
+ * - Install session telemetry (network/action logging)
+ * - Navigate to the requested URL
+ * - Stay alive until the browser disconnects or a signal is received
+ */
+
+import { chromium } from "playwright";
+import { mkdir, unlink } from "node:fs/promises";
+import { appendFileSync } from "node:fs";
+import { installSessionTelemetry } from "./session-telemetry.js";
+import {
+  getSessionDir,
+  getSessionLogsPath,
+  getSessionNetworkLogPath,
+  getSessionActionsLogPath,
+  getSessionStatePath,
+} from "./context.js";
+
+// ── Config schema ──────────────────────────────────────────────────────
+
+type DaemonConfig = {
+  port: number;
+  url: string;
+  session: string;
+  headed: boolean;
+  viewport: { width: number; height: number };
+  storageStatePath?: string;
+  windowPosition?: { x: number; y: number };
+};
+
+const config: DaemonConfig = JSON.parse(process.argv[2]);
+
+// ── Derived paths ──────────────────────────────────────────────────────
+
+const sessionDir = getSessionDir(config.session);
+await mkdir(sessionDir, { recursive: true });
+
+const logFile = getSessionLogsPath(config.session);
+const networkLogFile = getSessionNetworkLogPath(config.session);
+const actionsLogFile = getSessionActionsLogPath(config.session);
+
+type TelemetryEntry = Record<string, unknown>;
+
+function childLog(
+  level: string,
+  event: string,
+  data: Record<string, unknown> = {},
+): void {
+  const entry = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    id: Math.random().toString(36).slice(2, 10),
+    level,
+    scope: "libretto.child",
+    event,
+    data,
+  });
+  appendFileSync(logFile, entry + "\n");
+}
+
+function logAction(entry: TelemetryEntry): void {
+  appendFileSync(actionsLogFile, JSON.stringify(entry) + "\n");
+}
+
+function logNetwork(entry: TelemetryEntry): void {
+  appendFileSync(networkLogFile, JSON.stringify(entry) + "\n");
+}
+
+// ── Launch browser ─────────────────────────────────────────────────────
+
+const windowPositionArg = config.windowPosition
+  ? `--window-position=${config.windowPosition.x},${config.windowPosition.y}`
+  : undefined;
+
+const launchArgs = [
+  "--disable-blink-features=AutomationControlled",
+  `--remote-debugging-port=${config.port}`,
+  "--remote-debugging-address=127.0.0.1",
+  "--no-focus-on-check",
+  ...(windowPositionArg ? [windowPositionArg] : []),
+];
+
+const browser = await chromium.launch({
+  headless: !config.headed,
+  args: launchArgs,
+});
+
+async function cleanupSessionState(): Promise<void> {
+  const sessionStatePath = getSessionStatePath(config.session);
+  try {
+    await unlink(sessionStatePath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+}
+
+let shuttingDown = false;
+let wakeDaemon: () => void;
+const sleepPromise = new Promise<void>((resolve) => {
+  wakeDaemon = resolve;
+});
+
+async function shutdown(
+  reason: string,
+  closeBrowser: boolean,
+): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  try {
+    childLog("info", reason, { port: config.port });
+    await cleanupSessionState();
+    if (closeBrowser) await browser.close();
+  } finally {
+    wakeDaemon();
+  }
+}
+
+browser.on("disconnected", () => {
+  void shutdown("browser-disconnected-exiting", false);
+});
+
+// ── Create context & page ──────────────────────────────────────────────
+
+const context = await browser.newContext({
+  ...(config.storageStatePath ? { storageState: config.storageStatePath } : {}),
+  viewport: {
+    width: config.viewport.width,
+    height: config.viewport.height,
+  },
+  userAgent:
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
+});
+
+const page = await context.newPage();
+
+// ── Page defaults & telemetry ──────────────────────────────────────────
+
+page.setDefaultTimeout(30000);
+page.setDefaultNavigationTimeout(45000);
+
+await installSessionTelemetry({
+  context,
+  initialPage: page,
+  includeUserDomActions: true,
+  logAction,
+  logNetwork,
+});
+
+// ── Navigate ───────────────────────────────────────────────────────────
+
+await page.goto(config.url);
+
+// ── Process lifecycle ──────────────────────────────────────────────────
+
+process.on("SIGTERM", () => {
+  void shutdown("child-sigterm", true);
+});
+
+process.on("SIGINT", () => {
+  void shutdown("child-sigint", true);
+});
+
+process.on("uncaughtException", (err) => {
+  childLog("error", "uncaught-exception", {
+    message: err.message,
+    stack: err.stack,
+  });
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  childLog("warn", "unhandled-rejection", { reason: String(reason) });
+});
+
+process.on("exit", (code) => {
+  childLog("info", "child-exit", {
+    code,
+    pid: process.pid,
+    port: config.port,
+  });
+});
+
+childLog("info", "child-launched", {
+  port: config.port,
+  pid: process.pid,
+  session: config.session,
+});
+
+// Keep the daemon alive until the browser disconnects or a signal arrives.
+await sleepPromise;
+process.exit(0);

package/src/cli/core/browser.ts

@@ -5,27 +5,15 @@ import {
   type CDPSession,
   type Page,
 } from "playwright";
-import { openSync, existsSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { openSync, closeSync, existsSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
 import { spawn } from "node:child_process";
 import type { LoggerApi } from "../../shared/logger/index.js";
 import type { SessionAccessMode } from "../../shared/state/index.js";
-import {
-  filterSemanticClasses,
-  INTERACTIVE_ROLE_NAMES,
-  INTERACTIVE_TAG_NAMES,
-  isObfuscatedClass,
-  TEST_ATTRIBUTE_NAMES,
-  TRUSTED_ATTRIBUTE_NAMES,
-} from "../../shared/dom-semantics.js";
-import {
-  getSessionActionsLogPath,
-  getSessionNetworkLogPath,
-  PROFILES_DIR,
-} from "./context.js";
+import { PROFILES_DIR } from "./context.js";
 import { readLibrettoConfig } from "./config.js";
 import {
   assertSessionAvailableForStart,
@@ -39,7 +27,6 @@ import {
 } from "./session.js";
 import type { ProviderApi } from "./providers/types.js";
 import { getCloudProviderApi } from "./providers/index.js";
-import { installSessionTelemetry } from "./session-telemetry.js";
 
 const CLOSE_WAIT_MS = 1_500;
 const FORCE_CLOSE_WAIT_MS = 300;
@@ -434,8 +421,6 @@ export async function runOpen(
 
   const port = await pickFreePort();
   const runLogPath = logFileForSession(session);
-  const networkLogPath = getSessionNetworkLogPath(session);
-  const actionsLogPath = getSessionActionsLogPath(session);
 
   const browserMode = headed ? "headed" : "headless";
   const supportsSavedProfile =
@@ -459,178 +444,33 @@ export async function runOpen(
   }
   console.log(`Launching ${browserMode} browser (session: ${session})...`);
 
-  const escapedUrl = url.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-  const storageStateCode = useProfile
-    ? `storageState: '${profilePath!
-        .replace(/\\/g, "\\\\")
-        .replace(/'/g, "\\'")}',`
-    : "";
-
-  const escapedLogPath = runLogPath.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-  const escapedNetworkLogPath = networkLogPath
-    .replace(/\\/g, "\\\\")
-    .replace(/'/g, "\\'");
-  const escapedActionsLogPath = actionsLogPath
-    .replace(/\\/g, "\\\\")
-    .replace(/'/g, "\\'");
-  const windowPositionArg = windowPosition
-    ? `, '--window-position=${windowPosition.x},${windowPosition.y}'`
-    : "";
-  const windowBoundsSetupCode = windowPosition
-    ? `
-const requestedWindowBounds = { left: ${windowPosition.x}, top: ${windowPosition.y}, windowState: 'normal' };
-const pageCdp = await context.newCDPSession(page);
-let browserCdp;
-try {
-	const targetInfo = await pageCdp.send('Target.getTargetInfo');
-	const targetId = targetInfo?.targetInfo?.targetId;
-	browserCdp = await browser.newBrowserCDPSession();
-	const windowResult = await browserCdp.send(
-		'Browser.getWindowForTarget',
-		targetId ? { targetId } : {},
-	);
-	await browserCdp.send('Browser.setWindowBounds', {
-		windowId: windowResult.windowId,
-		bounds: requestedWindowBounds,
-	});
-	await new Promise((resolve) => setTimeout(resolve, 250));
-	const actualWindow = await browserCdp.send('Browser.getWindowBounds', {
-		windowId: windowResult.windowId,
-	});
-	childLog('info', 'window-bounds-set', {
-		windowId: windowResult.windowId,
-		requestedBounds: requestedWindowBounds,
-		actualBounds: actualWindow.bounds,
-	});
-} catch (error) {
-	childLog('warn', 'window-bounds-set-failed', {
-		requestedBounds: requestedWindowBounds,
-		message: error instanceof Error ? error.message : String(error),
-		stack: error instanceof Error ? error.stack : undefined,
-	});
-} finally {
-	await pageCdp.detach().catch(() => {});
-	if (browserCdp) {
-		await browserCdp.detach().catch(() => {});
-	}
-}
-`
-    : "";
-
-  const launcherCode = `
-import { chromium } from 'playwright';
-import { appendFileSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-
-const LOG_FILE = '${escapedLogPath}';
-const NETWORK_LOG = '${escapedNetworkLogPath}';
-const ACTIONS_LOG = '${escapedActionsLogPath}';
-mkdirSync(dirname(NETWORK_LOG), { recursive: true });
-
-// tsx/esbuild may emit __name() wrappers in Function#toString output.
-	const __name = (target, value) =>
-		Object.defineProperty(target, 'name', { value, configurable: true });
-
-	const TEST_ATTRIBUTE_NAMES = ${JSON.stringify([...TEST_ATTRIBUTE_NAMES])};
-	const TRUSTED_ATTRIBUTE_NAMES = ${JSON.stringify([...TRUSTED_ATTRIBUTE_NAMES])};
-	const INTERACTIVE_TAG_NAMES = ${JSON.stringify([...INTERACTIVE_TAG_NAMES])};
-	const INTERACTIVE_ROLE_NAMES = ${JSON.stringify([...INTERACTIVE_ROLE_NAMES])};
-	const filterSemanticClasses = ${filterSemanticClasses.toString()};
-	const isObfuscatedClass = ${isObfuscatedClass.toString()};
-
-	${installSessionTelemetry.toString()}
-
-	function logAction(entry) {
-		appendFileSync(ACTIONS_LOG, JSON.stringify(entry) + '\\n');
-	}
-
-function logNetwork(entry) {
-	appendFileSync(NETWORK_LOG, JSON.stringify(entry) + '\\n');
-}
-
-function childLog(level, event, data = {}) {
-	try {
-		const entry = JSON.stringify({
-			timestamp: new Date().toISOString(),
-			id: Math.random().toString(36).slice(2, 10),
-			level,
-			scope: 'libretto.child',
-			event,
-			data,
-		});
-		appendFileSync(LOG_FILE, entry + '\\n');
-	} catch {}
-}
-
-const browser = await chromium.launch({
-	headless: ${!headed},
-	args: ['--disable-blink-features=AutomationControlled', '--remote-debugging-port=${port}', '--remote-debugging-address=127.0.0.1', '--no-focus-on-check'${windowPositionArg}],
-});
-
-browser.on('disconnected', () => {
-	childLog('warn', 'browser-disconnected', { port: ${port} });
-});
-
-const context = await browser.newContext({
-	${storageStateCode}
-	viewport: { width: ${viewport.width}, height: ${viewport.height} },
-	userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36',
-});
-
-const page = await context.newPage();
-${windowBoundsSetupCode}
-page.setDefaultTimeout(30000);
-page.setDefaultNavigationTimeout(45000);
-
-await installSessionTelemetry({
-	context,
-	initialPage: page,
-	includeUserDomActions: true,
-	logAction,
-	logNetwork,
-});
-
-
-await page.goto('${escapedUrl}');
-
-process.on('SIGTERM', async () => {
-	childLog('info', 'child-sigterm');
-	await browser.close();
-	process.exit(0);
-});
-
-process.on('SIGINT', async () => {
-	childLog('info', 'child-sigint');
-	await browser.close();
-	process.exit(0);
-});
-
-process.on('uncaughtException', (err) => {
-	childLog('error', 'uncaught-exception', { message: err.message, stack: err.stack });
-	process.exit(1);
-});
-
-process.on('unhandledRejection', (reason) => {
-	childLog('warn', 'unhandled-rejection', { reason: String(reason) });
-});
-
-process.on('exit', (code) => {
-	childLog('info', 'child-exit', { code, pid: process.pid, port: ${port} });
-});
-
-childLog('info', 'child-launched', { port: ${port}, pid: process.pid, session: '${session}' });
-
-await new Promise(() => {});
-`;
+  const daemonEntryPath = fileURLToPath(
+    new URL("./browser-daemon.js", import.meta.url),
+  );
+  const require = createRequire(import.meta.url);
+  const tsxImportPath = pathToFileURL(require.resolve("tsx/esm")).href;
+  const daemonConfig = {
+    port,
+    url,
+    session,
+    headed,
+    viewport,
+    storageStatePath: useProfile ? profilePath : undefined,
+    windowPosition,
+  };
 
   const childStderrFd = openSync(runLogPath, "a");
 
-  const child = spawn("node", ["--input-type=module", "-e", launcherCode], {
-    detached: true,
-    stdio: ["ignore", "ignore", childStderrFd],
-    cwd: resolve(dirname(fileURLToPath(import.meta.url)), "../../.."),
-  });
+  const child = spawn(
+    process.execPath,
+    ["--import", tsxImportPath, daemonEntryPath, JSON.stringify(daemonConfig)],
+    {
+      detached: true,
+      stdio: ["ignore", "ignore", childStderrFd],
+    },
+  );
   child.unref();
+  closeSync(childStderrFd);
 
   logger.info("open-child-spawned", { pid: child.pid, port, session });
 
@@ -750,8 +590,13 @@ export async function runOpenWithProvider(
     provider: providerName,
     sessionId: providerSession.sessionId,
     cdpEndpoint: providerSession.cdpEndpoint,
+    liveViewUrl: providerSession.liveViewUrl,
   });
 
+  if (providerSession.liveViewUrl) {
+    console.log(`View live session: ${providerSession.liveViewUrl}`);
+  }
+
   console.log(`Connecting to ${providerName} browser...`);
 
   let browser: Browser | null = null;
@@ -923,6 +768,7 @@ export async function runClose(
     return;
   }
 
+  let replayUrl: string | undefined;
   if (state.provider) {
     // Cloud provider session — close via provider API, no local pid to kill
     logger.info("close-provider", {
@@ -932,7 +778,8 @@ export async function runClose(
     });
     try {
       const provider = getCloudProviderApi(state.provider.name);
-      await provider.closeSession(state.provider.sessionId);
+      const result = await provider.closeSession(state.provider.sessionId);
+      replayUrl = result.replayUrl;
     } catch (err) {
       logger.warn("close-provider-error", {
         session,
@@ -957,8 +804,11 @@ export async function runClose(
   }
 
   clearSessionState(session, logger);
-  logger.info("close-success", { session });
+  logger.info("close-success", { session, replayUrl });
   console.log(`Browser closed (session: ${session}).`);
+  if (replayUrl) {
+    console.log(`View recording: ${replayUrl}`);
+  }
 }
 
 type ClosableSession = {
@@ -1060,6 +910,7 @@ export async function runCloseAll(
 
   // Close provider sessions via their APIs
   const failedProviderSessions = new Set<string>();
+  const replayUrls: Array<{ session: string; replayUrl: string }> = [];
   for (const target of closable) {
     if (target.provider) {
       logger.info("close-all-provider", {
@@ -1069,7 +920,13 @@ export async function runCloseAll(
       });
       try {
         const provider = getCloudProviderApi(target.provider.name);
-        await provider.closeSession(target.provider.sessionId);
+        const result = await provider.closeSession(target.provider.sessionId);
+        if (result.replayUrl) {
+          replayUrls.push({
+            session: target.session,
+            replayUrl: result.replayUrl,
+          });
+        }
       } catch (err) {
         logger.warn("close-all-provider-error", {
           session: target.session,
@@ -1180,6 +1037,9 @@ export async function runCloseAll(
   if (forceKilled > 0) {
     console.log(`Force-killed ${forceKilled} session(s).`);
   }
+  for (const { session, replayUrl } of replayUrls) {
+    console.log(`View recording (${session}): ${replayUrl}`);
+  }
 }
 
 export async function runConnect(

package/src/cli/core/config.ts

@@ -67,7 +67,7 @@ function invalidConfigError(configPath: string, detail?: string): Error {
       '  - "snapshotModel", "viewport", "windowPosition", and "sessionMode" are optional.',
       '  - "snapshotModel" 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 openai | anthropic | gemini | vertex`,
+      `  npx libretto ai configure openai | anthropic | gemini | vertex | openrouter`,
     ]
       .filter(Boolean)
       .join("\n"),

package/src/cli/core/providers/browserbase.ts

@@ -52,6 +52,7 @@ export function createBrowserbaseProvider(): ProviderApi {
           `Browserbase API error closing session ${sessionId} (${resp.status}): ${body}`,
         );
       }
+      return {};
     },
   };
 }

package/src/cli/core/providers/kernel.ts

@@ -44,6 +44,7 @@ export function createKernelProvider(): ProviderApi {
           `Kernel API error closing session ${sessionId} (${resp.status}): ${body}`,
         );
       }
+      return {};
     },
   };
 }

package/src/cli/core/providers/libretto-cloud.ts

@@ -13,6 +13,8 @@ export function createLibrettoCloudProvider(): ProviderApi {
     );
   const endpoint = apiUrl.replace(/\/$/, "");
 
+  // The Libretto Cloud API is an oRPC RPCHandler, not plain REST, so inputs
+  // must be wrapped as { json: ... } and outputs arrive the same way.
   return {
     async createSession() {
       const timeoutSeconds = Number(
@@ -24,7 +26,9 @@ export function createLibrettoCloudProvider(): ProviderApi {
           "x-api-key": apiKey,
           "Content-Type": "application/json",
         },
-        body: JSON.stringify({ timeout_seconds: timeoutSeconds }),
+        body: JSON.stringify({
+          json: { timeout_seconds: timeoutSeconds },
+        }),
       });
       if (!resp.ok) {
         const body = await resp.text();
@@ -32,13 +36,18 @@ export function createLibrettoCloudProvider(): ProviderApi {
           `Libretto Cloud API error (${resp.status}): ${body}`,
         );
       }
-      const json = (await resp.json()) as {
-        session_id: string;
-        cdp_url: string;
+      const { json } = (await resp.json()) as {
+        json: {
+          session_id: string;
+          cdp_url: string;
+          live_view_url: string | null;
+          recording_url: string | null;
+        };
       };
       return {
         sessionId: json.session_id,
         cdpEndpoint: json.cdp_url,
+        liveViewUrl: json.live_view_url ?? undefined,
       };
     },
     async closeSession(sessionId) {
@@ -48,7 +57,7 @@ export function createLibrettoCloudProvider(): ProviderApi {
           "x-api-key": apiKey,
           "Content-Type": "application/json",
         },
-        body: JSON.stringify({ session_id: sessionId }),
+        body: JSON.stringify({ json: { session_id: sessionId } }),
       });
       if (!resp.ok) {
         const body = await resp.text();
@@ -56,6 +65,10 @@ export function createLibrettoCloudProvider(): ProviderApi {
           `Libretto Cloud API error closing session ${sessionId} (${resp.status}): ${body}`,
         );
       }
+      const { json } = (await resp.json()) as {
+        json: { replay_url: string | null };
+      };
+      return { replayUrl: json.replay_url ?? undefined };
     },
   };
 }

package/src/cli/core/providers/types.ts

@@ -1,9 +1,20 @@
 export type ProviderSession = {
   sessionId: string; // remote session id for cleanup
   cdpEndpoint: string; // CDP WebSocket URL
+  // Provider-hosted URL for watching the session live while it's running.
+  // Only libretto-cloud surfaces this today; direct-SDK providers leave it
+  // undefined.
+  liveViewUrl?: string;
+};
+
+export type ProviderCloseResult = {
+  // Provider-hosted URL for playback of the session recording, surfaced on
+  // successful close. Undefined when the provider didn't capture a
+  // recording or doesn't return one on close.
+  replayUrl?: string;
 };
 
 export type ProviderApi = {
   createSession(): Promise<ProviderSession>;
-  closeSession(sessionId: string): Promise<void>;
+  closeSession(sessionId: string): Promise<ProviderCloseResult>;
 };