Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

34.4 KB
Raw Blame
/**
 * The built-in browser as the routes drive it: one object per platform generation that owns
 * the shell link, the tab registry, the driver and actions over them, the history, the
 * settings, and the events the admins' windows hear.
 *
 * Availability comes first on every call that needs the shell: no port means this server is
 * not the desktop shell's child (`not_desktop`), an unanswered hello a shell too old to host
 * the browser (`shell_unsupported`), and an open nobody claims no window to put the tab in
 * (`no_window`). Tabs themselves are created by the Web App — a <webview> is an element of its
 * page — so opening one is a request published to the admins' windows, answered by a claim.
 *
 * Every agent action names a tab (`active` included), makes it the active one, and is
 * bracketed by `builtin_browser_activity` events so the window can show the agent at work.
 *
 * Load: the shell measures its guests every ~10 s, and this turns each measurement into the
 * browser's `metrics` — the tabs' memory with the verdict of load.ts — for the status and the
 * windows. And it keeps the tabs nobody is looking at or driving cheap: every tab but the one a
 * window shows and those an agent acts in (and for a grace period after) may be throttled by the
 * shell while it is out of sight.
 */
import os from "node:os";
import type {
  BuiltinBrowserAction,
  BuiltinBrowserExecResult,
  BuiltinBrowserHistoryEntry,
  BuiltinBrowserImportRequest,
  BuiltinBrowserImportResult,
  BuiltinBrowserImportSource,
  BuiltinBrowserMetrics,
  BuiltinBrowserScanResult,
  BuiltinBrowserScreenshot,
  BuiltinBrowserServerEvent,
  BuiltinBrowserSettings,
  BuiltinBrowserStatus,
  BuiltinBrowserTab,
  BuiltinBrowserTabsResponse,
  BuiltinBrowserUnavailableReason,
  DesktopBrowserEvent,
} from "../api/types.js";
import { HttpError } from "../http/errors.js";
import { BrowserActions, DEFAULT_ACTION_TIMING } from "./actions.js";
import type { ActionTiming } from "./actions.js";
import { BrowserDriver, mapLinkError, tabCrashedError } from "./driver.js";
import { HistoryStore, historyFile, isWebUrl } from "./history.js";
import { listImportSources, readCookies, readHistory } from "./import/index.js";
import { assessLoad, systemMemory } from "./load.js";
import { SettingsStore, settingsFile } from "./settings.js";
import { ShellLink, ShellLinkError, parseTab } from "./shell-link.js";
import type { BrowserShellPort, ShellLinkTiming } from "./shell-link.js";
import { TabRegistry } from "./tabs.js";
import type { OpenRequest } from "./tabs.js";

export interface BrowserTiming extends ShellLinkTiming, ActionTiming {
  /** How long an opened tab has to be claimed by a window. */
  openClaimMs: number;
  /** How long a closed tab has to disappear. */
  closeWaitMs: number;
  /** The shell's tab list after a handshake. */
  tabsTimeoutMs: number;
  /** Tab events within this window reach the admins as one `builtin_browser_tabs`. */
  publishDelayMs: number;
  /** After an agent's action in a tab (or a new tab opening), how long it runs unthrottled. */
  throttleGraceMs: number;
}

/**
 * The most tabs the browser holds; an agent's new tab beyond them is refused. Twenty busy
 * shopping and news sites held 3.3 GB between them (measured on Linux), which is already more
 * than an 8 GB laptop can spare; the load warning speaks up well before this.
 */
export const MAX_TABS = 20;
/** A page may open this many tabs (popups, target=_blank) in any POPUP_WINDOW_MS; more are dropped. */
const POPUP_LIMIT = 3;
const POPUP_WINDOW_MS = 5_000;

const DEFAULT_TIMING: Pick<
  BrowserTiming,
  "openClaimMs" | "closeWaitMs" | "tabsTimeoutMs" | "publishDelayMs" | "throttleGraceMs"
> = {
  openClaimMs: 15_000,
  closeWaitMs: 5_000,
  tabsTimeoutMs: 5_000,
  // A page announces itself in bursts (start, navigate, title, icon, stop), and a busy one never
  // stops (a ticking title); the windows get the tab list at most five times a second.
  publishDelayMs: 200,
  throttleGraceMs: 30_000,
};
/** How long the shell gets to apply a throttling change. */
const THROTTLE_TIMEOUT_MS = 5_000;

