@flrande/browserctl 0.4.0-dev.15.1 → 0.5.0-dev.19.1

package/apps/browserd/src/container.ts

@@ -1,8 +1,11 @@
 import {
   DriverRegistry,
   SessionStore,
+  createNavigationMemoryStore,
   type BrowserDriver,
-  type BrowserDriverScreenshot
+  type BrowserDriverScreenshot,
+  type NavigationMemoryMode,
+  type NavigationSignal
 } from "../../../packages/core/src";
 import {
   createChromeRelayDriver,
@@ -23,11 +26,12 @@ import {
   type ToolCallArgs,
   type ToolMap
 } from "../../../packages/transport-mcp-stdio/src";
-import { win32 as windowsPath } from "node:path";
+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;
@@ -41,6 +45,18 @@ export type BrowserdConfig = {
   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;
@@ -61,6 +77,14 @@ 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",
@@ -76,6 +100,11 @@ const TOOL_SCOPE_BY_NAME: Readonly<Record<string, CapabilityScope>> = {
   "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",
@@ -90,7 +119,19 @@ const TOOL_SCOPE_BY_NAME: Readonly<Record<string, CapabilityScope>> = {
   "browser.frame.list": "read",
   "browser.frame.snapshot": "read",
   "browser.console.list": "read",
-  "browser.network.responseBody": "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 {
@@ -133,6 +174,15 @@ function parseOptionalNumber(value: string | undefined): number | 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) {
@@ -190,6 +240,24 @@ function parseChromeRelayMode(value: string | undefined): ChromeRelayMode {
   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>;
@@ -210,6 +278,9 @@ export function loadBrowserdConfig(
 
   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",
@@ -226,6 +297,22 @@ export function loadBrowserdConfig(
     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),
@@ -493,6 +580,229 @@ function resolveOptionalIntegerArg(
   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
@@ -599,6 +909,214 @@ function readNetworkRequestSummaries(snapshot: unknown): NetworkRequestSummary[]
   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);
@@ -643,22 +1161,247 @@ function authorizeToolCall(
   return createOk(null);
 }
 
-function resolveWindowsPathWithinRoot(
+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 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 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("..") && !windowsPath.isAbsolute(relativePath));
+    (!relativePath.startsWith("..") && !pathRuntime.isAbsolute(relativePath));
   if (!isInRoot) {
     return createErr(
       ErrorCode.E_PERMISSION,
@@ -679,7 +1422,7 @@ function applyUploadRoot(files: string[], uploadRoot: string | undefined): ToolR
 
   const rootedFiles: string[] = [];
   for (const file of files) {
-    const rootedPath = resolveWindowsPathWithinRoot(file, uploadRoot, "upload");
+    const rootedPath = resolvePathWithinRoot(file, uploadRoot, "upload");
     if (!rootedPath.ok) {
       return rootedPath;
     }
@@ -707,26 +1450,46 @@ function normalizeDownloadPayload(
   }
 
   const download = { ...rawDownload };
-  const downloadPath =
-    requestedPath ??
-    (typeof download.path === "string" && download.path.trim().length > 0
+  const actualPath =
+    typeof download.path === "string" && download.path.trim().length > 0
       ? download.path.trim()
-      : undefined);
-  if (downloadPath === undefined) {
+      : undefined;
+  if (actualPath === 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;
+  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: rootedPath.data
+    path: rootedActualPath.data
   });
 }
 
@@ -736,7 +1499,186 @@ function createBrowserdToolMap(
   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,
@@ -799,36 +1741,242 @@ function createBrowserdToolMap(
         status
       });
     } catch (error) {
-      return mapDriverError(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.profile.use", async (args) => {
-    const requestedProfile = requireStringArg(args, "profile");
-    if (!requestedProfile.ok) {
-      return requestedProfile;
+  toolMap.set("browser.memory.ttl.set", async (args) => {
+    const ttlDays = resolveOptionalIntegerArg(args, "ttlDays", 0);
+    if (!ttlDays.ok) {
+      return ttlDays;
     }
 
-    if (!drivers.has(requestedProfile.data)) {
-      return createErr(ErrorCode.E_NOT_FOUND, `Unknown driver profile: ${requestedProfile.data}`);
+    if (ttlDays.data === undefined) {
+      return createErr(ErrorCode.E_INVALID_ARG, "ttlDays is required and must be an integer greater than or equal to 0.");
     }
 
-    sessions.useProfile(args.sessionId, requestedProfile.data);
-    return createOk({
-      profile: requestedProfile.data
-    });
+    try {
+      return createOk(await navigationMemoryStore.setTtlDays(ttlDays.data));
+    } catch (error) {
+      return mapNavigationMemoryError(error);
+    }
   });
 
-  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();
@@ -1270,7 +2418,7 @@ function createBrowserdToolMap(
         return requestedPath;
       }
 
-      const download = await driver.waitDownload(targetId.data);
+      const download = await driver.waitDownload(targetId.data, undefined, requestedPath.data);
       const normalizedDownload = normalizeDownloadPayload(
         download,
         requestedPath.data,
@@ -1288,6 +2436,211 @@ function createBrowserdToolMap(
     })
   );
 
+  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);
@@ -1295,16 +2648,45 @@ function createBrowserdToolMap(
         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: driver.getConsoleEntries(targetId.data)
+          entries
         });
       }
 
@@ -1316,6 +2698,128 @@ function createBrowserdToolMap(
     })
   );
 
+  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);
@@ -1447,14 +2951,53 @@ function createBrowserdToolMap(
     })
   );
 
+  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;
       }
 
-      return await handler(args);
+      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;
     });
   }
 
@@ -1462,11 +3005,23 @@ function createBrowserdToolMap(
 }
 
 export function createContainer(config: BrowserdConfig = loadBrowserdConfig()): BrowserdContainer {
-  const sessions = new SessionStore();
+  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);