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.

5.6 KB
Raw Blame
import {
  closeSync,
  existsSync,
  fsyncSync,
  mkdirSync,
  openSync,
  readFileSync,
  renameSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { join } from "node:path";
import type { HandoffRequest } from "../../shared/computer-control";
import { isUsableSeatId } from "./bot-id";

export type StoredControl = {
  version: 1;
  holder: "bot" | "human";
  since: string;
  resumeSnapshotRequired: boolean;
  recoveryRequired: boolean;
  currentRequestId?: string;
  requests: HandoffRequest[];
  aliases: Record<string, string>;
  /**
   * The user id of the person holding the wheel, when they took it with one. Optional, so a state saved before it
   * existed still loads: nobody may record in a Bot's browser or use its bar until the wheel is taken again.
   */
  heldBy?: string;
};
export type ControlStore = {
  load(): StoredControl | undefined;
  save(state: StoredControl): void;
};
const statuses = new Set([
  "waiting",
  "taken",
  "completed",
  "cancelled",
  "expired",
  "interrupted",
]);
const sources = new Set(["model", "manual", "cloudflare", "visible-challenge"]);
/** The longest user id kept as who holds the wheel: the contract's limit on a person's id. */
export const MAX_HELD_BY = 200;
/** The longest page address a request keeps. Longer ones are not kept rather than cut. */
export const MAX_REQUEST_URL = 2048;
const record = (v: unknown): v is Record<string, unknown> =>
  !!v && typeof v === "object" && !Array.isArray(v);
const timestamp = (v: unknown): v is string =>
  typeof v === "string" && Number.isFinite(Date.parse(v));

function validRequest(v: unknown): v is HandoffRequest {
  return (
    record(v) &&
    typeof v.id === "string" &&
    v.id.length > 0 &&
    v.id.length <= 200 &&
    typeof v.reason === "string" &&
    v.reason.length <= 500 &&
    typeof v.source === "string" &&
    sources.has(v.source) &&
    typeof v.status === "string" &&
    statuses.has(v.status) &&
    timestamp(v.createdAt) &&
    timestamp(v.updatedAt) &&
    (v.toolCallId === undefined ||
      (typeof v.toolCallId === "string" && v.toolCallId.length <= 200)) &&
    (v.expiresAt === undefined || timestamp(v.expiresAt)) &&
    (v.finishedAt === undefined || timestamp(v.finishedAt)) &&
    (v.interruption === undefined || typeof v.interruption === "string") &&
    (v.url === undefined ||
      (typeof v.url === "string" && v.url.length <= MAX_REQUEST_URL)) &&
    (v.keepsPage === undefined || typeof v.keepsPage === "boolean") &&
    (v.status !== "waiting" || timestamp(v.expiresAt)) &&
    (v.status === "waiting" || v.expiresAt === undefined) &&
    (v.status === "waiting" || v.status === "taken"
      ? v.finishedAt === undefined
      : timestamp(v.finishedAt))
  );
}

function validate(value: unknown): StoredControl {
  if (
    !record(value) ||
    value.version !== 1 ||
    !["bot", "human"].includes(String(value.holder)) ||
    !timestamp(value.since) ||
    typeof value.resumeSnapshotRequired !== "boolean" ||
    typeof value.recoveryRequired !== "boolean" ||
    !Array.isArray(value.requests) ||
    value.requests.length > 33 ||
    !value.requests.every(validRequest) ||
    !record(value.aliases) ||
    Object.keys(value.aliases).length > 256 ||
    (value.currentRequestId !== undefined &&
      typeof value.currentRequestId !== "string") ||
    (value.heldBy !== undefined &&
      (typeof value.heldBy !== "string" ||
        value.heldBy.length === 0 ||
        value.heldBy.length > MAX_HELD_BY ||
        value.holder !== "human"))
  )
    throw new Error("Corrupt computer control state.");
  const ids = new Set(value.requests.map((r) => r.id));
  if (
    ids.size !== value.requests.length ||
    (value.currentRequestId !== undefined &&
      !ids.has(value.currentRequestId)) ||
    Object.entries(value.aliases).some(
      ([key, id]) => key.length > 200 || typeof id !== "string" || !ids.has(id),
    )
  )
    throw new Error("Corrupt computer control request history.");
  const current = value.requests.find((r) => r.id === value.currentRequestId);
  if (
    (current?.status === "taken" && value.holder !== "human") ||
    (value.requests.length > 0 && !current) ||
    (value.holder === "human" &&
      current?.status !== "taken" &&
      current?.status !== "cancelled") ||
    value.requests.some(
      (r) =>
        (r.status === "waiting" || r.status === "taken") &&
        r.id !== value.currentRequestId,
    )
  )
    throw new Error("Corrupt computer control ownership.");
  return value as StoredControl;
}

/** Atomic replacement outside Chromium's profile. Never salvage corrupt data as success. */
export function createControlStore(
  profilesDirectory: string,
  botId: string,
): ControlStore {
  if (!isUsableSeatId(botId)) throw new Error("That is not a usable bot id.");
  const directory = join(profilesDirectory, ".control");
  const path = join(directory, `${botId}.json`);
  return {
    load() {
      if (!existsSync(path)) return undefined;
      const contents = readFileSync(path, "utf8");
      if (contents.length > 256_000)
        throw new Error("Computer control state exceeds its size limit.");
      return validate(JSON.parse(contents));
    },
    save(state) {
      validate(state);
      mkdirSync(directory, { recursive: true, mode: 0o700 });
      const temporary = `${path}.${crypto.randomUUID()}.tmp`;
      try {
        const fd = openSync(temporary, "wx", 0o600);
        try {
          writeFileSync(fd, JSON.stringify(state));
          fsyncSync(fd);
        } finally {
          closeSync(fd);
        }
        renameSync(temporary, path);
      } finally {
        // A write or rename that fails must not leave the copy behind; after a rename it is gone.
        rmSync(temporary, { force: true });
      }
    },
  };
}