/** The system-browser importer (./import), injectable for tests. */
export interface Importer {
  listImportSources: typeof listImportSources;
  readCookies: typeof readCookies;
  readHistory: typeof readHistory;
}

const UNAVAILABLE: Record<BuiltinBrowserUnavailableReason, string> = {
  not_desktop:
    "The built-in browser needs the Adelie desktop app, and this server is not running inside it.",
  shell_unsupported:
    "This installation of the desktop app is too old to host the built-in browser; update the app.",
  no_window: "No Adelie window took the tab; open the app window and try again.",
};

/** 503 `browser_unavailable`, with the reason the routes put beside the code. */
export class BrowserUnavailableError extends HttpError {
  constructor(readonly reason: BuiltinBrowserUnavailableReason) {
    super(503, "browser_unavailable", UNAVAILABLE[reason]);
  }
}

/** No such profile on this machine, as the import routes answer it. */
function sourceNotFound(sourceId: string): HttpError {
  return new HttpError(
    404,
    "source_not_found",
    `No browser profile '${sourceId}' was found on this machine.`,
  );
}

/**
 * Why an import could not read a store: the profile gone since it was listed (the importer's
 * ImportSourceNotFoundError) is the same 404 as one never listed; anything else is 422.
 */
function importError(err: unknown, sourceId: string, what: "cookies" | "history"): HttpError {
  if ((err as { code?: unknown } | null)?.code === "source_not_found") {
    return sourceNotFound(sourceId);
  }
  return new HttpError(422, "import_failed", `The ${what} could not be read: ${messageOf(err)}`);
}

function invalidUrl(url: unknown): HttpError {
  return new HttpError(
    400,
    "invalid_url",
    `${JSON.stringify(url)} is not a web address the browser can open (http, https, or about:blank).`,
  );
}

/**
 * The page a tab opens or navigates to: a web URL or about:blank. A bare host gets a scheme —
 * https, or http for this machine's own servers — as an address bar would give it.
 */
export function browserUrl(raw: unknown, blankWhenEmpty: boolean): string {
  if (raw === undefined || raw === null || raw === "") {
    if (blankWhenEmpty) return "about:blank";
    throw invalidUrl(raw);
  }
  if (typeof raw !== "string") throw invalidUrl(raw);
  const text = raw.trim();
  if (text.toLowerCase() === "about:blank") return "about:blank";
  // `name:` followed by a digit is a host and port (`localhost:5173`), anything else a scheme.
  const scheme = /^([a-z][a-z0-9+.-]*):(?!\d)/i.exec(text)?.[1]?.toLowerCase();
  if (scheme !== undefined && scheme !== "http" && scheme !== "https") throw invalidUrl(raw);
  const withScheme =
    scheme !== undefined
      ? text
      : /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i.test(text)
        ? `http://${text}`
        : `https://${text}`;
  let url: URL;
  try {
    url = new URL(withScheme);
  } catch {
    throw invalidUrl(raw);
  }
  if ((url.protocol !== "http:" && url.protocol !== "https:") || url.hostname === "") {
    throw invalidUrl(raw);
  }
  return url.toString();
}

/**
 * A homepage as PUT /settings takes it: null for none, else a web page read by the rule above,
 * a bare host given its scheme. Never the blank page: that is what no homepage already opens.
 */
export function homepageUrl(raw: unknown): string | null {
  if (raw === null) return null;
  let url: string | null;
  try {
    url = browserUrl(raw, false);
  } catch {
    url = null;
  }
  if (url === null || !isWebUrl(url)) {
    throw new HttpError(
      400,
      "invalid_url",
      `${JSON.stringify(raw)} is not a web address a homepage can be (http or https).`,
    );
  }
  return url;
}

/**
 * What raw CDP may not do: reach other targets (`Target.*`: open, attach to or close pages the
 * browser does not know), or navigate the tab where the browser would not go. The shell guards
 * the page's own navigations only; one that CDP makes passes it, so `Page.navigate` gets the
 * address bar's rule here: a web page or about:blank.
 */
function checkRawCdp(method: string, params: Record<string, unknown> | undefined): void {
  if (method.startsWith("Target.")) {
    throw new HttpError(
      403,
      "cdp_refused",
      `${method} is not available through the built-in browser; open, switch and close tabs with penguin browser open, switch and close.`,
    );
  }
  if (method === "Page.navigate") browserUrl(params?.url, false);
}

