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.

9.7 KB
Raw Blame
import { settleWithin } from "./env";
import type { Screencast } from "./screencast";

/**
 * How long a cast gets to stop before the teardown moves on without it.
 *
 * Bounded because occupancy counts teardowns that are still running, and the session sweep reads
 * occupancy. A `stop` that never settles would leave the entry in the set for the life of the
 * process, so the Bot would read as watched forever and its session could never be swept, which is
 * the unbounded growth that sweep exists to stop, arriving through the fix for it.
 */
const STOP_BUDGET_MS = 5_000;

/**
 * Who owns a Bot's live screen, and what may still act on it.
 *
 * A Bot has one live screen at a time, and a second `/stream` replaces the first rather than being
 * refused: a second cast on the same page would have Chrome encoding every frame twice with both
 * sockets acking independently, which stalls both. One person drives, one cast.
 *
 * What replacement does not do is close the socket it superseded, because that socket belongs to a
 * client that may still be using it. So a superseded socket stays open and closes on its own
 * schedule, which on an ordinary make-before-break reconnect is after the replacement is already
 * casting. Anything that stops a viewer therefore has to establish that it owns the one it is
 * stopping, and that is what this module exists to make unavoidable rather than remembered.
 *
 * Ownership is held per socket, as a claim taken before the browser is asked for a page. That order
 * is the load-bearing part. `open` awaits a page, which launches Chromium when nothing is running,
 * and a close landing inside that window used to find nothing installed and so did nothing, while
 * the launch went on to install a cast and a 1Hz follow loop for a socket that had already gone. No
 * second close ever arrived. With the claim taken first there is always something to release, and
 * everything the launch produces afterwards goes through that claim and is refused once it is
 * revoked.
 *
 * The refusals hand nothing back to the caller to clean up. A refused `install` stops the cast it was
 * given and a refused `setFollow` cancels the loop it was given, because a caller that forgets leaks
 * a screencast or a timer against a browser nobody is watching, and forgetting is exactly what this
 * module is here to take off the table. For the same reason there is no way to stop a cast you do
 * not own: `release` names a socket and does nothing when that socket owns nothing.
 *
 * It lives in its own file for the reason `browser-eviction.ts`, `authorisation.ts` and `bot-id.ts`
 * do: `index.ts` imports Playwright at module scope, so anything left there needs Chrome merely to
 * be imported by a test. `Screencast` comes in as a type only, which is erased at runtime, so this
 * module and its tests stay free of the browser. Starting and stopping a cast stays in `index.ts`;
 * the decisions are here.
 */

/**
 * What a socket may do with the screen right now.
 *
 * Three answers, not two. A socket holding a claim with no cast yet is mid-launch and its screen is
 * still opening; a socket holding nothing was superseded, closed, or never connected. Both own no
 * cast, and collapsing them tells somebody whose screen is still starting that their session ended.
 * The message is the only thing either of them gets, so it has to be the true one.
 */
export type ViewerStanding =
  | { state: "casting"; cast: Screencast }
  | { state: "starting" }
  | { state: "gone" };

/** What an in-flight `open` may do with the screen it is starting. Refused once revoked. */
export type ViewerClaim = {
  /**
   * Put a cast behind this claim, replacing one already there.
   *
   * Answers whether it was accepted. A refused cast is stopped here rather than returned, so a
   * launch that lost its claim cannot leak one. The replaced cast stops only after the new one is
   * installed, so the screen does not blank between the two while the Bot moves page to page.
   */
  install(cast: Screencast): Promise<boolean>;
  /** Register the loop that keeps the cast on the Bot's current page. A refused loop is cancelled. */
  setFollow(cancel: () => void): boolean;
};

export type ViewerSlot = {
  /** Take the screen for this socket, superseding and tearing down whoever held it. */
  claim(socket: unknown, notify: (reason: string) => void): ViewerClaim;
  /** Give up the screen, if this socket is the one holding it. Its own close, so it is not told. */
  release(socket: unknown): Promise<void>;
  /** The browser went away. Tear down whoever is watching and tell them why. */
  releaseAll(reason: string): Promise<void>;
  /** What this socket may do with the screen right now. */
  standingOf(socket: unknown): ViewerStanding;
  /** Is anybody watching, or about to be? What the session sweep asks. */
  occupied(): boolean;
  /** Settle in-flight teardowns. A test seam; nothing on the acting path waits on this. */
  settled(): Promise<void>;
};

