@yeaft/webchat-agent 1.0.413 → 1.0.414

package/browser-runtime/browser-install.js

@@ -0,0 +1,497 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import {
+  access,
+  chmod,
+  mkdir,
+  mkdtemp,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+
+import { constants } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { runProcess } from '../yeaft/tools/process-runner.js';
+import { readWindowsBrowserExecutableVersion } from './windows-version.js';
+
+// Chrome 151 is the first pinned Chrome for Testing build in this project that
+// exposes the Extensions CDP domain required for safe action activation.
+export const BROWSER_RUNTIME_CHROME_BUILD = '151.0.7922.71';
+const MANIFEST_FILE = '.yeaft-browser-manifest.json';
+const INSTALL_LOCK_WAIT_MS = 120_000;
+const INSTALL_LOCK_STALE_MS = 30 * 60_000;
+const INSTALL_RETRY_MS = 100;
+
+export const BROWSER_RUNTIME_CHROME_ARCHIVES = Object.freeze({
+  linux: Object.freeze({
+    fileName: 'chrome-linux64.zip',
+    sha256: '6bd04aab53fba1544ce6027d9daddb24137295033124a61ecdf9840d785792e9',
+  }),
+  mac: Object.freeze({
+    fileName: 'chrome-mac-x64.zip',
+    sha256: 'bedcd79ae533fed218c26232b74e73cffec2a7277fce42cafcf5ec7280e4f81c',
+  }),
+  mac_arm: Object.freeze({
+    fileName: 'chrome-mac-arm64.zip',
+    sha256: '1c516b5d6c00a074034d5ce03dc1cc9bd2cde2a09293d9613244e0bc153cb80f',
+  }),
+  win32: Object.freeze({
+    fileName: 'chrome-win32.zip',
+    sha256: '338f15dcf19d457f93f692c279843477a92324f0f91f78bf5380d3fe00a9796f',
+  }),
+  win64: Object.freeze({
+    fileName: 'chrome-win64.zip',
+    sha256: '7ea2e94833ef710026c8cb08d0d2dafcb13f5d304d9c475ac07a3fa8c11d846c',
+  }),
+});
+
+export function defaultBrowserCacheDir(yeaftDir) {
+  if (!yeaftDir) throw new Error('yeaftDir required');
+  return join(yeaftDir, 'managed-browser');
+}
+
+export async function isExecutable(path) {
+  if (!path) return false;
+  try {
+    const details = await stat(path);
+    if (!details.isFile()) return false;
+    await access(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function hashFile(path) {
+  const handle = await open(path, 'r');
+  try {
+    const hash = createHash('sha256');
+    for await (const chunk of handle.createReadStream()) hash.update(chunk);
+    return hash.digest('hex');
+  } finally {
+    await handle.close().catch(() => {});
+  }
+}
+
+function archiveForPlatform(platform, archives = BROWSER_RUNTIME_CHROME_ARCHIVES) {
+  const archive = archives[platform];
+  if (!archive) throw new Error(`Managed Chrome is unsupported on platform ${platform}`);
+  const folder = {
+    linux: 'linux64',
+    mac: 'mac-x64',
+    mac_arm: 'mac-arm64',
+    win32: 'win32',
+    win64: 'win64',
+  }[platform];
+  return {
+    ...archive,
+    platform,
+    url: `https://storage.googleapis.com/chrome-for-testing-public/${BROWSER_RUNTIME_CHROME_BUILD}/${folder}/${archive.fileName}`,
+  };
+}
+
+async function readManifest(cacheDir) {
+  try {
+    const parsed = JSON.parse(await readFile(join(cacheDir, MANIFEST_FILE), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeManifest(cacheDir, manifest) {
+  const target = join(cacheDir, MANIFEST_FILE);
+  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    await rename(temporary, target);
+  } finally {
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}
+
+async function inspectManagedBrowser(cacheDir, dependencies = {}) {
+  const browsers = dependencies.browsers || await import('@puppeteer/browsers');
+  const platform = dependencies.platform || browsers.detectBrowserPlatform();
+  if (!platform) return { valid: false, reason: 'platform_unsupported' };
+  const archive = archiveForPlatform(platform, dependencies.archives);
+  let executablePath = dependencies.executablePath || null;
+  if (!executablePath) {
+    const installed = await browsers.getInstalledBrowsers({ cacheDir });
+    const browser = installed.find(candidate => (
+      candidate.browser === browsers.Browser.CHROME
+        && candidate.buildId === BROWSER_RUNTIME_CHROME_BUILD
+        && candidate.platform === platform
+    ));
+    executablePath = browser?.executablePath || null;
+  }
+  if (!await isExecutable(executablePath)) {
+    return { valid: false, reason: 'executable_missing', executablePath, platform, archive };
+  }
+  const manifest = await readManifest(cacheDir);
+  if (!manifest
+    || manifest.buildId !== BROWSER_RUNTIME_CHROME_BUILD
+    || manifest.platform !== platform
+    || manifest.archiveSha256 !== archive.sha256
+    || manifest.executablePath !== executablePath
+    || typeof manifest.executableSha256 !== 'string') {
+    return { valid: false, reason: 'manifest_missing', executablePath, platform, archive };
+  }
+  const executableSha256 = await hashFile(executablePath);
+  if (executableSha256 !== manifest.executableSha256) {
+    return { valid: false, reason: 'executable_digest_mismatch', executablePath, platform, archive };
+  }
+  return { valid: true, executablePath, platform, archive, executableSha256 };
+}
+
+/** Resolve only a verified exact managed Chrome for Testing build. */
+export async function findManagedBrowser(cacheDir, dependencies = {}) {
+  const inspected = await inspectManagedBrowser(cacheDir, dependencies);
+  return inspected.valid ? inspected.executablePath : null;
+}
+
+/** Explicit executables are version-fenced by the probe before extension launch. */
+export async function resolveBrowserExecutable({ executablePath, cacheDir }) {
+  if (executablePath) return await isExecutable(executablePath) ? executablePath : null;
+  return findManagedBrowser(cacheDir);
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+async function readInstallLockOwner(lockDir) {
+  const details = await stat(lockDir);
+  if (!details.isDirectory()) throw new Error('Managed Chrome install lock is not a directory');
+  try {
+    return { owner: JSON.parse(await readFile(join(lockDir, 'owner.json'), 'utf8')), details };
+  } catch {
+    return { owner: null, details };
+  }
+}
+
+async function removeOrphanedInstallStaging(cacheDir) {
+  const prefix = `.chrome-${BROWSER_RUNTIME_CHROME_BUILD}-staging-`;
+  const entries = await readdir(cacheDir, { withFileTypes: true });
+  await Promise.all(entries
+    .filter(entry => entry.isDirectory() && entry.name.startsWith(prefix))
+    .map(async entry => {
+      const path = join(cacheDir, entry.name);
+      try {
+        const owner = JSON.parse(await readFile(join(path, 'owner.json'), 'utf8'));
+        if (owner?.host !== hostname() || processIsAlive(Number(owner.pid))) return;
+        await rm(path, { recursive: true, force: true });
+      } catch {}
+    }));
+}
+
+async function installLockCanBeTaken(lockDir, staleMs) {
+  const { owner, details } = await readInstallLockOwner(lockDir);
+  if (owner?.host === hostname()) return !processIsAlive(Number(owner.pid));
+  if (owner) return false;
+  return Date.now() - details.mtimeMs > staleMs;
+}
+
+async function installLockIsOwned(lockDir, token) {
+  try {
+    const owner = JSON.parse(await readFile(join(lockDir, 'owner.json'), 'utf8'));
+    return owner?.token === token;
+  } catch {
+    return false;
+  }
+}
+
+async function releaseInstallLock(lockDir, token) {
+  if (!await installLockIsOwned(lockDir, token)) return false;
+  const claimed = `${lockDir}.release-${token}`;
+  try {
+    await rename(lockDir, claimed);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (!await installLockIsOwned(claimed, token)) {
+    await rename(claimed, lockDir).catch(() => {});
+    return false;
+  }
+  await rm(claimed, { recursive: true, force: true });
+  return true;
+}
+
+function installLockOwnerIdentity(owner) {
+  if (!owner) return null;
+  if (typeof owner.token === 'string' && owner.token) return `token:${owner.token}`;
+  return `legacy:${owner.host || ''}:${Number(owner.pid) || 0}:${Number(owner.startedAt) || 0}`;
+}
+
+async function takeInstallLock(lockDir, staleMs) {
+  const observed = (await readInstallLockOwner(lockDir)).owner;
+  if (!await installLockCanBeTaken(lockDir, staleMs)) return false;
+  const observedIdentity = installLockOwnerIdentity(observed);
+  const claimed = `${lockDir}.stale-${randomUUID()}`;
+  try {
+    await rename(lockDir, claimed);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return true;
+    return false;
+  }
+  const claimedOwner = (await readInstallLockOwner(claimed)).owner;
+  const ownerChanged = installLockOwnerIdentity(claimedOwner) !== observedIdentity;
+  const ownerRevived = claimedOwner?.host === hostname()
+    && processIsAlive(Number(claimedOwner.pid));
+  if (ownerChanged || ownerRevived) {
+    await rename(claimed, lockDir).catch(() => {});
+    return false;
+  }
+  await rm(claimed, { recursive: true, force: true });
+  return true;
+}
+
+async function acquireInstallLock(cacheDir, {
+  waitMs = INSTALL_LOCK_WAIT_MS,
+  staleMs = INSTALL_LOCK_STALE_MS,
+  ready = null,
+} = {}) {
+  await mkdir(cacheDir, { recursive: true, mode: 0o700 });
+  const lockDir = join(cacheDir, `.chrome-${BROWSER_RUNTIME_CHROME_BUILD}.lock`);
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    if (typeof ready === 'function' && await ready()) return null;
+    const token = randomUUID();
+    try {
+      await mkdir(lockDir, { mode: 0o700 });
+      await writeFile(join(lockDir, 'owner.json'), JSON.stringify({
+        pid: process.pid,
+        host: hostname(),
+        token,
+        startedAt: Date.now(),
+      }), { flag: 'wx', mode: 0o600 });
+      return {
+        token,
+        release: () => releaseInstallLock(lockDir, token),
+      };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      try {
+        if (await takeInstallLock(lockDir, staleMs)) continue;
+      } catch (inspectionError) {
+        if (inspectionError?.code === 'ENOENT') continue;
+        throw inspectionError;
+      }
+      if (Date.now() >= deadline) throw new Error('Managed Chrome install is busy');
+      await delay(Math.min(INSTALL_RETRY_MS, Math.max(1, deadline - Date.now())));
+    }
+  }
+}
+
+async function downloadVerifiedArchive(asset, destination, { fetchFn, onProgress, signal }) {
+  const requestOptions = {
+    redirect: 'follow',
+    signal,
+    headers: { 'User-Agent': 'yeaft-agent-browser-runtime' },
+  };
+  let response = await fetchFn(asset.url, requestOptions);
+  if (!response.ok) throw new Error(`Managed Chrome download returned HTTP ${response.status}`);
+  if (response.body && typeof response.body[Symbol.asyncIterator] !== 'function') {
+    if (!response.url || response.url === asset.url) {
+      throw new Error('Managed Chrome downloader returned an unreadable response body');
+    }
+    const resolved = await fetchFn(response.url, requestOptions);
+    if (!resolved.ok) throw new Error(`Managed Chrome download returned HTTP ${resolved.status}`);
+    response = resolved;
+  }
+  const handle = await open(destination, 'wx', 0o600);
+  const hash = createHash('sha256');
+  let downloaded = 0;
+  const total = Number(response.headers?.get?.('content-length')) || 0;
+  try {
+    for await (const raw of response.body || []) {
+      const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+      downloaded += chunk.length;
+      hash.update(chunk);
+      await handle.write(chunk);
+      onProgress?.(downloaded, total);
+    }
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  const actual = hash.digest('hex');
+  if (actual !== asset.sha256) throw new Error(`Managed Chrome archive checksum mismatch for ${asset.fileName}`);
+  return actual;
+}
+
+export async function readBrowserExecutableVersion(executablePath, {
+  versionCheck = null,
+  signal = null,
+  gracefulTerminationDeadline = null,
+  terminationDeadline = null,
+  processOptions = null,
+  windowsVersionReader = readWindowsBrowserExecutableVersion,
+} = {}) {
+  if (typeof versionCheck === 'function') return versionCheck(executablePath, { signal });
+  const startedAt = Date.now();
+  const resolvedGracefulDeadline = Number.isFinite(gracefulTerminationDeadline)
+    ? gracefulTerminationDeadline
+    : startedAt + 5_000;
+  const resolvedTerminationDeadline = Number.isFinite(terminationDeadline)
+    ? terminationDeadline
+    : resolvedGracefulDeadline + 500;
+  const platform = processOptions?.platform || process.platform;
+  if (platform === 'win32') {
+    return windowsVersionReader(executablePath, {
+      signal,
+      terminationDeadline: resolvedTerminationDeadline,
+      ...(processOptions?.windowsVersionOptions || {}),
+    });
+  }
+  const result = await runProcess(executablePath, ['--version'], {
+    signal,
+    timeoutMs: Math.max(1, resolvedGracefulDeadline - Date.now()),
+    maxBytes: 64 * 1024,
+    killGraceMs: 100,
+    gracefulTerminationDeadline: resolvedGracefulDeadline,
+    terminationDeadline: resolvedTerminationDeadline,
+    forceSettleMs: 500,
+    treeKillTimeoutMs: 500,
+    requireExitConfirmation: true,
+    requireProcessGroupExit: true,
+    ...(processOptions || {}),
+    platform,
+  });
+  if (result.code !== 0) {
+    const termination = result.terminationError ? ` ${result.terminationError}` : '';
+    throw new Error(`Managed Chrome version check failed (${result.code}): ${result.stderr.slice(0, 200)}${termination}`);
+  }
+  return result.stdout.trim();
+}
+
+async function executableVersion(executablePath, dependencies = {}) {
+  return readBrowserExecutableVersion(executablePath, dependencies);
+}
+
+function installedDirectory(cacheDir, platform) {
+  return join(cacheDir, 'chrome', `${platform}-${BROWSER_RUNTIME_CHROME_BUILD}`);
+}
+
+export async function installManagedBrowser({
+  cacheDir,
+  onProgress,
+  fetchFn = globalThis.fetch,
+  signal = null,
+  dependencies = {},
+} = {}) {
+  if (!cacheDir) throw new Error('cacheDir required');
+  if (typeof fetchFn !== 'function') throw new Error('fetch is unavailable');
+  const lock = await acquireInstallLock(cacheDir, {
+    ...dependencies,
+    ready: async () => (await inspectManagedBrowser(cacheDir, dependencies)).valid,
+  });
+  if (!lock) {
+    const existing = await inspectManagedBrowser(cacheDir, dependencies);
+    if (!existing.valid) throw new Error('Managed Chrome install completed without a verified browser');
+    return {
+      buildId: BROWSER_RUNTIME_CHROME_BUILD,
+      executablePath: existing.executablePath,
+      executableSha256: existing.executableSha256,
+      cacheDir,
+      status: 'available',
+    };
+  }
+  let stagingRoot = null;
+  try {
+    if (lock) await removeOrphanedInstallStaging(cacheDir);
+    const existing = await inspectManagedBrowser(cacheDir, dependencies);
+    if (existing.valid) {
+      return {
+        buildId: BROWSER_RUNTIME_CHROME_BUILD,
+        executablePath: existing.executablePath,
+        executableSha256: existing.executableSha256,
+        cacheDir,
+        status: 'available',
+      };
+    }
+
+    const browsers = dependencies.browsers || await import('@puppeteer/browsers');
+    const platform = dependencies.platform || browsers.detectBrowserPlatform();
+    if (!platform) throw new Error('Cannot detect a supported Browser Runtime platform');
+    const asset = archiveForPlatform(platform, dependencies.archives);
+    const finalDir = installedDirectory(cacheDir, platform);
+
+    stagingRoot = await mkdtemp(join(
+      cacheDir,
+      `.chrome-${BROWSER_RUNTIME_CHROME_BUILD}-staging-${lock.token}-`,
+    ));
+    if (process.platform !== 'win32') await chmod(stagingRoot, 0o700);
+    await writeFile(join(stagingRoot, 'owner.json'), JSON.stringify({
+      pid: process.pid,
+      host: hostname(),
+      token: lock.token,
+      startedAt: Date.now(),
+    }), { flag: 'wx', mode: 0o600 });
+    const archivePath = join(stagingRoot, asset.fileName);
+    await downloadVerifiedArchive(asset, archivePath, { fetchFn, onProgress, signal });
+
+    const stagingCache = join(stagingRoot, 'cache');
+    await mkdir(join(stagingCache, 'chrome'), { recursive: true });
+    await rename(
+      archivePath,
+      join(stagingCache, 'chrome', `${BROWSER_RUNTIME_CHROME_BUILD}-${basename(asset.fileName)}`),
+    );
+    const installBrowser = dependencies.install || browsers.install;
+    const installed = await installBrowser({
+      browser: browsers.Browser.CHROME,
+      buildId: BROWSER_RUNTIME_CHROME_BUILD,
+      platform,
+      cacheDir: stagingCache,
+      installDeps: false,
+    });
+    if (!await isExecutable(installed.executablePath)) throw new Error('Managed Chrome executable missing after extraction');
+    const version = await executableVersion(installed.executablePath, dependencies);
+    if (!version.includes(BROWSER_RUNTIME_CHROME_BUILD)) {
+      throw new Error(`Managed Chrome build mismatch: expected ${BROWSER_RUNTIME_CHROME_BUILD}, got ${version}`);
+    }
+    const executableSha256 = await hashFile(installed.executablePath);
+    await mkdir(dirname(finalDir), { recursive: true });
+    await rm(finalDir, { recursive: true, force: true });
+    await rename(installedDirectory(stagingCache, platform), finalDir);
+    const executablePath = installed.executablePath.replace(
+      installedDirectory(stagingCache, platform),
+      finalDir,
+    );
+    await writeManifest(cacheDir, {
+      version: 1,
+      buildId: BROWSER_RUNTIME_CHROME_BUILD,
+      platform,
+      archiveFileName: asset.fileName,
+      archiveSha256: asset.sha256,
+      executablePath,
+      executableSha256,
+    });
+    return {
+      buildId: BROWSER_RUNTIME_CHROME_BUILD,
+      executablePath,
+      executableSha256,
+      cacheDir,
+      status: 'installed',
+    };
+  } finally {
+    if (stagingRoot) await rm(stagingRoot, { recursive: true, force: true }).catch(() => {});
+    await lock.release();
+  }
+}

package/browser-runtime/cli.js

@@ -0,0 +1,88 @@
+import {
+  resolveManagedYeaftDir,
+  resolveServiceInstanceId,
+  warnDeprecatedInstanceArg,
+} from '../service/config.js';
+
+/**
+ * Execute an Agent-instance-scoped Browser Runtime management command.
+ * Dependencies are injectable so tests never import the executable Agent CLI.
+ */
+export async function handleBrowserCommand(args, dependencies = {}) {
+  const action = args[0];
+  const options = {};
+  const identityArgs = [];
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--headful') {
+      options.headless = false;
+      continue;
+    }
+    if (arg === '--executable' || arg === '--name' || arg === '--instance' || arg === '--yeaft-dir') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      if (arg === '--executable') options.executablePath = value;
+      else identityArgs.push(arg, value);
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unexpected browser argument: ${arg}`);
+  }
+
+  const env = dependencies.env || process.env;
+  const warn = dependencies.warn || console.warn;
+  warnDeprecatedInstanceArg(identityArgs, warn);
+  const instanceId = resolveServiceInstanceId(identityArgs, env, { management: true });
+  const resolveManagementRoot = dependencies.resolveManagedYeaftDir || resolveManagedYeaftDir;
+  const yeaftDir = resolveManagementRoot(identityArgs, env, instanceId, {
+    loadServiceConfig: dependencies.loadServiceConfig,
+    getDefaultYeaftDir: dependencies.getDefaultYeaftDir,
+  });
+  const browser = dependencies.browserModule || await import('./index.js');
+  const configApi = dependencies.configApi || await import('../yeaft/config-api.js');
+  const current = configApi.getBrowserRuntimeSettings(yeaftDir);
+  if (current.error) throw new Error(current.error);
+  const cacheDir = current.cacheDir || browser.defaultBrowserCacheDir(yeaftDir);
+  const log = dependencies.log || console.log;
+
+  if (action === 'install') {
+    const result = await browser.installManagedBrowser({ cacheDir });
+    log(JSON.stringify({ ok: true, ...result }, null, 2));
+    return;
+  }
+  if (action === 'probe') {
+    const result = await browser.probeBrowserRuntime({
+      executablePath: options.executablePath || current.executablePath,
+      cacheDir,
+      headless: options.headless ?? current.headless,
+      timeoutMs: current.startupProbeTimeoutMs,
+      profileParent: `${cacheDir}-profiles`,
+    });
+    log(JSON.stringify(result, null, 2));
+    if (!result.ok) {
+      if (dependencies.onProbeFailure) dependencies.onProbeFailure(result);
+      else process.exitCode = 1;
+    }
+    return;
+  }
+  if (action === 'enable' || action === 'disable') {
+    const result = configApi.updateBrowserRuntimeSettings({ enabled: action === 'enable' }, yeaftDir);
+    if (result.error) throw new Error(result.error);
+    log(JSON.stringify(result, null, 2));
+    log('Restart the selected Agent instance to run the startup probe. Phase 0 does not advertise Browser capability.');
+    return;
+  }
+  if (action === 'status') {
+    const executablePath = await browser.findManagedBrowser(cacheDir);
+    log(JSON.stringify({
+      instanceId,
+      yeaftDir,
+      config: current,
+      managedBuildId: browser.BROWSER_RUNTIME_CHROME_BUILD,
+      managedExecutablePath: executablePath,
+      installed: !!executablePath,
+    }, null, 2));
+    return;
+  }
+  throw new Error('Usage: yeaft-agent browser install|probe|enable|disable|status [--name <id>] [--yeaft-dir <path>] [--executable <path>] [--headful]');
+}

package/browser-runtime/config.js

@@ -0,0 +1,116 @@
+const MIB = 1024 * 1024;
+
+export const BROWSER_RUNTIME_DEFAULTS = Object.freeze({
+  enabled: false,
+  executablePath: null,
+  cacheDir: null,
+  headless: true,
+  maxSessions: 2,
+  maxPeersPerSession: 2,
+  maxWidth: 1920,
+  maxHeight: 1080,
+  maxFps: 30,
+  maxBitrate: 4_000_000,
+  maxQueuedActionsPerSession: 128,
+  maxQueuedActionsPerProducer: 32,
+  maxActionQueueBytes: MIB,
+  maxActionRuntimeMs: 30_000,
+  producerCreditBurst: 16,
+  producerCreditRefillPerSecond: 8,
+  noViewerIdleMs: 120_000,
+  interactiveIdleMs: 2_100_000,
+  maxDownloadsBytes: 512 * MIB,
+  startupProbeTimeoutMs: 20_000,
+});
+
+const INTEGER_LIMITS = Object.freeze({
+  maxSessions: [1, 4],
+  maxPeersPerSession: [1, 4],
+  maxWidth: [320, 3840],
+  maxHeight: [240, 2160],
+  maxFps: [1, 60],
+  maxBitrate: [100_000, 8_000_000],
+  maxQueuedActionsPerSession: [1, 256],
+  maxQueuedActionsPerProducer: [1, 64],
+  maxActionQueueBytes: [64 * 1024, 4 * MIB],
+  maxActionRuntimeMs: [1_000, 120_000],
+  producerCreditBurst: [1, 64],
+  producerCreditRefillPerSecond: [1, 64],
+  noViewerIdleMs: [10_000, 30 * 60_000],
+  interactiveIdleMs: [60_000, 8 * 60 * 60_000],
+  maxDownloadsBytes: [0, 2 * 1024 * MIB],
+  startupProbeTimeoutMs: [5_000, 60_000],
+});
+
+export const BROWSER_RUNTIME_SETTING_KEYS = Object.freeze([
+  'enabled',
+  'executablePath',
+  'cacheDir',
+  'headless',
+  ...Object.keys(INTEGER_LIMITS),
+]);
+
+function normalizeOptionalPath(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function clampInteger(value, fallback, [minimum, maximum]) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(maximum, Math.max(minimum, Math.floor(number)));
+}
+
+/**
+ * Normalize the Agent-owned Browser Runtime configuration. Unknown keys are
+ * dropped and every resource knob is clamped to a hard ceiling. The feature is
+ * disabled unless the persisted value is the literal boolean `true`.
+ *
+ * @param {unknown} raw
+ * @returns {typeof BROWSER_RUNTIME_DEFAULTS}
+ */
+export function normaliseBrowserRuntimeSection(raw) {
+  const source = raw && typeof raw === 'object' && !Array.isArray(raw)
+    ? /** @type {Record<string, unknown>} */ (raw)
+    : {};
+  const result = {
+    ...BROWSER_RUNTIME_DEFAULTS,
+    enabled: source.enabled === true,
+    executablePath: normalizeOptionalPath(source.executablePath),
+    cacheDir: normalizeOptionalPath(source.cacheDir),
+    headless: source.headless !== false,
+  };
+  for (const [key, limits] of Object.entries(INTEGER_LIMITS)) {
+    result[key] = clampInteger(source[key], BROWSER_RUNTIME_DEFAULTS[key], limits);
+  }
+  return result;
+}
+
+/**
+ * Validate a partial write without silently turning a typo into a different
+ * resource policy. Reads clamp hand-edited values; public writes reject them.
+ *
+ * @param {unknown} update
+ * @returns {string|null}
+ */
+export function validateBrowserRuntimeUpdate(update) {
+  if (!update || typeof update !== 'object' || Array.isArray(update)) return 'update payload required';
+  const value = /** @type {Record<string, unknown>} */ (update);
+  const unknown = Object.keys(value).find(key => !BROWSER_RUNTIME_SETTING_KEYS.includes(key));
+  if (unknown) return `unknown browser runtime setting: ${unknown}`;
+  for (const key of ['enabled', 'headless']) {
+    if (key in value && typeof value[key] !== 'boolean') return `${key} must be a boolean`;
+  }
+  for (const key of ['executablePath', 'cacheDir']) {
+    if (key in value && value[key] !== null && typeof value[key] !== 'string') {
+      return `${key} must be a string or null`;
+    }
+  }
+  for (const [key, [minimum, maximum]] of Object.entries(INTEGER_LIMITS)) {
+    if (!(key in value)) continue;
+    const number = Number(value[key]);
+    if (!Number.isInteger(number) || number < minimum || number > maximum) {
+      return `${key} must be an integer between ${minimum} and ${maximum}`;
+    }
+  }
+  return null;
+}