export interface BuiltinBrowserDeps {
  /** The shell's message port; null when this server is not the desktop shell's child. */
  port: BrowserShellPort | null;
  /** The data root; the history and the settings live under it. */
  root: string;
  /** Sends one event to every admin's user channel. */
  publish(event: BuiltinBrowserServerEvent): void;
  log(line: string): void;
  now?: () => number;
  sleep?: (ms: number) => Promise<void>;
  importer?: Importer;
  timing?: Partial<BrowserTiming>;
  /** This computer's memory, for the load warning (os.freemem / os.totalmem by default). */
  systemMemory?: () => { freeBytes: number; totalBytes: number };
  /** process.platform by default. */
  platform?: string;
}

interface Connected {
  link: ShellLink;
  driver: BrowserDriver;
  actions: BrowserActions;
}

export class BuiltinBrowser {
  readonly tabs: TabRegistry;
  readonly history: HistoryStore;
  readonly settings: SettingsStore;
  private readonly connected: Connected | null;
  private readonly timing: typeof DEFAULT_TIMING;
  /** How long an opened web page gets to load before POST /tabs answers. */
  private readonly loadWaitMs: number;
  private readonly importer: Importer;
  /** Agent actions in flight per tab, and the session the latest one came from. */
  private readonly inflight = new Map<number, { count: number; sessionId?: string }>();
  /** Per opener tab, when its recent popups were let through (see `openFromPage`). */
  private readonly popups = new Map<number, number[]>();
  private readonly now: () => number;
  private publishTimer: NodeJS.Timeout | null = null;
  /** The last tab list the windows were sent, to skip sending the same one again. */
  private published: string | null = null;
  /** The shell's latest measurement with its verdict; null before the first. */
  private metrics: BuiltinBrowserMetrics | null = null;
  /** Per tab, when an agent last acted in it (or it opened): it runs unthrottled for a while after. */
  private readonly actedAt = new Map<number, number>();
  /** The throttled tabs the shell was last told of, as a key; null when it must be told again. */
  private throttleSent: string | null = null;
  /** An older shell does not throttle: every tab runs at full speed, as it always did. */
  private throttleUnsupported = false;
  /** The tab a window shows on screen (POST /tabs/on-screen); never throttled while it is there. */
  private onScreen: number | null = null;
  private throttleTimer: NodeJS.Timeout | null = null;
  private disposed = false;

  constructor(private readonly deps: BuiltinBrowserDeps) {
    const now = deps.now ?? Date.now;
    this.now = now;
    this.timing = { ...DEFAULT_TIMING, ...deps.timing };
    this.loadWaitMs = deps.timing?.loadWaitMs ?? DEFAULT_ACTION_TIMING.loadWaitMs;
    this.importer = deps.importer ?? { listImportSources, readCookies, readHistory };
    this.tabs = new TabRegistry(now);
    this.history = new HistoryStore(historyFile(deps.root), { now, log: deps.log });
    this.settings = new SettingsStore(settingsFile(deps.root), deps.log);
    if (deps.port === null) {
      this.connected = null;
      return;
    }
    const link = new ShellLink(deps.port, deps.timing, now, deps.log);
    const driver = new BrowserDriver(link, { now, ...(deps.sleep ? { sleep: deps.sleep } : {}) });
    const actions = new BrowserActions({
      driver,
      tabs: this.tabs,
      now,
      ...(deps.sleep ? { sleep: deps.sleep } : {}),
      ...(deps.timing ? { timing: deps.timing } : {}),
    });
    this.connected = { link, driver, actions };
    link.onEvent((event) => this.onShellEvent(event));
    link.onConnect(() => this.refreshTabs());
  }

  // --- availability and tabs ------------------------------------------------

  /** GET /status: never an error — an unavailable browser says why. Retries a failed handshake. */
  async status(): Promise<BuiltinBrowserStatus> {
    const reason = await this.unavailability(true);
    return {
      available: reason === null,
      ...(reason !== null ? { reason } : {}),
      tabs: this.tabs.list(),
      activeTabId: this.tabs.activeTabId,
      ...(this.metrics !== null ? { metrics: this.metrics } : {}),
    };
  }

  /** GET /tabs. */
  async listTabs(): Promise<BuiltinBrowserTabsResponse> {
    await this.ready();
    return { tabs: this.tabs.list(), activeTabId: this.tabs.activeTabId };
  }

