@ulpi/browse 0.7.4 → 0.10.0

package/src/cookie-import.ts

@@ -0,0 +1,410 @@
+/**
+ * Chromium browser cookie import — read and decrypt cookies from real browsers.
+ *
+ * Supports macOS Chromium-based browsers: Chrome, Arc, Brave, Edge.
+ * Pure logic module — no Playwright dependency, no HTTP concerns.
+ *
+ * Decryption pipeline (Chromium macOS "v10" format):
+ *
+ *   1. Keychain: `security find-generic-password -s "<svc>" -w`
+ *      → base64 password string
+ *
+ *   2. Key derivation:
+ *      PBKDF2(password, salt="saltysalt", iter=1003, len=16, sha1)
+ *      → 16-byte AES key
+ *
+ *   3. For each cookie with encrypted_value starting with "v10":
+ *      - Ciphertext = encrypted_value[3:]
+ *      - IV = 16 bytes of 0x20 (space character)
+ *      - Plaintext = AES-128-CBC-decrypt(key, iv, ciphertext)
+ *      - Remove PKCS7 padding
+ *      - Skip first 32 bytes (HMAC-SHA256 authentication tag)
+ *      - Remaining bytes = cookie value (UTF-8)
+ *
+ *   4. If encrypted_value is empty but `value` field is set,
+ *      use value directly (unencrypted cookie)
+ *
+ *   5. Chromium epoch: microseconds since 1601-01-01
+ *      Unix seconds = (epoch - 11644473600000000) / 1000000
+ *
+ *   6. sameSite: 0→"None", 1→"Lax", 2→"Strict", else→"Lax"
+ */
+
+import { Database } from 'bun:sqlite';
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export interface BrowserInfo {
+  name: string;
+  dataDir: string;        // relative to ~/Library/Application Support/
+  keychainService: string;
+  aliases: string[];
+}
+
+export interface DomainEntry {
+  domain: string;
+  count: number;
+}
+
+export interface ImportResult {
+  cookies: PlaywrightCookie[];
+  count: number;
+  failed: number;
+  domainCounts: Record<string, number>;
+}
+
+export interface PlaywrightCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires: number;
+  secure: boolean;
+  httpOnly: boolean;
+  sameSite: 'Strict' | 'Lax' | 'None';
+}
+
+export class CookieImportError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public action?: 'retry',
+  ) {
+    super(message);
+    this.name = 'CookieImportError';
+  }
+}
+
+// ─── Browser Registry ───────────────────────────────────────────
+// Hardcoded — NEVER interpolate user input into shell commands.
+
+const BROWSER_REGISTRY: BrowserInfo[] = [
+  { name: 'Chrome', dataDir: 'Google/Chrome/',                keychainService: 'Chrome Safe Storage',         aliases: ['chrome', 'google-chrome'] },
+  { name: 'Arc',    dataDir: 'Arc/User Data/',                keychainService: 'Arc Safe Storage',            aliases: ['arc'] },
+  { name: 'Brave',  dataDir: 'BraveSoftware/Brave-Browser/',  keychainService: 'Brave Safe Storage',          aliases: ['brave'] },
+  { name: 'Edge',   dataDir: 'Microsoft Edge/',               keychainService: 'Microsoft Edge Safe Storage', aliases: ['edge'] },
+];
+
+// ─── Key Cache ──────────────────────────────────────────────────
+// Cache derived AES keys per browser service. First import per browser
+// does Keychain + PBKDF2. Subsequent imports reuse the cached key.
+
+const keyCache = new Map<string, Buffer>();
+
+// ─── Public API ─────────────────────────────────────────────────
+
+/**
+ * Find which Chromium browsers are installed (have a cookie DB on disk).
+ */
+export function findInstalledBrowsers(): BrowserInfo[] {
+  const appSupport = path.join(os.homedir(), 'Library', 'Application Support');
+  return BROWSER_REGISTRY.filter(b => {
+    const dbPath = path.join(appSupport, b.dataDir, 'Default', 'Cookies');
+    try { return fs.existsSync(dbPath); } catch { return false; }
+  });
+}
+
+/**
+ * List unique cookie domains + counts from a browser's DB. No decryption needed.
+ */
+export function listDomains(browserName: string, profile = 'Default'): { domains: DomainEntry[]; browser: string } {
+  const browser = resolveBrowser(browserName);
+  const dbPath = getCookieDbPath(browser, profile);
+  const db = openDb(dbPath, browser.name);
+  try {
+    const now = chromiumNow();
+    const rows = db.query(
+      `SELECT host_key AS domain, COUNT(*) AS count
+       FROM cookies
+       WHERE has_expires = 0 OR expires_utc > ?
+       GROUP BY host_key
+       ORDER BY count DESC`
+    ).all(now) as DomainEntry[];
+    return { domains: rows, browser: browser.name };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Decrypt and return Playwright-compatible cookies for specified domains.
+ */
+export async function importCookies(
+  browserName: string,
+  domains: string[],
+  profile = 'Default',
+): Promise<ImportResult> {
+  if (domains.length === 0) return { cookies: [], count: 0, failed: 0, domainCounts: {} };
+
+  const browser = resolveBrowser(browserName);
+  const derivedKey = await getDerivedKey(browser);
+  const dbPath = getCookieDbPath(browser, profile);
+  const db = openDb(dbPath, browser.name);
+
+  try {
+    const now = chromiumNow();
+    const placeholders = domains.map(() => '?').join(',');
+    const rows = db.query(
+      `SELECT host_key, name, value, encrypted_value, path, expires_utc,
+              is_secure, is_httponly, has_expires, samesite
+       FROM cookies
+       WHERE host_key IN (${placeholders})
+         AND (has_expires = 0 OR expires_utc > ?)
+       ORDER BY host_key, name`
+    ).all(...domains, now) as RawCookie[];
+
+    const cookies: PlaywrightCookie[] = [];
+    let failed = 0;
+    const domainCounts: Record<string, number> = {};
+
+    for (const row of rows) {
+      try {
+        const value = decryptCookieValue(row, derivedKey);
+        const cookie = toPlaywrightCookie(row, value);
+        cookies.push(cookie);
+        domainCounts[row.host_key] = (domainCounts[row.host_key] || 0) + 1;
+      } catch {
+        failed++;
+      }
+    }
+
+    return { cookies, count: cookies.length, failed, domainCounts };
+  } finally {
+    db.close();
+  }
+}
+
+// ─── Internal: Browser Resolution ───────────────────────────────
+
+function resolveBrowser(nameOrAlias: string): BrowserInfo {
+  const needle = nameOrAlias.toLowerCase().trim();
+  const found = BROWSER_REGISTRY.find(b =>
+    b.aliases.includes(needle) || b.name.toLowerCase() === needle
+  );
+  if (!found) {
+    const supported = BROWSER_REGISTRY.flatMap(b => b.aliases).join(', ');
+    throw new CookieImportError(
+      `Unknown browser '${nameOrAlias}'. Supported: ${supported}`,
+      'unknown_browser',
+    );
+  }
+  return found;
+}
+
+function validateProfile(profile: string): void {
+  if (/[/\\]|\.\./.test(profile) || /[\x00-\x1f]/.test(profile)) {
+    throw new CookieImportError(
+      `Invalid profile name: '${profile}'`,
+      'bad_request',
+    );
+  }
+}
+
+function getCookieDbPath(browser: BrowserInfo, profile: string): string {
+  validateProfile(profile);
+  const appSupport = path.join(os.homedir(), 'Library', 'Application Support');
+  const dbPath = path.join(appSupport, browser.dataDir, profile, 'Cookies');
+  if (!fs.existsSync(dbPath)) {
+    throw new CookieImportError(
+      `${browser.name} is not installed (no cookie database at ${dbPath})`,
+      'not_installed',
+    );
+  }
+  return dbPath;
+}
+
+// ─── Internal: SQLite Access ────────────────────────────────────
+
+function openDb(dbPath: string, browserName: string): Database {
+  try {
+    return new Database(dbPath, { readonly: true });
+  } catch (err: any) {
+    if (err.message?.includes('SQLITE_BUSY') || err.message?.includes('database is locked')) {
+      return openDbFromCopy(dbPath, browserName);
+    }
+    if (err.message?.includes('SQLITE_CORRUPT') || err.message?.includes('malformed')) {
+      throw new CookieImportError(
+        'Cookie database is corrupt',
+        'db_corrupt',
+      );
+    }
+    throw err;
+  }
+}
+
+function openDbFromCopy(dbPath: string, browserName: string): Database {
+  const tmpPath = `/tmp/browse-cookies-${browserName.toLowerCase()}-${crypto.randomUUID()}.db`;
+  try {
+    fs.copyFileSync(dbPath, tmpPath);
+    // Copy WAL and SHM if they exist (for consistent reads)
+    const walPath = dbPath + '-wal';
+    const shmPath = dbPath + '-shm';
+    if (fs.existsSync(walPath)) fs.copyFileSync(walPath, tmpPath + '-wal');
+    if (fs.existsSync(shmPath)) fs.copyFileSync(shmPath, tmpPath + '-shm');
+
+    const db = new Database(tmpPath, { readonly: true });
+    // Wrap close() to clean up temp files
+    const origClose = db.close.bind(db);
+    db.close = () => {
+      origClose();
+      try { fs.unlinkSync(tmpPath); } catch {}
+      try { fs.unlinkSync(tmpPath + '-wal'); } catch {}
+      try { fs.unlinkSync(tmpPath + '-shm'); } catch {}
+    };
+    return db;
+  } catch {
+    try { fs.unlinkSync(tmpPath); } catch {}
+    throw new CookieImportError(
+      `Cookie database is locked (${browserName} may be running). Try closing ${browserName} first.`,
+      'db_locked',
+      'retry',
+    );
+  }
+}
+
+// ─── Internal: Keychain Access ──────────────────────────────────
+
+async function getDerivedKey(browser: BrowserInfo): Promise<Buffer> {
+  const cached = keyCache.get(browser.keychainService);
+  if (cached) return cached;
+
+  const password = await getKeychainPassword(browser.keychainService);
+  const derived = crypto.pbkdf2Sync(password, 'saltysalt', 1003, 16, 'sha1');
+  keyCache.set(browser.keychainService, derived);
+  return derived;
+}
+
+async function getKeychainPassword(service: string): Promise<string> {
+  // Array args — no shell injection possible.
+  // macOS may show an Allow/Deny dialog that blocks until the user responds.
+  const proc = Bun.spawn(
+    ['security', 'find-generic-password', '-s', service, '-w'],
+    { stdout: 'pipe', stderr: 'pipe' },
+  );
+
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => {
+      proc.kill();
+      reject(new CookieImportError(
+        `macOS is waiting for Keychain permission. Look for a dialog asking to allow access to "${service}".`,
+        'keychain_timeout',
+        'retry',
+      ));
+    }, 10_000),
+  );
+
+  try {
+    const exitCode = await Promise.race([proc.exited, timeout]);
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (exitCode !== 0) {
+      const errText = stderr.trim().toLowerCase();
+      if (errText.includes('user canceled') || errText.includes('denied') || errText.includes('interaction not allowed')) {
+        throw new CookieImportError(
+          `Keychain access denied. Click Allow in the macOS dialog for "${service}".`,
+          'keychain_denied',
+          'retry',
+        );
+      }
+      if (errText.includes('could not be found') || errText.includes('not found')) {
+        throw new CookieImportError(
+          `No Keychain entry for "${service}".`,
+          'keychain_not_found',
+        );
+      }
+      throw new CookieImportError(
+        `Could not read Keychain: ${stderr.trim()}`,
+        'keychain_error',
+        'retry',
+      );
+    }
+
+    return stdout.trim();
+  } catch (err) {
+    if (err instanceof CookieImportError) throw err;
+    throw new CookieImportError(
+      `Could not read Keychain: ${(err as Error).message}`,
+      'keychain_error',
+      'retry',
+    );
+  }
+}
+
+// ─── Internal: Cookie Decryption ────────────────────────────────
+
+interface RawCookie {
+  host_key: string;
+  name: string;
+  value: string;
+  encrypted_value: Buffer | Uint8Array;
+  path: string;
+  expires_utc: number | bigint;
+  is_secure: number;
+  is_httponly: number;
+  has_expires: number;
+  samesite: number;
+}
+
+function decryptCookieValue(row: RawCookie, key: Buffer): string {
+  // Prefer unencrypted value if present
+  if (row.value && row.value.length > 0) return row.value;
+
+  const ev = Buffer.from(row.encrypted_value);
+  if (ev.length === 0) return '';
+
+  const prefix = ev.slice(0, 3).toString('utf-8');
+  if (prefix !== 'v10') {
+    throw new Error(`Unknown encryption prefix: ${prefix}`);
+  }
+
+  const ciphertext = ev.slice(3);
+  const iv = Buffer.alloc(16, 0x20); // 16 space characters
+  const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+
+  // First 32 bytes are HMAC-SHA256 authentication tag; actual value follows
+  if (plaintext.length <= 32) return '';
+  return plaintext.slice(32).toString('utf-8');
+}
+
+function toPlaywrightCookie(row: RawCookie, value: string): PlaywrightCookie {
+  return {
+    name: row.name,
+    value,
+    domain: row.host_key,
+    path: row.path || '/',
+    expires: chromiumEpochToUnix(row.expires_utc, row.has_expires),
+    secure: row.is_secure === 1,
+    httpOnly: row.is_httponly === 1,
+    sameSite: mapSameSite(row.samesite),
+  };
+}
+
+// ─── Internal: Chromium Epoch Conversion ────────────────────────
+
+const CHROMIUM_EPOCH_OFFSET = 11644473600000000n;
+
+function chromiumNow(): bigint {
+  return BigInt(Date.now()) * 1000n + CHROMIUM_EPOCH_OFFSET;
+}
+
+function chromiumEpochToUnix(epoch: number | bigint, hasExpires: number): number {
+  if (hasExpires === 0 || epoch === 0 || epoch === 0n) return -1;
+  const epochBig = BigInt(epoch);
+  const unixMicro = epochBig - CHROMIUM_EPOCH_OFFSET;
+  return Number(unixMicro / 1000000n);
+}
+
+function mapSameSite(value: number): 'Strict' | 'Lax' | 'None' {
+  switch (value) {
+    case 0: return 'None';
+    case 1: return 'Lax';
+    case 2: return 'Strict';
+    default: return 'Lax';
+  }
+}

