@flrande/browserctl 0.1.0

package/apps/browserd/src/container.ts

@@ -0,0 +1,1531 @@
+import {
+  DriverRegistry,
+  SessionStore,
+  type BrowserDriver,
+  type BrowserDriverScreenshot
+} 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 { win32 as windowsPath } from "node:path";
+import { createChromeRelayExtensionBridge } from "./chrome-relay-extension-bridge";
+
+type CapabilityScope = "read" | "act" | "upload" | "download";
+type ChromeRelayMode = "cdp" | "extension";
+
+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[];
+  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_MANAGED_LOCAL_BROWSER_NAME: ManagedLocalBrowserName = "chromium";
+const DEFAULT_MANAGED_LOCAL_HEADLESS = true;
+const DEFAULT_CHROME_RELAY_MODE: ChromeRelayMode = "cdp";
+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 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.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"
+};
+
+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 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();
+  return normalizedValue === "extension" ? "extension" : DEFAULT_CHROME_RELAY_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);
+  if (chromeRelayMode === "extension" && chromeRelayExtensionToken === undefined) {
+    throw new Error(
+      "BROWSERD_CHROME_RELAY_EXTENSION_TOKEN is required when BROWSERD_CHROME_RELAY_MODE=extension."
+    );
+  }
+
+  const defaultDriver =
+    resolveNonEmptyString(env.BROWSERD_DEFAULT_DRIVER) ??
+    (managedLocalEnabled ? MANAGED_LOCAL_DRIVER_KEY : DEFAULT_DRIVER_KEY);
+
+  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),
+    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 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;
+}
+
+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 resolveWindowsPathWithinRoot(
+  inputPath: string,
+  rootPath: string,
+  context: "upload" | "download"
+): ToolResponse<string> {
+  const resolvedRoot = windowsPath.resolve(rootPath);
+  const resolvedPath = windowsPath.isAbsolute(inputPath)
+    ? windowsPath.resolve(inputPath)
+    : windowsPath.resolve(resolvedRoot, inputPath);
+  const relativePath = windowsPath.relative(
+    resolvedRoot.toLowerCase(),
+    resolvedPath.toLowerCase()
+  );
+  const isInRoot =
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && !windowsPath.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 = resolveWindowsPathWithinRoot(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 downloadPath =
+    requestedPath ??
+    (typeof download.path === "string" && download.path.trim().length > 0
+      ? download.path.trim()
+      : undefined);
+  if (downloadPath === undefined) {
+    return createErr(
+      ErrorCode.E_INTERNAL,
+      "Driver download payload is missing path required for allowlist enforcement."
+    );
+  }
+
+  const rootedPath = resolveWindowsPathWithinRoot(downloadPath, downloadRoot, "download");
+  if (!rootedPath.ok) {
+    return rootedPath;
+  }
+
+  return createOk({
+    ...download,
+    path: rootedPath.data
+  });
+}
+
+function createBrowserdToolMap(
+  drivers: Map<string, BrowserDriver>,
+  sessions: SessionStore,
+  defaultDriverKey: string,
+  config: BrowserdConfig
+): ToolMap {
+  const toolMap = buildToolMap();
+  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.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);
+      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.console.list", async (args) =>
+    runWithDefaultDriver(args, async (driver, driverKey) => {
+      const targetId = resolveTargetId(args, sessions);
+      if (!targetId.ok) {
+        return targetId;
+      }
+
+      const snapshot = await driver.snapshot(targetId.data);
+      if (!isTargetKnownSnapshot(snapshot)) {
+        return createErr(ErrorCode.E_NOT_FOUND, `Unknown targetId: ${targetId.data}`);
+      }
+
+      if (hasConsoleEntriesGetter(driver)) {
+        return createOk({
+          driver: driverKey,
+          targetId: targetId.data,
+          entries: driver.getConsoleEntries(targetId.data)
+        });
+      }
+
+      return createOk({
+        driver: driverKey,
+        targetId: targetId.data,
+        entries: []
+      });
+    })
+  );
+
+  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"
+      });
+    })
+  );
+
+  for (const [toolName, handler] of [...toolMap.entries()]) {
+    toolMap.set(toolName, async (args) => {
+      const authorization = authorizeToolCall(args, toolName, config.authToken, allowedScopes);
+      if (!authorization.ok) {
+        return authorization;
+      }
+
+      return await handler(args);
+    });
+  }
+
+  return toolMap;
+}
+
+export function createContainer(config: BrowserdConfig = loadBrowserdConfig()): BrowserdContainer {
+  const sessions = new SessionStore();
+  const driverRegistry = new DriverRegistry();
+  const drivers = new Map<string, BrowserDriver>();
+  const cleanupHandlers: Array<() => void> = [];
+
+  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();
+      }
+    }
+  };
+}