@agent-flow-board/bridge 0.1.0 → 0.3.0

package/dist/checks/browser.js

@@ -0,0 +1,275 @@
+// THE BROWSER OF A CHECK: ONE CHROMIUM SERVER STARTED BY THE PARENT, WHICH THE SANDBOXED CHILD ONLY CONNECTS TO.
+// Playwright is not a dependency of the bridge (it is large and most people never run a check). It is found next to the bridge when it is there,
+// and otherwise installed once into ~/.agent-flow-board/checks/runtime. Nothing in this file imports Playwright at load time.
+// -- DEP-MODULES -- //
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+// -- MODULES -- //
+import { acquireLock } from './lock.js';
+import { checksHome, ensureDir } from './paths.js';
+// -- CONSTANTS -- //
+/** The Playwright version the runtime install pins, so a check behaves the same on every machine. */
+export const PLAYWRIGHT_VERSION = '1.64.0';
+const INSTALL_TIMEOUT_MS = 10 * 60_000;
+/** Written when the runtime and the Chromium download both finished. Only this note says the install is whole (a download that was cut leaves files behind). */
+const COMPLETE_NOTE = '.complete';
+/** One machine installs once: the lock outlives the longest install, and a waiter gives up after a little longer than that. */
+const INSTALL_LOCK_STALE_MS = 2 * INSTALL_TIMEOUT_MS + 60_000;
+const INSTALL_LOCK_WAIT_MS = 2 * INSTALL_TIMEOUT_MS + 120_000;
+// -- FUNCTIONS -- //
+/** Where the runtime install lives. It is a folder of the bridge's own state, never a repo. */
+const runtimeDir = () => join(checksHome(), 'runtime');
+const looksInstalled = (nodeModules) => existsSync(join(nodeModules, 'playwright-core', 'package.json'));
+/** The version of the playwright-core in a node_modules folder, or '' when it cannot be read. */
+function versionIn(nodeModules) {
+    try {
+        const v = JSON.parse(readFileSync(join(nodeModules, 'playwright-core', 'package.json'), 'utf8'));
+        return v && typeof v === 'object' ? String(v.version ?? '') : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Which of two Playwright folders to use. The one next to the bridge is used when it is the pinned version; when it is another version and the runtime
+ * install holds the pinned one, the runtime copy wins (the browser pool relies on the isolation of that exact version). With neither pinned, the one next to
+ * the bridge is returned (assertPlaywrightVersion then says what is wrong), else the runtime copy, else null.
+ */
+export function choosePlaywrightDir(beside, runtime, versionOf = versionIn) {
+    if (beside && versionOf(beside) === PLAYWRIGHT_VERSION)
+        return beside;
+    if (runtime && versionOf(runtime) === PLAYWRIGHT_VERSION)
+        return runtime;
+    return beside ?? runtime;
+}
+/**
+ * The node_modules folder that holds playwright-core (and @playwright/test when it is there): next to the bridge first (when it is the pinned version),
+ * then the runtime install. The sandboxed child is allowed to read this folder and nothing else outside its own. Null when Playwright is not installed anywhere.
+ */
+export function playwrightRuntimeDir() {
+    let beside = null;
+    try {
+        const pkg = createRequire(import.meta.url).resolve('playwright-core/package.json');
+        // .../node_modules/playwright-core/package.json -> .../node_modules
+        beside = dirname(dirname(pkg));
+    }
+    catch {
+        /* Not next to the bridge: try the runtime install */
+    }
+    const own = join(runtimeDir(), 'node_modules');
+    return choosePlaywrightDir(beside, looksInstalled(own) ? own : null);
+}
+/** The folders whose playwright-core version was already compared with the pin. */
+const versionChecked = new Set();
+/**
+ * Throws when the playwright-core in `dir` is not the pinned version. The browser pool relies on the isolation of that exact version
+ * (every connection to a launched server gets contexts of its own), so another version is refused rather than trusted.
+ */
+export function assertPlaywrightVersion(dir) {
+    if (versionChecked.has(dir))
+        return;
+    let found = '';
+    try {
+        const v = JSON.parse(readFileSync(join(dir, 'playwright-core', 'package.json'), 'utf8'));
+        found = v && typeof v === 'object' ? String(v.version ?? '') : '';
+    }
+    catch {
+        /* Unreadable: reported below */
+    }
+    if (found !== PLAYWRIGHT_VERSION)
+        throw new Error(`The check tool needs Playwright ${PLAYWRIGHT_VERSION} but found ${found || 'no readable version'} in ${dir}. Run "agent-flow-board check setup".`);
+    versionChecked.add(dir);
+}
+/** Loads playwright-core from the folder playwrightRuntimeDir names, by absolute path. */
+export async function loadPlaywright() {
+    const dir = playwrightRuntimeDir();
+    if (!dir)
+        throw new Error('Playwright is not installed yet. Run "agent-flow-board check setup" and it will install it.');
+    assertPlaywrightVersion(dir);
+    const req = createRequire(join(dir, 'package.json'));
+    return req(join(dir, 'playwright-core'));
+}
+/** The Chromium rule that makes every host unresolvable except the preview's, localhost and the hosts named. */
+export function hostResolverRule(hosts = []) {
+    const exclude = [...new Set(['127.0.0.1', 'localhost', ...hosts])]
+        .map((h) => `EXCLUDE ${h}`)
+        .join(', ');
+    return `--host-resolver-rules=MAP * ~NOTFOUND, ${exclude}`;
+}
+/**
+ * A browser the parent starts, so a check's process only connects to it and never has to start a program itself.
+ * Every host except the preview's (and the hosts named) is unresolvable, whatever a check does with routes.
+ */
+export async function launchBrowserServer({ headed = false, hosts = [] } = {}) {
+    const { chromium } = await loadPlaywright();
+    // Never pass the shared-browser option: without it every connection gets contexts of its own and sees none of another connection's
+    const server = await chromium.launchServer({
+        headless: !headed,
+        args: [hostResolverRule(hosts), '--disable-background-networking', '--no-first-run']
+    });
+    return {
+        wsEndpoint: () => server.wsEndpoint(),
+        close: () => server.close(),
+        onClose: (callback) => void server.on('close', callback)
+    };
+}
+/** Says whether an installer failure looks like no network or a proxy, so the one-line error can tell the person what to look at. */
+export function describeInstallFailure(output) {
+    if (/proxy|407|tunnel|ECONNRESET|self[- ]signed|certificate/i.test(output))
+        return 'it looks like a proxy problem (check HTTPS_PROXY and the proxy settings)';
+    if (/ENOTFOUND|EAI_AGAIN|ENETUNREACH|ECONNREFUSED|ETIMEDOUT|getaddrinfo|offline|network/i.test(output))
+        return 'it looks like this machine is offline';
+    return 'see the last lines above';
+}
+/** Runs a program with the exact arguments (no shell, no stdin) and sends every output line to `log`. Resolves with the exit code and the last output. */
+function runLogged(file, args, log, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, args, {
+            cwd,
+            shell: false,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let tail = '';
+        const feed = (chunk) => {
+            for (const line of chunk.toString('utf8').split(/\r?\n/)) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                tail = `${tail}\n${t}`.slice(-2000);
+                log(t);
+            }
+        };
+        child.stdout.on('data', feed);
+        child.stderr.on('data', feed);
+        const timer = setTimeout(() => child.kill(), INSTALL_TIMEOUT_MS);
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ code, tail });
+        });
+    });
+}
+/** The npm that belongs to this Node: its npm-cli.js, so no shell is needed. Null when it is not where Node keeps it. */
+function npmCli() {
+    const root = dirname(process.execPath);
+    const candidates = [
+        join(root, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        join(root, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js')
+    ];
+    return candidates.find((c) => existsSync(c)) ?? null;
+}
+/**
+ * Installs Playwright into the runtime folder of the bridge's state.
+ * This is the ONE place npm is used: it installs a runtime for the installed bridge into ~/.agent-flow-board, never into a repo,
+ * so the Yarn-only rule of the repos does not apply here.
+ */
+async function installRuntime(log) {
+    const dir = ensureDir(runtimeDir());
+    const manifest = join(dir, 'package.json');
+    if (!existsSync(manifest))
+        writeFileSync(manifest, JSON.stringify({ private: true }, null, 2));
+    log(`Installing Playwright ${PLAYWRIGHT_VERSION} into ${dir} (first use only)...`);
+    // @playwright/test brings the expect that checks use; playwright-core is what the parent drives
+    const npmArgs = [
+        'install',
+        '--no-audit',
+        '--no-fund',
+        '--prefix',
+        dir,
+        `playwright-core@${PLAYWRIGHT_VERSION}`,
+        `@playwright/test@${PLAYWRIGHT_VERSION}`
+    ];
+    const cli = npmCli();
+    const out = await new Promise((resolve) => {
+        const done = (error, stdout, stderr) => resolve({ error, text: `${stdout}\n${stderr}` });
+        if (cli)
+            execFile(process.execPath, [cli, ...npmArgs], { windowsHide: true, timeout: INSTALL_TIMEOUT_MS, shell: false }, (e, so, se) => done(e, so, se));
+        else
+            execFile('npm', npmArgs, { windowsHide: true, timeout: INSTALL_TIMEOUT_MS, shell: process.platform === 'win32' }, (e, so, se) => done(e, so, se));
+    });
+    if (out.error || !looksInstalled(join(dir, 'node_modules'))) {
+        const last = out.text.trim().split('\n').slice(-3).join(' ').slice(0, 300);
+        throw new Error(`Could not install Playwright: ${describeInstallFailure(out.text)}. ${last}`);
+    }
+}
+/** The pinned Playwright folder, or null: the runtime has to be installed (again) when the only copy is another version. */
+function pinnedDir() {
+    const dir = playwrightRuntimeDir();
+    return dir && versionIn(dir) === PLAYWRIGHT_VERSION ? dir : null;
+}
+async function installChromium(dir, log) {
+    log('Installing the Chromium browser for Playwright (first use only)...');
+    const cli = join(dir, 'playwright-core', 'cli.js');
+    if (!existsSync(cli))
+        throw new Error('Playwright is installed but its installer (cli.js) is missing. Remove the runtime folder and try again.');
+    const { code, tail } = await runLogged(process.execPath, [cli, 'install', 'chromium'], log).catch((e) => ({ code: -1, tail: String(e) }));
+    if (code !== 0)
+        throw new Error(`Could not install the Chromium browser: ${describeInstallFailure(tail)}. ${tail.split('\n').slice(-2).join(' ').trim().slice(0, 300)}`);
+}
+const realInstallIo = {
+    pinnedDir,
+    chromiumPresent: async () => {
+        try {
+            const { chromium } = await loadPlaywright();
+            return existsSync(chromium.executablePath());
+        }
+        catch {
+            return false;
+        }
+    },
+    installRuntime,
+    installChromium,
+    notePath: () => join(runtimeDir(), COMPLETE_NOTE),
+    lockName: 'browser-install',
+    pause: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+};
+/** Takes the install lock without blocking the event loop. Null when another install kept it for longer than a whole install takes. */
+async function takeInstallLock(io, waitMs, staleMs) {
+    const until = Date.now() + waitMs;
+    for (;;) {
+        const lock = acquireLock(io.lockName, { staleMs });
+        if (lock)
+            return lock;
+        if (Date.now() > until)
+            return null;
+        await io.pause(500);
+    }
+}
+/**
+ * Makes sure Playwright and its Chromium are there. The first use installs them (a few hundred megabytes, with progress lines in `log`);
+ * later uses return at once. Never prompts. A failure is one Error that says whether it looks like offline or a proxy.
+ * Two processes never install at once: a lock covers the runtime install and the Chromium download, and a note (.complete) is written only after both finished, so a
+ * download that was cut short is done again instead of being trusted.
+ */
+export async function ensureBrowser(log = () => { }, io = realInstallIo, limits = {}) {
+    const whole = async () => existsSync(io.notePath()) && io.pinnedDir() !== null && (await io.chromiumPresent());
+    if (await whole())
+        return;
+    const lock = await takeInstallLock(io, limits.waitMs ?? INSTALL_LOCK_WAIT_MS, limits.staleMs ?? INSTALL_LOCK_STALE_MS);
+    if (!lock)
+        throw new Error('Another process has been installing the browser for a long time. Wait for it, or run "agent-flow-board check doctor".');
+    try {
+        // Whoever held the lock before may have finished the whole install
+        if (await whole())
+            return;
+        rmSync(io.notePath(), { force: true });
+        if (!io.pinnedDir())
+            await io.installRuntime(log);
+        const dir = io.pinnedDir() ?? playwrightRuntimeDir();
+        if (!dir)
+            throw new Error('Playwright was installed but cannot be found.');
+        if (!(await io.chromiumPresent()))
+            await io.installChromium(dir, log);
+        ensureDir(dirname(io.notePath()));
+        writeFileSync(io.notePath(), new Date().toISOString() + '\n');
+    }
+    finally {
+        lock.release();
+    }
+}

package/dist/checks/browserpool.js

@@ -0,0 +1,221 @@
+// THE BROWSER POOL: RUNS THAT NEED THE SAME REACHABLE HOSTS SHARE ONE CHROMIUM SERVER, EACH RUN WITH A FRESH CONTEXT OF ITS OWN.
+// Why sharing is safe: the server is started with Playwright's launchServer and never with the shared-browser option, so every connection to its endpoint
+// gets contexts of its own and sees none of another connection's (proved by the opt-in real browser test). Why the key holds the hosts: the host
+// resolver rule is a launch argument of the browser, so a browser started for one set of hosts can never reach the hosts of another set.
+// A registration for a live site (`dedicated: true`) always gets a browser of its own.
+//
+// FILE LAYOUT (poolDir()): browser-<id>.json, one per launched browser, written whole when the browser is up and removed when it closes or crashes:
+//   { kind: 'browser', id, pid (the process that owns the pool), key, headed, hosts, dedicated, startedAt }
+// The websocket endpoint is NOT written: it is a capability. Sharing one browser across processes is the machine broker's job; until it exists a pool
+// lives in one process, and the marker only lets doctor see (and sweep, when the owner is dead) what was left.
+// -- DEP-MODULES -- //
+import { randomBytes } from 'node:crypto';
+import { readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+// -- MODULES -- //
+import { launchBrowserServer } from './browser.js';
+import { pidAlive } from './lock.js';
+import { ensureDir, poolDir } from './paths.js';
+// -- CONSTANTS -- //
+/** A shared browser with no runs on it stays up this long, so the next run of a burst does not pay for a new launch. */
+const DEFAULT_IDLE_MS = 15_000;
+const MARKER_PREFIX = 'browser-';
+// -- FUNCTIONS -- //
+/** The pool key: the sorted, lower-cased host set and the headed flag. Two runs share a browser only when this is equal. */
+export function browserKey(hosts, headed) {
+    const set = [...new Set(hosts.map((h) => h.trim().toLowerCase()).filter(Boolean))].sort();
+    return `${headed ? 'headed' : 'headless'}|${set.join(',')}`;
+}
+function writeWhole(file, text) {
+    const tmp = `${file}.${process.pid}.${randomBytes(3).toString('hex')}.tmp`;
+    writeFileSync(tmp, text, { mode: 0o600 });
+    renameSync(tmp, file);
+}
+const markerFile = (id) => join(poolDir(), `${MARKER_PREFIX}${id}.json`);
+/** Every browser marker on this machine, with whether the process that owns it is alive. For doctor. */
+export function listBrowserMarkers() {
+    const out = [];
+    let names;
+    try {
+        names = readdirSync(poolDir());
+    }
+    catch {
+        return out;
+    }
+    for (const n of names) {
+        if (!n.startsWith(MARKER_PREFIX) || !n.endsWith('.json'))
+            continue;
+        try {
+            const v = JSON.parse(readFileSync(join(poolDir(), n), 'utf8'));
+            const m = v;
+            if (m && m.kind === 'browser' && typeof m.id === 'string' && typeof m.pid === 'number')
+                out.push({ marker: m, ownerAlive: pidAlive(m.pid) });
+        }
+        catch {
+            /* A damaged marker is not listed */
+        }
+    }
+    return out;
+}
+/** Removes the markers of browsers whose owner process is gone (the browser died with it). Returns how many. */
+export function sweepBrowserMarkers() {
+    let removed = 0;
+    for (const { marker, ownerAlive } of listBrowserMarkers()) {
+        if (ownerAlive || !/^[a-f0-9]{6,16}$/.test(marker.id))
+            continue;
+        rmSync(markerFile(marker.id), { force: true });
+        removed++;
+    }
+    return removed;
+}
+export class BrowserPool {
+    entries = new Map();
+    all = new Set();
+    launcher;
+    idleMs;
+    markers;
+    constructor(opts = {}) {
+        this.launcher = opts.launcher ?? ((o) => launchBrowserServer(o));
+        this.idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+        this.markers = opts.markers ?? true;
+    }
+    /** How many browsers are up (or starting), counting dedicated ones. */
+    get size() {
+        return this.all.size;
+    }
+    launch(entry) {
+        entry.server = this.launcher({
+            headed: entry.request.headed,
+            hosts: entry.request.hosts
+        }).then((server) => {
+            if (this.markers)
+                this.writeMarker(entry);
+            // A crash takes only this entry out: the next acquire of its key launches a new browser, runs that hold this one fail on their own
+            server.onClose?.(() => this.markGone(entry));
+            return server;
+        }, (e) => {
+            this.markGone(entry);
+            throw e;
+        });
+        // The rejection is handled by the acquire that awaits it
+        entry.server.catch(() => { });
+    }
+    writeMarker(entry) {
+        try {
+            ensureDir(poolDir());
+            const marker = {
+                kind: 'browser',
+                id: entry.id,
+                pid: process.pid,
+                key: entry.key,
+                headed: entry.request.headed,
+                hosts: entry.request.hosts,
+                dedicated: entry.request.dedicated,
+                startedAt: new Date().toISOString()
+            };
+            writeWhole(markerFile(entry.id), JSON.stringify(marker) + '\n');
+        }
+        catch {
+            /* The marker is for doctor only: a browser still works without it */
+        }
+    }
+    markGone(entry) {
+        if (entry.gone)
+            return;
+        entry.gone = true;
+        if (entry.idleTimer)
+            clearTimeout(entry.idleTimer);
+        if (this.entries.get(entry.key) === entry)
+            this.entries.delete(entry.key);
+        this.all.delete(entry);
+        if (this.markers)
+            rmSync(markerFile(entry.id), { force: true });
+    }
+    async closeEntry(entry) {
+        this.markGone(entry);
+        try {
+            await (await entry.server).close();
+        }
+        catch {
+            /* Already closed or never started */
+        }
+    }
+    async acquire(req = {}) {
+        const headed = req.headed === true;
+        const hosts = [
+            ...new Set((req.hosts ?? []).map((h) => h.trim().toLowerCase()).filter(Boolean))
+        ].sort();
+        const dedicated = req.dedicated === true;
+        const key = browserKey(hosts, headed);
+        let entry = dedicated ? undefined : this.entries.get(key);
+        if (!entry || entry.gone) {
+            entry = {
+                id: randomBytes(4).toString('hex'),
+                key,
+                request: { headed, hosts, dedicated },
+                server: Promise.resolve(null),
+                refs: 0,
+                gone: false
+            };
+            if (!dedicated)
+                this.entries.set(key, entry);
+            this.all.add(entry);
+            this.launch(entry);
+        }
+        const mine = entry;
+        mine.refs++;
+        if (mine.idleTimer) {
+            clearTimeout(mine.idleTimer);
+            mine.idleTimer = undefined;
+        }
+        let server;
+        try {
+            server = await mine.server;
+        }
+        catch (e) {
+            mine.refs--;
+            throw e;
+        }
+        let released = false;
+        return {
+            wsEndpoint: () => server.wsEndpoint(),
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                mine.refs--;
+                if (mine.refs > 0 || mine.gone)
+                    return;
+                if (dedicated || this.idleMs <= 0)
+                    return this.closeEntry(mine);
+                // The grace period: a run that starts a moment later reuses this browser
+                mine.idleTimer = setTimeout(() => {
+                    if (mine.refs === 0)
+                        void this.closeEntry(mine);
+                }, this.idleMs);
+                mine.idleTimer.unref();
+            }
+        };
+    }
+    /** Closes every browser at once, whatever holds it. For the end of a worker or a run. */
+    async closeAll() {
+        await Promise.all([...this.all].map((e) => this.closeEntry(e)));
+    }
+}
+let shared = null;
+/** The pool of this process. */
+export function browserPool() {
+    shared ??= new BrowserPool();
+    return shared;
+}
+/**
+ * A browser for one run. The same sorted host set and headed flag share one Chromium; `dedicated` (a live site) never shares. Call `release()` when the
+ * run ends; the browser closes after a short idle grace once nobody holds it.
+ */
+export function acquireBrowser(req = {}) {
+    return browserPool().acquire(req);
+}
+/** Closes every browser of this process's pool. */
+export async function closeAllBrowsers() {
+    await shared?.closeAll();
+}