@flrande/browserctl 0.5.0 → 0.6.0

package/apps/browserd/src/container.ts

@@ -1,3088 +0,0 @@
-import {
-  DriverRegistry,
-  SessionStore,
-  createNavigationMemoryStore,
-  type BrowserDriver,
-  type BrowserDriverScreenshot,
-  type NavigationMemoryMode,
-  type NavigationSignal
-} from "../../../packages/core/src";
-import {
-  createChromeRelayDriver,
-  createChromeRelayExtensionRuntime
-} from "../../../packages/driver-chrome-relay/src";
-import {
-  createManagedDriver,
-  createManagedLocalDriver,
-  type ManagedLocalBrowserName,
-  type ManagedLocalTelemetryDriverExtensions
-} from "../../../packages/driver-managed/src";
-import { createRemoteCdpDriver } from "../../../packages/driver-remote-cdp/src";
-import { ErrorCode, createErr, createOk, type ToolResponse } from "../../../packages/protocol/src";
-import {
-  buildToolMap,
-  createMcpStdioServer,
-  type McpStdioServer,
-  type ToolCallArgs,
-  type ToolMap
-} from "../../../packages/transport-mcp-stdio/src";
-import { posix as posixPath, win32 as windowsPath } from "node:path";
-import { createChromeRelayExtensionBridge } from "./chrome-relay-extension-bridge";
-
-type CapabilityScope = "read" | "act" | "upload" | "download";
-type ChromeRelayMode = "cdp" | "extension";
-type DomainAllowlistMode = "off" | "enforce";
-
-export type BrowserdConfig = {
-  chromeRelayUrl: string;
-  chromeRelayMode: ChromeRelayMode;
-  chromeRelayExtensionToken?: string;
-  chromeRelayExtensionRequestTimeoutMs: number;
-  remoteCdpUrl: string;
-  defaultDriver: string;
-  managedLocalEnabled: boolean;
-  uploadRoot?: string;
-  downloadRoot?: string;
-  authToken?: string;
-  authScopes: CapabilityScope[];
-  sessionTtlMs: number;
-  sessionCleanupIntervalMs: number;
-  domainAllowlistMode: DomainAllowlistMode;
-  domainAllowlist: string[];
-  sessionMaxTotal: number;
-  sessionMaxPerTenant: number;
-  sessionRequireTenantPrefix: boolean;
-  tenantAllowlist: string[];
-  memoryEnabled: boolean;
-  memoryMode: NavigationMemoryMode;
-  memoryTtlDays: number;
-  memoryPath: string;
-  managedLocalLaunch: {
-    browserName: ManagedLocalBrowserName;
-    headless: boolean;
-    channel?: string;
-    executablePath?: string;
-    launchTimeoutMs?: number;
-    args: string[];
-  };
-};
-
-const DEFAULT_DRIVER_KEY = "managed";
-const MANAGED_LOCAL_DRIVER_KEY = "managed-local";
-const DEFAULT_CONFIG_DRIVER_KEY = "chrome-relay";
-const DEFAULT_MANAGED_LOCAL_BROWSER_NAME: ManagedLocalBrowserName = "chromium";
-const DEFAULT_MANAGED_LOCAL_HEADLESS = true;
-const DEFAULT_CHROME_RELAY_MODE: ChromeRelayMode = "extension";
-const DEFAULT_CHROME_RELAY_EXTENSION_TOKEN = "browserctl-relay";
-const DEFAULT_CHROME_RELAY_EXTENSION_REQUEST_TIMEOUT_MS = 5_000;
-const DEFAULT_NETWORK_WAIT_TIMEOUT_MS = 10_000;
-const DEFAULT_NETWORK_WAIT_POLL_MS = 200;
-const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1_000;
-const DEFAULT_SESSION_CLEANUP_INTERVAL_MS = 60 * 1_000;
-const DEFAULT_DOMAIN_ALLOWLIST_MODE: DomainAllowlistMode = "off";
-const DEFAULT_SESSION_MAX_TOTAL = 200;
-const DEFAULT_SESSION_MAX_PER_TENANT = 50;
-const DEFAULT_MEMORY_MODE: NavigationMemoryMode = "ask";
-const DEFAULT_MEMORY_TTL_DAYS = 30;
-const DEFAULT_MEMORY_PATH = ".browserctl-runtime/navigation-memory.json";
-const ALL_CAPABILITY_SCOPES: readonly CapabilityScope[] = ["read", "act", "upload", "download"];
-const TOOL_SCOPE_BY_NAME: Readonly<Record<string, CapabilityScope>> = {
-  "browser.status": "read",
-  "browser.profile.list": "read",
-  "browser.profile.use": "act",
-  "browser.tab.list": "read",
-  "browser.tab.open": "act",
-  "browser.tab.focus": "act",
-  "browser.tab.close": "act",
-  "browser.snapshot": "read",
-  "browser.screenshot": "read",
-  "browser.dom.query": "read",
-  "browser.dom.queryAll": "read",
-  "browser.element.screenshot": "read",
-  "browser.a11y.snapshot": "read",
-  "browser.wait.element": "read",
-  "browser.wait.text": "read",
-  "browser.wait.url": "read",
-  "browser.network.list": "read",
-  "browser.network.harExport": "read",
-  "browser.act": "act",
-  "browser.upload.arm": "upload",
-  "browser.dialog.arm": "act",
-  "browser.download.wait": "download",
-  "browser.download.trigger": "download",
-  "browser.network.waitFor": "read",
-  "browser.cookie.get": "read",
-  "browser.cookie.set": "act",
-  "browser.cookie.clear": "act",
-  "browser.storage.get": "read",
-  "browser.storage.set": "act",
-  "browser.frame.list": "read",
-  "browser.frame.snapshot": "read",
-  "browser.console.list": "read",
-  "browser.network.responseBody": "read",
-  "browser.memory.status": "read",
-  "browser.memory.resolve": "read",
-  "browser.memory.upsert": "act",
-  "browser.memory.list": "read",
-  "browser.memory.inspect": "read",
-  "browser.memory.delete": "act",
-  "browser.memory.purge": "act",
-  "browser.memory.mode.set": "act",
-  "browser.memory.ttl.set": "act",
-  "browser.trace.get": "read",
-  "browser.session.list": "read",
-  "browser.session.drop": "act"
-};
-
-function resolveNonEmptyString(value: string | undefined): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-
-  const trimmedValue = value.trim();
-  return trimmedValue.length === 0 ? undefined : trimmedValue;
-}
-
-function parseBooleanFlag(value: string | undefined, fallback: boolean): boolean {
-  if (value === undefined) {
-    return fallback;
-  }
-
-  const normalizedValue = value.trim().toLowerCase();
-  if (normalizedValue === "1" || normalizedValue === "true" || normalizedValue === "yes" || normalizedValue === "on") {
-    return true;
-  }
-
-  if (normalizedValue === "0" || normalizedValue === "false" || normalizedValue === "no" || normalizedValue === "off") {
-    return false;
-  }
-
-  return fallback;
-}
-
-function parseOptionalNumber(value: string | undefined): number | undefined {
-  const parsedValue = resolveNonEmptyString(value);
-  if (parsedValue === undefined) {
-    return undefined;
-  }
-
-  const parsedNumber = Number(parsedValue);
-  if (!Number.isFinite(parsedNumber) || parsedNumber < 0) {
-    return undefined;
-  }
-
-  return parsedNumber;
-}
-
-function parseOptionalPositiveInteger(value: string | undefined): number | undefined {
-  const parsedNumber = parseOptionalNumber(value);
-  if (parsedNumber === undefined || parsedNumber <= 0) {
-    return undefined;
-  }
-
-  return Math.trunc(parsedNumber);
-}
-
-function parseCsv(value: string | undefined): string[] {
-  const rawValue = resolveNonEmptyString(value);
-  if (rawValue === undefined) {
-    return [];
-  }
-
-  return rawValue
-    .split(",")
-    .map((item) => item.trim())
-    .filter((item) => item.length > 0);
-}
-
-function isCapabilityScope(value: string): value is CapabilityScope {
-  return (
-    value === "read" ||
-    value === "act" ||
-    value === "upload" ||
-    value === "download"
-  );
-}
-
-function parseCapabilityScopes(value: string | undefined): CapabilityScope[] {
-  const parsed = parseCsv(value).map((item) => item.toLowerCase());
-  if (parsed.length === 0) {
-    return [...ALL_CAPABILITY_SCOPES];
-  }
-
-  const scopes: CapabilityScope[] = [];
-  for (const item of parsed) {
-    if (!isCapabilityScope(item) || scopes.includes(item)) {
-      continue;
-    }
-
-    scopes.push(item);
-  }
-
-  return scopes;
-}
-
-function parseManagedLocalBrowserName(value: string | undefined): ManagedLocalBrowserName {
-  const normalizedValue = value?.trim().toLowerCase();
-  if (normalizedValue === "firefox" || normalizedValue === "webkit" || normalizedValue === "chromium") {
-    return normalizedValue;
-  }
-
-  return DEFAULT_MANAGED_LOCAL_BROWSER_NAME;
-}
-
-function parseChromeRelayMode(value: string | undefined): ChromeRelayMode {
-  const normalizedValue = value?.trim().toLowerCase();
-  if (normalizedValue === "extension" || normalizedValue === "cdp") {
-    return normalizedValue;
-  }
-
-  return DEFAULT_CHROME_RELAY_MODE;
-}
-
-function parseDomainAllowlistMode(value: string | undefined): DomainAllowlistMode {
-  const normalizedValue = value?.trim().toLowerCase();
-  if (normalizedValue === "off" || normalizedValue === "enforce") {
-    return normalizedValue;
-  }
-
-  return DEFAULT_DOMAIN_ALLOWLIST_MODE;
-}
-
-function parseNavigationMemoryMode(value: string | undefined): NavigationMemoryMode {
-  const normalizedValue = value?.trim().toLowerCase();
-  if (normalizedValue === "off" || normalizedValue === "ask" || normalizedValue === "auto") {
-    return normalizedValue;
-  }
-
-  return DEFAULT_MEMORY_MODE;
-}
-
-export type BrowserdContainer = {
-  config: BrowserdConfig;
-  drivers: Map<string, BrowserDriver>;
-  driverRegistry: DriverRegistry;
-  sessions: SessionStore;
-  mcpServer: McpStdioServer;
-  close(): void;
-};
-
-export function loadBrowserdConfig(
-  env: Record<string, string | undefined> = process.env
-): BrowserdConfig {
-  const managedLocalEnabled = parseBooleanFlag(env.BROWSERD_MANAGED_LOCAL_ENABLED, true);
-  const chromeRelayMode = parseChromeRelayMode(env.BROWSERD_CHROME_RELAY_MODE);
-  const chromeRelayExtensionToken =
-    resolveNonEmptyString(env.BROWSERD_CHROME_RELAY_EXTENSION_TOKEN) ??
-    (chromeRelayMode === "extension" ? DEFAULT_CHROME_RELAY_EXTENSION_TOKEN : undefined);
-
-  const defaultDriver =
-    resolveNonEmptyString(env.BROWSERD_DEFAULT_DRIVER) ?? DEFAULT_CONFIG_DRIVER_KEY;
-  const domainAllowlistMode = parseDomainAllowlistMode(env.BROWSERD_DOMAIN_ALLOWLIST_MODE);
-  const memoryEnabled = parseBooleanFlag(env.BROWSERD_MEMORY_ENABLED, true);
-  const memoryMode = parseNavigationMemoryMode(env.BROWSERD_MEMORY_MODE);
-
-  return {
-    chromeRelayUrl: env.BROWSERD_CHROME_RELAY_URL ?? "http://127.0.0.1:9223",
-    chromeRelayMode,
-    chromeRelayExtensionToken,
-    chromeRelayExtensionRequestTimeoutMs:
-      parseOptionalNumber(env.BROWSERD_CHROME_RELAY_EXTENSION_REQUEST_TIMEOUT_MS) ??
-      DEFAULT_CHROME_RELAY_EXTENSION_REQUEST_TIMEOUT_MS,
-    remoteCdpUrl:
-      env.BROWSERD_REMOTE_CDP_URL ?? "http://127.0.0.1:9222/devtools/browser/default",
-    defaultDriver,
-    managedLocalEnabled,
-    uploadRoot: resolveNonEmptyString(env.BROWSERD_UPLOAD_ROOT),
-    downloadRoot: resolveNonEmptyString(env.BROWSERD_DOWNLOAD_ROOT),
-    authToken: resolveNonEmptyString(env.BROWSERD_AUTH_TOKEN),
-    authScopes: parseCapabilityScopes(env.BROWSERD_AUTH_SCOPES),
-    sessionTtlMs: parseOptionalNumber(env.BROWSERD_SESSION_TTL_MS) ?? DEFAULT_SESSION_TTL_MS,
-    sessionCleanupIntervalMs:
-      parseOptionalNumber(env.BROWSERD_SESSION_CLEANUP_INTERVAL_MS) ??
-      DEFAULT_SESSION_CLEANUP_INTERVAL_MS,
-    domainAllowlistMode,
-    domainAllowlist: parseCsv(env.BROWSERD_DOMAIN_ALLOWLIST).map((entry) => entry.toLowerCase()),
-    sessionMaxTotal:
-      parseOptionalPositiveInteger(env.BROWSERD_SESSION_MAX_TOTAL) ?? DEFAULT_SESSION_MAX_TOTAL,
-    sessionMaxPerTenant:
-      parseOptionalPositiveInteger(env.BROWSERD_SESSION_MAX_PER_TENANT) ?? DEFAULT_SESSION_MAX_PER_TENANT,
-    sessionRequireTenantPrefix: parseBooleanFlag(env.BROWSERD_SESSION_REQUIRE_TENANT_PREFIX, false),
-    tenantAllowlist: parseCsv(env.BROWSERD_TENANT_ALLOWLIST).map((entry) => entry.toLowerCase()),
-    memoryEnabled,
-    memoryMode,
-    memoryTtlDays: parseOptionalNumber(env.BROWSERD_MEMORY_TTL_DAYS) ?? DEFAULT_MEMORY_TTL_DAYS,
-    memoryPath: resolveNonEmptyString(env.BROWSERD_MEMORY_PATH) ?? DEFAULT_MEMORY_PATH,
-    managedLocalLaunch: {
-      browserName: parseManagedLocalBrowserName(env.BROWSERD_MANAGED_LOCAL_BROWSER),
-      headless: parseBooleanFlag(env.BROWSERD_MANAGED_LOCAL_HEADLESS, DEFAULT_MANAGED_LOCAL_HEADLESS),
-      channel: resolveNonEmptyString(env.BROWSERD_MANAGED_LOCAL_CHANNEL),
-      executablePath: resolveNonEmptyString(env.BROWSERD_MANAGED_LOCAL_EXECUTABLE_PATH),
-      launchTimeoutMs: parseOptionalNumber(env.BROWSERD_MANAGED_LOCAL_LAUNCH_TIMEOUT_MS),
-      args: parseCsv(env.BROWSERD_MANAGED_LOCAL_ARGS)
-    }
-  };
-}
-
-function isObjectRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-function toErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : "Unexpected browserd failure.";
-}
-
-function mapDriverError(error: unknown): ToolResponse<never> {
-  const message = toErrorMessage(error);
-  if (message.startsWith("Unknown targetId:")) {
-    return createErr(ErrorCode.E_NOT_FOUND, message);
-  }
-
-  if (message.startsWith("Unknown driver:")) {
-    return createErr(ErrorCode.E_NOT_FOUND, message);
-  }
-
-  return createErr(ErrorCode.E_INTERNAL, message);
-}
-
-function requireStringArg(args: ToolCallArgs, key: string): ToolResponse<string> {
-  const value = args[key];
-  if (typeof value !== "string" || value.trim().length === 0) {
-    return createErr(ErrorCode.E_INVALID_ARG, `${key} is required and must be a non-empty string.`);
-  }
-
-  return createOk(value.trim());
-}
-
-function resolveTargetId(args: ToolCallArgs, sessions: SessionStore): ToolResponse<string> {
-  const explicit = requireStringArg(args, "targetId");
-  if (explicit.ok) {
-    sessions.useTarget(args.sessionId, explicit.data);
-    return explicit;
-  }
-
-  const sessionTarget = sessions.get(args.sessionId)?.targetId;
-  if (sessionTarget === undefined) {
-    return explicit;
-  }
-
-  return createOk(sessionTarget);
-}
-
-function resolveAction(args: ToolCallArgs): ToolResponse<{ type: string; payload?: Record<string, unknown> }> {
-  const rawAction = args.action;
-  if (!isObjectRecord(rawAction)) {
-    return createErr(ErrorCode.E_INVALID_ARG, "action is required and must be an object.");
-  }
-
-  const actionType = rawAction.type;
-  if (typeof actionType !== "string" || actionType.trim().length === 0) {
-    return createErr(ErrorCode.E_INVALID_ARG, "action.type is required and must be a non-empty string.");
-  }
-
-  const rawPayload = rawAction.payload;
-  if (rawPayload !== undefined && !isObjectRecord(rawPayload)) {
-    return createErr(ErrorCode.E_INVALID_ARG, "action.payload must be an object when provided.");
-  }
-
-  return createOk({
-    type: actionType.trim(),
-    payload: rawPayload as Record<string, unknown> | undefined
-  });
-}
-
-function resolveFiles(args: ToolCallArgs): ToolResponse<string[]> {
-  const files = args.files;
-  if (!isStringArray(files)) {
-    return createErr(ErrorCode.E_INVALID_ARG, "files is required and must be a string array.");
-  }
-
-  const normalizedFiles = files.map((file) => file.trim());
-  if (normalizedFiles.some((file) => file.length === 0)) {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      "files must contain only non-empty string paths."
-    );
-  }
-
-  return createOk(normalizedFiles);
-}
-
-function resolveRequestId(args: ToolCallArgs): ToolResponse<string> {
-  return requireStringArg(args, "requestId");
-}
-
-function resolveOptionalPathArg(args: ToolCallArgs, key: string): ToolResponse<string | undefined> {
-  const value = args[key];
-  if (value === undefined) {
-    return createOk(undefined);
-  }
-
-  if (typeof value !== "string" || value.trim().length === 0) {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `${key} must be a non-empty string when provided.`
-    );
-  }
-
-  return createOk(value.trim());
-}
-
-function resolveDriver(
-  args: ToolCallArgs,
-  drivers: Map<string, BrowserDriver>,
-  sessions: SessionStore,
-  defaultDriverKey: string
-): ToolResponse<{ driverKey: string; driver: BrowserDriver }> {
-  const requestedProfile = args.profile;
-  if (requestedProfile !== undefined) {
-    const requestedDriver = drivers.get(requestedProfile);
-    if (requestedDriver === undefined) {
-      return createErr(ErrorCode.E_NOT_FOUND, `Unknown driver profile: ${requestedProfile}`);
-    }
-
-    sessions.useProfile(args.sessionId, requestedProfile);
-    return createOk({
-      driverKey: requestedProfile,
-      driver: requestedDriver
-    });
-  }
-
-  const sessionProfile = sessions.get(args.sessionId)?.profile;
-  if (sessionProfile !== undefined) {
-    const sessionDriver = drivers.get(sessionProfile);
-    if (sessionDriver !== undefined) {
-      return createOk({
-        driverKey: sessionProfile,
-        driver: sessionDriver
-      });
-    }
-  }
-
-  const defaultDriver = drivers.get(defaultDriverKey);
-  if (defaultDriver === undefined) {
-    return createErr(ErrorCode.E_DRIVER_UNAVAILABLE, `Default driver is not registered: ${defaultDriverKey}`);
-  }
-
-  sessions.useProfile(args.sessionId, defaultDriverKey);
-  return createOk({
-    driverKey: defaultDriverKey,
-    driver: defaultDriver
-  });
-}
-
-async function runWithDriver<TData>(
-  args: ToolCallArgs,
-  drivers: Map<string, BrowserDriver>,
-  sessions: SessionStore,
-  defaultDriverKey: string,
-  operation: (
-    driver: BrowserDriver,
-    driverKey: string
-  ) => Promise<ToolResponse<TData>> | ToolResponse<TData>
-): Promise<ToolResponse<TData>> {
-  const resolvedDriver = resolveDriver(args, drivers, sessions, defaultDriverKey);
-  if (!resolvedDriver.ok) {
-    return resolvedDriver;
-  }
-
-  try {
-    return await operation(resolvedDriver.data.driver, resolvedDriver.data.driverKey);
-  } catch (error) {
-    return mapDriverError(error);
-  }
-}
-
-function isTargetKnownSnapshot(snapshot: unknown): boolean {
-  if (!isObjectRecord(snapshot)) {
-    return false;
-  }
-
-  return snapshot.hasTarget === true;
-}
-
-function hasConsoleEntriesGetter(
-  driver: BrowserDriver
-): driver is BrowserDriver & {
-  getConsoleEntries: NonNullable<ManagedLocalTelemetryDriverExtensions["getConsoleEntries"]>;
-} {
-  return typeof (driver as ManagedLocalTelemetryDriverExtensions).getConsoleEntries === "function";
-}
-
-function hasNetworkResponseBodyGetter(
-  driver: BrowserDriver
-): driver is BrowserDriver & {
-  getNetworkResponseBody: NonNullable<ManagedLocalTelemetryDriverExtensions["getNetworkResponseBody"]>;
-} {
-  return typeof (driver as ManagedLocalTelemetryDriverExtensions).getNetworkResponseBody === "function";
-}
-
-function hasScreenshotGetter(
-  driver: BrowserDriver
-): driver is BrowserDriver & BrowserDriverScreenshot {
-  return typeof (driver as Partial<BrowserDriverScreenshot>).screenshot === "function";
-}
-
-function resolveOptionalStringArg(args: ToolCallArgs, key: string): ToolResponse<string | undefined> {
-  const value = args[key];
-  if (value === undefined) {
-    return createOk(undefined);
-  }
-
-  if (typeof value !== "string") {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `${key} must be a string when provided.`
-    );
-  }
-
-  const trimmedValue = value.trim();
-  return trimmedValue.length === 0 ? createOk(undefined) : createOk(trimmedValue);
-}
-
-function resolveOptionalNumberArg(args: ToolCallArgs, key: string): ToolResponse<number | undefined> {
-  const value = args[key];
-  if (value === undefined) {
-    return createOk(undefined);
-  }
-
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `${key} must be a finite number when provided.`
-    );
-  }
-
-  return createOk(value);
-}
-
-function resolveOptionalIntegerArg(
-  args: ToolCallArgs,
-  key: string,
-  minimum: number
-): ToolResponse<number | undefined> {
-  const resolved = resolveOptionalNumberArg(args, key);
-  if (!resolved.ok || resolved.data === undefined) {
-    return resolved;
-  }
-
-  if (!Number.isInteger(resolved.data) || resolved.data < minimum) {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `${key} must be an integer greater than or equal to ${minimum}.`
-    );
-  }
-
-  return resolved;
-}
-
-function resolveOptionalTimestampArg(
-  args: ToolCallArgs,
-  key: string
-): ToolResponse<number | undefined> {
-  const value = args[key];
-  if (value === undefined) {
-    return createOk(undefined);
-  }
-
-  if (typeof value !== "string") {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `${key} must be an ISO timestamp string when provided.`
-    );
-  }
-
-  const trimmedValue = value.trim();
-  if (trimmedValue.length === 0) {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `${key} must be an ISO timestamp string when provided.`
-    );
-  }
-
-  const parsedValue = Date.parse(trimmedValue);
-  if (!Number.isFinite(parsedValue)) {
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `${key} must be a valid ISO timestamp string.`
-    );
-  }
-
-  return createOk(parsedValue);
-}
-
-function mapNavigationMemoryError(error: unknown): ToolResponse<never> {
-  const message = toErrorMessage(error);
-  if (
-    message === "Navigation memory write requires confirmation in ask mode." ||
-    message === "Navigation memory write is disabled when mode is off."
-  ) {
-    return createErr(ErrorCode.E_PERMISSION, message);
-  }
-
-  return createErr(ErrorCode.E_INTERNAL, message);
-}
-
-function resolveNavigationMemoryScope(
-  args: ToolCallArgs
-): ToolResponse<{ domain: string; profileId: string; intentKey: string }> {
-  const domain = requireStringArg(args, "domain");
-  if (!domain.ok) {
-    return domain;
-  }
-
-  const profileId = requireStringArg(args, "profileId");
-  if (!profileId.ok) {
-    return profileId;
-  }
-
-  const intentKey = requireStringArg(args, "intentKey");
-  if (!intentKey.ok) {
-    return intentKey;
-  }
-
-  return createOk({
-    domain: domain.data,
-    profileId: profileId.data,
-    intentKey: intentKey.data
-  });
-}
-
-function resolveNavigationMemoryMode(args: ToolCallArgs): ToolResponse<NavigationMemoryMode> {
-  const mode = requireStringArg(args, "mode");
-  if (!mode.ok) {
-    return mode;
-  }
-
-  if (mode.data !== "off" && mode.data !== "ask" && mode.data !== "auto") {
-    return createErr(ErrorCode.E_INVALID_ARG, "mode must be one of: off, ask, auto.");
-  }
-
-  return createOk(mode.data);
-}
-
-const MAX_NAVIGATION_SIGNAL_LENGTH = 256;
-const MAX_NAVIGATION_SELECTOR_TOKEN_COUNT = 16;
-const STRUCTURED_SELECTOR_MARKER = /[#.\[:>+~*=]/;
-const SIMPLE_SELECTOR_TOKEN_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-
-function containsControlWhitespace(value: string): boolean {
-  return /[\r\n\t]/.test(value);
-}
-
-function isStructuredRoutePattern(value: string): boolean {
-  if (value.length === 0 || value.length > MAX_NAVIGATION_SIGNAL_LENGTH) {
-    return false;
-  }
-
-  if (containsControlWhitespace(value) || /\s/.test(value)) {
-    return false;
-  }
-
-  return (
-    value.startsWith("/") ||
-    value.startsWith("http://") ||
-    value.startsWith("https://") ||
-    value.includes("://") ||
-    value.includes("?") ||
-    value.includes("#") ||
-    value.includes("*")
-  );
-}
-
-function isStructuredSelectorPattern(value: string): boolean {
-  if (value.length === 0 || value.length > MAX_NAVIGATION_SIGNAL_LENGTH) {
-    return false;
-  }
-
-  if (containsControlWhitespace(value)) {
-    return false;
-  }
-
-  const tokens = value.split(/\s+/).filter((token) => token.length > 0);
-  if (tokens.length === 0 || tokens.length > MAX_NAVIGATION_SELECTOR_TOKEN_COUNT) {
-    return false;
-  }
-
-  if (tokens.length === 1 && SIMPLE_SELECTOR_TOKEN_PATTERN.test(tokens[0])) {
-    return true;
-  }
-
-  return STRUCTURED_SELECTOR_MARKER.test(value);
-}
-
-function resolveNavigationSignals(args: ToolCallArgs): ToolResponse<NavigationSignal[]> {
-  const rawSignals = args.signals;
-  if (!Array.isArray(rawSignals)) {
-    return createErr(ErrorCode.E_INVALID_ARG, "signals is required and must be an array.");
-  }
-
-  const signals: NavigationSignal[] = [];
-  for (const [index, rawSignal] of rawSignals.entries()) {
-    if (!isObjectRecord(rawSignal)) {
-      return createErr(
-        ErrorCode.E_INVALID_ARG,
-        `signals[${index}] must be an object.`
-      );
-    }
-
-    const kind = rawSignal.kind;
-    if (kind === "urlPattern" || kind === "selector") {
-      const value = rawSignal.value;
-      if (typeof value !== "string" || value.trim().length === 0) {
-        return createErr(
-          ErrorCode.E_INVALID_ARG,
-          `signals[${index}].value must be a non-empty string.`
-        );
-      }
-
-      const normalizedValue = value.trim();
-      if (
-        (kind === "urlPattern" && !isStructuredRoutePattern(normalizedValue)) ||
-        (kind === "selector" && !isStructuredSelectorPattern(normalizedValue))
-      ) {
-        const expectedFormat =
-          kind === "urlPattern"
-            ? "a structured URL pattern like /route/* or https://host/path*"
-            : "a structured selector like #id, .class, [data-x], or main .item";
-        return createErr(
-          ErrorCode.E_INVALID_ARG,
-          `signals[${index}].value must be ${expectedFormat}.`
-        );
-      }
-
-      signals.push({
-        kind,
-        value: normalizedValue
-      });
-      continue;
-    }
-
-    if (kind === "hop") {
-      const from = rawSignal.from;
-      const to = rawSignal.to;
-      if (
-        typeof from !== "string" ||
-        from.trim().length === 0 ||
-        typeof to !== "string" ||
-        to.trim().length === 0
-      ) {
-        return createErr(
-          ErrorCode.E_INVALID_ARG,
-          `signals[${index}] hop requires non-empty string from/to values.`
-        );
-      }
-
-      const normalizedFrom = from.trim();
-      const normalizedTo = to.trim();
-      if (!isStructuredRoutePattern(normalizedFrom) || !isStructuredRoutePattern(normalizedTo)) {
-        return createErr(
-          ErrorCode.E_INVALID_ARG,
-          `signals[${index}] hop from/to must be structured route patterns like /from and /to.`
-        );
-      }
-
-      signals.push({
-        kind: "hop",
-        from: normalizedFrom,
-        to: normalizedTo
-      });
-      continue;
-    }
-
-    return createErr(
-      ErrorCode.E_INVALID_ARG,
-      `signals[${index}].kind must be one of: urlPattern, selector, hop.`
-    );
-  }
-
-  return createOk(signals);
-}
-
-function resolveDriverActionData(
-  actionResult: unknown,
-  actionType: string
-): ToolResponse<Record<string, unknown>> {
-  if (!isObjectRecord(actionResult)) {
-    return createErr(ErrorCode.E_INTERNAL, `Invalid action result payload for ${actionType}.`);
-  }
-
-  if (actionResult.targetKnown === false) {
-    return createErr(
-      ErrorCode.E_NOT_FOUND,
-      typeof actionResult.error === "string"
-        ? actionResult.error
-        : `Unknown target for action ${actionType}.`
-    );
-  }
-
-  if (actionResult.ok !== true) {
-    return createErr(
-      ErrorCode.E_INTERNAL,
-      typeof actionResult.error === "string"
-        ? actionResult.error
-        : `Driver action failed: ${actionType}`
-    );
-  }
-
-  if (actionResult.executed !== true) {
-    return createErr(
-      ErrorCode.E_DRIVER_UNAVAILABLE,
-      `Driver does not support action: ${actionType}`
-    );
-  }
-
-  const data = actionResult.data;
-  if (data === undefined) {
-    return createOk({});
-  }
-
-  if (!isObjectRecord(data)) {
-    return createErr(ErrorCode.E_INTERNAL, `Invalid action data payload for ${actionType}.`);
-  }
-
-  return createOk(data);
-}
-
-type NetworkRequestSummary = {
-  requestId: string;
-  url: string;
-  method?: string;
-  status?: number;
-  resourceType?: string;
-  timestamp?: string;
-};
-
-function readNetworkRequestSummaries(snapshot: unknown): NetworkRequestSummary[] {
-  if (!isObjectRecord(snapshot)) {
-    return [];
-  }
-
-  const rawSummaries = snapshot.requestSummaries;
-  if (!Array.isArray(rawSummaries)) {
-    return [];
-  }
-
-  const summaries: NetworkRequestSummary[] = [];
-  for (const rawSummary of rawSummaries) {
-    if (!isObjectRecord(rawSummary)) {
-      continue;
-    }
-
-    const requestId = rawSummary.requestId;
-    const url = rawSummary.url;
-    if (typeof requestId !== "string" || typeof url !== "string") {
-      continue;
-    }
-
-    const method =
-      typeof rawSummary.method === "string" && rawSummary.method.trim().length > 0
-        ? rawSummary.method
-        : undefined;
-    const status =
-      typeof rawSummary.status === "number" && Number.isFinite(rawSummary.status)
-        ? rawSummary.status
-        : undefined;
-    const resourceType =
-      typeof rawSummary.resourceType === "string" && rawSummary.resourceType.trim().length > 0
-        ? rawSummary.resourceType
-        : undefined;
-    const timestamp =
-      typeof rawSummary.timestamp === "string" && rawSummary.timestamp.trim().length > 0
-        ? rawSummary.timestamp
-        : undefined;
-
-    summaries.push({
-      requestId,
-      url,
-      ...(method !== undefined ? { method } : {}),
-      ...(status !== undefined ? { status } : {}),
-      ...(resourceType !== undefined ? { resourceType } : {}),
-      ...(timestamp !== undefined ? { timestamp } : {})
-    });
-  }
-
-  return summaries;
-}
-
-type NetworkSummaryFilters = {
-  urlContains?: string;
-  method?: string;
-  status?: number;
-  sinceMs?: number;
-  limit?: number;
-};
-
-type ConsoleEntry = {
-  type?: string;
-  text?: string;
-  timestamp?: string;
-  [key: string]: unknown;
-};
-
-type ConsoleFilters = {
-  type?: string;
-  contains?: string;
-  sinceMs?: number;
-  limit?: number;
-};
-
-function readConsoleEntries(value: unknown): ConsoleEntry[] {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-
-  return value
-    .filter(isObjectRecord)
-    .map((entry) => ({ ...entry }));
-}
-
-function applyLimitToTail<TValue>(values: TValue[], limit: number | undefined): TValue[] {
-  if (limit === undefined || values.length <= limit) {
-    return values;
-  }
-
-  return values.slice(values.length - limit);
-}
-
-function filterConsoleEntries(
-  entries: ConsoleEntry[],
-  filters: ConsoleFilters
-): ConsoleEntry[] {
-  const normalizedType = filters.type?.toLowerCase();
-  const normalizedContains = filters.contains?.toLowerCase();
-
-  const filtered = entries.filter((entry) => {
-    if (
-      normalizedType !== undefined &&
-      (typeof entry.type !== "string" || entry.type.toLowerCase() !== normalizedType)
-    ) {
-      return false;
-    }
-
-    if (
-      normalizedContains !== undefined &&
-      (typeof entry.text !== "string" || !entry.text.toLowerCase().includes(normalizedContains))
-    ) {
-      return false;
-    }
-
-    if (filters.sinceMs !== undefined) {
-      const timestampMs =
-        typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : Number.NaN;
-      if (!Number.isFinite(timestampMs) || timestampMs < filters.sinceMs) {
-        return false;
-      }
-    }
-
-    return true;
-  });
-
-  return applyLimitToTail(filtered, filters.limit);
-}
-
-function filterNetworkSummaries(
-  summaries: NetworkRequestSummary[],
-  filters: NetworkSummaryFilters
-): NetworkRequestSummary[] {
-  const normalizedMethod = filters.method?.toUpperCase();
-  const filtered = summaries.filter((summary) => {
-    if (filters.urlContains !== undefined && !summary.url.includes(filters.urlContains)) {
-      return false;
-    }
-
-    if (
-      normalizedMethod !== undefined &&
-      (summary.method === undefined || summary.method.toUpperCase() !== normalizedMethod)
-    ) {
-      return false;
-    }
-
-    if (filters.status !== undefined && summary.status !== filters.status) {
-      return false;
-    }
-
-    if (filters.sinceMs !== undefined) {
-      const timestampMs =
-        summary.timestamp === undefined ? Number.NaN : Date.parse(summary.timestamp);
-      if (!Number.isFinite(timestampMs) || timestampMs < filters.sinceMs) {
-        return false;
-      }
-    }
-
-    return true;
-  });
-
-  return applyLimitToTail(filtered, filters.limit);
-}
-
-function createHarLog(
-  summaries: NetworkRequestSummary[],
-  includeBodies: boolean,
-  readBody: (requestId: string) => { body: string; encoding: "utf8" | "base64" } | undefined
-): Record<string, unknown> {
-  const startedDateTime =
-    summaries[0]?.timestamp ?? new Date().toISOString();
-  const entries = summaries.map((summary) => {
-    const bodyPayload = includeBodies ? readBody(summary.requestId) : undefined;
-    const bodyText = bodyPayload?.body;
-    const bodyEncoding = bodyPayload?.encoding;
-    const bodySize = bodyText === undefined ? -1 : bodyText.length;
-
-    return {
-      startedDateTime: summary.timestamp ?? startedDateTime,
-      time: 0,
-      request: {
-        method: summary.method ?? "GET",
-        url: summary.url,
-        httpVersion: "HTTP/1.1",
-        headers: [],
-        queryString: [],
-        cookies: [],
-        headersSize: -1,
-        bodySize: -1
-      },
-      response: {
-        status: summary.status ?? 0,
-        statusText: "",
-        httpVersion: "HTTP/1.1",
-        headers: [],
-        cookies: [],
-        content: {
-          size: bodySize,
-          mimeType: "",
-          ...(bodyText !== undefined ? { text: bodyText } : {}),
-          ...(bodyEncoding !== undefined ? { encoding: bodyEncoding } : {})
-        },
-        redirectURL: "",
-        headersSize: -1,
-        bodySize
-      },
-      cache: {},
-      timings: {
-        send: 0,
-        wait: 0,
-        receive: 0
-      }
-    };
-  });
-
-  return {
-    log: {
-      version: "1.2",
-      creator: {
-        name: "browserctl",
-        version: "0.5.0"
-      },
-      pages: [
-        {
-          id: "page:1",
-          startedDateTime,
-          title: "browserctl",
-          pageTimings: {}
-        }
-      ],
-      entries
-    }
-  };
-}
-
-function readSnapshotUrl(snapshot: unknown): string | undefined {
-  if (!isObjectRecord(snapshot)) {
-    return undefined;
-  }
-
-  const value = snapshot.url;
-  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
-}
-
-function readSnapshotHtml(snapshot: unknown): string | undefined {
-  if (!isObjectRecord(snapshot)) {
-    return undefined;
-  }
-
-  const value = snapshot.html;
-  return typeof value === "string" ? value : undefined;
-}
-
-function readElementList(value: unknown): Array<Record<string, unknown>> {
-  if (!Array.isArray(value)) {
-    return [];
-  }
-
-  return value.filter(isObjectRecord);
-}
-
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-function resolveRequiredScope(toolName: string): CapabilityScope {
-  return TOOL_SCOPE_BY_NAME[toolName] ?? "read";
-}
-
-function resolveProvidedAuthToken(args: ToolCallArgs): string | undefined {
-  const rawToken = args.authToken;
-  if (typeof rawToken !== "string") {
-    return undefined;
-  }
-
-  const trimmedToken = rawToken.trim();
-  return trimmedToken.length === 0 ? undefined : trimmedToken;
-}
-
-function authorizeToolCall(
-  args: ToolCallArgs,
-  toolName: string,
-  configuredToken: string | undefined,
-  allowedScopes: ReadonlySet<CapabilityScope>
-): ToolResponse<null> {
-  if (configuredToken !== undefined) {
-    const providedToken = resolveProvidedAuthToken(args);
-    if (providedToken === undefined || providedToken !== configuredToken) {
-      return createErr(ErrorCode.E_PERMISSION, "Invalid auth token.");
-    }
-  }
-
-  const requiredScope = resolveRequiredScope(toolName);
-  if (!allowedScopes.has(requiredScope)) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      `Tool scope is not allowed: ${toolName} requires ${requiredScope}.`
-    );
-  }
-
-  return createOk(null);
-}
-
-function resolveSessionTenant(sessionId: string): string | undefined {
-  const delimiterIndex = sessionId.indexOf(":");
-  if (delimiterIndex <= 0) {
-    return undefined;
-  }
-
-  const tenant = sessionId.slice(0, delimiterIndex).trim();
-  return tenant.length === 0 ? undefined : tenant.toLowerCase();
-}
-
-function authorizeSessionDrop(
-  requesterSessionId: string,
-  sessionIdToDelete: string
-): ToolResponse<null> {
-  if (requesterSessionId === sessionIdToDelete) {
-    return createOk(null);
-  }
-
-  const requesterTenant = resolveSessionTenant(requesterSessionId);
-  const targetTenant = resolveSessionTenant(sessionIdToDelete);
-  if (
-    requesterTenant === undefined ||
-    targetTenant === undefined ||
-    requesterTenant !== targetTenant
-  ) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      "browser.session.drop can only delete sessions in the same tenant."
-    );
-  }
-
-  return createOk(null);
-}
-
-function parseHostnameFromUrl(rawUrl: string): ToolResponse<string> {
-  const trimmedUrl = rawUrl.trim();
-  if (trimmedUrl.length === 0) {
-    return createErr(ErrorCode.E_INVALID_ARG, "URL must be a non-empty string.");
-  }
-
-  let parsedUrl: URL;
-  try {
-    parsedUrl = new URL(trimmedUrl);
-  } catch {
-    return createErr(ErrorCode.E_INVALID_ARG, `Invalid URL: ${trimmedUrl}`);
-  }
-
-  if (parsedUrl.hostname.trim().length === 0) {
-    return createErr(ErrorCode.E_INVALID_ARG, `URL hostname is missing: ${trimmedUrl}`);
-  }
-
-  return createOk(parsedUrl.hostname.toLowerCase());
-}
-
-function isHostnameAllowed(hostname: string, allowlistEntry: string): boolean {
-  if (allowlistEntry.startsWith("*.")) {
-    const suffix = allowlistEntry.slice(2);
-    if (suffix.length === 0) {
-      return false;
-    }
-
-    return hostname === suffix || hostname.endsWith(`.${suffix}`);
-  }
-
-  return hostname === allowlistEntry;
-}
-
-function resolveRestrictedUrlFromToolArgs(
-  toolName: string,
-  args: ToolCallArgs
-): ToolResponse<string | undefined> {
-  if (toolName === "browser.tab.open") {
-    const url = args.url;
-    if (typeof url !== "string" || url.trim().length === 0) {
-      return createErr(ErrorCode.E_INVALID_ARG, "url is required and must be a non-empty string.");
-    }
-
-    return createOk(url.trim());
-  }
-
-  if (toolName === "browser.cookie.set") {
-    const url = args.url;
-    if (url === undefined) {
-      return createOk(undefined);
-    }
-
-    if (typeof url !== "string" || url.trim().length === 0) {
-      return createErr(
-        ErrorCode.E_INVALID_ARG,
-        "url must be a non-empty string when provided."
-      );
-    }
-
-    return createOk(url.trim());
-  }
-
-  if (toolName === "browser.act") {
-    const action = args.action;
-    if (!isObjectRecord(action)) {
-      return createOk(undefined);
-    }
-
-    const actionType = typeof action.type === "string" ? action.type.trim().toLowerCase() : "";
-    if (actionType !== "navigate" && actionType !== "goto") {
-      return createOk(undefined);
-    }
-
-    const payload = action.payload;
-    if (!isObjectRecord(payload)) {
-      return createErr(ErrorCode.E_INVALID_ARG, "action.payload.url is required for navigate action.");
-    }
-
-    const url = payload.url;
-    if (typeof url !== "string" || url.trim().length === 0) {
-      return createErr(ErrorCode.E_INVALID_ARG, "action.payload.url is required for navigate action.");
-    }
-
-    return createOk(url.trim());
-  }
-
-  return createOk(undefined);
-}
-
-function authorizeDomainAllowlist(
-  toolName: string,
-  args: ToolCallArgs,
-  config: BrowserdConfig
-): ToolResponse<null> {
-  if (config.domainAllowlistMode !== "enforce") {
-    return createOk(null);
-  }
-
-  if (config.domainAllowlist.length === 0) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      "Domain allowlist mode is enforce but BROWSERD_DOMAIN_ALLOWLIST is empty."
-    );
-  }
-
-  const restrictedUrl = resolveRestrictedUrlFromToolArgs(toolName, args);
-  if (!restrictedUrl.ok) {
-    return restrictedUrl;
-  }
-  if (restrictedUrl.data === undefined) {
-    return createOk(null);
-  }
-
-  const hostname = parseHostnameFromUrl(restrictedUrl.data);
-  if (!hostname.ok) {
-    return hostname;
-  }
-
-  const matched = config.domainAllowlist.some((entry) => isHostnameAllowed(hostname.data, entry));
-  if (!matched) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      `URL host is outside domain allowlist: ${hostname.data}`
-    );
-  }
-
-  return createOk(null);
-}
-
-function authorizeSessionGovernance(
-  args: ToolCallArgs,
-  sessions: SessionStore,
-  config: BrowserdConfig
-): ToolResponse<null> {
-  const sessionId = args.sessionId;
-  const tenant = resolveSessionTenant(sessionId);
-  if (config.sessionRequireTenantPrefix && tenant === undefined) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      "Session governance requires tenant-prefixed sessionId format: <tenant>:<session>."
-    );
-  }
-
-  if (
-    config.tenantAllowlist.length > 0 &&
-    (tenant === undefined || !config.tenantAllowlist.includes(tenant))
-  ) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      `Tenant is not allowed for sessionId: ${sessionId}`
-    );
-  }
-
-  if (sessions.has(sessionId)) {
-    return createOk(null);
-  }
-
-  const activeSessions = sessions.listSnapshots();
-  if (activeSessions.length >= config.sessionMaxTotal) {
-    return createErr(
-      ErrorCode.E_CONFLICT,
-      `Active session limit exceeded: ${config.sessionMaxTotal}.`
-    );
-  }
-
-  if (tenant !== undefined) {
-    const tenantSessionCount = activeSessions.reduce((count, snapshot) => {
-      const snapshotTenant = resolveSessionTenant(snapshot.state.sessionId);
-      return snapshotTenant === tenant ? count + 1 : count;
-    }, 0);
-    if (tenantSessionCount >= config.sessionMaxPerTenant) {
-      return createErr(
-        ErrorCode.E_CONFLICT,
-        `Active session limit exceeded for tenant ${tenant}: ${config.sessionMaxPerTenant}.`
-      );
-    }
-  }
-
-  return createOk(null);
-}
-
-function isWindowsPathStyle(pathValue: string): boolean {
-  return (
-    /^[a-zA-Z]:[\\/]/.test(pathValue) ||
-    pathValue.startsWith("\\\\") ||
-    pathValue.includes("\\")
-  );
-}
-
-function resolvePathWithinRoot(
-  inputPath: string,
-  rootPath: string,
-  context: "upload" | "download"
-): ToolResponse<string> {
-  const useWindowsSemantics = isWindowsPathStyle(rootPath);
-  const pathRuntime = useWindowsSemantics ? windowsPath : posixPath;
-  const resolvedRoot = pathRuntime.resolve(rootPath);
-  const resolvedPath = pathRuntime.isAbsolute(inputPath)
-    ? pathRuntime.resolve(inputPath)
-    : pathRuntime.resolve(resolvedRoot, inputPath);
-
-  const comparableRoot = useWindowsSemantics ? resolvedRoot.toLowerCase() : resolvedRoot;
-  const comparablePath = useWindowsSemantics ? resolvedPath.toLowerCase() : resolvedPath;
-  const relativePath = pathRuntime.relative(comparableRoot, comparablePath);
-  const isInRoot =
-    relativePath === "" ||
-    (!relativePath.startsWith("..") && !pathRuntime.isAbsolute(relativePath));
-  if (!isInRoot) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      `${context} path is outside configured allowlist root: ${inputPath}`
-    );
-  }
-
-  return createOk(resolvedPath);
-}
-
-function applyUploadRoot(files: string[], uploadRoot: string | undefined): ToolResponse<string[]> {
-  if (uploadRoot === undefined) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      "Upload root is not configured. Set BROWSERD_UPLOAD_ROOT to enable browser.upload.arm."
-    );
-  }
-
-  const rootedFiles: string[] = [];
-  for (const file of files) {
-    const rootedPath = resolvePathWithinRoot(file, uploadRoot, "upload");
-    if (!rootedPath.ok) {
-      return rootedPath;
-    }
-
-    rootedFiles.push(rootedPath.data);
-  }
-
-  return createOk(rootedFiles);
-}
-
-function normalizeDownloadPayload(
-  rawDownload: unknown,
-  requestedPath: string | undefined,
-  downloadRoot: string | undefined
-): ToolResponse<Record<string, unknown>> {
-  if (downloadRoot === undefined) {
-    return createErr(
-      ErrorCode.E_PERMISSION,
-      "Download root is not configured. Set BROWSERD_DOWNLOAD_ROOT to enable browser.download.wait."
-    );
-  }
-
-  if (!isObjectRecord(rawDownload)) {
-    return createErr(ErrorCode.E_INTERNAL, "Invalid driver download payload.");
-  }
-
-  const download = { ...rawDownload };
-  const actualPath =
-    typeof download.path === "string" && download.path.trim().length > 0
-      ? download.path.trim()
-      : undefined;
-  if (actualPath === undefined) {
-    return createErr(
-      ErrorCode.E_INTERNAL,
-      "Driver download payload is missing path required for allowlist enforcement."
-    );
-  }
-
-  const rootedActualPath = resolvePathWithinRoot(actualPath, downloadRoot, "download");
-  if (!rootedActualPath.ok) {
-    return rootedActualPath;
-  }
-
-  if (requestedPath !== undefined) {
-    const rootedRequestedPath = resolvePathWithinRoot(requestedPath, downloadRoot, "download");
-    if (!rootedRequestedPath.ok) {
-      return rootedRequestedPath;
-    }
-
-    const useWindowsSemantics = isWindowsPathStyle(downloadRoot);
-    const comparableActualPath = useWindowsSemantics
-      ? rootedActualPath.data.toLowerCase()
-      : rootedActualPath.data;
-    const comparableRequestedPath = useWindowsSemantics
-      ? rootedRequestedPath.data.toLowerCase()
-      : rootedRequestedPath.data;
-    if (comparableActualPath !== comparableRequestedPath) {
-      return createErr(
-        ErrorCode.E_INTERNAL,
-        `Driver failed to persist download to requested path: ${rootedRequestedPath.data}`
-      );
-    }
-  }
-
-  return createOk({
-    ...download,
-    path: rootedActualPath.data
-  });
-}
-
-function createBrowserdToolMap(
-  drivers: Map<string, BrowserDriver>,
-  sessions: SessionStore,
-  defaultDriverKey: string,
-  config: BrowserdConfig
-): ToolMap {
-  type TraceStep = {
-    index: number;
-    timestamp: string;
-    tool: string;
-    ok: boolean;
-    durationMs: number;
-    targetId?: string;
-    profile?: string;
-    errorCode?: string;
-  };
-  type TraceKeyResponse = {
-    stepIndex: number;
-    kind: string;
-    timestamp: string;
-    data: Record<string, unknown>;
-  };
-  type TraceScreenshot = {
-    stepIndex: number;
-    timestamp: string;
-    tool: string;
-    targetId?: string;
-  };
-  type SessionTraceState = {
-    nextStepIndex: number;
-    steps: TraceStep[];
-    keyResponses: TraceKeyResponse[];
-    screenshots: TraceScreenshot[];
-  };
-  const traceStateBySession = new Map<string, SessionTraceState>();
-  const TRACE_EVENT_LIMIT = 500;
-
-  const getOrCreateSessionTraceState = (sessionId: string): SessionTraceState => {
-    const existing = traceStateBySession.get(sessionId);
-    if (existing !== undefined) {
-      return existing;
-    }
-
-    const created: SessionTraceState = {
-      nextStepIndex: 1,
-      steps: [],
-      keyResponses: [],
-      screenshots: []
-    };
-    traceStateBySession.set(sessionId, created);
-    return created;
-  };
-
-  const trimTraceState = (state: SessionTraceState): void => {
-    if (state.steps.length > TRACE_EVENT_LIMIT) {
-      state.steps.splice(0, state.steps.length - TRACE_EVENT_LIMIT);
-    }
-    if (state.keyResponses.length > TRACE_EVENT_LIMIT) {
-      state.keyResponses.splice(0, state.keyResponses.length - TRACE_EVENT_LIMIT);
-    }
-    if (state.screenshots.length > TRACE_EVENT_LIMIT) {
-      state.screenshots.splice(0, state.screenshots.length - TRACE_EVENT_LIMIT);
-    }
-  };
-
-  const recordTrace = (
-    sessionId: string,
-    toolName: string,
-    args: ToolCallArgs,
-    response: ToolResponse<Record<string, unknown>> | ToolResponse<unknown>,
-    startedAtMs: number,
-    finishedAtMs: number
-  ): void => {
-    const state = getOrCreateSessionTraceState(sessionId);
-    const stepIndex = state.nextStepIndex;
-    state.nextStepIndex += 1;
-    const timestamp = new Date(startedAtMs).toISOString();
-    const targetId = typeof args.targetId === "string" ? args.targetId : undefined;
-    const profile = typeof args.profile === "string" ? args.profile : undefined;
-    const errorCode =
-      !response.ok && isObjectRecord(response.error) && typeof response.error.code === "string"
-        ? response.error.code
-        : undefined;
-
-    state.steps.push({
-      index: stepIndex,
-      timestamp,
-      tool: toolName,
-      ok: response.ok,
-      durationMs: Math.max(0, finishedAtMs - startedAtMs),
-      ...(targetId !== undefined ? { targetId } : {}),
-      ...(profile !== undefined ? { profile } : {}),
-      ...(errorCode !== undefined ? { errorCode } : {})
-    });
-
-    if (
-      response.ok &&
-      (toolName === "browser.screenshot" || toolName === "browser.element.screenshot")
-    ) {
-      state.screenshots.push({
-        stepIndex,
-        timestamp,
-        tool: toolName,
-        ...(targetId !== undefined ? { targetId } : {})
-      });
-    }
-
-    if (response.ok && isObjectRecord(response.data)) {
-      if (toolName === "browser.network.waitFor" && isObjectRecord(response.data.request)) {
-        state.keyResponses.push({
-          stepIndex,
-          kind: "network.waitFor",
-          timestamp,
-          data: {
-            ...response.data.request
-          }
-        });
-      }
-
-      if (toolName === "browser.network.responseBody") {
-        const requestId = response.data.requestId;
-        const encoding = response.data.encoding;
-        const body = response.data.body;
-        state.keyResponses.push({
-          stepIndex,
-          kind: "network.responseBody",
-          timestamp,
-          data: {
-            ...(typeof requestId === "string" ? { requestId } : {}),
-            ...(typeof encoding === "string" ? { encoding } : {}),
-            ...(typeof body === "string" ? { size: body.length } : {})
-          }
-        });
-      }
-
-      if (toolName === "browser.network.list") {
-        const requests = response.data.requests;
-        state.keyResponses.push({
-          stepIndex,
-          kind: "network.list",
-          timestamp,
-          data: {
-            count: Array.isArray(requests) ? requests.length : 0
-          }
-        });
-      }
-
-      if (toolName === "browser.network.harExport") {
-        const har = response.data.har;
-        const entriesCount =
-          isObjectRecord(har) &&
-          isObjectRecord(har.log) &&
-          Array.isArray(har.log.entries)
-            ? har.log.entries.length
-            : 0;
-        state.keyResponses.push({
-          stepIndex,
-          kind: "network.harExport",
-          timestamp,
-          data: {
-            entries: entriesCount
-          }
-        });
-      }
-
-      if (toolName === "browser.memory.resolve") {
-        state.keyResponses.push({
-          stepIndex,
-          kind: "memory.resolve",
-          timestamp,
-          data: {
-            memoryHit: response.data.hit === true
-          }
-        });
-      }
-    }
-
-    trimTraceState(state);
-  };
-
-  const toolMap = buildToolMap();
-  const navigationMemoryStore = createNavigationMemoryStore({
-    path: config.memoryPath,
-    mode: config.memoryEnabled ? config.memoryMode : "off",
-    ttlDays: config.memoryTtlDays
-  });
-  const allowedScopes = new Set<CapabilityScope>(config.authScopes);
-  const runWithDefaultDriver = <TData>(
-    args: ToolCallArgs,
-    operation: (
-      driver: BrowserDriver,
-      driverKey: string
-    ) => Promise<ToolResponse<TData>> | ToolResponse<TData>
-  ): Promise<ToolResponse<TData>> =>
-    runWithDriver(args, drivers, sessions, defaultDriverKey, operation);
-
-  const runStructuredAction = async (
-    args: ToolCallArgs,
-    actionType: string,
-    payload: Record<string, unknown>
-  ): Promise<
-    ToolResponse<{
-      driver: string;
-      targetId: string;
-      data: Record<string, unknown>;
-    }>
-  > =>
-    await runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const actionResult = await driver.act(
-        {
-          type: actionType,
-          payload
-        },
-        targetId.data
-      );
-      const resolvedData = resolveDriverActionData(actionResult, actionType);
-      if (!resolvedData.ok) {
-        return resolvedData;
-      }
-
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        data: resolvedData.data
-      });
-    });
-
-  toolMap.set("browser.status", async (args) => {
-    const resolvedDriver = resolveDriver(args, drivers, sessions, defaultDriverKey);
-    if (!resolvedDriver.ok) {
-      return resolvedDriver;
-    }
-
-    try {
-      const status = await resolvedDriver.data.driver.status();
-      return createOk({
-        kind: "browserd",
-        ready: true,
-        driver: resolvedDriver.data.driverKey,
-        drivers: [...drivers.keys()].sort(),
-        status
-      });
-    } catch (error) {
-      return mapDriverError(error);
-    }
-  });
-
-  toolMap.set("browser.profile.use", async (args) => {
-    const requestedProfile = requireStringArg(args, "profile");
-    if (!requestedProfile.ok) {
-      return requestedProfile;
-    }
-
-    if (!drivers.has(requestedProfile.data)) {
-      return createErr(ErrorCode.E_NOT_FOUND, `Unknown driver profile: ${requestedProfile.data}`);
-    }
-
-    sessions.useProfile(args.sessionId, requestedProfile.data);
-    return createOk({
-      profile: requestedProfile.data
-    });
-  });
-
-  toolMap.set("browser.profile.list", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const profiles = await driver.listProfiles();
-      return createOk({
-        driver: driverKey,
-        profiles
-      });
-    })
-  );
-
-  toolMap.set("browser.session.list", async (args) => {
-    const tenant = resolveOptionalStringArg(args, "tenant");
-    if (!tenant.ok) {
-      return tenant;
-    }
-
-    const limit = resolveOptionalIntegerArg(args, "limit", 1);
-    if (!limit.ok) {
-      return limit;
-    }
-
-    const normalizedTenant = tenant.data?.toLowerCase();
-    const sessionsPayload = sessions
-      .listSnapshots()
-      .map((snapshot) => ({
-        sessionId: snapshot.state.sessionId,
-        tenant: resolveSessionTenant(snapshot.state.sessionId),
-        profile: snapshot.state.profile,
-        targetId: snapshot.state.targetId,
-        touchedAt: new Date(snapshot.touchedAt).toISOString()
-      }))
-      .filter((entry) =>
-        normalizedTenant === undefined ? true : entry.tenant === normalizedTenant
-      )
-      .sort((left, right) => right.touchedAt.localeCompare(left.touchedAt));
-
-    const limitedSessions =
-      limit.data === undefined ? sessionsPayload : sessionsPayload.slice(0, limit.data);
-    return createOk({
-      sessions: limitedSessions,
-      totalActive: sessions.size()
-    });
-  });
-
-  toolMap.set("browser.session.drop", async (args) => {
-    const sessionIdToDelete = requireStringArg(args, "sessionIdToDelete");
-    if (!sessionIdToDelete.ok) {
-      return sessionIdToDelete;
-    }
-
-    const dropAuthorization = authorizeSessionDrop(args.sessionId, sessionIdToDelete.data);
-    if (!dropAuthorization.ok) {
-      return dropAuthorization;
-    }
-
-    return createOk({
-      sessionIdToDelete: sessionIdToDelete.data,
-      dropped: sessions.delete(sessionIdToDelete.data)
-    });
-  });
-
-  toolMap.set("browser.memory.status", async () => createOk(navigationMemoryStore.status()));
-
-  toolMap.set("browser.memory.resolve", async (args) => {
-    const scope = resolveNavigationMemoryScope(args);
-    if (!scope.ok) {
-      return scope;
-    }
-
-    try {
-      return createOk(await navigationMemoryStore.resolve(scope.data));
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.memory.upsert", async (args) => {
-    const scope = resolveNavigationMemoryScope(args);
-    if (!scope.ok) {
-      return scope;
-    }
-
-    const signals = resolveNavigationSignals(args);
-    if (!signals.ok) {
-      return signals;
-    }
-
-    const confidence = resolveOptionalNumberArg(args, "confidence");
-    if (!confidence.ok) {
-      return confidence;
-    }
-
-    const confirmed = args.confirmed;
-    if (confirmed !== undefined && typeof confirmed !== "boolean") {
-      return createErr(ErrorCode.E_INVALID_ARG, "confirmed must be a boolean when provided.");
-    }
-
-    try {
-      return createOk(
-        await navigationMemoryStore.upsert({
-          ...scope.data,
-          signals: signals.data,
-          ...(confidence.data !== undefined ? { confidence: confidence.data } : {}),
-          ...(confirmed !== undefined ? { confirmed } : {})
-        })
-      );
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.memory.list", async (args) => {
-    const domain = resolveOptionalStringArg(args, "domain");
-    if (!domain.ok) {
-      return domain;
-    }
-
-    const profileId = resolveOptionalStringArg(args, "profileId");
-    if (!profileId.ok) {
-      return profileId;
-    }
-
-    const intentKey = resolveOptionalStringArg(args, "intentKey");
-    if (!intentKey.ok) {
-      return intentKey;
-    }
-
-    try {
-      const entries = await navigationMemoryStore.list({
-        ...(domain.data !== undefined ? { domain: domain.data } : {}),
-        ...(profileId.data !== undefined ? { profileId: profileId.data } : {}),
-        ...(intentKey.data !== undefined ? { intentKey: intentKey.data } : {})
-      });
-      return createOk({ entries });
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.memory.inspect", async (args) => {
-    const id = requireStringArg(args, "id");
-    if (!id.ok) {
-      return id;
-    }
-
-    try {
-      return createOk({
-        entry: await navigationMemoryStore.inspect(id.data)
-      });
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.memory.delete", async (args) => {
-    const id = requireStringArg(args, "id");
-    if (!id.ok) {
-      return id;
-    }
-
-    try {
-      return createOk({
-        deleted: await navigationMemoryStore.delete(id.data)
-      });
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.memory.purge", async () => {
-    try {
-      return createOk({
-        purged: await navigationMemoryStore.purgeExpired()
-      });
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.memory.mode.set", async (args) => {
-    if (!config.memoryEnabled) {
-      return createErr(
-        ErrorCode.E_PERMISSION,
-        "Navigation memory is disabled by BROWSERD_MEMORY_ENABLED=false."
-      );
-    }
-
-    const mode = resolveNavigationMemoryMode(args);
-    if (!mode.ok) {
-      return mode;
-    }
-
-    try {
-      return createOk(await navigationMemoryStore.setMode(mode.data));
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.memory.ttl.set", async (args) => {
-    const ttlDays = resolveOptionalIntegerArg(args, "ttlDays", 0);
-    if (!ttlDays.ok) {
-      return ttlDays;
-    }
-
-    if (ttlDays.data === undefined) {
-      return createErr(ErrorCode.E_INVALID_ARG, "ttlDays is required and must be an integer greater than or equal to 0.");
-    }
-
-    try {
-      return createOk(await navigationMemoryStore.setTtlDays(ttlDays.data));
-    } catch (error) {
-      return mapNavigationMemoryError(error);
-    }
-  });
-
-  toolMap.set("browser.tab.list", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const tabs = await driver.listTabs();
-      return createOk({
-        driver: driverKey,
-        tabs
-      });
-    })
-  );
-
-  toolMap.set("browser.tab.open", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const url = requireStringArg(args, "url");
-      if (!url.ok) {
-        return url;
-      }
-
-      const targetId = await driver.openTab(url.data);
-      sessions.useTarget(args.sessionId, targetId);
-      return createOk({
-        driver: driverKey,
-        targetId
-      });
-    })
-  );
-
-  toolMap.set("browser.tab.focus", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      await driver.focusTab(targetId.data);
-      sessions.useTarget(args.sessionId, targetId.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        focused: true
-      });
-    })
-  );
-
-  toolMap.set("browser.tab.close", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      await driver.closeTab(targetId.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        closed: true
-      });
-    })
-  );
-
-  toolMap.set("browser.snapshot", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const snapshot = await driver.snapshot(targetId.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        snapshot
-      });
-    })
-  );
-
-  toolMap.set("browser.screenshot", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      if (!hasScreenshotGetter(driver)) {
-        return createErr(
-          ErrorCode.E_DRIVER_UNAVAILABLE,
-          `Driver does not support screenshots: ${driverKey}`
-        );
-      }
-
-      const screenshot = await driver.screenshot(targetId.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        screenshot
-      });
-    })
-  );
-
-  toolMap.set("browser.dom.query", async (args) => {
-    const selector = requireStringArg(args, "selector");
-    if (!selector.ok) {
-      return selector;
-    }
-
-    const result = await runStructuredAction(args, "domQuery", {
-      selector: selector.data
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      query: result.data.data
-    });
-  });
-
-  toolMap.set("browser.dom.queryAll", async (args) => {
-    const selector = requireStringArg(args, "selector");
-    if (!selector.ok) {
-      return selector;
-    }
-
-    const result = await runStructuredAction(args, "domQueryAll", {
-      selector: selector.data
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      query: result.data.data
-    });
-  });
-
-  toolMap.set("browser.element.screenshot", async (args) => {
-    const selector = requireStringArg(args, "selector");
-    if (!selector.ok) {
-      return selector;
-    }
-
-    const result = await runStructuredAction(args, "elementScreenshot", {
-      selector: selector.data
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      screenshot: result.data.data
-    });
-  });
-
-  toolMap.set("browser.a11y.snapshot", async (args) => {
-    const selector = resolveOptionalStringArg(args, "selector");
-    if (!selector.ok) {
-      return selector;
-    }
-
-    const result = await runStructuredAction(args, "a11ySnapshot", {
-      ...(selector.data !== undefined ? { selector: selector.data } : {})
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      snapshot: result.data.data
-    });
-  });
-
-  toolMap.set("browser.cookie.get", async (args) => {
-    const name = resolveOptionalStringArg(args, "name");
-    if (!name.ok) {
-      return name;
-    }
-
-    const result = await runStructuredAction(args, "cookieGet", {
-      ...(name.data !== undefined ? { name: name.data } : {})
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      ...result.data.data
-    });
-  });
-
-  toolMap.set("browser.cookie.set", async (args) => {
-    const name = requireStringArg(args, "name");
-    if (!name.ok) {
-      return name;
-    }
-
-    const value = requireStringArg(args, "value");
-    if (!value.ok) {
-      return value;
-    }
-
-    const url = resolveOptionalStringArg(args, "url");
-    if (!url.ok) {
-      return url;
-    }
-
-    const result = await runStructuredAction(args, "cookieSet", {
-      name: name.data,
-      value: value.data,
-      ...(url.data !== undefined ? { url: url.data } : {})
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      ...result.data.data
-    });
-  });
-
-  toolMap.set("browser.cookie.clear", async (args) => {
-    const name = resolveOptionalStringArg(args, "name");
-    if (!name.ok) {
-      return name;
-    }
-
-    const result = await runStructuredAction(args, "cookieClear", {
-      ...(name.data !== undefined ? { name: name.data } : {})
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      ...result.data.data
-    });
-  });
-
-  toolMap.set("browser.storage.get", async (args) => {
-    const scope = requireStringArg(args, "scope");
-    if (!scope.ok) {
-      return scope;
-    }
-
-    if (scope.data !== "local" && scope.data !== "session") {
-      return createErr(ErrorCode.E_INVALID_ARG, "scope must be local or session.");
-    }
-
-    const key = requireStringArg(args, "key");
-    if (!key.ok) {
-      return key;
-    }
-
-    const result = await runStructuredAction(args, "storageGet", {
-      scope: scope.data,
-      key: key.data
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      ...result.data.data
-    });
-  });
-
-  toolMap.set("browser.storage.set", async (args) => {
-    const scope = requireStringArg(args, "scope");
-    if (!scope.ok) {
-      return scope;
-    }
-
-    if (scope.data !== "local" && scope.data !== "session") {
-      return createErr(ErrorCode.E_INVALID_ARG, "scope must be local or session.");
-    }
-
-    const key = requireStringArg(args, "key");
-    if (!key.ok) {
-      return key;
-    }
-
-    const value = requireStringArg(args, "value");
-    if (!value.ok) {
-      return value;
-    }
-
-    const result = await runStructuredAction(args, "storageSet", {
-      scope: scope.data,
-      key: key.data,
-      value: value.data
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      ...result.data.data
-    });
-  });
-
-  toolMap.set("browser.frame.list", async (args) => {
-    const result = await runStructuredAction(args, "frameList", {});
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      ...result.data.data
-    });
-  });
-
-  toolMap.set("browser.frame.snapshot", async (args) => {
-    const frameId = requireStringArg(args, "frameId");
-    if (!frameId.ok) {
-      return frameId;
-    }
-
-    const result = await runStructuredAction(args, "frameSnapshot", {
-      frameId: frameId.data
-    });
-    if (!result.ok) {
-      return result;
-    }
-
-    return createOk({
-      driver: result.data.driver,
-      targetId: result.data.targetId,
-      ...result.data.data
-    });
-  });
-
-  toolMap.set("browser.act", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const action = resolveAction(args);
-      if (!action.ok) {
-        return action;
-      }
-
-      const result = await driver.act(action.data, targetId.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        result
-      });
-    })
-  );
-
-  toolMap.set("browser.upload.arm", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const files = resolveFiles(args);
-      if (!files.ok) {
-        return files;
-      }
-
-      const rootedFiles = applyUploadRoot(files.data, config.uploadRoot);
-      if (!rootedFiles.ok) {
-        return rootedFiles;
-      }
-
-      await driver.armUpload(targetId.data, rootedFiles.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        armed: true,
-        files: rootedFiles.data
-      });
-    })
-  );
-
-  toolMap.set("browser.dialog.arm", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      await driver.armDialog(targetId.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        armed: true
-      });
-    })
-  );
-
-  toolMap.set("browser.download.trigger", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      await driver.triggerDownload(targetId.data);
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        triggered: true
-      });
-    })
-  );
-
-  toolMap.set("browser.download.wait", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const requestedPath = resolveOptionalPathArg(args, "path");
-      if (!requestedPath.ok) {
-        return requestedPath;
-      }
-
-      const download = await driver.waitDownload(targetId.data, undefined, requestedPath.data);
-      const normalizedDownload = normalizeDownloadPayload(
-        download,
-        requestedPath.data,
-        config.downloadRoot
-      );
-      if (!normalizedDownload.ok) {
-        return normalizedDownload;
-      }
-
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        download: normalizedDownload.data
-      });
-    })
-  );
-
-  toolMap.set("browser.wait.element", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const selector = requireStringArg(args, "selector");
-      if (!selector.ok) {
-        return selector;
-      }
-
-      const timeoutMs = resolveOptionalIntegerArg(args, "timeoutMs", 1);
-      if (!timeoutMs.ok) {
-        return timeoutMs;
-      }
-
-      const pollMs = resolveOptionalIntegerArg(args, "pollMs", 1);
-      if (!pollMs.ok) {
-        return pollMs;
-      }
-
-      const maxWaitMs = timeoutMs.data ?? DEFAULT_NETWORK_WAIT_TIMEOUT_MS;
-      const intervalMs = pollMs.data ?? DEFAULT_NETWORK_WAIT_POLL_MS;
-      const startTime = Date.now();
-
-      while (Date.now() - startTime <= maxWaitMs) {
-        const actionResult = await driver.act(
-          {
-            type: "domQuery",
-            payload: {
-              selector: selector.data
-            }
-          },
-          targetId.data
-        );
-        const data = resolveDriverActionData(actionResult, "domQuery");
-        if (!data.ok) {
-          return data;
-        }
-
-        if (data.data.found === true) {
-          return createOk({
-            driver: driverKey,
-            targetId: targetId.data,
-            selector: selector.data,
-            element: data.data,
-            elapsedMs: Date.now() - startTime
-          });
-        }
-
-        await delay(intervalMs);
-      }
-
-      return createErr(
-        ErrorCode.E_TIMEOUT,
-        `Timed out waiting for element: ${selector.data}`
-      );
-    })
-  );
-
-  toolMap.set("browser.wait.text", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const text = requireStringArg(args, "text");
-      if (!text.ok) {
-        return text;
-      }
-
-      const selector = resolveOptionalStringArg(args, "selector");
-      if (!selector.ok) {
-        return selector;
-      }
-
-      const timeoutMs = resolveOptionalIntegerArg(args, "timeoutMs", 1);
-      if (!timeoutMs.ok) {
-        return timeoutMs;
-      }
-
-      const pollMs = resolveOptionalIntegerArg(args, "pollMs", 1);
-      if (!pollMs.ok) {
-        return pollMs;
-      }
-
-      const maxWaitMs = timeoutMs.data ?? DEFAULT_NETWORK_WAIT_TIMEOUT_MS;
-      const intervalMs = pollMs.data ?? DEFAULT_NETWORK_WAIT_POLL_MS;
-      const startTime = Date.now();
-
-      while (Date.now() - startTime <= maxWaitMs) {
-        if (selector.data !== undefined) {
-          const actionResult = await driver.act(
-            {
-              type: "domQueryAll",
-              payload: {
-                selector: selector.data
-              }
-            },
-            targetId.data
-          );
-          const data = resolveDriverActionData(actionResult, "domQueryAll");
-          if (!data.ok) {
-            return data;
-          }
-
-          const elements = readElementList(data.data.elements);
-          const matchingElement = elements.find(
-            (element) =>
-              typeof element.text === "string" &&
-              element.text.includes(text.data)
-          );
-          if (matchingElement !== undefined) {
-            return createOk({
-              driver: driverKey,
-              targetId: targetId.data,
-              text: text.data,
-              selector: selector.data,
-              element: matchingElement,
-              elapsedMs: Date.now() - startTime
-            });
-          }
-        } else {
-          const snapshot = await driver.snapshot(targetId.data);
-          if (!isTargetKnownSnapshot(snapshot)) {
-            return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
-          }
-
-          const html = readSnapshotHtml(snapshot);
-          if (html !== undefined && html.includes(text.data)) {
-            return createOk({
-              driver: driverKey,
-              targetId: targetId.data,
-              text: text.data,
-              elapsedMs: Date.now() - startTime,
-              matchedIn: "snapshot.html"
-            });
-          }
-        }
-
-        await delay(intervalMs);
-      }
-
-      return createErr(
-        ErrorCode.E_TIMEOUT,
-        `Timed out waiting for text: ${text.data}`
-      );
-    })
-  );
-
-  toolMap.set("browser.wait.url", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const urlPattern = requireStringArg(args, "urlPattern");
-      if (!urlPattern.ok) {
-        return urlPattern;
-      }
-
-      const timeoutMs = resolveOptionalIntegerArg(args, "timeoutMs", 1);
-      if (!timeoutMs.ok) {
-        return timeoutMs;
-      }
-
-      const pollMs = resolveOptionalIntegerArg(args, "pollMs", 1);
-      if (!pollMs.ok) {
-        return pollMs;
-      }
-
-      const maxWaitMs = timeoutMs.data ?? DEFAULT_NETWORK_WAIT_TIMEOUT_MS;
-      const intervalMs = pollMs.data ?? DEFAULT_NETWORK_WAIT_POLL_MS;
-      const startTime = Date.now();
-
-      while (Date.now() - startTime <= maxWaitMs) {
-        const snapshot = await driver.snapshot(targetId.data);
-        if (!isTargetKnownSnapshot(snapshot)) {
-          return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
-        }
-
-        const currentUrl = readSnapshotUrl(snapshot);
-        if (currentUrl !== undefined && currentUrl.includes(urlPattern.data)) {
-          return createOk({
-            driver: driverKey,
-            targetId: targetId.data,
-            urlPattern: urlPattern.data,
-            currentUrl,
-            elapsedMs: Date.now() - startTime
-          });
-        }
-
-        await delay(intervalMs);
-      }
-
-      return createErr(
-        ErrorCode.E_TIMEOUT,
-        `Timed out waiting for URL: ${urlPattern.data}`
-      );
-    })
-  );
-
-  toolMap.set("browser.console.list", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const consoleType = resolveOptionalStringArg(args, "type");
-      if (!consoleType.ok) {
-        return consoleType;
-      }
-
-      const contains = resolveOptionalStringArg(args, "contains");
-      if (!contains.ok) {
-        return contains;
-      }
-
-      const since = resolveOptionalTimestampArg(args, "since");
-      if (!since.ok) {
-        return since;
-      }
-
-      const limit = resolveOptionalIntegerArg(args, "limit", 1);
-      if (!limit.ok) {
-        return limit;
-      }
-
-      const snapshot = await driver.snapshot(targetId.data);
-      if (!isTargetKnownSnapshot(snapshot)) {
-        return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
-      }
-
-      if (hasConsoleEntriesGetter(driver)) {
-        const entries = filterConsoleEntries(
-          readConsoleEntries(driver.getConsoleEntries(targetId.data)),
-          {
-            type: consoleType.data,
-            contains: contains.data,
-            sinceMs: since.data,
-            limit: limit.data
-          }
-        );
-        return createOk({
-          driver: driverKey,
-          targetId: targetId.data,
-          entries
-        });
-      }
-
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        entries: []
-      });
-    })
-  );
-
-  toolMap.set("browser.network.list", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const urlContains = resolveOptionalStringArg(args, "urlContains");
-      if (!urlContains.ok) {
-        return urlContains;
-      }
-
-      const method = resolveOptionalStringArg(args, "method");
-      if (!method.ok) {
-        return method;
-      }
-
-      const status = resolveOptionalIntegerArg(args, "status", 100);
-      if (!status.ok) {
-        return status;
-      }
-
-      const since = resolveOptionalTimestampArg(args, "since");
-      if (!since.ok) {
-        return since;
-      }
-
-      const limit = resolveOptionalIntegerArg(args, "limit", 1);
-      if (!limit.ok) {
-        return limit;
-      }
-
-      const snapshot = await driver.snapshot(targetId.data);
-      if (!isTargetKnownSnapshot(snapshot)) {
-        return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
-      }
-
-      const requests = filterNetworkSummaries(readNetworkRequestSummaries(snapshot), {
-        urlContains: urlContains.data,
-        method: method.data,
-        status: status.data,
-        sinceMs: since.data,
-        limit: limit.data
-      });
-
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        requests
-      });
-    })
-  );
-
-  toolMap.set("browser.network.harExport", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const includeBodiesRaw = args.includeBodies;
-      if (includeBodiesRaw !== undefined && typeof includeBodiesRaw !== "boolean") {
-        return createErr(
-          ErrorCode.E_INVALID_ARG,
-          "includeBodies must be a boolean when provided."
-        );
-      }
-      const includeBodies = includeBodiesRaw === true;
-
-      const urlContains = resolveOptionalStringArg(args, "urlContains");
-      if (!urlContains.ok) {
-        return urlContains;
-      }
-
-      const method = resolveOptionalStringArg(args, "method");
-      if (!method.ok) {
-        return method;
-      }
-
-      const status = resolveOptionalIntegerArg(args, "status", 100);
-      if (!status.ok) {
-        return status;
-      }
-
-      const since = resolveOptionalTimestampArg(args, "since");
-      if (!since.ok) {
-        return since;
-      }
-
-      const limit = resolveOptionalIntegerArg(args, "limit", 1);
-      if (!limit.ok) {
-        return limit;
-      }
-
-      const snapshot = await driver.snapshot(targetId.data);
-      if (!isTargetKnownSnapshot(snapshot)) {
-        return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
-      }
-
-      const filteredSummaries = filterNetworkSummaries(readNetworkRequestSummaries(snapshot), {
-        urlContains: urlContains.data,
-        method: method.data,
-        status: status.data,
-        sinceMs: since.data,
-        limit: limit.data
-      });
-      const har = createHarLog(filteredSummaries, includeBodies, (requestId) => {
-        if (!hasNetworkResponseBodyGetter(driver)) {
-          return undefined;
-        }
-
-        return driver.getNetworkResponseBody(requestId, targetId.data);
-      });
-
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        har
-      });
-    })
-  );
-
-  toolMap.set("browser.network.waitFor", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const urlPattern = requireStringArg(args, "urlPattern");
-      if (!urlPattern.ok) {
-        return urlPattern;
-      }
-
-      const method = resolveOptionalStringArg(args, "method");
-      if (!method.ok) {
-        return method;
-      }
-
-      const status = resolveOptionalIntegerArg(args, "status", 100);
-      if (!status.ok) {
-        return status;
-      }
-
-      const timeoutMs = resolveOptionalIntegerArg(args, "timeoutMs", 1);
-      if (!timeoutMs.ok) {
-        return timeoutMs;
-      }
-
-      const pollMs = resolveOptionalIntegerArg(args, "pollMs", 1);
-      if (!pollMs.ok) {
-        return pollMs;
-      }
-
-      const methodPattern = method.data?.toUpperCase();
-      const expectedStatus = status.data;
-      const maxWaitMs = timeoutMs.data ?? DEFAULT_NETWORK_WAIT_TIMEOUT_MS;
-      const intervalMs = pollMs.data ?? DEFAULT_NETWORK_WAIT_POLL_MS;
-      const startTime = Date.now();
-
-      while (Date.now() - startTime <= maxWaitMs) {
-        const snapshot = await driver.snapshot(targetId.data);
-        if (!isTargetKnownSnapshot(snapshot)) {
-          return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
-        }
-
-        const summaries = readNetworkRequestSummaries(snapshot);
-        const matchedSummary = summaries
-          .slice()
-          .reverse()
-          .find((summary) => {
-            if (!summary.url.includes(urlPattern.data)) {
-              return false;
-            }
-
-            if (
-              methodPattern !== undefined &&
-              (summary.method === undefined || summary.method.toUpperCase() !== methodPattern)
-            ) {
-              return false;
-            }
-
-            if (expectedStatus !== undefined && summary.status !== expectedStatus) {
-              return false;
-            }
-
-            return true;
-          });
-
-        if (matchedSummary !== undefined) {
-          return createOk({
-            driver: driverKey,
-            targetId: targetId.data,
-            request: matchedSummary,
-            elapsedMs: Date.now() - startTime
-          });
-        }
-
-        await delay(intervalMs);
-      }
-
-      return createErr(
-        ErrorCode.E_TIMEOUT,
-        `Timed out waiting for network response: ${urlPattern.data}`
-      );
-    })
-  );
-
-  toolMap.set("browser.network.responseBody", async (args) =>
-    runWithDefaultDriver(args, async (driver, driverKey) => {
-      const targetId = resolveTargetId(args, sessions);
-      if (!targetId.ok) {
-        return targetId;
-      }
-
-      const requestId = resolveRequestId(args);
-      if (!requestId.ok) {
-        return requestId;
-      }
-
-      const snapshot = await driver.snapshot(targetId.data);
-      if (!isTargetKnownSnapshot(snapshot)) {
-        return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
-      }
-
-      if (hasNetworkResponseBodyGetter(driver)) {
-        const responseBody = driver.getNetworkResponseBody(requestId.data, targetId.data);
-        if (responseBody === undefined) {
-          return createErr(
-            ErrorCode.E_NOT_FOUND,
-            `Unknown requestId: ${requestId.data} (target: ${targetId.data})`
-          );
-        }
-
-        return createOk({
-          driver: driverKey,
-          targetId: targetId.data,
-          requestId: requestId.data,
-          body: responseBody.body,
-          encoding: responseBody.encoding
-        });
-      }
-
-      return createOk({
-        driver: driverKey,
-        targetId: targetId.data,
-        requestId: requestId.data,
-        body: "",
-        encoding: "utf8"
-      });
-    })
-  );
-
-  toolMap.set("browser.trace.get", async (args) => {
-    const limit = resolveOptionalIntegerArg(args, "limit", 1);
-    if (!limit.ok) {
-      return limit;
-    }
-
-    const traceState = traceStateBySession.get(args.sessionId);
-    const steps = applyLimitToTail(traceState?.steps ?? [], limit.data);
-    const keyResponses = applyLimitToTail(traceState?.keyResponses ?? [], limit.data);
-    const screenshots = applyLimitToTail(traceState?.screenshots ?? [], limit.data);
-
-    return createOk({
-      sessionId: args.sessionId,
-      steps,
-      keyResponses,
-      screenshots
-    });
-  });
-
-  for (const [toolName, handler] of [...toolMap.entries()]) {
-    toolMap.set(toolName, async (args) => {
-      const startedAtMs = Date.now();
-      const authorization = authorizeToolCall(args, toolName, config.authToken, allowedScopes);
-      if (!authorization.ok) {
-        const finishedAtMs = Date.now();
-        recordTrace(args.sessionId, toolName, args, authorization, startedAtMs, finishedAtMs);
-        return authorization;
-      }
-
-      const sessionAuthorization = authorizeSessionGovernance(args, sessions, config);
-      if (!sessionAuthorization.ok) {
-        const finishedAtMs = Date.now();
-        recordTrace(args.sessionId, toolName, args, sessionAuthorization, startedAtMs, finishedAtMs);
-        return sessionAuthorization;
-      }
-
-      const domainAuthorization = authorizeDomainAllowlist(toolName, args, config);
-      if (!domainAuthorization.ok) {
-        const finishedAtMs = Date.now();
-        recordTrace(args.sessionId, toolName, args, domainAuthorization, startedAtMs, finishedAtMs);
-        return domainAuthorization;
-      }
-
-      const response = await handler(args);
-      const finishedAtMs = Date.now();
-      recordTrace(args.sessionId, toolName, args, response, startedAtMs, finishedAtMs);
-      return response;
-    });
-  }
-
-  return toolMap;
-}
-
-export function createContainer(config: BrowserdConfig = loadBrowserdConfig()): BrowserdContainer {
-  const sessions = new SessionStore({
-    ttlMs: config.sessionTtlMs
-  });
-  const driverRegistry = new DriverRegistry();
-  const drivers = new Map<string, BrowserDriver>();
-  const cleanupHandlers: Array<() => void> = [];
-
-  if (config.sessionTtlMs > 0 && config.sessionCleanupIntervalMs > 0) {
-    const cleanupTimer = setInterval(() => {
-      sessions.cleanupExpired();
-    }, config.sessionCleanupIntervalMs);
-    cleanupTimer.unref?.();
-    cleanupHandlers.push(() => {
-      clearInterval(cleanupTimer);
-    });
-  }
-
-  function registerDriver(driverKey: string, driver: BrowserDriver): void {
-    driverRegistry.register(driverKey, driver);
-    drivers.set(driverKey, driver);
-  }
-
-  registerDriver(DEFAULT_DRIVER_KEY, createManagedDriver());
-  if (config.managedLocalEnabled) {
-    registerDriver(
-      MANAGED_LOCAL_DRIVER_KEY,
-      createManagedLocalDriver({
-        browserName: config.managedLocalLaunch.browserName,
-        headless: config.managedLocalLaunch.headless,
-        channel: config.managedLocalLaunch.channel,
-        executablePath: config.managedLocalLaunch.executablePath,
-        launchTimeoutMs: config.managedLocalLaunch.launchTimeoutMs,
-        args: [...config.managedLocalLaunch.args]
-      })
-    );
-  }
-  const chromeRelayDriver =
-    config.chromeRelayMode === "extension"
-      ? (() => {
-          const extensionBridge = createChromeRelayExtensionBridge({
-            relayUrl: config.chromeRelayUrl,
-            token: config.chromeRelayExtensionToken,
-            requestTimeoutMs: config.chromeRelayExtensionRequestTimeoutMs
-          });
-          cleanupHandlers.push(() => {
-            void extensionBridge.close();
-          });
-
-          return createChromeRelayDriver({
-            relayUrl: config.chromeRelayUrl,
-            runtime: createChromeRelayExtensionRuntime({
-              transport: {
-                invoke: async (method, params) => await extensionBridge.invoke(method, params),
-                isConnected: () => extensionBridge.isConnected(),
-                onEvent: (listener) => extensionBridge.onEvent(listener)
-              }
-            })
-          });
-        })()
-      : createChromeRelayDriver({ relayUrl: config.chromeRelayUrl });
-  registerDriver("chrome-relay", chromeRelayDriver);
-  registerDriver("remote-cdp", createRemoteCdpDriver({ cdpUrl: config.remoteCdpUrl }));
-  const defaultDriverKey = drivers.has(config.defaultDriver)
-    ? config.defaultDriver
-    : DEFAULT_DRIVER_KEY;
-
-  return {
-    config,
-    drivers,
-    driverRegistry,
-    sessions,
-    mcpServer: createMcpStdioServer(
-      createBrowserdToolMap(drivers, sessions, defaultDriverKey, config)
-    ),
-    close() {
-      for (const cleanupHandler of [...cleanupHandlers].reverse()) {
-        cleanupHandler();
-      }
-    }
-  };
-}