Skip to content

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

8.1 KB
Raw Blame
/**
 * The built-in browser's driver: GenericAgent's TMWebDriver, over CDP instead of an extension's
 * WebSocket. Every call is a raw CDP command the shell relays to one guest's
 * `webContents.debugger`; what this adds is the JavaScript evaluation contract the actions are
 * written against, and the mapping from the ways a page can fail to the errors the routes speak.
 *
 * - A script is wrapped as `(async () => { <code> })()` and evaluated with the promise awaited
 *   and the value returned by value, as a user gesture (so a script may open a popup or write
 *   the clipboard). It returns what it `return`s.
 * - A page that navigated or reloaded under the script ("Execution context was destroyed", …)
 *   is not an error: the call reports `{ reloaded: true }`, as TMWebDriver's `closed` does.
 * - A script that throws is a PageScriptError carrying the page's own message.
 */
import { HttpError } from "../http/errors.js";
import { ShellLinkError } from "./shell-link.js";
import type { ShellLink } from "./shell-link.js";

/** How long a raw CDP command may take when its caller names no timeout. */
export const CDP_TIMEOUT_MS = 30_000;
/** Beyond the in-page evaluation timeout, how long the link waits for the answer to travel back. */
const EVALUATE_LINK_MARGIN_MS = 2_000;
const LOAD_POLL_MS = 250;
/** After `readyState` reaches complete: a beat for the scripts a page starts on load. */
const LOAD_SETTLE_MS = 300;

/** The texts CDP answers with when the page's context went away under a call. */
const CONTEXT_LOST =
  /Execution context was destroyed|Inspected target navigated or closed|Cannot find context/i;

/** A script the page threw from; the message is the page's own. */
export class PageScriptError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "PageScriptError";
  }
}

export type EvaluateOutcome = { value: unknown } | { reloaded: true };

interface RemoteObject {
  type?: string;
  value?: unknown;
  unserializableValue?: string;
  description?: string;
}

interface ExceptionDetails {
  text?: string;
  exception?: RemoteObject;
}

/** The page's message for a thrown exception: the first line of its description (`Error: …`), else what CDP says. */
export function exceptionMessage(details: ExceptionDetails): string {
  const description = details.exception?.description;
  if (typeof description === "string" && description !== "") return description.split("\n")[0]!;
  const value = details.exception?.value;
  if (value !== undefined)
    return `Uncaught ${typeof value === "string" ? value : JSON.stringify(value)}`;
  return details.text ?? "The page script failed.";
}

/**
 * 409 `tab_crashed`: the tab's page has no renderer (it crashed, or the system took its memory
 * back) until someone reloads it, so nothing can run in it. `reason` is Electron's word for it.
 */
export function tabCrashedError(tabId: number, reason?: string): HttpError {
  return new HttpError(
    409,
    "tab_crashed",
    `Tab ${tabId}'s page crashed${reason !== undefined && reason !== "crashed" ? ` (${reason})` : ""}. ` +
      `Reload it in the Browser panel, or close it (penguin browser close ${tabId}) and open the page in a new tab.`,
  );
}

/** What a failed link request means to the route that asked. */
export function mapLinkError(err: unknown, tabId: number): Error {
  if (!(err instanceof ShellLinkError)) return err instanceof Error ? err : new Error(String(err));
  switch (err.kind) {
    case "timeout":
      return new HttpError(504, "timeout", err.message);
    case "closed":
      return new HttpError(
        503,
        "browser_unavailable",
        "The built-in browser's link closed; retry.",
      );
    case "refused":
      if (err.message === "no_such_tab") {
        return new HttpError(
          404,
          "no_such_tab",
          `Tab ${tabId} is not open in the built-in browser.`,
        );
      }
      if (err.message === "tab_crashed") return tabCrashedError(tabId);
      return new HttpError(422, "cdp_error", err.message);
  }
}

export interface DriverOptions {
  sleep?: (ms: number) => Promise<void>;
  now?: () => number;
}

