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.
/**
* The Bot's browser, and the profile that outlives it.
*
* A persistent profile lets a Bot remain signed in across process and container restarts.
*
* Persistent context, not a saved storage state. Playwright can export cookies and localStorage as
* JSON and replay them, and that is the wrong tool here: it captures what the automation knew about,
* on demand, and misses IndexedDB, service workers, and anything written after the snapshot.
* `launchPersistentContext` points Chromium at a real user-data directory, so the browser persists
* its own state the way it does on a desktop. On a mounted volume, that directory outlives the
* container.
*
* Profile behavior in this image and Playwright version:
* - A cookie with an expiry survives close-and-reopen. So does localStorage.
* - A session cookie (no expiry) does not: Chromium drops those on restart, exactly as a desktop
* browser does. Here a restart is a pod being deleted by an idle suspend or an image update, so
* `session-cookies.ts` writes them to a file in the same profile and puts them back on launch.
* - Killing the browser process with SIGKILL leaves no stale singleton lock in the profile, and the
* profile reopens with its cookies intact. The widely-reported `SingletonLock` breakage does not
* reproduce here. The defensive sweep below stays anyway, because it is three lines and the
* failure it prevents is "the computer never comes back".
*
* One profile per Bot. Two Bots sharing a profile share their logins, which makes "this Bot may reach
* Salesforce" unenforceable: whatever one signs into, the other is signed into. Each Bot gets its own
* directory, so its cookies and its storage are its own.
*
* A profile is not a container. Two Bots in this process are isolated from each other's cookies, not
* from each other's kernel, filesystem or memory.
*
* Container-per-Bot needs something privileged to create containers, and the API server must never be
* that: access to the Docker socket is unrestricted root on the host. Stop and reset are
* operations this process applies to its own browser, so the same design works under Compose,
* Kubernetes or ECS, where the orchestrator's own restart policy brings a process back.
*/
import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import {
type BrowserContext,
type CDPSession,
chromium,
type Page,
} from "playwright";
import {
isPersonBrowserId,
RECORDER_DIR_ENV,
} from "../../shared/openbot-browser";
import { profileDirectoryFor, seatParts } from "./bot-id";
import {
chooseEvictions,
chooseForMemory,
chooseIdle,
chooseIdleTabs,
keptOpen,
} from "./browser-eviction";
import { type BrowserRuntime, browserRuntimeFromEnv } from "./browser-runtime";
import { type CarryOverOutcome, carryOverProfile } from "./carry-over";
import {
type MemoryReading,
memoryAtOrAbove,
memoryRunsHigh,
memoryTargetPercent,
readContainerMemory,
} from "./container-memory";
import { egressFor, egressLabel } from "./egress";
import { numberFromEnv, settleWithin } from "./env";
import { chooseLivePage } from "./live-page";
import { attachBrowserNetwork, attachPageNetwork } from "./page-network";
import { BrowserNotOpenError } from "./person-access";
import {
launchPersonBrowser,
type PersonBrowser,
personPages,
windowPages,
} from "./person-browser";
import {
type PersonDisplay,
PLAYWRIGHT_DISABLED_FEATURES,
personWindow,
recorderLaunchOptions,
} from "./person-launch";
import { seatIdsIn } from "./profile-listing";
import { findRecorder, isRecorderPage, type Recorder } from "./recorder";
import {
fitWindowsToViewport,
keepRecorderCurrent,
reachRecorder,
} from "./recorder-in-browser";
import type { RecorderLauncher } from "./recorder-launcher";
import {
type SessionCookieKeeper,
sessionCookieKeeper,
} from "./session-cookies";
// Re-exported so callers that already import it from here do not change, while the test imports it
// from the playwright-free `./env` instead of pulling this module's browser driver in with it.
export { numberFromEnv };
/** The viewport, which is what a person's click coordinates are relative to. */
export const VIEWPORT = { width: 1280, height: 800 };
/**
* Files Chromium uses to refuse a second instance on one profile.
*
* Swept on the way in rather than the way out, because the way out is the case that does not happen:
* a container that is killed does not get to run cleanup. If this process is starting, no browser of
* ours is running, so any lock here is by definition from a life that has already ended.
*/
const SINGLETON_FILES = ["SingletonLock", "SingletonSocket", "SingletonCookie"];
/**
* How the browser is started, and why each flag is here.
*
* `--password-store=basic` makes a durable profile work in a container. Chromium normally encrypts
* cookie values with a desktop keyring; containers have no stable gnome-keyring or kwallet, so the
* default fallback can make stored cookies unreadable after restart.
*
* `basic` pins it to Chromium's own fixed fallback, which is deterministic and survives restarts.
* This is obfuscation at rest, not protection. Anything that can read the volume can read the
* cookies. The volume's own permissions are the security boundary.
*/
/**
* Whether Chromium gets to use its own sandbox.
*
* OFF BY DEFAULT, AND THAT IS NOT A PREFERENCE. Chromium's sandbox creates user namespaces, and
* Docker's default seccomp profile blocks the syscall it needs, so a container that does nothing
* special gets `No usable sandbox!` and the browser will not start at all. Verified both ways in
* this image: default profile fails, relaxed profile renders.
*
* TURN IT ON WHERE THE HOST ALLOWS IT. On a VM or self-hosted Docker, run with a Chromium seccomp
* profile and set `COMPUTER_SANDBOX=on`. That is strictly better than everything below, because it
* is the boundary Chromium itself maintains against the pages it renders.
*
* WHERE IT CANNOT BE ON. Serverless container platforms do not let you set a seccomp profile or add
* capabilities; Fargate restricts `CAP_SYS_ADMIN` explicitly. There the sandbox is unavailable, and
* the compensating controls are the ones this image already has, a non-root user, plus gVisor
* underneath, which Cloud Run applies to everything by default.
*
* Said out loud at start-up either way. An operator should not have to read this file to find out
* whether the browser rendering the open internet is sandboxed.
*/
const BROWSER_RUNTIME = browserRuntimeFromEnv(process.env);
// Native Chrome has no container boundary. Always retain its own process sandbox and OS keychain.
const sandboxFor = (runtime: BrowserRuntime) =>
runtime.backend === "local-chrome" || process.env.COMPUTER_SANDBOX === "on";
const SANDBOX_ENABLED = sandboxFor(BROWSER_RUNTIME);
/**
* Playwright's own disabled features, and AcceptCHFrame, for every browser that reaches the network
* through the egress filter: a Bot's, and a person's on the live screen.
*
* WHY. Such a browser is given the filter with the Bot in its proxy credentials, and a Playwright
* browser given proxy credentials answers the proxy's challenge itself, through DevTools request
* interception, so every request it makes is intercepted. Google (www.google.com and
* accounts.google.com) sends an HTTP/2 ACCEPT_CH frame while the connection is set up, asking for
* client hints; Chromium then aborts the page's request and restarts it with those hints, and under
* Playwright's interception the restarted request is never sent. Measured on this filter with
* Playwright 1.62.1's Chromium: the main-frame request for https://www.google.com/ ends ERR_ABORTED
* at "connected" and no second one follows, so the page waited until the navigation timed out,
* while Bing and Wikipedia (no ACCEPT_CH frame) loaded. The same browser loaded Google in about 330
* ms with this feature off, or with no proxy credentials.
*
* With it off, Chromium learns which hints a site wants from its Accept-CH response header, as it
* did before the frame existed, and sends them from the next request on. Playwright itself launched
* with it off from 2021 (microsoft/playwright#10380, for the same restart under interception) until
* 1.58 (#38472); #40194 is this hang reported against later versions.
*
* Playwright's own list is repeated because Chromium keeps only the last `--disable-features` on a
* command line (base/command_line.cc), and this one comes after Playwright's. Both lists are checked
* against the launched browser's own command line in `person-browser.test.ts`.
*/
const BEHIND_THE_FILTER_FEATURES = `--disable-features=${[
...PLAYWRIGHT_DISABLED_FEATURES,
"AcceptCHFrame",
].join(",")}`;
const launchArgsFor = (local: boolean, sandbox: boolean): string[] => [
...(sandbox ? [] : ["--no-sandbox"]),
"--disable-dev-shm-usage",
...(local ? [] : ["--password-store=basic"]),
// Drop the automation signals Chromium sets for itself, so a real person who takes the wheel can
// sign in to a site that refuses obvious automation (Google among them). This is the flag, not a
// JS patch of `navigator.webdriver`: the flag turns the property off at the source, where spoofing
// it from a script leaves the other tells a detector cross-checks. It does not change what the Bot
// may do; the governed path is unchanged. Full Chromium is selected explicitly in both modes;
// headed mode also provides a window a person can use on the native desktop or virtual display.
"--disable-blink-features=AutomationControlled",
BEHIND_THE_FILTER_FEATURES,
];
/**
* WebRTC kept inside the proxy, written into the profile before Chromium reads it.
*
* Chromium sends WebRTC over UDP straight past an HTTP proxy unless told not to, so a page in a Bot's
* browser could reach the network around the egress filter. `disable_non_proxied_udp` allows only
* UDP through a proxy, and an HTTP proxy carries none, so WebRTC goes over the proxy or not at all.
* A preference rather than the `--force-webrtc-ip-handling-policy` switch, which current Chromium
* no longer reads (measured: the switch on the command line, packets still sent). Merged into
* whatever Preferences the profile already has, so nothing else the profile remembers is lost.
*/
export async function keepWebRtcInsideProxy(profileDir: string) {
const file = join(profileDir, "Default", "Preferences");
let preferences: Record<string, unknown> = {};
try {
const parsed = JSON.parse(await readFile(file, "utf8"));
if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
preferences = parsed;
} catch {
// No Preferences yet (a new profile), or one Chromium never finished writing: start clean.
}
const webrtc =
preferences.webrtc && typeof preferences.webrtc === "object"
? (preferences.webrtc as Record<string, unknown>)
: {};
if (webrtc.ip_handling_policy === "disable_non_proxied_udp") return;
preferences.webrtc = {
...webrtc,
ip_handling_policy: "disable_non_proxied_udp",
};
await mkdir(join(profileDir, "Default"), { recursive: true });
await writeFile(file, JSON.stringify(preferences));
}
console.info(
JSON.stringify({
type: "computer-sandbox",
sandbox: SANDBOX_ENABLED ? "on" : "off",
...(SANDBOX_ENABLED
? {
note: "Chromium's own sandbox is in use. It will refuse to start if the host does not permit user namespaces.",
}
: {
note: "Chromium runs without its own sandbox, which is the only thing that works under a default container seccomp profile. Set COMPUTER_SANDBOX=on where the host allows it.",
}),
}),
);
/**
* How long to let a closing browser finish writing before moving on.
*
* The profile's Cookies file may be rewritten shortly after `close()` is called. This delay stays
* clear of that window while remaining inside the container's
* 30s stop grace period, so a shutdown never becomes the reason a computer does not come back.
*/
const CLOSE_SETTLE_MS = 2_000;
/**
* How long a change of the page in front of a person's browser waits before it is logged. A person
* who closes their browser's window, or quits it, closes its tabs one after another, each making the
* next the page in front, and none of those is a change the browser stays open for. A quit of Google
* Chrome 156 (headless, three tabs) closed the tabs within 20 ms and the browser within 60 ms.
*/
const PAGE_CHANGE_SETTLE_MS = 500;
/**
* How long telling a viewer its browser went away may take before the close carries on without it.
*
* The close is what has to happen; the announcement is courtesy. Unbounded, one screencast that will
* not stop would hold a browser close open, and because the cap evicts from inside another Bot's
* launch, it would hold that launch and everything queued behind it too. On the way out it would
* keep every profile from flushing until the container was killed.
*/
const ANNOUNCE_BUDGET_MS = 2_000;
/**
* How long a stop or reset waits for a launch it is racing.
*
* Long enough for a cold Chromium start, which is what it is waiting for, and bounded so a launch
* that never finishes cannot hold a request open forever. Timing out leaves the browser running,
* which is the same answer the caller got before this waited at all.
*/
const LAUNCH_WAIT_MS = 30_000;
/** What a Bot's browser looks like from outside. */
export type BotBrowser = {
botId: string;
context: BrowserContext;
page: Page;
};
export type ProfileSummary = {
/** The seat: the Bot, or the person and the Bot on a computer many people share. */
seat: string;
botId: string;
/** Whose seat it is, where this computer serves more than one person. */
personId?: string;
/** Whether a browser is running for this Bot right now. */
running: boolean;
/** When this Bot's browser was last started, or null if it is not running. */
startedAt: string | null;
/** The proxy its traffic leaves through, by host only. Never the credentials. */
egress: string | null;
};
/**
* Close a context and wait for Chromium to finish writing.
*
* Chromium batches cookie writes and commits them as it exits, while `close()` only asks it to exit.
* Bounded, because a shutdown that hangs must never be the reason a computer does not come back. We
* would rather lose the last few seconds of cookies than never restart.
*/
async function closeAndWait(context: BrowserContext): Promise<void> {
await context.close().catch(() => undefined);
// A fixed settle is used because persistent contexts do not expose a reliable browser-exit signal.
await new Promise((resolve) => setTimeout(resolve, CLOSE_SETTLE_MS));
}
/**
* How many browsers one computer holds at once.
*
* There was no cap. A context was started the first time each Bot was used and kept, and the only
* things that dropped one were an explicit stop, a browser that had already died, and shutdown. A
* deployment where every employee has a Bot therefore trends toward one resident Chromium per
* employee in a single container, at a few hundred MB each, until the container is killed for memory
* and `page()` relaunches its way back to the same state.
*
* A cap rather than only an idle timeout, because the failure is concurrent breadth rather than age:
* fifty people using their Bots inside the same minute are fifty live browsers and none of them are
* idle. The least recently used is closed, which is the one whose Bot has been quiet longest.
*
* Closing is not losing anything. The profile is on disk, so a Bot whose browser was closed starts
* again where it left off, which is what `stop` already means here.
*/
const MAX_LIVE_BROWSERS = numberFromEnv("COMPUTER_MAX_BROWSERS", 8);
/**
* How long a browser may sit untouched before it is closed.
*
* The other half. A deployment under the cap still holds a browser per Bot that was used once last
* Tuesday, and that memory is doing nothing for anybody.
*
* Zero is the documented way to say "keep them resident", which is why it is read as a value here
* rather than as a value that is not set. Read like the cap, an operator who wrote it got the
* default back and the sweep they had switched off carried on closing their browsers.
*/
const IDLE_TIMEOUT_MS = numberFromEnv("COMPUTER_BROWSER_IDLE_MS", 30 * 60_000, {
zeroSwitchesItOff: true,
});
/**
* How often the idle sweep looks. Cheap: it walks a map of at most `MAX_LIVE_BROWSERS`, their tabs,
* and three small files under `/sys/fs/cgroup`.
*/
const IDLE_SWEEP_MS = 60_000;
/**
* At what share of the computer's memory it starts closing browsers, least recently used first.
*
* The cap counts browsers, and a browser is not a fixed size: a few heavy pages can take a container
* past its memory limit well under the cap, and the OOM killer does not choose by use. On Kubernetes
* with cgroup v2 it kills every process in the container together, every Bot's browser at once, and
* nothing can reach the computer until it comes back. So memory is read the way Kubernetes reads it
* (`container-memory.ts`) before every launch, which is when memory jumps, and on every tick of the
* idle sweep. At or above this share of the limit, browsers are closed one at a time, least recently
* used first, until memory is ten points under it (`memoryTargetPercent`). Closing one costs its Bot
* a relaunch and nothing else, the same as the cap.
*
* A check, not a guarantee. Between two checks a page can grow on its own, and memory can run out
* before the next launch or the next minute comes round. What this removes is the computer filling
* itself up one launch at a time with browsers nobody is using.
*
* Eighty-five leaves room for the launch that asked, and for a page that grows after the check,
* before the limit is reached. Zero switches it off, as it does for the idle sweep. A computer with no
* cgroup of its own (OpenBot Desktop's, on a person's Mac) has no limit to read and closes nothing
* for memory either way. In the all-in-one image the share counts the database and the API server as
* well, deliberately: the OOM kill counts them too, and a browser closed first is what keeps them up.
*/
const MEMORY_HIGH_PERCENT = numberFromEnv("COMPUTER_MEMORY_HIGH_PERCENT", 85, {
zeroSwitchesItOff: true,
max: 100,
});
/**
* How long a Bot's background tab may sit untouched before the idle sweep closes it.
*
* A Bot is always on its newest page, so a tab it left behind (the page a sign-in popup opened from,
* a link a site opened in a new tab) is one it cannot get back to, holding a renderer and its memory
* for as long as the browser is up. Ten minutes is long enough for a popup's sign-in to come back to
* the page that opened it, and a third of the thirty after which a whole idle browser is closed, so a
* tab left behind in a browser that is still in use does not wait for the browser to go. See
* `chooseIdleTabs` for what is never closed. Zero switches it off.
*
* No count of tabs alongside it. A count is the wrong measure for the same reason the browser cap is
* not enough on its own: one heavy tab outweighs twenty light ones, and memory is now watched
* directly. A count would also close tabs a site opened a moment ago, in the middle of the flow they
* were opened for, where a timeout only ever closes what has been left alone.
*/
const TAB_IDLE_MS = numberFromEnv("COMPUTER_TAB_IDLE_MS", 10 * 60_000, {
zeroSwitchesItOff: true,
});
/**
* Told whenever a Bot's browser is closed and forgotten, before the close is waited on.
*
* Exists because closing a browser is not the whole of stopping a computer: anything still pointed
* at the page it was showing has to be taken down with it, and the live screen's follow loop calls
* back in for a page every second, which is a launch path. A viewer left running therefore relaunches
* whatever was just closed, so a stopped computer restarts itself and an idle one never goes away.
*
* It is announced here rather than called from the two request handlers because a browser closes
* from more places than those: the cap after a launch and the idle sweep close one without any
* request being involved. Hanging the teardown off the close itself covers those by construction,
* where remembering to add a call at each new handler does not.
*
* Awaited before the context closes, so a follow loop cannot squeeze a relaunch into the gap.
*/
export type BrowserClosed = (botId: string) => void | Promise<void>;
export type ProfilesOptions = {
/**
* How browsers start here. The computer's own, read from its environment, unless a test needs a
* combination the environment refuses: a person's native browser launched headless, which is how
* that launch is tested without opening a window on the machine running the tests.
*/
runtime?: BrowserRuntime;
/**
* The display the person's desktop session had, captured before this process pointed `DISPLAY`
* at its own Xvfb. A person's native window opens there. Defaults to this process's environment
* as it is now.
*/
personDisplay?: PersonDisplay;
/**
* The built Recorder (`OPENBOT_RECORDER_DIR`), read at every launch of a Bot's browser, so a rebuilt Recorder is the
* one the next browser gets. Defaults to this process's environment as it is at that launch.
*/
recorderDir?: () => string | undefined;
/**
* The computer's memory now, or nothing when it has no limit to read. The container's own cgroup
* unless a test hands in the reading it wants the computer to see.
*/
memory?: () => Promise<MemoryReading | undefined>;
/** {@link MEMORY_HIGH_PERCENT}, for a test. */
memoryHighPercent?: number;
/** {@link TAB_IDLE_MS}, for a test that cannot wait ten minutes. */
tabIdleMs?: number;
/**
* The clock every use, idle timeout and memory decision here is measured by. `Date.now` unless a
* test needs a browser to have gone quiet a minute ago without waiting a minute for it.
*/
now?: () => number;
/**
* Whether a person holds this Bot's wheel, or has been asked to take it. Such a browser is never
* closed for memory, and none of its tabs are closed for being idle: a person may be working across
* them. The computer's sessions answer it (`sessions.personHasTheWheel`); without it, nobody does.
*/
heldByPerson?: (botId: string) => boolean;
};
/** Opening a person's browser, which is the one way it starts. See `person-browser.ts`. */
export type PersonOpen = { recorder: Recorder };
/**
* The Recorder in a Bot's browser (`shared/bot-browser.ts`): loaded at every launch on a computer that has it, and
* disconnected and silent until a person holding the wheel presses Record.
*/
export type BotRecorder = {
/** The Recorder's id in this browser, which says which pages and which worker are its own. */
recorderId: string;
launcher: RecorderLauncher;
/**
* Why it cannot be used, when taking hold of it at launch failed. The Bot's browser carries on without it: a
* Recorder that will not start is never a reason a Bot cannot work.
*/
problem?: string;
};
/** A Bot's Recorder as this module holds it: with the browser-level session its launcher speaks over. */
type HeldRecorder = BotRecorder & { session: CDPSession };
/** A Bot's running browser, for the bar a person holding its wheel works (`bot-browser-host.ts`). */
export type OpenBotBrowser = {
context: BrowserContext;
/** Absent where this computer has no Recorder, or runs Bots in local Chrome. */
recorder?: BotRecorder;
/** The browser-level DevTools session, which the tab list reads titles from. */
session(): Promise<CDPSession>;
/** The page the Bot is on, which the live screen shows and the bar acts on. */
active(): Page;
/**
* Put a tab in front for the Bot as well as on the screen: it stays the Bot's page until another tab opens or it
* closes, so the Bot carries on where the person left it.
*/
activate(page: Page): void;
/** The Bot's tabs, oldest first, never the Recorder's own pages. */
pages(): Page[];
/**
* Make the window hold exactly the page the live screen shows, from the first time a person switches its tabs (see
* `fitWindowsToViewport`). Not at launch: a Bot's browser nobody works stays exactly as it launches.
*/
fitWindows(): Promise<void>;
};
/** A person's open browser, for the browser routes. */
export type OpenPersonBrowser = PersonBrowser & {
context: BrowserContext;
/** The tab the person is on, which the live screen shows. */
active(): Page;
/** Put a tab in front: the one the live screen follows and the routes act on. */
activate(page: Page): void;
/** The person's tabs, oldest first, never the Recorder's own pages. */
pages(): Page[];
};
export function createProfiles(
root: string,
onClosed: BrowserClosed,
options: ProfilesOptions = {},
) {
const runtime = options.runtime ?? BROWSER_RUNTIME;
const local = runtime.backend === "local-chrome";
const sandbox = sandboxFor(runtime);
const launchArgs = launchArgsFor(local, sandbox);
const personDisplay: PersonDisplay = options.personDisplay ?? {
DISPLAY: process.env.DISPLAY,
WAYLAND_DISPLAY: process.env.WAYLAND_DISPLAY,
};
const recorderDir =
options.recorderDir ?? (() => process.env[RECORDER_DIR_ENV]);
const readMemory = options.memory ?? (() => readContainerMemory());
const memoryHighPercent = options.memoryHighPercent ?? MEMORY_HIGH_PERCENT;
const tabIdleMs = options.tabIdleMs ?? TAB_IDLE_MS;
const now = options.now ?? Date.now;
const heldByPerson = options.heldByPerson ?? (() => false);
/*
* A wheel that cannot be read counts as held. The control state throws when its store has failed,
* and the answer decides whether a browser or a tab is closed: keeping one is the mistake that
* costs nothing, and a throw here must never fail the launch that asked.
*/
const spared = (botId: string): boolean => {
try {
return heldByPerson(botId);
} catch {
return true;
}
};
type LiveBrowser = {
context: BrowserContext;
page: Page;
startedAt: string;
/** When this Bot last asked for its page. Decides what the cap and the sweep close. */
usedAt: number;
/** Point `page` at whatever is open now. Called on every page opening and closing. */
retarget: () => void;
/** Keeps this browser's session cookies on the profile volume. Absent for a native Chrome. */
sessionCookies?: SessionCookieKeeper;
/** Present for a person's browser, which has the Recorder in it and no Bot acting in it. */
person?: PersonBrowser;
/** Present for a Bot's browser: what the bar a person holding its wheel works needs of it. */
bot?: {
recorder?: BotRecorder;
/** Whether a page is one of the Bot's own, rather than one of the Recorder's. */
own(page: Page): boolean;
/** Put a page in front, and keep it there (see `OpenBotBrowser.activate`). */
pin(page: Page): void;
session(): Promise<CDPSession>;
fitWindows(): Promise<void>;
};
};
/**
* Write a browser's session cookies one last time and stop checking them.
*
* Before the close, because a closed context has no cookies to read. Bounded like the
* announcement, because a browser that will not answer must not hold a close open.
*/
const keepSessionCookies = async (running: LiveBrowser): Promise<void> => {
const keeper = running.sessionCookies;
if (!keeper) return;
await settleWithin(
keeper.save().then(() => keeper.stop()),
ANNOUNCE_BUDGET_MS,
);
};
/** One running browser per Bot, up to {@link MAX_LIVE_BROWSERS}. */
const live = new Map<string, LiveBrowser>();
/** A person's native window: the idle sweep leaves it and the cap takes it last. See `keptOpen`. */
const stays = keptOpen(personWindow(runtime));
/**
* When each of a Bot's tabs was last used: acted on, navigated, or in front. Decides which
* background tabs the idle sweep closes. Weak, so a closed page takes its entry with it.
*/
const tabUsedAt = new WeakMap<Page, number>();
const touchTab = (page: Page): void => {
tabUsedAt.set(page, now());
};
/** A tab never seen before counts as used now, so one this process missed is not closed at once. */
const tabLastUsed = (page: Page): number => {
const at = tabUsedAt.get(page) ?? now();
tabUsedAt.set(page, at);
return at;
};
/** A tab that navigates is in use, a background one included: a site moving it on, a sign-in finishing. */
const touchOnNavigation = (page: Page): void => {
page.on("framenavigated", (frame) => {
if (frame === page.mainFrame()) touchTab(page);
});
};
/** Launches in flight, so a cold computer is started once however many callers ask at once. */
const starting = new Map<string, Promise<Page>>();
/** Closes and resets in flight, so a Bot's browser is never reopened from a profile being closed or deleted. */
const closing = new Map<string, Promise<void>>();
const whileClosing = async (
botId: string,
work: () => Promise<void>,
): Promise<void> => {
const { promise: done, resolve } = Promise.withResolvers<void>();
const held = Promise.all([closing.get(botId), done]).then(() => undefined);
closing.set(botId, held);
try {
await work();
} finally {
resolve();
void held.then(() => {
if (closing.get(botId) === held) closing.delete(botId);
});
}
};
// Checked, not joined. `join(root, botId)` normalizes `..` away, so a Bot id of `../workspace`
// used to resolve outside the root and `reset` would delete whatever was there.
const directoryFor = (botId: string): string =>
profileDirectoryFor(root, botId);
/**
* Close one Bot's browser and forget it.
*
* Gracefully, so Chromium flushes the profile: the whole point of closing one is that the Bot's
* logins survive and its next request starts where it left off.
*/
const evict = async (botId: string, reason: string): Promise<boolean> => {
const running = live.get(botId);
if (!running) return false;
live.delete(botId);
console.info(
JSON.stringify({ type: "computer-browser-closed", botId, reason }),
);
// Before the close, so whatever was watching this browser is taken down while it is still the
// browser being closed. A live screen surviving here relaunches it a second later.
//
// Bounded, because this now sits on the launch path: `enforceCap` evicts from inside another
// Bot's launch, so a teardown that never answers would pin that launch and every caller waiting
// on it. The close is the thing that must happen; being told about it is best effort.
await whileClosing(botId, async () => {
await settleWithin(Promise.resolve(onClosed(botId)), ANNOUNCE_BUDGET_MS);
await keepSessionCookies(running);
await closeAndWait(running.context).catch(() => undefined);
});
return true;
};
/**
* Keep the number of running browsers under the cap.
*
* Least recently used first, which is the Bot that has been quiet longest. Called after a launch
* rather than before, so the Bot that just asked is never the one closed.
*/
const enforceCap = async (): Promise<void> => {
for (const botId of chooseEvictions(
live.entries(),
MAX_LIVE_BROWSERS,
stays,
)) {
await evict(botId, "the cap on running browsers was reached");
}
};
/**
* Close browsers, least recently used first, once the computer's memory runs high, until it is ten
* points under the line.
*
* One at a time, reading memory again after each close, because what one browser was holding is
* not known until it has gone. Starts at {@link MEMORY_HIGH_PERCENT} and goes on to
* `memoryTargetPercent` under it, so the launch after it does not cross the line again at once.
* Stops when memory is there, when nothing is left that may be closed (`chooseForMemory`: never
* the browser launching, the most recently used, one in use within the last minute, one a person
* holds the wheel of, or a person's own), or when the same browser comes up twice.
*/
const relieveMemoryOnce = async (): Promise<void> => {
if (memoryHighPercent <= 0) return;
// A reading that fails is a computer with nothing to act on, the same as one with no cgroup.
const read = () => readMemory().catch(() => undefined);
let reading = await read();
if (!reading || !memoryRunsHigh(reading, memoryHighPercent)) return;
const target = memoryTargetPercent(memoryHighPercent);
const tried = new Set<string>();
while (reading && memoryAtOrAbove(reading, target)) {
const next = chooseForMemory(live.entries(), now(), { spared });
if (!next || tried.has(next)) return;
tried.add(next);
console.info(
JSON.stringify({
type: "computer-browser-closed-for-memory",
botId: next,
workingSetBytes: reading.workingSet,
limitBytes: reading.limit,
}),
);
await evict(next, "the computer's memory ran high");
reading = await read();
}
};
/**
* One pass at a time, which every caller waits on.
*
* A burst of launches each ran a pass of its own, and each read memory before any close had given
* any back: a browser's memory is released when its Chromium exits, seconds after it was taken out
* of the map. So K launches at once read the same high number and closed K browsers where one was
* enough. A launch that arrives while a pass is running waits for that pass and launches after it.
*/
let relieving: Promise<void> | undefined;
const relieveMemory = (): Promise<void> => {
relieving ??= relieveMemoryOnce().finally(() => {
relieving = undefined;
});
return relieving;
};
/**
* Close the background tabs of every Bot's browser that nothing has touched for a while.
*
* Never a person's browser, whose tabs are theirs and which has no Bot in it, and never a Bot's
* while a person holds its wheel, because they may be working across its tabs. Within a Bot's
* browser, `chooseIdleTabs` decides, and the page the Bot is on is never one of them, so it is
* still the newest open page afterwards and the record does not move. The address is not logged:
* a page left behind can be a sign-in link with a one-time token in it.
*/
const closeIdleTabs = async (): Promise<number> => {
if (tabIdleMs <= 0) return 0;
const sweptAt = now();
let closed = 0;
for (const [botId, running] of [...live.entries()]) {
if (running.person || isPersonBrowserId(botId) || spared(botId)) continue;
// Closed while an earlier Bot's tabs were being closed: nothing of it is left to sweep.
if (live.get(botId) !== running) continue;
running.retarget();
const tabs = running.context
.pages()
.filter((page) => !page.isClosed())
.map((page) => ({
page,
usedAt: tabLastUsed(page),
front: page === running.page,
kept:
page.url().startsWith("chrome-extension://") ||
page.url().startsWith("devtools://"),
}));
for (const { page } of chooseIdleTabs(tabs, tabIdleMs, sweptAt)) {
console.info(
JSON.stringify({
type: "computer-tab-closed",
botId,
reason: "it had been idle",
}),
);
await page.close().catch(() => undefined);
closed += 1;
}
}
return closed;
};
/**
* Close browsers nothing has touched for a while, then the tabs Bots left behind, then, if memory
* still runs high, browsers by use.
*
* The cap answers concurrent breadth; this answers a Bot used once last Tuesday whose browser is
* still resident and doing nothing for anybody. In that order because each step is gentler than the
* next: a browser nobody is using goes before a tab of one somebody is, and a tab nobody can reach
* goes before a browser that is still in use.
*/
const sweepIdle = async (): Promise<void> => {
for (const botId of chooseIdle(
live.entries(),
IDLE_TIMEOUT_MS,
now(),
stays,
)) {
await evict(botId, "it had been idle");
}
const tabsClosed = await closeIdleTabs().catch(() => 0);
// A closed tab's renderer exits a moment after the tab does, so memory read at once would still
// count it, and a browser could be closed for memory the tabs had already given back.
if (tabsClosed > 0)
await new Promise((resolve) => setTimeout(resolve, CLOSE_SETTLE_MS));
await relieveMemory();
};
const idleSweep = setInterval(() => {
void sweepIdle().catch(() => undefined);
}, IDLE_SWEEP_MS);
// Housekeeping must not hold the process open on the way out.
idleSweep.unref?.();
/**
* Close a browser a person asked to close, including one that is still starting.
*
* `evict` only knows about browsers already in `live`, and a launch does not land there until it
* finishes. A request arriving inside that window therefore passed straight through: it answered
* "nothing was running", the launch completed a moment later, and the browser the person asked to
* close was up with the live screen still on it and the follow loop keeping it marked recently
* used, so the idle sweep would not reclaim it either. Reset was worse, deleting the profile
* directory that the finishing launch then recreated.
*
* So a request waits for the launch it is racing and closes what it produced. This is deliberately
* NOT inside `evict`: the cap evicts from inside a launch, and an `evict` that waited on `starting`
* could wait on the very launch it is running under.
*/
const closeOnRequest = async (
botId: string,
reason: string,
): Promise<boolean> => {
// Its failure is the launch's own to report; here it only means there is nothing left to close.
await settleWithin(starting.get(botId), LAUNCH_WAIT_MS);
return evict(botId, reason);
};
const sweepLocks = async (dir: string): Promise<void> => {
await Promise.all(
SINGLETON_FILES.map((name) =>
rm(join(dir, name), { force: true }).catch(() => undefined),
),
);
};
/*
* Session cookies back before anything navigates, so the first request a site sees from this
* launch is already signed in. Not for a native Chrome: its cookies are protected by the OS
* keychain, and a plain file beside them would undo that. The container profile uses the
* basic password store, so the file adds no exposure the volume did not already have.
*/
const keepSessionCookiesFrom = async (
botId: string,
dir: string,
context: BrowserContext,
): Promise<SessionCookieKeeper | undefined> => {
if (local) return undefined;
const sessionCookies = sessionCookieKeeper(botId, dir, context);
await sessionCookies.restore().catch((error: unknown) => {
console.info(
JSON.stringify({
type: "computer-session-cookies-not-restored",
botId,
reason: error instanceof Error ? error.message : String(error),
}),
);
});
sessionCookies.start();
return sessionCookies;
};
/** The built Recorder a Bot's browser launches with, or none: none configured, or one that is not a built Recorder. */
const recorderForBot = async (
botId: string,
): Promise<Recorder | undefined> => {
const configured = recorderDir();
if (!configured?.trim()) return undefined;
const found = await findRecorder(configured);
if (found.ok) return found.recorder;
console.info(
JSON.stringify({
type: "computer-bot-recorder-unavailable",
botId,
reason: found.error,
}),
);
return undefined;
};
/**
* Take hold of the Recorder a Bot's browser launched with, as a person's is held: its setup pages closed as they
* appear, its launcher reached, its worker made to run the Recorder on disk. Before the Bot's first page is chosen,
* so a setup page the launch or a reload opens has come and gone by then.
*
* Never fatal. A Recorder that will not start costs the Bot nothing: the browser runs on, the failure is said in the
* log, and Record answers that this browser cannot record.
*/
const holdBotRecorder = async (
botId: string,
context: BrowserContext,
recorder: Recorder,
): Promise<HeldRecorder | undefined> => {
const reason = (error: unknown) =>
error instanceof Error ? error.message : String(error);
let session: CDPSession;
try {
const browser = context.browser();
if (!browser) throw new Error("The browser did not start.");
session = await browser.newBrowserCDPSession();
} catch (error) {
console.info(
JSON.stringify({
type: "computer-bot-recorder-unavailable",
botId,
reason: reason(error),
}),
);
return undefined;
}
// Loaded by flag, so its id is the one its manifest key fixes (`findRecorder`).
const recorderId = recorder.id;
const launcher = reachRecorder({ session, context, recorderId });
try {
await keepRecorderCurrent({
session,
launcher,
recorder,
recorderId,
botId,
});
return { recorderId, launcher, session };
} catch (error) {
console.info(
JSON.stringify({
type: "computer-bot-recorder-unavailable",
botId,
reason: reason(error),
}),
);
return { recorderId, launcher, session, problem: reason(error) };
}
};
/**
* A person's browser: the Recorder in it, their tabs, and the one they are on.
*
* The tab in front is kept rather than recomputed. A Bot's browser follows the newest page,
* because a window a site opened is where the Bot's work went; a person moves between tabs, so
* the one they put in front stays in front until they choose another, a new tab opens (which a
* browser brings to the front), or it closes. The live screen follows whichever that is.
*
* It is closed when the person closes it. Quitting the browser ends the context, and closing the
* last window ends it too: on macOS Chrome keeps running with no window, and a browser nobody can
* see is one the person closed. A native window is not closed by the idle sweep, and goes last at
* the cap; a cloud browser, which the person reaches only through the Browser page, closes when
* nobody has touched it for as long as a Bot's would (`keptOpen`).
*
* A window is a window whatever it shows. One left on one of the Recorder's own pages (its
* options, say) is still the person's browser on the screen: it is open, it is not closed under
* them, and opening it again brings it forward rather than relaunching it. The Recorder's pages are
* never put in front over a tab of the person's, but when they are all there is, the one in front
* is one of them.
*/
const launchPerson = async (
botId: string,
dir: string,
open: PersonOpen,
): Promise<Page> => {
const window = personWindow(runtime);
const { context, person } = await launchPersonBrowser({
botId,
dir,
runtime,
recorder: open.recorder,
// A hosted browser runs on OpenBot's network, so it goes through the egress filter like any
// other browser here. A native window is the person's own browser on their own machine, and
// reaches the network the way their everyday browser does.
proxy: window === "screen" ? egressFor(botId, process.env) : null,
sandbox,
botArgs: launchArgs,
viewport: VIEWPORT,
display: personDisplay,
});
const sessionCookies = await keepSessionCookiesFrom(botId, dir, context);
const { recorderId } = person;
let page = personPages(context, recorderId).at(-1);
try {
page ??= await context.newPage();
/*
* What a hosted Bot's browser says about itself, said by the hosted person's browser too:
* both are this computer's Chromium on its network, and a person's search or sign-in is
* judged by the same signals. Without it a headless one sent `HeadlessChrome` in its user
* agent and its client hints, and Google answered searches with its "unusual traffic" check
* and refused sign-in as a browser that "may not be secure", from an address where Chrome was
* fine. Before the person's first page loads, and for every tab as it opens. Read from one of
* the person's own tabs first, because what the browser says is read once per browser from
* a page, and the Recorder's setup page may be the other one there, closing. A native window
* is the person's own browser, which says who it is already, as a local Bot's does. Never the
* Web Bot Auth signature: that says the deployment's automated agent sent the request, and a
* person browsing is not it.
*/
if (window === "screen") {
const network = { headless: runtime.mode === "headless" };
await attachPageNetwork(context, page, network);
await attachBrowserNetwork(context, { ...network, signs: false });
for (const opened of context.pages())
void attachPageNetwork(context, opened, network);
context.on("page", (opened) => {
void attachPageNetwork(context, opened, network);
});
}
} catch (error) {
// Not left running unrecorded: a browser that never made it into the map is closed here.
await sessionCookies?.stop();
await context.close().catch(() => undefined);
throw error;
}
const record: LiveBrowser = {
context,
page,
startedAt: new Date().toISOString(),
usedAt: now(),
retarget: () => {},
...(sessionCookies ? { sessionCookies } : {}),
person,
};
const bringForward = (next: Page) => {
if (next === record.page) return;
record.page = next;
// In front at once; said once the browser has stayed open with it in front.
setTimeout(() => {
if (live.get(botId) !== record || record.page !== next) return;
if (next.isClosed() || !context.browser()?.isConnected()) return;
console.info(
JSON.stringify({
type: "computer-page-changed",
botId,
url: next.url(),
}),
);
}, PAGE_CHANGE_SETTLE_MS).unref();
};
record.retarget = () => {
if (
!record.page.isClosed() &&
!isRecorderPage(record.page.url(), recorderId)
)
return;
// The person's newest tab; failing that, while the one in front has closed, whatever window
// is left.
const next =
personPages(context, recorderId).at(-1) ??
(record.page.isClosed() ? windowPages(context).at(-1) : undefined);
if (next) bringForward(next);
};
const closed = () => {
// A browser being closed closes its tabs one by one, and none of them is a page change: a
// close takes the browser out of `live` before it closes it.
if (live.get(botId) !== record) return;
record.retarget();
if (windowPages(context).length === 0)
void evict(botId, "its last window was closed");
};
const follow = (opened: Page) => {
opened.on("close", closed);
// A tab that becomes one of the Recorder's own pages is never the one in front.
opened.on("framenavigated", (frame) => {
if (frame === opened.mainFrame() && opened === record.page)
record.retarget();
});
};
for (const existing of context.pages()) follow(existing);
context.on("page", (opened) => {
follow(opened);
if (!isRecorderPage(opened.url(), recorderId)) bringForward(opened);
});
context.on("close", () => {
if (live.get(botId) === record) void evict(botId, "it was closed");
});
live.set(botId, record);
await enforceCap();
return record.page;
};
return {
/**
* The Bot's page, starting its browser if it is not running.
*
* Started on first use rather than at boot, and re-created if it died: a crashed Chromium would
* otherwise leave this process alive and answering the same error for every request until the
* container restarts. This turns that into one slow request instead of an outage.
*/
async page(
botId: string,
request: { open?: PersonOpen } = {},
): Promise<Page> {
// Only when something is closing: an unconditional await would let a stop slip in ahead of the launch.
const closingNow = closing.get(botId);
if (closingNow) await closingNow;
/*
* One launch at a time per Bot. Calls that arrive during a launch wait for that launch instead
* of starting another browser against the same profile directory.
*/
const launching = starting.get(botId);
if (launching) return launching;
const existing = live.get(botId);
// Asked before the page is judged, so a close that has not been delivered yet does not read as
// a browser that has gone.
existing?.retarget();
// A person's browser whose one window shows a Recorder page is open like any other (see
// `launchPerson`), so the page in front is judged only by whether it is still there.
if (
existing?.context.browser()?.isConnected() &&
!existing.page.isClosed()
) {
// Touched on every use, which is what makes "least recently used" mean anything. The page in
// front with it: a Bot's next action, and a person's input on the live screen, land there.
existing.usedAt = now();
touchTab(existing.page);
return existing.page;
}
if (existing) {
// Half-dead: the browser went away, or its page did. Dropped rather than repaired, because a
// context whose browser has gone is not usable for anything.
//
// The one close that does not announce itself, deliberately. A replacement is launched on the
// next line and the live screen's follow loop re-attaches to it within the second, so this is
// a browser being swapped rather than one going away. Telling the viewer here would end a
// screen that is about to be fine, which is the opposite of what the announcement is for.
await existing.sessionCookies?.stop();
await existing.context.close().catch(() => undefined);
live.delete(botId);
}
/*
* A person's browser starts only when they open it. Anything else asking for its page (the
* live screen's follow loop, a person's input arriving late) finds it closed and says so,
* rather than opening a window on somebody's desktop they have just closed.
*/
const { open } = request;
if (isPersonBrowserId(botId) && !open) throw new BrowserNotOpenError();
const launch = (async () => {
// Before the launch, which is when memory jumps: a cold Chromium and its first page are the
// largest single step up a computer takes, and the OOM killer does not wait for the cap.
await relieveMemory();
const dir = directoryFor(botId);
// A second native helper can target the same data root on another port. Do not remove an
// active Chrome profile's lock; Chrome reports contention and handles its own stale locks.
if (!local) {
await sweepLocks(dir);
await keepWebRtcInsideProxy(dir);
}
if (open && isPersonBrowserId(botId))
return launchPerson(botId, dir, open);
// The Bot's own proxy and policy, whoever's seat this is: a seat is a Bot's place on this
// computer (see `seatIdFor`), and what it may reach is decided per Bot.
const proxy = egressFor(seatParts(botId).botId, process.env);
// The Recorder, where this computer has one. Never in local Chrome, whose Bot browser is a window on the
// person's own desktop, and absent the Bot's browser launches exactly as it always has.
const recorder = local ? undefined : await recorderForBot(botId);
const headless = runtime.mode === "headless";
const context = await chromium.launchPersistentContext(dir, {
channel: runtime.channel,
...(recorder
? // A Bot's launch with the Recorder let in, as the hosted person's browser launches.
recorderLaunchOptions(
{
recorderDir: recorder.dir,
headless,
sandbox,
botArgs: launchArgs,
},
VIEWPORT,
)
: {
headless,
args: launchArgs,
// Playwright launches with `--enable-automation`, which sets `navigator.webdriver` and the
// "controlled by automated software" banner. Dropped for the same reason as the flag above:
// a person who takes the wheel should be able to sign in. Named explicitly so the sandbox
// default args Playwright still supplies are otherwise left intact.
ignoreDefaultArgs: ["--enable-automation"],
// Playwright adds `--no-sandbox` on its own unless told otherwise, so leaving this out
// means the flag above decides nothing and a deployment that asked for the sandbox does
// not get one. Verified by reading the launched process arguments, not by trusting either.
chromiumSandbox: sandbox,
viewport: VIEWPORT,
}),
// This process owns shutdown. Playwright's signal handlers kill Chromium immediately on
// SIGTERM, before pending cookie writes have time to flush.
handleSIGTERM: false,
handleSIGINT: false,
handleSIGHUP: false,
...(proxy ? { proxy } : {}),
});
const held = recorder
? await holdBotRecorder(botId, context, recorder)
: undefined;
const recorderId = recorder?.id;
/*
* A Bot's page is never one of the Recorder's own. The Recorder opens its setup page each time a launch
* installs it, and that page closes the moment it shows (`holdRecorder`), but until then it is the newest
* page, which the Bot would otherwise have followed as a window the site opened.
*/
const own = (opened: Page) =>
recorderId === undefined || !isRecorderPage(opened.url(), recorderId);
const sessionCookies = await keepSessionCookiesFrom(
botId,
dir,
context,
);
// Persistent contexts open with a page already; reuse it rather than leaving an extra blank tab.
const page =
context.pages().filter(own)[0] ?? (await context.newPage());
/*
* The user agent fix and the Web Bot Auth signature, before the first navigation so the first
* request a site sees already carries both. Not for a native Chrome: that is the person's own
* browser, which says who it is already and should not announce a deployment on their behalf.
*/
const network = { headless };
if (!local) {
await attachBrowserNetwork(context, network);
await attachPageNetwork(context, page, network);
}
/*
* The tab a person holding the wheel put in front with the bar. It stays the Bot's page until another tab
* opens (a browser brings a new tab to the front) or it closes, so the Bot carries on in the tab the person
* left in front. Without one, the Bot follows the newest page, as it always has.
*/
let pinned: Page | undefined;
let browserSession: Promise<CDPSession> | undefined;
let fitted: Promise<void> | undefined;
const record: LiveBrowser = {
context,
page,
startedAt: new Date().toISOString(),
usedAt: now(),
retarget: () => {},
...(sessionCookies ? { sessionCookies } : {}),
bot: {
...(held ? { recorder: held } : {}),
own,
pin: (chosen: Page) => {
pinned = chosen;
record.retarget();
},
// The Recorder's session when there is one, which the launcher already holds; otherwise one opened the
// first time the bar asks, so a Bot nobody works the bar of opens none.
session: () => {
browserSession ??= held
? Promise.resolve(held.session)
: (async () => {
const browser = context.browser();
if (!browser) throw new BrowserNotOpenError();
return browser.newBrowserCDPSession();
})();
return browserSession;
},
// A window on the person's own desktop (local Chrome) is theirs to size.
fitWindows: () => {
if (local) return Promise.resolve();
fitted ??= fitWindowsToViewport(context, VIEWPORT, botId);
return fitted;
},
},
};
touchTab(page);
touchOnNavigation(page);
record.retarget = () => {
const next =
pinned && !pinned.isClosed() && own(pinned)
? pinned
: chooseLivePage(context.pages().filter(own));
if (!next || next === record.page) return;
// Both are in use at this moment: the one going behind was in front until now.
touchTab(record.page);
touchTab(next);
record.page = next;
console.info(
JSON.stringify({
type: "computer-page-changed",
botId,
url: next.url(),
}),
);
};
/*
* A page that closes while the browser stays open moves the record on. One closing because the
* browser is being closed (out of `live` already) moves nothing: it is not a page change, and
* saying so for every tab as it went only filled the log.
*/
const closed = () => {
if (live.get(botId) === record) record.retarget();
};
// A tab that turns out to be one of the Recorder's own (it can report the blank page it started on when it
// opens) is never the Bot's page.
const watchForRecorderPages = (opened: Page) => {
if (recorderId === undefined) return;
opened.on("framenavigated", (frame) => {
if (frame === opened.mainFrame() && opened === record.page)
record.retarget();
});
};
watchForRecorderPages(page);
// Without this the Bot stays pinned to the page it launched with, so a sign-in the site opens
// in a new window is neither shown to the person taking the wheel nor reachable by input.
context.on("page", (opened) => {
if (!local) void attachPageNetwork(context, opened, network);
if (own(opened)) pinned = undefined;
touchTab(opened);
touchOnNavigation(opened);
record.retarget();
watchForRecorderPages(opened);
// A popup closes itself when it succeeds, and the record must move back to the opener
// rather than leave a closed page to be read as a dead browser.
opened.on("close", closed);
});
page.on("close", closed);
live.set(botId, record);
// After the new one is in the map, so the cap counts what is really running and the Bot that
// just asked is the most recently used and therefore never the one closed.
await enforceCap();
// Not `page`: a window opened while the browser was starting is already the live one.
return record.page;
})();
starting.set(botId, launch);
try {
return await launch;
} finally {
// Cleared whether it worked or not so a failed launch does not pin future calls to a rejected
// promise.
starting.delete(botId);
}
},
/**
* Stop this Bot's browser, keeping what it knows.
*
* The same close the cap and the idle sweep make, so it goes through the same path rather than
* repeating it: a request is one more reason a browser closes, not a different kind of closing,
* and anything watching has to come down either way. `reason` is what the close is logged with,
* when the caller knows better than "it was stopped".
*/
async stop(botId: string, reason = "it was stopped"): Promise<boolean> {
return closeOnRequest(botId, reason);
},
/**
* Forget everything this Bot knows and start over.
*
* The browser is closed before the directory is deleted: deleting a profile
* out from under a running Chromium is how you get a browser that is alive, writing to files that
* no longer exist, and reporting success. Nothing is recreated here, the next request starts a
* clean browser, which is the same path as a first ever start and so needs no second code path.
*/
async reset(botId: string): Promise<void> {
// Its own reason rather than borrowing stop's, so the trail says which of the two happened.
await whileClosing(botId, async () => {
await closeOnRequest(botId, "it was reset");
await rm(directoryFor(botId), { recursive: true, force: true });
});
},
/**
* Give a person the profile their private Bot had before seats were per person. See carry-over.ts.
*
* Held as a close of the seat, so a request for it cannot launch a browser on a directory that is
* half way through arriving.
*/
async carryOver(botId: string, seatId: string): Promise<CarryOverOutcome> {
let outcome: CarryOverOutcome = "absent";
await whileClosing(seatId, async () => {
outcome = await carryOverProfile(root, botId, seatId, () =>
closeOnRequest(
botId,
"its profile moved to the person it belongs to",
),
);
});
return outcome;
},
/**
* Wipe this browser's data, at the request of the person working it (`shared/bot-browser.ts`, CLEARING A BROWSER):
* closed, its whole profile deleted, and nothing recreated, as `reset` does to the profile.
*
* NOT A CLOSE ANYTHING WATCHING IS TOLD OF. Every other close announces itself (`onClosed`), which ends the live
* screen and hands the wheel back to the Bot, because a browser that went from under a person is a restart they
* have to look at again. This one is the person's own doing, and the browser is about to start again under them,
* as the half-dead browser `page` drops is swapped: the live screen's follow loop finds the fresh one within the
* second, and the wheel stays where it is. `forget` is told after the close and before anything can start the
* browser again, so the computer forgets the browser it described (its run, its page) before the fresh one is
* seen. Whatever has to happen while the browser can still be told (a recording ending) is the caller's, first.
*
* Its session cookies are not written on the way out: they are part of what goes. Answers whether a browser was
* running.
*/
async clear(botId: string, forget: () => void): Promise<boolean> {
let wasRunning = false;
await whileClosing(botId, async () => {
// A launch it is racing finishes first, and is closed with the rest, as a reset closes it.
await settleWithin(starting.get(botId), LAUNCH_WAIT_MS);
const running = live.get(botId);
if (running) {
wasRunning = true;
live.delete(botId);
console.info(
JSON.stringify({
type: "computer-browser-closed",
botId,
reason: "its data was cleared",
}),
);
await running.sessionCookies?.stop();
await closeAndWait(running.context);
}
forget();
await rm(directoryFor(botId), { recursive: true, force: true });
});
return wasRunning;
},
/**
* Every Bot that has a computer, whether or not one is running.
*
* Read from disk rather than from memory, because a Bot's computer exists as long as its profile
* does: after a restart nothing is running and every login is still there, and an admin page that
* listed only live browsers would show an empty screen and imply the logins were gone.
*/
async known(): Promise<string[]> {
const onDisk = await readdir(root, { withFileTypes: true }).catch(
() => [],
);
/*
* The rule lives in its own module, so the test that covers it imports the same one this uses.
* It had a copy before, which meant deleting this filter left the suite green.
*/
return [...new Set([...seatIdsIn(onDisk), ...live.keys()])].sort();
},
/** What the admin surface lists. Running or not, because a Bot that has a profile has a computer. */
summary(botIds: string[]): ProfileSummary[] {
const known = new Set([...botIds, ...live.keys()]);
return [...known].sort().map((seat) => {
const running = live.get(seat);
const { botId, personId } = seatParts(seat);
return {
seat,
botId,
...(personId ? { personId } : {}),
running: Boolean(running),
startedAt: running?.startedAt ?? null,
egress: egressLabel(botId, process.env),
};
});
},
/**
* Close every browser, for shutdown.
*
* `docker stop` and a Kubernetes eviction both send SIGTERM and then wait. Closing the contexts
* here gives Chromium the chance to flush its profile within that grace period.
*/
async closeAll(): Promise<void> {
clearInterval(idleSweep);
const entries = [...live.entries()];
live.clear();
// Told for each, the same as any other close. On the way out it changes nothing that survives,
// but a viewer whose socket outlives this by a moment is still owed the message.
await Promise.all(
entries.map(([botId]) =>
settleWithin(Promise.resolve(onClosed(botId)), ANNOUNCE_BUDGET_MS),
),
);
// Written before the close, so a pod deleted by a suspend or an image update keeps its sign-ins.
await Promise.all(entries.map(([, c]) => keepSessionCookies(c)));
await Promise.all(entries.map(([, c]) => closeAndWait(c.context)));
},
/** How many browsers are running. For the idle sweep's own tests, and for a status reader. */
liveCount(): number {
return live.size;
},
/** Whether this Bot has a browser right now, so a caller can drop state that belongs to one. */
isLive(botId: string): boolean {
return live.has(botId);
},
/**
* A person's browser when it is open, touched like any page request so the cap sees it in use.
* Undefined when it is closed, still starting, or has no window left. A window showing only one
* of the Recorder's own pages is open: its tab list is then empty, and the page in front is that
* Recorder page.
*/
person(botId: string): OpenPersonBrowser | undefined {
const running = live.get(botId);
const person = running?.person;
if (!running || !person) return undefined;
if (!running.context.browser()?.isConnected()) return undefined;
running.retarget();
const pages = () => personPages(running.context, person.recorderId);
if (!windowPages(running.context).includes(running.page))
return undefined;
running.usedAt = now();
return {
...person,
context: running.context,
active: () => {
running.retarget();
return running.page;
},
activate: (page: Page) => {
running.page = page;
},
pages,
};
},
/**
* A Bot's browser when it is running, for the bar. Never starts it, and does not count as a use: the app reads the
* bar's state while the Bot's screen is open, and that alone must not keep an idle browser from being closed.
*/
bot(botId: string): OpenBotBrowser | undefined {
const running = live.get(botId);
const bot = running?.bot;
if (!running || !bot) return undefined;
if (!running.context.browser()?.isConnected()) return undefined;
running.retarget();
if (running.page.isClosed()) return undefined;
return {
context: running.context,
...(bot.recorder ? { recorder: bot.recorder } : {}),
session: bot.session,
active: () => {
running.retarget();
return running.page;
},
activate: bot.pin,
pages: () =>
running.context
.pages()
.filter((page) => !page.isClosed() && bot.own(page)),
fitWindows: bot.fitWindows,
};
},
/** Run the idle sweep now. Exposed so a test does not have to wait a minute for the interval. */
sweepIdleNow(): Promise<void> {
return sweepIdle();
},
};
}
export type Profiles = ReturnType<typeof createProfiles>;