Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

7.2 KB
Raw Blame
/**
 * The shape of a call, checked before it reaches the browser or the shell.
 *
 * This process holds no policy engine: the server gateway decides whether an action may run. What
 * is checked here is whether the request is well-formed at all, so a typo'd caller gets a 400
 * naming the field rather than a 502 that reads as a broken computer.
 */
import type { InputMessage } from "./screencast";

/** Long enough for an install, short enough that a hung command is not a hung Bot. */
export const EXEC_DEFAULT_TIMEOUT_MS = 120_000;
/** A command has to be given long enough to start. Below this, a caller is asking for nothing. */
export const EXEC_MIN_TIMEOUT_MS = 1_000;
export const EXEC_MAX_TIMEOUT_MS = 600_000;

export type NavigateParseResult =
  | { ok: true; url: string }
  | { ok: false; error: string };

/**
 * A navigation target, checked before Playwright is asked.
 *
 * An empty string used to travel into `page.goto` and come back as a 502 "Navigation failed",
 * which reads as a broken computer rather than a caller error. A `javascript:`, `file://`, or
 * `data:` URL is never a page a Bot should be sent to from this endpoint.
 */
export function parseNavigateUrl(input: unknown): NavigateParseResult {
  if (typeof input !== "string" || !input.trim()) {
    return { ok: false, error: "A url is required." };
  }
  const trimmed = input.trim();
  let parsed: URL;
  try {
    parsed = new URL(trimmed);
  } catch {
    return { ok: false, error: "That is not a valid http(s) URL." };
  }
  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
    return { ok: false, error: "Only http(s) URLs can be opened." };
  }
  return { ok: true, url: trimmed };
}

/**
 * An address as a person types one: a full http(s) url, or a host with the scheme left off.
 *
 * http and https only, as for a Bot's navigation, and deliberately so for the hosted browser:
 * `file://` there would read the computer's own files, its environment and secrets among them.
 */
export function addressFrom(input: string): string | null {
  const trimmed = input.trim();
  const direct = parseNavigateUrl(trimmed);
  if (direct.ok) return direct.url;
  // Any other scheme is refused rather than guessed at. `example.com:8080` names a port, not one.
  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed) && !/^[^:/]+:\d/.test(trimmed))
    return null;
  // Words with spaces are a search, which is the app's to turn into an address.
  if (/\s/.test(trimmed)) return null;
  const guessed = parseNavigateUrl(`https://${trimmed}`);
  if (!guessed.ok) return null;
  const host = new URL(guessed.url).hostname;
  return host.includes(".") || host === "localhost" || host.startsWith("[")
    ? guessed.url
    : null;
}

export type ExecTimeoutParseResult =
  | { ok: true; timeoutMs: number | undefined }
  | { ok: false; error: string };

export type ScrollDeltaParseResult =
  | { ok: true; deltaY: number | undefined }
  | { ok: false; error: string };

const SCROLL_DELTA_ERROR = "deltaY must be a finite number of pixels.";

/**
 * A wheel delta, checked before Playwright is asked.
 *
 * `typeof` alone accepts `Infinity` (valid JSON: `1e999` parses to it), which then travels into
 * `mouse.wheel` and comes back as a 502 that reads as a broken computer. Anything that is not a
 * finite number answers 400 here, matching the server gateway's validation of the same field.
 * Absent stays absent: the caller gets the endpoint's own default distance.
 */
export function parseScrollDelta(input: unknown): ScrollDeltaParseResult {
  if (input === undefined) return { ok: true, deltaY: undefined };
  if (typeof input !== "number" || !Number.isFinite(input)) {
    return { ok: false, error: SCROLL_DELTA_ERROR };
  }
  return { ok: true, deltaY: input };
}

export type InputMessageParseResult =
  | { ok: true; message: InputMessage }
  | { ok: false; error: string };

const EXEC_TIMEOUT_ERROR =
  "timeoutMs must be a whole number of milliseconds between 1000 and 600000.";

/**
 * A shell timeout, checked before the command is spawned.
 *
 * A `NaN` or `Infinity` used to travel into `Math.min(Math.max(...))` as `NaN`, so `setTimeout`
 * fired immediately: the command was killed before it did anything and the answer said it had
 * timed out, which is true and useless. Anything outside the shell's own bounds answers 400 here,
 * matching the server gateway's validation of the same field.
 */
export function parseExecTimeout(input: unknown): ExecTimeoutParseResult {
  if (input === undefined) return { ok: true, timeoutMs: undefined };
  if (
    typeof input !== "number" ||
    !Number.isInteger(input) ||
    input < EXEC_MIN_TIMEOUT_MS ||
    input > EXEC_MAX_TIMEOUT_MS
  ) {
    return { ok: false, error: EXEC_TIMEOUT_ERROR };
  }
  return { ok: true, timeoutMs: input };
}

function isFiniteNumber(value: unknown): value is number {
  return typeof value === "number" && Number.isFinite(value);
}

/**
 * A live-screen input message, checked before it reaches CDP.
 *
 * Anything JSON-decodable used to pass the cast and fall through to `Input.insertText` with an
 * undefined text, or forward wrong-typed coordinates into `Input.dispatchMouseEvent`. An unknown
 * type and every malformed field is refused here so a buggy surface gets an error naming the
 * message, not a CDP failure that reads as a broken computer.
 */
export function parseInputMessage(input: unknown): InputMessageParseResult {
  if (typeof input !== "object" || input === null) {
    return { ok: false, error: "That input message is not an object." };
  }
  const body = input as Record<string, unknown>;
  if (body.type === "mouse") {
    if (
      body.event !== "pressed" &&
      body.event !== "released" &&
      body.event !== "moved"
    ) {
      return { ok: false, error: "A mouse message needs an event." };
    }
    if (!isFiniteNumber(body.x) || !isFiniteNumber(body.y)) {
      return { ok: false, error: "A mouse message needs an x and a y." };
    }
    if (
      body.button !== undefined &&
      body.button !== "left" &&
      body.button !== "right" &&
      body.button !== "middle"
    ) {
      return { ok: false, error: "A mouse button must be named." };
    }
    return { ok: true, message: body as unknown as InputMessage };
  }
  if (body.type === "wheel") {
    if (
      !isFiniteNumber(body.x) ||
      !isFiniteNumber(body.y) ||
      !isFiniteNumber(body.deltaX) ||
      !isFiniteNumber(body.deltaY)
    ) {
      return {
        ok: false,
        error: "A wheel message needs a position and a delta.",
      };
    }
    return { ok: true, message: body as unknown as InputMessage };
  }
  if (body.type === "key") {
    if (body.event !== "down" && body.event !== "up") {
      return { ok: false, error: "A key message needs an event." };
    }
    if (typeof body.key !== "string" || !body.key) {
      return { ok: false, error: "A key message needs a key name." };
    }
    if (typeof body.code !== "string" || !body.code) {
      return { ok: false, error: "A key message needs a code." };
    }
    return { ok: true, message: body as unknown as InputMessage };
  }
  if (body.type === "text") {
    if (typeof body.text !== "string" || !body.text) {
      return { ok: false, error: "A text message needs text." };
    }
    return { ok: true, message: body as unknown as InputMessage };
  }
  return { ok: false, error: "That input message has an unknown type." };
}