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.

13.6 KB
Raw Blame
/**
 * Where a person's computer lives, asked of the supervisor.
 *
 * Each person gets a container of their own, and every Bot they use runs on it; an isolated Bot gets
 * one of its own. So the address of a computer is no longer one fixed URL, it is whatever port the
 * supervisor published for that person or Bot, and it changes when the computer is reset. So the
 * server stops holding an address and starts asking for one.
 *
 * The server still never touches Docker. It asks for a computer by whose it is; the supervisor
 * decides what that means. Everything the API server can express is in this file, and it is four
 * verbs.
 *
 * Without a supervisor configured, nothing here is used and the fixed `AGENT_COMPUTER_URL` still
 * answers for every Bot. That is the single-container mode: fine for one person on a laptop, and
 * honest about being one shared computer.
 */

import { ComputerStillStartingError } from "./client";
import {
  type ComputerKey,
  type ComputerSeat,
  computerKeyText,
} from "./computer-key";
import type {
  ComputerLocation,
  ComputerProvider,
  ComputerTarget,
} from "./provider";
import type { ComputerStatus } from "./schema";

type SupervisorComputerLocation = {
  /** Whose computer: `person` or `bot`, and their id. */
  kind?: string;
  id?: string;
  container?: string;
  status: string;
  port?: number;
  /** Where to reach it, decided by the supervisor rather than assembled here. */
  url?: string;
  startedAt?: string;
  /** The image's healthcheck verdict, from a supervisor new enough to report it. */
  health?: string;
  /** What giving private Bots' old profiles to this person did, when it was asked for. */
  carriedOver?: Record<string, string>;
};

/** The supervisor's path for a computer: `/computers/person/<id>` or `/computers/bot/<id>`. */
function pathOf(key: ComputerKey): string {
  return key.kind === "person"
    ? `/computers/person/${encodeURIComponent(key.personId)}`
    : `/computers/bot/${encodeURIComponent(key.botId)}`;
}

/** Whose computer a listed one is, or undefined for one this server cannot name. */
function keyOf(computer: SupervisorComputerLocation): ComputerKey | undefined {
  if (!computer.id) return undefined;
  if (computer.kind === "person")
    return { kind: "person", personId: computer.id };
  if (computer.kind === "bot") return { kind: "bot", botId: computer.id };
  return undefined;
}

export type SupervisorOptions = {
  baseUrl: string;
  token?: string;
  /** How a published port becomes a URL the server can reach. */
  hostForPort?: (port: number) => string;
  fetchImpl?: typeof fetch;
  timeoutMs?: number;
};

export class SupervisorError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "SupervisorError";
  }
}