  /**
   * POST /tabs: asks the admins' windows for a tab — at the address given, else at the
   * homepage, else blank — waits for one to claim it, and, for a web page, for the page to load.
   */
  async openTab(opts: {
    url?: unknown;
    sessionId?: string;
    activate?: boolean;
  }): Promise<BuiltinBrowserTab> {
    const { driver } = await this.ready();
    const url = await this.newTabUrl(opts.url);
    if (this.tabsHeld() >= MAX_TABS) {
      throw new HttpError(
        409,
        "too_many_tabs",
        `The built-in browser holds ${MAX_TABS} tabs, the most it keeps; close some first (penguin browser close <tab-id>).`,
      );
    }
    const request = this.requestOpen({
      url,
      activate: opts.activate !== false,
      ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
    });
    const tabId = await this.tabs.waitForClaim(request.requestId, this.timing.openClaimMs);
    if (tabId === null) throw new BrowserUnavailableError("no_window");
    if (!this.tabs.has(tabId)) await this.refreshTabs().catch(() => undefined);
    // The agent's (or the panel's) new tab: its grace runs from now, as after an action.
    this.actedAt.set(tabId, this.now());
    this.syncThrottle();
    if (isWebUrl(url)) {
      // A window claims the tab as soon as it exists, on its initial empty document, which reads
      // as loaded: the page asked for is waited for once it has committed.
      const deadline = this.now() + this.loadWaitMs;
      await this.tabs.waitForFirstPage(tabId, this.loadWaitMs);
      await driver.waitForLoad(tabId, Math.max(0, deadline - this.now()));
    }
    return this.tabOrThrow(tabId);
  }

  /** POST /tabs/claim: the window that created a requested tab names it. */
  async claim(requestId: string, tabId: number): Promise<void> {
    await this.ready();
    const outcome = this.tabs.claim(requestId, tabId);
    if (outcome === "duplicate") {
      throw new HttpError(
        409,
        "already_claimed",
        "Another window already created this tab; remove the duplicate.",
      );
    }
    if (outcome === "unknown") {
      throw new HttpError(
        409,
        "unknown_request",
        "No tab is waiting for this request any more; remove the tab.",
      );
    }
    if (this.tabs.openRequest(requestId)?.activate === true && this.tabs.activate(tabId)) {
      this.schedulePublish();
    }
  }

  /** POST /tabs/:tab/activate: the user focused a tab, or the agent switched to one. */
  async activate(tab: string): Promise<BuiltinBrowserTab> {
    await this.ready();
    const tabId = this.resolve(tab);
    if (this.tabs.activate(tabId)) this.schedulePublish();
    return this.tabOrThrow(tabId);
  }

  /**
   * POST /tabs/on-screen: the tab a window shows now, or none (its panel closed, the window
   * hidden). That tab is left at full speed; the one it replaces may be throttled.
   */
  setOnScreen(tabId: number | null): void {
    this.onScreen = tabId;
    this.syncThrottle();
  }

  /** DELETE /tabs/:tab: the window holding the tab removes it; this waits until it is gone. */
  async close(tab: string): Promise<void> {
    await this.ready();
    const tabId = this.resolve(tab);
    this.deps.publish({ type: "builtin_browser_close", tabId });
    if (!(await this.tabs.waitForClose(tabId, this.timing.closeWaitMs))) {
      throw new BrowserUnavailableError("no_window");
    }
  }

  // --- agent actions ----------------------------------------------------------

  /** POST /tabs/:tab/navigate. `active` with no tab open opens one. */
  async navigate(tab: string, rawUrl: unknown, sessionId?: string): Promise<BuiltinBrowserTab> {
    const url = browserUrl(rawUrl, false);
    await this.ready();
    if (tab === "active" && this.tabs.activeTabId === null) {
      return this.openTab({
        url,
        activate: true,
        ...(sessionId !== undefined ? { sessionId } : {}),
      });
    }
    return this.act(tab, "navigate", sessionId, async (tabId, actions) => {
      await actions.navigate(tabId, url);
      return this.tabOrThrow(tabId);
    });
  }

  scan(
    tab: string,
    opts: { textOnly?: boolean; maxChars?: number; instruction?: string },
    sessionId?: string,
  ): Promise<BuiltinBrowserScanResult> {
    return this.act(tab, "scan", sessionId, async (tabId, actions) => {
      const { content, truncated } = await actions.scan(tabId, opts);
      return {
        tab: this.tabOrThrow(tabId),
        tabs: this.tabs.list(),
        activeTabId: this.tabs.activeTabId,
        content,
        ...(truncated ? { truncated } : {}),
      };
    });
  }

