Skip to content

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

11.8 KB
Raw Blame
/**
 * The built-in browser's tab registry: what the shell reports (its `tab` / `tab-closed` events,
 * and the full list it answers after each handshake), which tab is active, and the tabs that
 * were asked for but do not exist yet.
 *
 * The shell is the truth about which guests exist; this is its reflection plus two facts the
 * shell does not have. The active tab is the last one the agent used or the user focused, and
 * falls back to the most recently created one. An open request is a tab the server asked the
 * Web App to create (POST /tabs, or a popup the shell turned into a request): the page creates
 * the <webview>, learns its webContents id, and claims the request with it — the first claim
 * wins, and a second window's claim is a duplicate it should remove.
 */
import { randomUUID } from "node:crypto";
import type { BuiltinBrowserTab } from "../api/types.js";

/** How long an unclaimed open request stays claimable. */
const OPEN_REQUEST_TTL_MS = 60_000;

export interface OpenRequest {
  requestId: string;
  url: string;
  /** Whether the tab becomes the active one once it exists. */
  activate: boolean;
  /** The tab whose popup (or "Open link in new tab") this is. */
  openerTabId?: number;
  createdAt: number;
  /** The tab that claimed it; null until then. */
  claimedTabId: number | null;
}

interface OpenState extends OpenRequest {
  waiters: Set<(tabId: number | null) => void>;
}

export type ClaimOutcome = "claimed" | "duplicate" | "unknown";

/**
 * Whether a tab is past its initial empty document: its first page committed (the shell reports
 * no address before that), or its first load ended without one.
 */
function firstPageStarted(tab: BuiltinBrowserTab): boolean {
  return tab.url !== "" || !tab.loading;
}

export class TabRegistry {
  /** In creation order: the last entry is the most recently created tab. */
  private tabs = new Map<number, BuiltinBrowserTab>();
  private active: number | null = null;
  /** A tab activated before the shell reported it. */
  private pendingActive: number | null = null;
  private readonly opens = new Map<string, OpenState>();
  private readonly closeWaiters = new Map<number, Set<() => void>>();
  private readonly firstPageWaiters = new Map<number, Set<(started: boolean) => void>>();
  private readonly timers = new Set<NodeJS.Timeout>();

  constructor(private readonly now: () => number = Date.now) {}

  list(): BuiltinBrowserTab[] {
    return [...this.tabs.values()];
  }

  ids(): number[] {
    return [...this.tabs.keys()];
  }

  get(id: number): BuiltinBrowserTab | undefined {
    return this.tabs.get(id);
  }

  has(id: number): boolean {
    return this.tabs.has(id);
  }

  /** The active tab: the last one used or focused while it is open, else the newest, else none. */
  get activeTabId(): number | null {
    if (this.active !== null && this.tabs.has(this.active)) return this.active;
    let newest: number | null = null;
    for (const id of this.tabs.keys()) newest = id;
    return newest;
  }

  /**
   * Makes a tab the active one; true when the active tab changed. A tab the shell has not
   * reported yet (a claim can overtake the tab's first event) becomes active once it is.
   */
  activate(id: number): boolean {
    if (!this.tabs.has(id)) {
      this.pendingActive = id;
      return false;
    }
    this.pendingActive = null;
    const before = this.activeTabId;
    this.active = id;
    return before !== id;
  }

  /** Applies one `tab` event; returns the tab as it was before (undefined for a new one). */
  upsert(tab: BuiltinBrowserTab): BuiltinBrowserTab | undefined {
    const previous = this.tabs.get(tab.id);
    this.tabs.set(tab.id, tab);
    if (this.pendingActive === tab.id) {
      this.active = tab.id;
      this.pendingActive = null;
    }
    if (firstPageStarted(tab)) this.settleFirstPage(tab.id, true);
    return previous;
  }