export function createDockerSupervisorProvider(
  options: SupervisorOptions,
): ComputerProvider {
  const doFetch = options.fetchImpl ?? fetch;
  const base = options.baseUrl.replace(/\/$/, "");
  const timeoutMs = options.timeoutMs ?? 120_000;
  /*
   * Numeric, never `localhost`.
   *
   * `localhost` does not resolve the same way on every operating system — Node prefers `::1`, bun
   * prefers `127.0.0.1` — so a name here reaches a different interface depending on what started
   * the process, and a computer that is listening looks like one that is not.
   */
  const hostForPort =
    options.hostForPort ?? ((port) => `http://127.0.0.1:${port}`);

  /**
   * Seats whose Bot's old profile the supervisor has answered for, so it is asked once per process.
   *
   * The supervisor remembers too, and its marker in the person's volume is the record that outlives
   * both; this only keeps the question off every `/ensure` after the first.
   */
  const carried = new Set<string>();

  /**
   * The last container start time seen for each computer, from the `/ensure` that located it.
   *
   * ONE MAP PER PROVIDER, not one per process. It was module-scope, so every provider built in a
   * process shared it: two supervisors, or a test's second stack, answered each other's question
   * about which run a Bot's computer is on, and the answer they gave was whichever one wrote last.
   *
   * Not a cache in front of the supervisor: `locate` still calls it every time, and a governed
   * action locates before it asks. This only carries that answer the few lines to whoever needs to
   * know which run of the computer they are talking to.
   *
   * Still process-local, and therefore never the only answer. A replica that has never located this
   * computer has nothing here, and an unknown run skips the generation check rather than failing it,
   * so `sessionOf` falls back to asking rather than letting an empty map quietly stop checking.
   *
   * Keyed by computer, not by Bot: every Bot on a person's computer is on the same run of it.
   */
  const sessions = new Map<string, string>();

  async function call(
    path: string,
    method = "POST",
    body?: unknown,
    /**
     * Whether running out of time means the computer is still starting.
     *
     * Only for `/ensure`, which is the one call that waits on a container coming up: there a timeout
     * is a slow start, and the caller is told so gently. Anywhere else it is a supervisor that has
     * stopped answering, which is a real fault and keeps its own message.
     */
    startingOnTimeout = false,
  ): Promise<unknown> {
    let response: Response;
    try {
      response = await doFetch(`${base}${path}`, {
        method,
        headers: {
          ...(options.token
            ? { authorization: `Bearer ${options.token}` }
            : {}),
          ...(body !== undefined ? { "content-type": "application/json" } : {}),
        },
        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
        signal: AbortSignal.timeout(timeoutMs),
      });
    } catch (error) {
      if (
        startingOnTimeout &&
        error instanceof Error &&
        error.name === "TimeoutError"
      ) {
        throw new ComputerStillStartingError();
      }
      throw new SupervisorError(
        `The container supervisor at ${base} could not be reached (${error instanceof Error ? error.message : String(error)}).`,
      );
    }

    const answer = (await response.json().catch(() => null)) as {
      error?: string;
      stopped?: boolean;
      reset?: boolean;
      computers?: SupervisorComputerLocation[];
      starting?: boolean;
    } | null;
    if (!response.ok) {
      // The supervisor's own health wait ran out on a container that is up and still booting. The
      // same slow start as a timeout here, so it gets the same gentle answer.
      if (
        startingOnTimeout &&
        response.status === 503 &&
        answer?.starting === true
      ) {
        throw new ComputerStillStartingError();
      }
      throw new SupervisorError(
        answer?.error ?? `The supervisor answered ${response.status}.`,
      );
    }
    return answer;
  }

  async function listRaw(): Promise<SupervisorComputerLocation[]> {
    const body = (await call("/computers", "GET")) as {
      computers?: SupervisorComputerLocation[];
    } | null;
    return body?.computers ?? [];
  }

  /** The listed computer that is this key's, if there is one. */
  function find(
    computers: SupervisorComputerLocation[],
    key: ComputerKey,
  ): SupervisorComputerLocation | undefined {
    const wanted = computerKeyText(key);
    return computers.find((computer) => {
      const of = keyOf(computer);
      return of !== undefined && computerKeyText(of) === wanted;
    });
  }

  async function list(): Promise<ComputerLocation[]> {
    const computers = await listRaw();
    return computers
      .flatMap((computer) => {
        const key = keyOf(computer);
        return key ? [{ key, computer }] : [];
      })
      .map(({ key, computer }) => ({
        key,
        status:
          computer.status.toLowerCase() === "running" ? "running" : "stopped",
        ...(computer.url
          ? { url: computer.url }
          : computer.port
            ? { url: hostForPort(computer.port) }
            : {}),
        ...(computer.startedAt ? { startedAt: computer.startedAt } : {}),
      }));
  }

  function statusFromLocation(
    botId: string,
    location: SupervisorComputerLocation | undefined,
  ): ComputerStatus {
    // About the computer the seat is on; reported for the seat's Bot, which is who asked.
    if (!location) return { botId, state: "absent" };

    const rawStatus = location.status.toLowerCase();
    switch (rawStatus) {
      case "running":
        // Running is the process; healthy is the browser inside it. Until the healthcheck passes,
        // `/ensure` holds every caller, so the computer is still starting.
        return location.health === "starting"
          ? { botId, state: "starting" }
          : { botId, state: "ready" };
      case "created":
      case "restarting":
        return { botId, state: "starting" };
      case "paused":
      case "removing":
      case "exited":
        return { botId, state: "absent" };
      case "dead":
        return {
          botId,
          state: "unreachable",
          reason: `The computer reported state "${location.status}".`,
        };
      default:
        return {
          botId,
          state: "unreachable",
          reason: `The computer reported unknown state "${location.status}".`,
        };
    }
  }

  return {
    name: "Docker supervisor",
    isolation: "per-person",

    async sessionOf(seat: ComputerSeat): Promise<string | undefined> {
      const id = computerKeyText(seat.key);
      /*
       * Read from the same `/ensure` every action already makes, and remembered rather than asked
       * for again: on the replica that located this computer, `locate` ran immediately before the
       * call that needs this, so the value is as fresh as the address it was fetched with. Asking
       * twice would double the supervisor's work on the hot path to learn something it just told us.
       */
      const known = sessions.get(id);
      if (known) return known;

      /*
       * Nothing here means another replica did the work, not that there is nothing to know.
       *
       * LISTING, NOT ENSURING, and the difference is the whole feature. `/ensure` starts a computer
       * that is not running, so answering "which run is this" with it would wake every idle computer
       * that anything asked about, and a deployment that suspends idle computers would quietly never
       * suspend one. Listing is a read: a computer that does not exist answers undefined, which is the
       * same answer as before and leaves the check exactly where it was.
       */
      try {
        const startedAt = find(await listRaw(), seat.key)?.startedAt;
        if (startedAt) sessions.set(id, startedAt);
        return startedAt;
      } catch {
        // Unknown, not mismatched. A supervisor that cannot be reached must not turn every ref into
        // a refusal; the generation check goes back to being skipped, which is where it started.
        return undefined;
      }
    },

    /**
     * The URL of the computer this seat is on, starting it if it is not already up.
     *
     * A computer that is running but has published no port is a computer nothing can reach, so that
     * is an error rather than a URL, the alternative is a caller quietly falling back to somebody
     * else's computer.
     *
     * A private Bot on its owner's computer also asks, once, for the Bot's profile from before
     * computers were per person: the supervisor copies it in before it answers, so the Bot's first
     * request already finds its logins.
     */
    async locate(seat: ComputerSeat): Promise<string> {
      const id = computerKeyText(seat.key);
      const seatId = `${id}/${seat.botId}`;
      const carryOver =
        seat.inheritsProfile &&
        seat.key.kind === "person" &&
        !carried.has(seatId);
      const state = (await call(
        `${pathOf(seat.key)}/ensure`,
        "POST",
        carryOver ? { carryOver: [seat.botId] } : undefined,
        true,
      )) as SupervisorComputerLocation;
      if (carryOver && state?.carriedOver?.[seat.botId]) carried.add(seatId);
      // Recorded on every ensure, so a replaced container is visible to whatever asks next.
      if (state?.startedAt) sessions.set(id, state.startedAt);
      // The supervisor says where it is, because only it knows whether these computers sit on a
      // shared network or answer on a published port.
      if (state?.url) return state.url;
      if (state?.port) return hostForPort(state.port);
      throw new SupervisorError(
        `The computer for ${id} started but reported no address, so it cannot be reached.`,
      );
    },

    async status(seat: ComputerSeat): Promise<ComputerStatus> {
      try {
        return statusFromLocation(seat.botId, find(await listRaw(), seat.key));
      } catch (error) {
        return {
          botId: seat.botId,
          state: "unreachable",
          reason:
            error instanceof Error && error.message.length > 0
              ? error.message
              : "Unknown failure.",
        };
      }
    },

    /** The whole computer: on a person's, every Bot there stops with it and keeps its logins. */
    async stop(target: ComputerTarget): Promise<{ wasRunning: boolean }> {
      const result = (await call(`${pathOf(target.key)}/stop`)) as {
        stopped?: boolean;
      } | null;
      return { wasRunning: result?.stopped === true };
    },

    /** The whole computer: on a person's, every Bot there is signed out. */
    async reset(target: ComputerTarget): Promise<{ cleared: boolean }> {
      const result = (await call(`${pathOf(target.key)}/reset`)) as {
        reset?: boolean;
      } | null;
      return { cleared: result?.reset === true };
    },

    list,
  };
}