  exec(
    tab: string,
    script: string,
    opts: { noMonitor?: boolean; timeoutMs?: number; acceptDialogs?: boolean },
    sessionId?: string,
  ): Promise<BuiltinBrowserExecResult> {
    return this.act(tab, "exec", sessionId, (tabId, actions) => actions.exec(tabId, script, opts));
  }

  click(
    tab: string,
    target: { selector: string; index?: number } | { x: number; y: number },
    opts: { acceptDialogs?: boolean },
    sessionId?: string,
  ): Promise<BuiltinBrowserExecResult> {
    return this.act(tab, "click", sessionId, (tabId, actions) =>
      actions.click(tabId, target, opts),
    );
  }

  type(
    tab: string,
    opts: { text: string; selector?: string; submit?: boolean; acceptDialogs?: boolean },
    sessionId?: string,
  ): Promise<BuiltinBrowserExecResult> {
    return this.act(tab, "type", sessionId, (tabId, actions) => actions.type(tabId, opts));
  }

  screenshot(
    tab: string,
    opts: { fullPage?: boolean },
    sessionId?: string,
  ): Promise<BuiltinBrowserScreenshot> {
    return this.act(tab, "screenshot", sessionId, (tabId, actions) =>
      actions.screenshot(tabId, opts),
    );
  }

  cdp(
    tab: string,
    method: string,
    params: Record<string, unknown> | undefined,
    sessionId?: string,
  ): Promise<unknown> {
    checkRawCdp(method, params);
    return this.act(tab, "cdp", sessionId, (tabId, actions) => actions.cdp(tabId, method, params));
  }

  // --- settings ----------------------------------------------------------------

  /** GET /settings: the server's own file, so it needs no shell. */
  getSettings(): Promise<BuiltinBrowserSettings> {
    return this.settings.read();
  }

  /** PUT /settings: the homepage as a web address (a bare host gets a scheme), or null for none. */
  async updateSettings(update: { homepage: unknown }): Promise<BuiltinBrowserSettings> {
    return this.settings.write({ homepage: homepageUrl(update.homepage) });
  }

  // --- import, history, data --------------------------------------------------

  listImportSources(): BuiltinBrowserImportSource[] {
    return this.importer.listImportSources();
  }

  /**
   * POST /import: cookies go into the browser's session through the shell, history into the
   * history file. With neither flag both are imported. `sourceId` may also name just a
   * browser (`chrome`), meaning its first profile.
   */
  async importFrom(req: BuiltinBrowserImportRequest): Promise<BuiltinBrowserImportResult> {
    const sources = this.importer.listImportSources();
    const source =
      sources.find((s) => s.id === req.sourceId) ?? sources.find((s) => s.browser === req.sourceId);
    if (source === undefined) throw sourceNotFound(req.sourceId);
    const both = req.cookies === undefined && req.history === undefined;
    const result: BuiltinBrowserImportResult = { sourceId: source.id, warnings: [] };
    if (both || req.cookies === true) {
      const { link } = await this.ready();
      let read: Awaited<ReturnType<Importer["readCookies"]>>;
      try {
        read = await this.importer.readCookies(source, {
          ...(req.domains !== undefined ? { domains: req.domains } : {}),
        });
      } catch (err) {
        throw importError(err, source.id, "cookies");
      }
      let written = { set: 0, failed: 0, errors: [] as string[] };
      if (read.cookies.length > 0) {
        try {
          written = (await link.request(
            { op: "set-cookies", cookies: read.cookies },
            30_000 + read.cookies.length * 20,
          )) as typeof written;
        } catch (err) {
          throw mapLinkError(err, -1);
        }
      }
      result.cookies = {
        found: read.found,
        imported: written.set,
        skipped: read.skipped,
        failed: written.failed,
      };
      result.warnings.push(...read.warnings);
      if (written.failed > 0) {
        const named = written.errors.slice(0, 3).join("; ");
        result.warnings.push(
          `${written.failed} cookies could not be set in the browser${named !== "" ? `: ${named}` : "."}`,
        );
      }
    }
    if (both || req.history === true) {
      let read: Awaited<ReturnType<Importer["readHistory"]>>;
      try {
        read = await this.importer.readHistory(source);
      } catch (err) {
        throw importError(err, source.id, "history");
      }
      result.history = { found: read.entries.length, imported: this.history.merge(read.entries) };
      result.warnings.push(...read.warnings);
    }
    return result;
  }