  /**
   * Applies a `tab-crashed` event: the tab stays, marked with why its page is gone, until the
   * shell reports it reloaded. True when that changed the tab.
   */
  markCrashed(id: number, reason: string): boolean {
    const tab = this.tabs.get(id);
    if (tab === undefined || (tab.crashed === reason && !tab.loading)) return false;
    this.tabs.set(id, { ...tab, loading: false, crashed: reason });
    this.settleFirstPage(id, true);
    return true;
  }

  /** Applies a `tab-closed` event; true when the tab was known. */
  remove(id: number): boolean {
    const known = this.tabs.delete(id);
    if (this.active === id) this.active = null;
    this.settleClose(id);
    this.settleFirstPage(id, true);
    return known;
  }

  /**
   * Replaces the registry with the shell's full list, keeping the order tabs were first seen in
   * and the active tab while it is still open. Returns whether anything changed.
   */
  replaceAll(tabs: readonly BuiltinBrowserTab[]): boolean {
    const incoming = new Map(tabs.map((tab) => [tab.id, tab]));
    const next = new Map<number, BuiltinBrowserTab>();
    for (const id of this.tabs.keys()) {
      const tab = incoming.get(id);
      if (tab !== undefined) next.set(id, tab);
    }
    for (const [id, tab] of incoming) if (!next.has(id)) next.set(id, tab);
    const changed =
      next.size !== this.tabs.size ||
      [...next].some(([id, tab]) => JSON.stringify(this.tabs.get(id)) !== JSON.stringify(tab));
    const gone = [...this.tabs.keys()].filter((id) => !next.has(id));
    this.tabs = next;
    if (this.pendingActive !== null && next.has(this.pendingActive)) {
      this.active = this.pendingActive;
      this.pendingActive = null;
    }
    if (this.active !== null && !next.has(this.active)) this.active = null;
    for (const id of gone) this.settleClose(id);
    for (const id of [...this.firstPageWaiters.keys()]) {
      const tab = next.get(id);
      if (tab === undefined ? gone.includes(id) : firstPageStarted(tab)) {
        this.settleFirstPage(id, true);
      }
    }
    return changed;
  }

  /** Resolves true once the tab is gone (at once when it already is), false after `timeoutMs`. */
  waitForClose(id: number, timeoutMs: number): Promise<boolean> {
    if (!this.tabs.has(id)) return Promise.resolve(true);
    return new Promise((resolve) => {
      const waiters = this.closeWaiters.get(id) ?? new Set<() => void>();
      this.closeWaiters.set(id, waiters);
      const timer = this.timer(() => {
        waiters.delete(done);
        resolve(false);
      }, timeoutMs);
      const done = () => {
        this.clearTimer(timer);
        resolve(true);
      };
      waiters.add(done);
    });
  }

  /**
   * Resolves true once a new tab's first page has committed, or its first load ended without
   * one; at once when that already happened; false after `timeoutMs`. Until then the tab shows
   * its initial empty document, which reads as fully loaded, so a wait for the page to load has
   * to start after this. A tab not reported yet (a claim can overtake its first event) is waited
   * for, and one that closes ends the wait.
   */
  waitForFirstPage(id: number, timeoutMs: number): Promise<boolean> {
    const tab = this.tabs.get(id);
    if (tab !== undefined && firstPageStarted(tab)) return Promise.resolve(true);
    return new Promise((resolve) => {
      const waiters = this.firstPageWaiters.get(id) ?? new Set<(started: boolean) => void>();
      this.firstPageWaiters.set(id, waiters);
      const timer = this.timer(() => {
        waiters.delete(done);
        if (waiters.size === 0) this.firstPageWaiters.delete(id);
        resolve(false);
      }, timeoutMs);
      const done = (started: boolean) => {
        this.clearTimer(timer);
        resolve(started);
      };
      waiters.add(done);
    });
  }

  // --- open requests ---------------------------------------------------------