package/src/encryption.ts

@@ -0,0 +1,48 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function resolveEncryptionKey(localDir: string): Buffer {
+  const envKey = process.env.BROWSE_ENCRYPTION_KEY;
+  if (envKey) {
+    if (envKey.length !== 64) {
+      throw new Error('BROWSE_ENCRYPTION_KEY must be 64 hex characters (32 bytes)');
+    }
+    return Buffer.from(envKey, 'hex');
+  }
+
+  const keyPath = path.join(localDir, '.encryption-key');
+  if (fs.existsSync(keyPath)) {
+    const hex = fs.readFileSync(keyPath, 'utf-8').trim();
+    return Buffer.from(hex, 'hex');
+  }
+
+  const key = crypto.randomBytes(32);
+  fs.writeFileSync(keyPath, key.toString('hex') + '\n', { mode: 0o600 });
+  return key;
+}
+
+export function encrypt(plaintext: string, key: Buffer): { ciphertext: string; iv: string; authTag: string } {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+  return {
+    ciphertext: encrypted.toString('base64'),
+    iv: iv.toString('base64'),
+    authTag: cipher.getAuthTag().toString('base64'),
+  };
+}
+
+export function decrypt(ciphertext: string, iv: string, authTag: string, key: Buffer): string {
+  const decipher = crypto.createDecipheriv(
+    'aes-256-gcm',
+    key,
+    Buffer.from(iv, 'base64'),
+  );
+  decipher.setAuthTag(Buffer.from(authTag, 'base64'));
+  const decrypted = Buffer.concat([
+    decipher.update(Buffer.from(ciphertext, 'base64')),
+    decipher.final(),
+  ]);
+  return decrypted.toString('utf-8');
+}