export class BrowserDriver {
  private readonly sleep: (ms: number) => Promise<void>;
  private readonly now: () => number;

  constructor(
    private readonly link: ShellLink,
    opts: DriverOptions = {},
  ) {
    this.sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
    this.now = opts.now ?? Date.now;
  }

  /**
   * One raw CDP command on a tab; resolves with CDP's result object. `events`, when given, is
   * the list of the tab's CDP events the shell relays from then on (`onCdpEvent` hears them).
   */
  async cdp(
    tabId: number,
    method: string,
    params?: Record<string, unknown>,
    timeoutMs = CDP_TIMEOUT_MS,
    events?: string[],
  ): Promise<unknown> {
    try {
      return await this.link.request(
        {
          op: "cdp",
          tabId,
          method,
          ...(params !== undefined ? { params } : {}),
          ...(events !== undefined ? { events } : {}),
        },
        timeoutMs,
      );
    } catch (err) {
      throw mapLinkError(err, tabId);
    }
  }

  /** The CDP events the shell relays for one tab. Returns the unsubscribe. */
  onCdpEvent(
    tabId: number,
    listener: (method: string, params: Record<string, unknown>) => void,
  ): () => void {
    return this.link.onEvent((event) => {
      if (event.kind === "cdp-event" && event.tabId === tabId) listener(event.method, event.params);
    });
  }

  /** Evaluates `code` as the body of an async function in the tab's page (see the module doc). */
  async evaluate(
    tabId: number,
    code: string,
    opts: { timeoutMs?: number } = {},
  ): Promise<EvaluateOutcome> {
    const timeoutMs = opts.timeoutMs ?? CDP_TIMEOUT_MS;
    let raw: unknown;
    try {
      raw = await this.link.request(
        {
          op: "cdp",
          tabId,
          method: "Runtime.evaluate",
          params: {
            // The newlines keep a trailing `// comment` in the code from swallowing the close.
            expression: `(async () => {\n${code}\n})()`,
            awaitPromise: true,
            returnByValue: true,
            userGesture: true,
            timeout: timeoutMs,
          },
        },
        timeoutMs + EVALUATE_LINK_MARGIN_MS,
      );
    } catch (err) {
      if (
        err instanceof ShellLinkError &&
        err.kind === "refused" &&
        CONTEXT_LOST.test(err.message)
      ) {
        return { reloaded: true };
      }
      throw mapLinkError(err, tabId);
    }
    const res = (raw ?? {}) as { result?: RemoteObject; exceptionDetails?: ExceptionDetails };
    if (res.exceptionDetails !== undefined) {
      const message = exceptionMessage(res.exceptionDetails);
      if (CONTEXT_LOST.test(message)) return { reloaded: true };
      throw new PageScriptError(message);
    }
    const result = res.result;
    if (result === undefined) return { value: undefined };
    if ("value" in result) return { value: result.value };
    if (result.unserializableValue !== undefined) return { value: result.unserializableValue };
    return { value: undefined };
  }

  /**
   * Waits until the tab's document is complete (plus a short settle), or `timeoutMs` passes.
   * A page between documents answers nothing useful, so failures other than a closed tab only
   * mean "not yet". Resolves whether the load finished in time.
   */
  async waitForLoad(tabId: number, timeoutMs: number): Promise<boolean> {
    const deadline = this.now() + timeoutMs;
    for (;;) {
      const left = deadline - this.now();
      if (left <= 0) return false;
      try {
        const outcome = await this.evaluate(tabId, "return document.readyState;", {
          timeoutMs: Math.max(100, Math.min(5_000, left)),
        });
        if ("value" in outcome && outcome.value === "complete") {
          await this.sleep(LOAD_SETTLE_MS);
          return true;
        }
      } catch (err) {
        // Gone or crashed: no amount of waiting loads it.
        if (err instanceof HttpError && (err.code === "no_such_tab" || err.code === "tab_crashed"))
          throw err;
      }
      await this.sleep(Math.max(0, Math.min(LOAD_POLL_MS, deadline - this.now())));
    }
  }
}