  /** Records a tab the Web App is about to be asked to create. */
  createOpen(opts: { url: string; activate: boolean; openerTabId?: number }): OpenRequest {
    this.prune();
    const state: OpenState = {
      requestId: randomUUID(),
      url: opts.url,
      activate: opts.activate,
      ...(opts.openerTabId !== undefined ? { openerTabId: opts.openerTabId } : {}),
      createdAt: this.now(),
      claimedTabId: null,
      waiters: new Set(),
    };
    this.opens.set(state.requestId, state);
    return this.snapshot(state);
  }

  /**
   * Correlates a created <webview> with the request it was created for. The first claim wins;
   * the same claim again is harmless; another tab's claim of a taken request is a duplicate,
   * and so is a claim of a request that expired or never existed.
   */
  claim(requestId: string, tabId: number): ClaimOutcome {
    this.prune();
    const state = this.opens.get(requestId);
    if (state === undefined) return "unknown";
    if (state.claimedTabId !== null) return state.claimedTabId === tabId ? "claimed" : "duplicate";
    state.claimedTabId = tabId;
    for (const waiter of state.waiters) waiter(tabId);
    state.waiters.clear();
    return "claimed";
  }

  /** The claiming tab's id, or null when nobody claims the request within `timeoutMs`. */
  waitForClaim(requestId: string, timeoutMs: number): Promise<number | null> {
    const state = this.opens.get(requestId);
    if (state === undefined) return Promise.resolve(null);
    if (state.claimedTabId !== null) return Promise.resolve(state.claimedTabId);
    return new Promise((resolve) => {
      const timer = this.timer(() => {
        state.waiters.delete(done);
        resolve(null);
      }, timeoutMs);
      const done = (tabId: number | null) => {
        this.clearTimer(timer);
        resolve(tabId);
      };
      state.waiters.add(done);
    });
  }

  /** The open requests no window has claimed yet: tabs on their way. */
  pendingOpens(): number {
    this.prune();
    let pending = 0;
    for (const state of this.opens.values()) if (state.claimedTabId === null) pending += 1;
    return pending;
  }

  /** One open request as it stands, or undefined once it expired. */
  openRequest(requestId: string): OpenRequest | undefined {
    const state = this.opens.get(requestId);
    return state === undefined ? undefined : this.snapshot(state);
  }

  /** The requests `openerTabId` made since `since` (its popups during one call). */
  opensFrom(openerTabId: number, since: number): OpenRequest[] {
    return [...this.opens.values()]
      .filter((state) => state.openerTabId === openerTabId && state.createdAt >= since)
      .map((state) => this.snapshot(state));
  }

  /** Settles every waiter (claims with null, closes with false) and stops the timers. */
  dispose(): void {
    for (const timer of this.timers) clearTimeout(timer);
    this.timers.clear();
    for (const state of this.opens.values()) {
      for (const waiter of state.waiters) waiter(null);
      state.waiters.clear();
    }
    this.closeWaiters.clear();
    for (const id of [...this.firstPageWaiters.keys()]) this.settleFirstPage(id, false);
  }

  private settleFirstPage(id: number, started: boolean): void {
    const waiters = this.firstPageWaiters.get(id);
    if (waiters === undefined) return;
    this.firstPageWaiters.delete(id);
    for (const waiter of waiters) waiter(started);
  }

  private settleClose(id: number): void {
    const waiters = this.closeWaiters.get(id);
    if (waiters === undefined) return;
    this.closeWaiters.delete(id);
    for (const waiter of waiters) waiter();
  }

  private prune(): void {
    const cutoff = this.now() - OPEN_REQUEST_TTL_MS;
    for (const [id, state] of this.opens) {
      if (state.createdAt < cutoff && state.waiters.size === 0) this.opens.delete(id);
    }
  }

  private snapshot(state: OpenState): OpenRequest {
    const { waiters: _waiters, ...request } = state;
    return request;
  }

  private timer(fn: () => void, ms: number): NodeJS.Timeout {
    const timer = setTimeout(() => {
      this.timers.delete(timer);
      fn();
    }, ms);
    this.timers.add(timer);
    return timer;
  }

  private clearTimer(timer: NodeJS.Timeout): void {
    clearTimeout(timer);
    this.timers.delete(timer);
  }
}