package/src/record-export.ts

@@ -0,0 +1,98 @@
+/**
+ * Record export — converts recorded browse commands into replayable formats.
+ * - browse: chain-compatible JSON (replay with `browse chain`)
+ * - replay: Chrome DevTools Recorder format (replay with `npx @puppeteer/replay` or Playwright)
+ */
+
+export interface RecordedStep {
+  command: string;
+  args: string[];
+  timestamp: number;
+}
+
+// ─── Helpers ──────────────────────────────────────────
+
+function escapeJS(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n').replace(/\r/g, '\\r');
+}
+
+function parseViewport(sizeArg: string): { width: number; height: number } | null {
+  const match = sizeArg.match(/^(\d+)x(\d+)$/i);
+  if (!match) return null;
+  return { width: parseInt(match[1], 10), height: parseInt(match[2], 10) };
+}
+
+// ─── Browse JSON (chain-compatible) ──────────────────
+
+export function exportBrowse(steps: RecordedStep[]): string {
+  const commands = steps.map(step => [step.command, ...step.args]);
+  return JSON.stringify(commands);
+}
+
+// ─── Chrome DevTools Recorder (replay format) ────────
+
+function replayStep(step: RecordedStep): object | null {
+  const { command, args } = step;
+  const selector = args[0] || '';
+
+  switch (command) {
+    case 'goto':
+      return { type: 'navigate', url: args[0] || '', assertedEvents: [{ type: 'navigation', url: args[0] || '', title: '' }] };
+    case 'click':
+      return { type: 'click', selectors: [[selector]], offsetX: 1, offsetY: 1 };
+    case 'dblclick':
+      return { type: 'doubleClick', selectors: [[selector]], offsetX: 1, offsetY: 1 };
+    case 'fill':
+      return { type: 'change', selectors: [[selector]], value: args.slice(1).join(' ') };
+    case 'type':
+      return null; // handled as individual key events in exportReplay
+    case 'press':
+      return { type: 'keyDown', key: args[0] || '' };
+    case 'select':
+      return { type: 'change', selectors: [[selector]], value: args.slice(1).join(' ') };
+    case 'scroll':
+      if (args[0] === 'down') return { type: 'scroll', x: 0, y: 500 };
+      if (args[0] === 'up') return { type: 'scroll', x: 0, y: -500 };
+      return { type: 'scroll', selectors: [[selector]], x: 0, y: 200 };
+    case 'hover':
+      return { type: 'hover', selectors: [[selector]] };
+    case 'viewport': {
+      const vp = parseViewport(args[0] || '');
+      if (!vp) return null;
+      return { type: 'setViewport', width: vp.width, height: vp.height, deviceScaleFactor: 1, isMobile: false, hasTouch: false, isLandscape: false };
+    }
+    case 'wait':
+      if (args[0] === '--network-idle') return { type: 'waitForExpression', expression: 'new Promise(r => setTimeout(r, 2000))' };
+      if (args[0] === '--url') return { type: 'waitForExpression', expression: `location.href.includes('${escapeJS(args[1] || '')}')` };
+      return { type: 'waitForElement', selectors: [[selector]] };
+    case 'back':
+      return { type: 'waitForExpression', expression: '(window.history.back(), true)' };
+    case 'forward':
+      return { type: 'waitForExpression', expression: '(window.history.forward(), true)' };
+    default:
+      return null;
+  }
+}
+
+export function exportReplay(steps: RecordedStep[]): string {
+  const replaySteps: object[] = [
+    { type: 'setViewport', width: 1920, height: 1080, deviceScaleFactor: 1, isMobile: false, hasTouch: false, isLandscape: false },
+  ];
+
+  for (const step of steps) {
+    if (step.command === 'type') {
+      const text = step.args.join(' ');
+      for (const char of text) {
+        replaySteps.push({ type: 'keyDown', key: char });
+        replaySteps.push({ type: 'keyUp', key: char });
+      }
+      continue;
+    }
+    const converted = replayStep(step);
+    if (converted) {
+      replaySteps.push(converted);
+    }
+  }
+
+  return JSON.stringify({ title: 'browse recording', steps: replaySteps }, null, 2);
+}