/** What a person is told when somebody else takes the screen they were watching. */
export const SUPERSEDED =
  "This screen is now being watched somewhere else, so it stopped here.";

type Entry = {
  socket: unknown;
  notify: (reason: string) => void;
  cast?: Screencast;
  cancelFollow?: () => void;
  /** Set the moment the entry stops owning the screen, and never unset. The one source of truth. */
  revoked: boolean;
};

export function createViewerSlot(): ViewerSlot {
  let current: Entry | undefined;
  /*
   * Teardowns still running. Occupancy counts them, because a browser whose cast is still stopping
   * is not yet a Bot nobody is watching, and the session sweep reading otherwise would drop the
   * control state out from under a screen that is mid-handover.
   */
  const tearing = new Set<Promise<void>>();

  function track(work: Promise<void>): void {
    tearing.add(work);
    void work.finally(() => tearing.delete(work));
  }

  /*
   * Everything is best effort and nothing throws. The page can go away before its cast is told to
   * stop, and the socket can be gone before we can tell it anything, and neither is a reason to
   * leave the rest of the teardown undone: one dead page must not wedge the slot for every later
   * connection.
   */
  async function tearDown(entry: Entry, reason?: string): Promise<void> {
    if (reason !== undefined) {
      try {
        entry.notify(reason);
      } catch {
        // The socket is already gone. It cannot be told, and does not need to be.
      }
    }
    if (entry.cancelFollow) {
      try {
        entry.cancelFollow();
      } catch {
        // Cancelling a timer does not fail, but a caller's callback might.
      }
      entry.cancelFollow = undefined;
    }
    const cast = entry.cast;
    entry.cast = undefined;
    await settleWithin(cast?.stop(), STOP_BUDGET_MS);
  }

  async function stopStray(cast: Screencast): Promise<void> {
    await settleWithin(cast.stop(), STOP_BUDGET_MS);
  }

  return {
    claim(socket, notify) {
      const previous = current;
      const entry: Entry = { socket, notify, revoked: false };
      /*
       * The new claim owns the screen from here, before anything is awaited. A reconnect that
       * arrives while the previous cast is still stopping must not be able to lose to it.
       */
      current = entry;
      if (previous) {
        previous.revoked = true;
        track(tearDown(previous, SUPERSEDED));
      }

      return {
        async install(cast) {
          if (entry.revoked) {
            /*
             * Tracked, not merely awaited. Occupancy and `settled` are how everything else learns
             * that nothing is casting any more, and a cast stopped outside that accounting means
             * both of them can answer "nothing" while Chrome is still encoding frames.
             */
            const work = stopStray(cast);
            track(work);
            await work;
            return false;
          }
          const replaced = entry.cast;
          entry.cast = cast;
          // After the replacement is running, so the screen does not go blank in between.
          if (replaced) {
            const work = stopStray(replaced);
            track(work);
            await work;
          }
          return true;
        },
        setFollow(cancel) {
          if (entry.revoked) {
            try {
              cancel();
            } catch {
              // Same reason the teardown swallows it.
            }
            return false;
          }
          entry.cancelFollow?.();
          entry.cancelFollow = cancel;
          return true;
        },
      };
    },

    async release(socket) {
      const entry = current;
      // Identity, never shape. Two sockets are distinct objects however alike they look, and an
      // equality that compared their contents would hand the screen to any socket resembling the
      // owner. This is also what makes a superseded socket's late close a no-op.
      if (!entry || entry.socket !== socket) return;
      current = undefined;
      entry.revoked = true;
      // Its own close, so nobody is told: the client already knows, and the socket is going away.
      const work = tearDown(entry);
      track(work);
      await work;
    },

    async releaseAll(reason) {
      const entry = current;
      if (!entry) return;
      current = undefined;
      entry.revoked = true;
      const work = tearDown(entry, reason);
      track(work);
      await work;
    },

    standingOf(socket) {
      if (!current || current.socket !== socket) return { state: "gone" };
      return current.cast
        ? { state: "casting", cast: current.cast }
        : { state: "starting" };
    },

    occupied() {
      return current !== undefined || tearing.size > 0;
    },

    async settled() {
      await Promise.all([...tearing]);
    },
  };
}