  searchHistory(query: string, limit: number): BuiltinBrowserHistoryEntry[] {
    return this.history.search(query, limit);
  }

  clearHistory(): void {
    this.history.clear();
  }

  /** POST /clear-data: the browser's cookies, cache or site storage. */
  async clearData(storages: ("cookies" | "cache" | "storage")[]): Promise<void> {
    const { link } = await this.ready();
    try {
      await link.request({ op: "clear-data", storages }, 60_000);
    } catch (err) {
      throw mapLinkError(err, -1);
    }
  }

  dispose(): void {
    if (this.disposed) return;
    this.disposed = true;
    if (this.publishTimer !== null) clearTimeout(this.publishTimer);
    this.publishTimer = null;
    if (this.throttleTimer !== null) clearTimeout(this.throttleTimer);
    this.throttleTimer = null;
    this.connected?.link.dispose();
    this.tabs.dispose();
    void this.history.dispose();
  }

  // --- internals ---------------------------------------------------------------

  private async unavailability(force: boolean): Promise<BuiltinBrowserUnavailableReason | null> {
    if (this.connected === null) return "not_desktop";
    return (await this.connected.link.handshake(force)) ? null : "shell_unsupported";
  }

  private async ready(): Promise<Connected> {
    const reason = await this.unavailability(false);
    if (reason !== null) throw new BrowserUnavailableError(reason);
    return this.connected!;
  }

  /** `active` or a tab id, to an open tab. */
  private resolve(tab: string): number {
    if (tab === "active") {
      const id = this.tabs.activeTabId;
      if (id === null)
        throw new HttpError(404, "no_tab", "No tab is open in the built-in browser.");
      return id;
    }
    const id = /^\d{1,15}$/.test(tab) ? Number(tab) : Number.NaN;
    if (!this.tabs.has(id)) {
      throw new HttpError(404, "no_such_tab", `Tab ${tab} is not open in the built-in browser.`);
    }
    return id;
  }

  private tabOrThrow(tabId: number): BuiltinBrowserTab {
    const tab = this.tabs.get(tabId);
    if (tab === undefined) {
      throw new HttpError(404, "no_such_tab", `Tab ${tabId} is not open in the built-in browser.`);
    }
    return tab;
  }

  /** The page a new tab opens: the address it was given, else the homepage, else the blank page. */
  private async newTabUrl(raw: unknown): Promise<string> {
    if (raw !== undefined && raw !== null && raw !== "") return browserUrl(raw, false);
    return (await this.settings.read()).homepage ?? "about:blank";
  }

  /**
   * One agent action on one tab: made active, running unthrottled and announced busy while it
   * runs. A tab whose page crashed answers `tab_crashed` at once, and so does an action whose
   * page crashed under it, whatever error that left behind.
   */
  private async act<T>(
    tab: string,
    action: BuiltinBrowserAction,
    sessionId: string | undefined,
    run: (tabId: number, actions: BrowserActions) => Promise<T>,
  ): Promise<T> {
    const { actions } = await this.ready();
    const tabId = this.resolve(tab);
    const crashed = this.tabs.get(tabId)?.crashed;
    if (crashed !== undefined) throw tabCrashedError(tabId, crashed);
    if (this.tabs.activate(tabId)) this.schedulePublish();
    this.activity(tabId, action, sessionId, 1);
    try {
      return await run(tabId, actions);
    } catch (err) {
      // The shell no longer has it: the registry catches up rather than waiting for the event.
      if (err instanceof HttpError && err.code === "no_such_tab" && this.tabs.remove(tabId)) {
        this.schedulePublish();
      }
      const crashedNow = this.tabs.get(tabId)?.crashed;
      if (crashedNow !== undefined) throw tabCrashedError(tabId, crashedNow);
      throw err;
    } finally {
      this.activity(tabId, action, sessionId, -1);
    }
  }