package/src/server.ts

@@ -11,7 +11,7 @@
 
 import type { Browser } from 'playwright';
 import { getRuntime, type BrowserRuntime } from './runtime';
-import { SessionManager, type Session } from './session-manager';
+import { SessionManager, type Session, type RecordedStep } from './session-manager';
 import { handleReadCommand } from './commands/read';
 import { handleWriteCommand } from './commands/write';
 import { handleMetaCommand } from './commands/meta';
@@ -111,6 +111,7 @@ const READ_COMMANDS = new Set([
   'js', 'eval', 'css', 'attrs', 'element-state', 'dialog',
   'console', 'network', 'cookies', 'storage', 'perf', 'devices',
   'value', 'count', 'clipboard',
+  'box', 'errors',
 ]);
 
 const WRITE_COMMANDS = new Set([
@@ -121,6 +122,8 @@ const WRITE_COMMANDS = new Set([
   'upload', 'dialog-accept', 'dialog-dismiss', 'emulate',
   'drag', 'keydown', 'keyup',
   'highlight', 'download', 'route', 'offline',
+  'rightclick', 'tap', 'swipe', 'mouse', 'keyboard',
+  'scrollinto', 'scrollintoview', 'set',
 ]);
 
 const META_COMMANDS = new Set([
@@ -131,7 +134,14 @@ const META_COMMANDS = new Set([
   'url', 'snapshot', 'snapshot-diff', 'screenshot-diff',
   'sessions', 'session-close',
   'frame', 'state', 'find',
-  'auth', 'har', 'video', 'inspect',
+  'auth', 'har', 'video', 'inspect', 'record', 'cookie-import',
+  'doctor', 'upgrade',
+]);
+
+// Commands excluded from recording — meta/diagnostic commands that don't represent user actions
+const RECORDING_SKIP = new Set([
+  'record', 'status', 'stop', 'restart', 'sessions', 'session-close',
+  'console', 'network', 'snapshot-diff', 'screenshot-diff', 'cookie-import',
 ]);
 
 // Probe if a port is free using net.createServer (not Bun.serve which fatally crashes on EADDRINUSE)
@@ -175,6 +185,7 @@ const BOUNDARY_NONCE = crypto.randomUUID();
 interface RequestOptions {
   jsonMode: boolean;
   contentBoundaries: boolean;
+  maxOutput: number;
 }
 
 /**
@@ -282,6 +293,16 @@ async function handleCommand(body: any, session: Session, opts: RequestOptions):
       });
     }
 
+    // Record step if recording is active
+    if (session.recording && !RECORDING_SKIP.has(command)) {
+      session.recording.push({ command, args, timestamp: Date.now() });
+    }
+
+    // Apply max-output truncation
+    if (opts.maxOutput > 0 && result.length > opts.maxOutput) {
+      result = result.slice(0, opts.maxOutput) + `\n... (truncated at ${opts.maxOutput} chars)`;
+    }
+
     // Apply content boundaries for page-content commands
     if (opts.contentBoundaries && PAGE_CONTENT_COMMANDS.has(command)) {
       const origin = session.manager.getCurrentUrl();
@@ -450,9 +471,29 @@ async function start() {
         const sessionId = req.headers.get('x-browse-session') || 'default';
         const allowedDomains = req.headers.get('x-browse-allowed-domains') || undefined;
         const session = await sessionManager.getOrCreate(sessionId, allowedDomains);
+
+        // Load state file (cookies) if requested via --state flag
+        const stateFilePath = req.headers.get('x-browse-state');
+        if (stateFilePath) {
+          const context = session.manager.getContext();
+          if (context) {
+            try {
+              const stateData = JSON.parse(fs.readFileSync(stateFilePath, 'utf-8'));
+              if (stateData.cookies?.length) {
+                await context.addCookies(stateData.cookies);
+              }
+            } catch (err: any) {
+              return new Response(JSON.stringify({ error: `Failed to load state file: ${err.message}` }), {
+                status: 400, headers: { 'Content-Type': 'application/json' },
+              });
+            }
+          }
+        }
+
         const opts: RequestOptions = {
           jsonMode: req.headers.get('x-browse-json') === '1',
           contentBoundaries: req.headers.get('x-browse-boundaries') === '1',
+          maxOutput: parseInt(req.headers.get('x-browse-max-output') || '0', 10) || 0,
         };
         return handleCommand(body, session, opts);
       }