@reclaimprotocol/agent 0.1.24 → 0.1.25

package/src/cdp/container.ts

@@ -0,0 +1,593 @@
+/**
+ * Run the Reclaim browser runtime in a container.
+ *
+ * This is the same image Popcorn serves for `builder` mode, run on the
+ * developer's own Docker instead of on quota. It brings its own Chromium and
+ * its own live view — a real VNC viewer with an IME, gesture handling and an
+ * OS-level pointer path — so nothing here renders anything. It starts the
+ * container, waits for it to mean it, and hands back the two URLs.
+ *
+ * Three ports exist inside; we publish two, and the distinction matters:
+ *
+ *  - **6080, the viewer.** Safe to put behind a tunnel, which is what
+ *    `share_browser_view` does.
+ *  - **9226, full CDP.** Unfiltered, unauthenticated browser control. Bound to
+ *    loopback and NEVER tunnelled: upstream's own warning is that exposing it
+ *    "would hand anyone control of the browser".
+ *  - **9222, restricted CDP.** Not published at all. Its allowlist is 19
+ *    methods with no `Runtime.*` and no `Network.*`, so it cannot drive the
+ *    authoring loop — verified against a running container.
+ */
+import { execFile } from 'node:child_process'
+import { mkdirSync } from 'node:fs'
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { LOGGER } from '../logger.ts'
+import { reclaimHomeDirPath } from '../paths.ts'
+import {
+	busySlots,
+	claim,
+	ownSlots,
+	processAlive,
+	release,
+} from './claims.ts'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * The pinned runtime image.
+ *
+ * A digest, not a tag. Upstream publishes 40-char git SHAs plus moving
+ * `main`/`latest` aliases and no semver at all, and its own docs say to
+ * "prefer immutable digests". Pinning one means an agent release cannot have
+ * the browser changed underneath it.
+ *
+ * Digest of `latest` as of 2026-08-22, built from popcorn-oss
+ * `4df751c25c7b329699033957b93f6486837e4acb`.
+ */
+export const BROWSER_RUNTIME_IMAGE =
+	'ghcr.io/reclaimprotocol/popcorn-oss/browser-runtime'
+	+ '@sha256:6858c30a37886bc30d8f658e31aeb0bb253ad22eece16e4e41c8883345b399e1'
+
+/**
+ * The image is amd64-only and cannot be otherwise: the browser is Tilion
+ * Fortress, pinned by digest upstream, and Fortress publishes no arm64
+ * manifest. On Apple Silicon it therefore runs translated — which works under
+ * Docker Desktop's Rosetta and OrbStack, and crashes under QEMU. Pinning the
+ * platform is what stops Docker quietly trying to find an arm64 variant that
+ * does not exist.
+ */
+const PLATFORM = 'linux/amd64'
+
+/** Ports inside the container. */
+const VIEWER_PORT = 6080
+const CDP_PORT = 9226
+
+/**
+ * How many browsers may run at once.
+ *
+ * Each is about 2 GB of RAM, so this is a guard against a runaway rather than a
+ * capability. Sessions normally SHARE one: a slot is only added when another
+ * session is actively holding the previous one.
+ */
+const MAX_SLOTS = 4
+
+/**
+ * Marks a container as ours and records which process owns it.
+ *
+ * The PID makes orphan cleanup safe. A container outlives its owner whenever a
+ * session is killed, so something has to remove it — but never one another
+ * session is still using. Whether the owning PID is alive answers that, and
+ * errs harmlessly: a recycled PID leaves a container behind rather than killing
+ * a live one.
+ */
+const OWNER_LABEL = 'org.reclaim.agent.owner-pid'
+
+/**
+ * Two ports nobody is using, guaranteed different from each other.
+ *
+ * A fixed port would give concurrent sessions the same container — the name
+ * derives from the viewer port — so session two would silently drive session
+ * one's browser.
+ *
+ * Both listeners are held open together and released together. Asking twice in
+ * sequence can return the same port, since the first is already closed by the
+ * time the second asks, and one port cannot carry both the viewer and CDP.
+ *
+ * Between releasing a port and Docker publishing it, another process can take
+ * it. That race is unavoidable, and losing it fails the `docker run` loudly
+ * rather than doing anything silent.
+ */
+async function freePortPair(): Promise<{ viewer: number, cdp: number }> {
+	const servers = [createServer(), createServer()]
+	try {
+		const ports = await Promise.all(servers.map(async(server) => {
+			await new Promise<void>((resolve) => {
+				server.listen(0, '127.0.0.1', resolve)
+			})
+			return (server.address() as AddressInfo).port
+		}))
+		return { viewer: ports[0], cdp: ports[1] }
+	} finally {
+		await Promise.all(servers.map((server) => {
+			return new Promise<void>((resolve) => server.close(() => resolve()))
+		}))
+	}
+}
+
+/**
+ * Readiness deadline. The entrypoint gives Chromium 30s to put a window on the
+ * X display before failing, and a cold start measured 6.6s here with the geoip
+ * lookup disabled. 90s leaves room for a slow machine without hanging forever.
+ */
+const READY_TIMEOUT_MS = 90_000
+const READY_POLL_MS = 250
+
+export interface ContainerBrowser {
+	/** Local viewer origin — what `share_browser_view` tunnels. */
+	viewerUrl: string
+	/** Browser-level CDP websocket, for `connectCdpUrl`. */
+	cdpUrl: string
+	/** Loopback port the viewer is published on. */
+	viewerPort: number
+	/** Docker's name for this container. */
+	name: string
+	/** Whether the image had to be pulled first — worth telling the developer. */
+	pulled: boolean
+	/** Which slot this browser occupies, for diagnostics. */
+	slot: number
+	stop: () => Promise<void>
+}
+
+export interface ContainerOptions {
+	/** Loopback port for the viewer. Allocated when omitted. */
+	viewerPort?: number
+	/** Loopback port for full CDP. Allocated when omitted. */
+	cdpPort?: number
+	/** Override the pinned image, e.g. a local `build.sh` output. */
+	image?: string
+	/** Framebuffer size, which is also the browser window's size. */
+	width?: number
+	height?: number
+	/** Page to open on start. */
+	url?: string
+}
+
+/**
+ * Where the container's Chromium profile lives on the host.
+ *
+ * Mounted, unlike the reference dev script, for two reasons. Provider authoring
+ * means signing in once and capturing an authenticated request, which a profile
+ * that dies with the container makes impossible. And the profile holds the
+ * persisted fingerprint identity — canvas/audio seed, timezone, locale — which
+ * upstream warns must stay stable, since "flipping any of them against the same
+ * cookie jar is itself a bot signal".
+ */
+export function containerProfileDir(slot = 0): string {
+	// Slot 0 keeps the original path, so an existing profile — and the login in
+	// it — survives this change. Later slots get their own, because two
+	// Chromiums on one `user-data-dir` corrupt it silently.
+	const suffix = slot === 0 ? '' : `-${slot}`
+	return join(reclaimHomeDirPath(), `browser-runtime-profile${suffix}`)
+}
+
+/** Docker CLI present AND its daemon reachable. */
+export async function dockerAvailable(): Promise<boolean> {
+	try {
+		// `--format {{.Server.Version}}` talks to the daemon, so unlike
+		// `docker --version` it fails when Docker is installed but not running.
+		const { stdout } = await execFileAsync(
+			'docker', ['version', '--format', '{{.Server.Version}}'],
+			{ timeout: 15_000 },
+		)
+		return stdout.trim().length > 0
+	} catch(err) {
+		LOGGER.debug({ err }, 'docker is unavailable')
+		return false
+	}
+}
+
+/** Message for the case we cannot fix for them. */
+export function dockerMissingMessage(): string {
+	return 'Container mode needs Docker, and its daemon is not reachable. '
+		+ 'Install Docker Desktop (https://docs.docker.com/get-started/get-docker/)'
+		+ ' or OrbStack and start it, then retry. On Apple Silicon, enable Rosetta '
+		+ 'for x86/amd64 emulation — the runtime image is amd64-only. '
+		+ 'Or pick another browser: `dedicated` uses local Chrome, and `builder` '
+		+ 'is a remote browser that comes with its own hosted live view.'
+}
+
+async function imagePresent(image: string): Promise<boolean> {
+	try {
+		await execFileAsync('docker', ['image', 'inspect', image],
+			{ timeout: 20_000 })
+		return true
+	} catch{
+		return false
+	}
+}
+
+/** Fetch the image. About 432 MB, so `startContainer` reports it happened. */
+async function pullImage(image: string): Promise<void> {
+	await execFileAsync(
+		'docker', ['pull', '--platform', PLATFORM, image],
+		{ timeout: 900_000, maxBuffer: 1024 * 1024 * 8 },
+	)
+}
+
+/**
+ * The `docker run` argv.
+ *
+ * A pure function because every flag here is load bearing and none of it is
+ * obvious from the outside: which ports are loopback-only, that the image is
+ * digest-pinned, that the profile is mounted. Tests assert on this directly
+ * rather than trying to observe a running container.
+ */
+export function buildRunArgs(
+	opts: ContainerOptions & { viewerPort: number, cdpPort: number },
+	image: string,
+	name: string,
+	profileDir: string,
+): string[] {
+	const args = [
+		'run', '--rm', '-d',
+		'--name', name,
+		'--platform', PLATFORM,
+		// Whose container this is, so an orphan can be told from a container
+		// another session is still driving.
+		'--label', `${OWNER_LABEL}=${process.pid}`,
+		// Loopback only. Both CDP proxies listen on 0.0.0.0 INSIDE the container,
+		// so what is reachable is entirely down to this mapping.
+		'-p', `127.0.0.1:${opts.viewerPort}:${VIEWER_PORT}`,
+		'-p', `127.0.0.1:${opts.cdpPort}:${CDP_PORT}`,
+		// Chromium on Docker's default 64 MB /dev/shm is a crash waiting for a
+		// heavy page. The image README and the upstream Helm chart both give it
+		// 1-2 GiB; only the dev script leaves the default.
+		'--shm-size=1g',
+		// The runtime looks up its own geolocation at boot, twice, with an 8s
+		// timeout each — up to 16s added to every cold start. We are not
+		// impersonating a locale (that is what `builder` mode's country routing is
+		// for), so skip it. Measured: 6.6s to ready with this off.
+		'-e', 'CLOAK_GEOIP=false',
+		// Cookies, localStorage and the persisted fingerprint identity. Without
+		// it, signing in once — the entire point of authoring — cannot survive a
+		// restart.
+		'-v', `${profileDir}:/home/kernel/user-data`,
+	]
+	if(opts.width) {
+		args.push('-e', `WIDTH=${opts.width}`)
+	}
+
+	if(opts.height) {
+		args.push('-e', `HEIGHT=${opts.height}`)
+	}
+
+	if(opts.url) {
+		args.push('-e', `APP_URL=${opts.url}`)
+	}
+
+	args.push(image)
+	return args
+}
+
+/**
+ * Start a browser container and wait until it is actually serving.
+ *
+ * Ports are allocated per call, so concurrent sessions never land on the same
+ * container. Pass `viewerPort` to pin one — re-attaching with the same port
+ * reuses the container that is already there.
+ */
+export async function startContainer(
+	options: ContainerOptions = {},
+): Promise<ContainerBrowser> {
+	// Containers whose session died without cleaning up, cleared before we look
+	// for one to adopt. Deliberately here rather than at server startup: a
+	// short-lived server exits before a fire-and-forget reap finishes, and nobody
+	// who never uses container mode should pay for a `docker ps` at launch.
+	await reapOrphanedContainers()
+
+	const image = options.image ?? BROWSER_RUNTIME_IMAGE
+	const slot = await pickSlot()
+	const name = containerName(slot)
+	const token = claim(name)
+
+	// Adopt a container that is already serving on this slot. This is the common
+	// case for one developer working across sessions: the browser, and whatever
+	// they signed into, is still there.
+	const adopted = await adopt(name)
+	if(adopted) {
+		LOGGER.info({ name }, 'adopted the browser container already running')
+		return describe(adopted, name, false, slot, token)
+	}
+
+	// Anything left under this name is wreckage — the slot has no live claimant.
+	if(await inspectContainer(name)) {
+		LOGGER.info({ name }, 'removing a container that is no longer serving')
+		await execFileAsync('docker', ['rm', '-f', name], { timeout: 60_000 })
+			.catch(() => {})
+	}
+
+	const ports = await freePortPair()
+	const opts = {
+		...options,
+		viewerPort: options.viewerPort ?? ports.viewer,
+		cdpPort: options.cdpPort ?? ports.cdp,
+	}
+	const profileDir = containerProfileDir(slot)
+	mkdirSync(profileDir, { recursive: true })
+
+	const pulled = !await imagePresent(image)
+	if(pulled) {
+		LOGGER.info({ image }, 'pulling the browser runtime image')
+		await pullImage(image)
+	}
+
+	await execFileAsync('docker', buildRunArgs(opts, image, name, profileDir),
+		{ timeout: 120_000 })
+	try {
+		await waitUntilServing(opts.cdpPort)
+	} catch(err) {
+		await captureLogs(name)
+		release(name, token)
+		await stopContainer(name)
+		throw err
+	}
+
+	return describe(opts, name, pulled, slot, token)
+}
+
+/** `reclaim-browser-0`, `-1`, … — one name per slot, so a slot is findable. */
+function containerName(slot: number): string {
+	return `reclaim-browser-${slot}`
+}
+
+/**
+ * A slot this session may use.
+ *
+ * Prefers one we ALREADY hold, so re-attaching within a session adopts the
+ * browser it is already running instead of paying 2 GB and twenty seconds for a
+ * second one. Then the lowest slot nobody holds. A new slot only appears when
+ * ANOTHER session is actively using the earlier ones, because two containers on
+ * one profile would corrupt it.
+ */
+async function pickSlot(): Promise<number> {
+	const held = ownSlots()
+	for(let slot = 0; slot < MAX_SLOTS; slot++) {
+		if(held.has(containerName(slot))) {
+			return slot
+		}
+	}
+
+	const busy = busySlots()
+	for(let slot = 0; slot < MAX_SLOTS; slot++) {
+		if(!busy.has(containerName(slot))) {
+			return slot
+		}
+	}
+
+	throw new Error(
+		`All ${MAX_SLOTS} browser containers are in use by other sessions, which `
+		+ 'is as many as this runs at once — each costs about 2 GB of RAM. Close '
+		+ 'one of those sessions, or attach with mode "dedicated" to use local '
+		+ 'Chrome instead.',
+	)
+}
+
+/**
+ * The ports a running container publishes, or undefined when there is nothing
+ * healthy to adopt.
+ *
+ * Adoption has to DISCOVER the ports rather than allocate them: the container
+ * was started by a previous session that chose its own.
+ */
+async function adopt(
+	name: string,
+): Promise<{ viewerPort: number, cdpPort: number } | undefined> {
+	if(await inspectContainer(name) !== 'running') {
+		return undefined
+	}
+
+	let mapped = ''
+	try {
+		const { stdout } = await execFileAsync('docker', ['port', name],
+			{ timeout: 20_000 })
+		mapped = stdout
+	} catch{
+		return undefined
+	}
+
+	// Lines look like `6080/tcp -> 127.0.0.1:49987`.
+	const portFor = (containerPort: number) => {
+		const line = mapped.split('\n')
+			.find((l) => l.startsWith(`${containerPort}/tcp`))
+		const host = line?.split(':').pop()?.trim()
+		return host ? Number(host) : undefined
+	}
+
+	const viewerPort = portFor(VIEWER_PORT)
+	const cdpPort = portFor(CDP_PORT)
+	if(!viewerPort || !cdpPort || !await isServing(cdpPort)) {
+		return undefined
+	}
+
+	return { viewerPort, cdpPort }
+}
+
+/** Read the container's CDP websocket and assemble the handle. */
+async function describe(
+	opts: { viewerPort: number, cdpPort: number },
+	name: string,
+	pulled: boolean,
+	slot: number,
+	token: string,
+): Promise<ContainerBrowser> {
+	const version = await fetch(`http://127.0.0.1:${opts.cdpPort}/json/version`)
+		.then((res) => res.json()) as { webSocketDebuggerUrl?: string }
+	if(!version.webSocketDebuggerUrl) {
+		await stopContainer(name)
+		throw new Error(
+			'The browser container is serving but reported no CDP websocket.',
+		)
+	}
+
+	return {
+		viewerUrl: `http://127.0.0.1:${opts.viewerPort}/liveview.html?magnify=1`,
+		cdpUrl: version.webSocketDebuggerUrl,
+		viewerPort: opts.viewerPort,
+		name,
+		pulled,
+		slot,
+		// Stopping is really "I am done with it". The container only goes when
+		// this was the last session holding the slot; otherwise it keeps serving
+		// whoever else is using it.
+		stop: async() => {
+			if(release(name, token)) {
+				await stopContainer(name)
+				return
+			}
+
+			LOGGER.info({ name }, 'left the container running for another session')
+		},
+	}
+}
+
+/** Stop a container. `--rm` means stopping it also removes it. Best effort:
+ *  teardown must not throw on the way out. */
+async function stopContainer(name: string): Promise<void> {
+	try {
+		await execFileAsync('docker', ['stop', '-t', '2', name],
+			{ timeout: 60_000 })
+	} catch(err) {
+		// Already gone is the outcome we wanted, not a problem to report.
+		const message = err instanceof Error ? err.message : String(err)
+		if(/No such container/i.test(message)) {
+			LOGGER.debug({ name }, 'container was already stopped')
+			return
+		}
+
+		LOGGER.warn({ err, name }, 'could not stop the browser container')
+	}
+}
+
+/** Docker's state for a container, or undefined when there is no such name. */
+async function inspectContainer(name: string): Promise<string | undefined> {
+	try {
+		const { stdout } = await execFileAsync('docker',
+			['inspect', '--format', '{{.State.Status}}', name], { timeout: 20_000 })
+		return stdout.trim() || undefined
+	} catch{
+		return undefined
+	}
+}
+
+/** One shot of the readiness check, for deciding whether to reuse. */
+async function isServing(cdpPort: number): Promise<boolean> {
+	try {
+		const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
+			signal: AbortSignal.timeout(2_000),
+		})
+		return res.ok
+	} catch{
+		return false
+	}
+}
+
+/**
+ * Wait until the runtime is serving, not merely listening.
+ *
+ * The proxy binds its ports early and answers `503 app is not ready` on EVERY
+ * route until the entrypoint has seen a Chromium window and touched
+ * `/tmp/minimal-vnc-ready`. So a plain "did the socket accept" check passes
+ * while there is no browser — which is exactly the trap the reference script
+ * falls into, polling with `curl -sS` and no `-f`. Requiring a 2xx is the whole
+ * point.
+ */
+async function waitUntilServing(cdpPort: number): Promise<void> {
+	const deadline = Date.now() + READY_TIMEOUT_MS
+	let lastStatus = 'no response'
+	while(Date.now() < deadline) {
+		try {
+			const res = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
+				signal: AbortSignal.timeout(2_000),
+			})
+			if(res.ok) {
+				return
+			}
+
+			lastStatus = `HTTP ${res.status}`
+		} catch(err) {
+			lastStatus = err instanceof Error ? err.message : String(err)
+		}
+
+		await new Promise((resolve) => setTimeout(resolve, READY_POLL_MS))
+	}
+
+	throw new Error(
+		'The browser container never became ready within '
+		+ `${READY_TIMEOUT_MS / 1000}s (last: ${lastStatus}). On Apple Silicon `
+		+ 'this usually means x86 emulation is unavailable — enable Rosetta in '
+		+ 'Docker Desktop, or use OrbStack.',
+	)
+}
+
+/** Log the container's own account of a failed start, which is where the
+ *  reason lives (a SIGTRAP under QEMU, say). */
+async function captureLogs(name: string): Promise<void> {
+	try {
+		const { stdout, stderr } = await execFileAsync(
+			'docker', ['logs', '--tail', '40', name], { timeout: 20_000 },
+		)
+		LOGGER.warn({ name, logs: `${stdout}\n${stderr}`.trim().slice(-4000) },
+			'browser container failed to start')
+	} catch(err) {
+		LOGGER.debug({ err }, 'could not read the container logs')
+	}
+}
+
+/**
+ * Remove containers whose owning process is gone.
+ *
+ * Shutdown cleanup covers an orderly exit, but a SIGKILL or a crash runs
+ * nothing — and a 1.3 GB container with a live browser in it should not outlive
+ * the session that made it. Reaping at startup catches those, and the owner-PID
+ * label keeps it safe: a container whose owner still runs belongs to another
+ * session and is left alone.
+ */
+export async function reapOrphanedContainers(): Promise<string[]> {
+	let listed = ''
+	try {
+		const { stdout } = await execFileAsync('docker', [
+			'ps', '--filter', `label=${OWNER_LABEL}`,
+			'--format', `{{.Names}} {{.Label "${OWNER_LABEL}"}}`,
+		], { timeout: 20_000 })
+		listed = stdout
+	} catch{
+		// No Docker, or no daemon. Nothing to reap and nothing to report.
+		return []
+	}
+
+	const reaped: string[] = []
+	for(const line of listed.split('\n')) {
+		const [name, pid] = line.trim().split(/\s+/)
+		if(!name || !pid) {
+			continue
+		}
+
+		if(processAlive(Number(pid))) {
+			continue
+		}
+
+		try {
+			await execFileAsync('docker', ['rm', '-f', name], { timeout: 60_000 })
+			reaped.push(name)
+			LOGGER.info({ name, pid }, 'removed an orphaned browser container')
+		} catch(err) {
+			// Someone else may have removed it first. Not worth failing a start.
+			LOGGER.debug({ err, name }, 'could not remove an orphan')
+		}
+	}
+
+	return reaped
+}