  private activity(
    tabId: number,
    action: BuiltinBrowserAction,
    sessionId: string | undefined,
    delta: 1 | -1,
  ): void {
    const entry = this.inflight.get(tabId) ?? { count: 0 };
    entry.count += delta;
    if (delta > 0 && sessionId !== undefined) entry.sessionId = sessionId;
    if (entry.count > 0) this.inflight.set(tabId, entry);
    else this.inflight.delete(tabId);
    if (delta < 0) this.actedAt.set(tabId, this.now());
    // Before the action's first command: the port keeps order, so the page is at full speed
    // by the time the action reaches it.
    this.syncThrottle();
    this.deps.publish({
      type: "builtin_browser_activity",
      tabId,
      busy: entry.count > 0,
      action,
      ...(sessionId !== undefined ? { sessionId } : {}),
    });
  }

  private requestOpen(opts: {
    url: string;
    activate: boolean;
    openerTabId?: number;
    sessionId?: string;
  }): OpenRequest {
    const request = this.tabs.createOpen({
      url: opts.url,
      activate: opts.activate,
      ...(opts.openerTabId !== undefined ? { openerTabId: opts.openerTabId } : {}),
    });
    this.deps.publish({
      type: "builtin_browser_open",
      requestId: request.requestId,
      url: opts.url,
      activate: opts.activate,
      ...(opts.openerTabId !== undefined ? { openerTabId: opts.openerTabId } : {}),
      ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
    });
    return request;
  }

  /**
   * A popup, or "Open link in new tab". The session of an action running in the opener is the
   * one that caused it. A page gets at most POPUP_LIMIT tabs in any POPUP_WINDOW_MS, and none
   * while the browser holds MAX_TABS: one looping on window.open would otherwise open tabs
   * without end. What goes over is dropped, with a log line.
   */
  private openFromPage(event: { url: string; openerTabId: number; background?: boolean }): void {
    const now = this.now();
    const recent = (this.popups.get(event.openerTabId) ?? []).filter(
      (at) => now - at < POPUP_WINDOW_MS,
    );
    const full = this.tabsHeld() >= MAX_TABS;
    if (full || recent.length >= POPUP_LIMIT) {
      this.popups.set(event.openerTabId, recent);
      this.deps.log(
        `builtin browser: dropped a popup of tab ${event.openerTabId}: ${
          full ? `the browser holds ${MAX_TABS} tabs` : `more than ${POPUP_LIMIT} in 5 s`
        }`,
      );
      return;
    }
    this.popups.set(event.openerTabId, [...recent, now]);
    const sessionId = this.inflight.get(event.openerTabId)?.sessionId;
    this.requestOpen({
      url: event.url,
      activate: event.background !== true,
      openerTabId: event.openerTabId,
      ...(sessionId !== undefined ? { sessionId } : {}),
    });
  }

  /** The tabs open, and those on their way (asked of a window, not yet claimed). */
  private tabsHeld(): number {
    return this.tabs.list().length + this.tabs.pendingOpens();
  }

  /** One shell event. Never throws: a failure is logged, and the next event starts clean. */
  private onShellEvent(event: DesktopBrowserEvent): void {
    try {
      this.applyShellEvent(event);
    } catch (err) {
      this.deps.log(`builtin browser: the shell's '${event.kind}' event failed: ${messageOf(err)}`);
    }
  }

  private applyShellEvent(event: DesktopBrowserEvent): void {
    switch (event.kind) {
      case "tab": {
        const previous = this.tabs.upsert(event.tab);
        if (previous === undefined) {
          // A new tab loads at full speed for the grace period, whoever opened it.
          if (!this.actedAt.has(event.tab.id)) this.actedAt.set(event.tab.id, this.now());
          this.syncThrottle();
        }
        this.history.observe(previous, event.tab);
        this.schedulePublish();
        break;
      }
      case "tab-closed":
        if (this.tabs.remove(event.tabId)) this.schedulePublish();
        this.inflight.delete(event.tabId);
        this.popups.delete(event.tabId);
        this.actedAt.delete(event.tabId);
        this.syncThrottle();
        break;
      case "tab-crashed":
        this.deps.log(
          `builtin browser: tab ${event.tabId}'s page crashed (${event.reason}, exit code ${event.exitCode})`,
        );
        if (this.tabs.markCrashed(event.tabId, event.reason)) this.schedulePublish();
        break;
      case "metrics":
        this.measure(event.tabs, event.totalKB);
        break;
      case "open-request":
        if (isWebUrl(event.url)) this.openFromPage(event);
        break;
      case "cdp-event":
        // An action's own subscription (driver.onCdpEvent); nothing for the registry.
        break;
    }
    // An event proves the shell speaks the protocol. A link that has not shaken hands yet (a
    // server that started under a running window) does it now, and learns the other tabs.
    if (this.connected !== null && !this.connected.link.connected) {
      void this.connected.link.handshake(true);
    }
  }

  private async refreshTabs(): Promise<void> {
    if (this.connected === null) return;
    const answer = (await this.connected.link.request(
      { op: "tabs" },
      this.timing.tabsTimeoutMs,
    )) as {
      tabs?: unknown;
    } | null;
    const tabs = Array.isArray(answer?.tabs)
      ? answer.tabs.map(parseTab).filter((tab): tab is BuiltinBrowserTab => tab !== null)
      : [];
    if (this.tabs.replaceAll(tabs)) this.schedulePublish();
    // A shell met again (a new generation, a restarted server) is told afresh which tabs to throttle.
    this.throttleSent = null;
    this.syncThrottle();
  }

  /** A measurement from the shell: judged (load.ts), kept for the status, and sent to the windows. */
  private measure(
    measured: { tabId: number; memoryKB: number; cpuPercent: number }[],
    totalKB: number,
  ) {
    const open = new Set(this.tabs.ids());
    const read =
      this.deps.systemMemory ?? (() => ({ freeBytes: os.freemem(), totalBytes: os.totalmem() }));
    const { freeBytes, totalBytes } = read();
    const system = systemMemory(this.deps.platform ?? process.platform, freeBytes, totalBytes);
    this.metrics = assessLoad(
      {
        at: this.now(),
        tabs: measured.filter((tab) => open.has(tab.tabId)),
        totalKB,
        ...(system !== undefined ? { system } : {}),
        tabCount: open.size,
      },
      this.metrics?.warnings ?? [],
    );
    this.deps.publish({ type: "builtin_browser_metrics", metrics: this.metrics });
  }

  /**
   * Tells the shell which tabs may be throttled while out of sight: every open tab but the one on
   * screen and those an agent is acting in or acted in within the grace period (new tabs
   * included). Sent only when the list changes, and re-checked when the earliest grace runs out.
   * A shell too old for the command leaves every tab at full speed, as before.
   */
  private syncThrottle(): void {
    const link = this.connected?.link;
    if (link === undefined || !link.connected || this.throttleUnsupported || this.disposed) return;
    const now = this.now();
    const grace = this.timing.throttleGraceMs;
    let recheckAt = Number.POSITIVE_INFINITY;
    const throttled: number[] = [];
    for (const id of this.tabs.ids()) {
      if (id === this.onScreen || this.inflight.has(id)) continue;
      const acted = this.actedAt.get(id);
      if (acted !== undefined && now - acted < grace) {
        recheckAt = Math.min(recheckAt, acted + grace);
        continue;
      }
      throttled.push(id);
    }
    if (this.throttleTimer !== null) clearTimeout(this.throttleTimer);
    this.throttleTimer = null;
    if (recheckAt !== Number.POSITIVE_INFINITY) {
      this.throttleTimer = setTimeout(() => {
        this.throttleTimer = null;
        this.syncThrottle();
      }, recheckAt - now);
      this.throttleTimer.unref?.();
    }
    throttled.sort((a, b) => a - b);
    const key = throttled.join(",");
    if (key === this.throttleSent) return;
    this.throttleSent = key;
    link
      .request({ op: "throttle", tabIds: throttled }, THROTTLE_TIMEOUT_MS)
      .catch((err: unknown) => {
        if (
          err instanceof ShellLinkError &&
          err.kind === "refused" &&
          err.message === "unknown_op"
        ) {
          this.throttleUnsupported = true;
          return;
        }
        // Told again with the next change.
        if (this.throttleSent === key) this.throttleSent = null;
      });
  }

  /** The tab list to the windows, once per burst of changes, and only when it differs from the last one sent. */
  private schedulePublish(): void {
    if (this.publishTimer !== null || this.disposed) return;
    this.publishTimer = setTimeout(() => {
      this.publishTimer = null;
      if (this.disposed) return;
      const tabs = this.tabs.list();
      const activeTabId = this.tabs.activeTabId;
      const snapshot = JSON.stringify({ tabs, activeTabId });
      if (snapshot === this.published) return;
      this.published = snapshot;
      try {
        this.deps.publish({ type: "builtin_browser_tabs", tabs, activeTabId });
      } catch (err) {
        this.published = null;
        this.deps.log(`builtin browser: the tab list could not be sent: ${messageOf(err)}`);
      }
    }, this.timing.publishDelayMs);
  }
}

const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));