@agent-flow-board/bridge 0.2.0 → 0.4.0

package/dist/checks/run.js

@@ -3,26 +3,107 @@
 // with it. The folder is the repo the agent is in: running a check there is the approval of that folder for `check watch`.
 // -- DEP-MODULES -- //
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 // -- MODULES -- //
 import { appendAudit, verifyAudit } from './audit.js';
 import { bindFolder } from './bind.js';
 import { BoardError, RunnerBoard } from './board.js';
-import { ensureBrowser, launchBrowserServer } from './browser.js';
+import { ensureBrowser } from './browser.js';
+import { acquireBrowser } from './browserpool.js';
+import { JPEG_MAGIC, MAX_SHOT_BYTES, readPlainFile } from './evidence.js';
+import { acquireSlot, slotsHeader } from './broker.js';
+import { closePoolIfIdle } from './dbpool.js';
 import { lintCheck } from './guard.js';
 import { assertName, ORG_SLUG, runsDir, scriptPath, scriptsDir } from './paths.js';
+import { liveSiteGuardOptions } from './live.js';
+import { pictureUploadAllowed, savedStateFor } from './login.js';
 import { startPreview } from './preview.js';
 import { redact } from './redact.js';
 import { pinFiles, resolveProjectConfig } from './recipe.js';
+import { configFor, listRegistrations, pinRegistration, pinState, readRegistrations } from './registry.js';
+import { registrationHeader, routeRun } from './routing.js';
+import { registrationsHeader, sanitiseReport, withBranch } from './wire.js';
 import { runCheckInSandbox } from './sandbox.js';
 import { installSignalHandlers, RunScope, sweepOrphans } from './scope.js';
 import { signInWithPassword, stateNeedles } from './signin.js';
 // -- CONSTANTS -- //
 const BEAT_EVERY_MS = 30_000;
 const MAX_EVIDENCE = 8;
+/** A run started by hand (not by the worker, whose scheduler has its own limit) stops after this long. */
+const DEFAULT_RUN_LIMIT_MS = 40 * 60_000;
 // -- FUNCTIONS -- //
-/** The slots header: this process takes one run at a time. */
-const slotsHeader = (busy) => `1:${busy}`;
+/** The run limit of a standalone run in ms: AFB_CHECKS_RUN_LIMIT_MS when it is a positive number, else 40 minutes. */
+export function runLimitMs(env = process.env) {
+    const v = Number(env.AFB_CHECKS_RUN_LIMIT_MS);
+    return Number.isFinite(v) && v > 0 ? v : DEFAULT_RUN_LIMIT_MS;
+}
+/** The sentence for a run stopped by its limit. */
+export function limitSentence(ms) {
+    return ms < 60_000
+        ? `The run took longer than ${Math.round(ms / 1000)} seconds and was stopped.`
+        : `The run took longer than ${Math.round(ms / 60_000)} minutes and was stopped.`;
+}
+/** Writes an audit line, and never lets a failure of the log change the outcome of a run. */
+function auditSafely(log, action, detail) {
+    try {
+        appendAudit(action, detail);
+    }
+    catch {
+        log('The audit log could not be written for this run.');
+    }
+}
+/** The registrations of this organisation, for the board to route a run that names one (at most 16, refreshed by every call). */
+function registrationsHeaderFor(org) {
+    try {
+        const value = registrationsHeader(org, listRegistrations(org).map(withBranch));
+        return value ? { 'x-afb-tool-registrations': value } : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The registration of a run: the one the board names, else the one asked for with --registration, else the check script's own header, else the board
+ * project's only registration. With none registered for the board project the folder of the current directory is used, as before registrations existed.
+ */
+export function configForRun(o, job, source, log, fromWatch) {
+    const read = readRegistrations(o.org);
+    const all = read.registrations;
+    const mine = all.filter((r) => r.boardProject === job.project.key);
+    if (!mine.length) {
+        // A registration that is damaged or was changed by hand is not "no registration": the folder of the current directory is never taken in its place
+        if (read.problems.length)
+            throw new Error(`${read.problems.join(' ')} No other registration serves ${job.project.key}, so the run was not started. Register the project again with: agent-flow-board check project`);
+        const cfg = resolveProjectConfig(o.dir);
+        // Running a check in a folder is the approval of that folder (and of the files that decide what runs) for `check watch`
+        bindFolder(o.org, job.project.key, cfg.repo, pinFiles(cfg.repo));
+        return { cfg, registration: null, scriptRegistration: null };
+    }
+    const registration = routeRun({
+        org: o.org,
+        boardProject: job.project.key,
+        run: job.registration ?? o.registration ?? null,
+        script: source,
+        all
+    });
+    if (registration.repo) {
+        if (fromWatch) {
+            // The board's Run button never re-approves: a changed or missing pin needs a `check run` in the folder first
+            if (pinState(registration) !== 'ok')
+                throw new Error(`The files that decide what runs in ${registration.name} changed since they were approved. In that folder run: agent-flow-board check run <item> <key> --org ${o.org}`);
+        }
+        else {
+            const pin = pinRegistration(o.org, registration.name);
+            if (pin.changed)
+                log(`The files that decide what runs in ${registration.name} changed and were pinned again (${pin.files.length} files).`);
+        }
+    }
+    return {
+        cfg: configFor(registration),
+        registration,
+        scriptRegistration: registrationHeader(source)
+    };
+}
 function auditHeaders() {
     try {
         const v = verifyAudit();
@@ -77,6 +158,14 @@ export async function runCheck(o) {
     let beat = null;
     let uninstall = () => undefined;
     let claimed = false;
+    let slot = null;
+    // Everything the run must never print, filled in as it becomes known; the reasons that go to the board are redacted with it
+    const needlesAll = [];
+    let limitTimer = null;
+    let limitHit = false;
+    // A run the worker's scheduler holds is stopped, timed out or given up on by the scheduler, which gives it back or reports it by id
+    const schedulerOwns = () => Boolean(o.scheduled && o.signal?.aborted);
+    const reasonFor = (text) => redact(text, needlesAll).slice(0, 1900);
     try {
         if (o.claimed)
             claimed = true;
@@ -85,7 +174,6 @@ export async function runCheck(o) {
         assertName(o.item, 'item reference');
         assertName(o.key, 'check key');
         // -- THE FOLDER AND THE SCRIPT -- //
-        const cfg = resolveProjectConfig(o.dir);
         const script = scriptPath(o.org, o.item, o.key);
         if (!existsSync(script))
             return stop(`There is no check file for ${o.item} ${o.key} at ${script}. Write it there, or read the board's copy with: agent-flow-board check pull ${o.item} ${o.key} --org ${o.org}`);
@@ -93,14 +181,11 @@ export async function runCheck(o) {
         const unsafe = lintCheck(source);
         if (unsafe.length)
             return stop(`This check uses ${unsafe.join(', ')}, which a check has no business doing, so it was not run. Rewrite it.`);
-        // Running a check in a folder is the approval of that folder (and of the files that decide what runs) for `check watch`
-        const projectKey = /^([A-Z][A-Z0-9]{1,9})-\d{8}-\d{4}/.exec(o.item)?.[1];
-        if (projectKey)
-            bindFolder(o.org, projectKey, cfg.repo, pinFiles(cfg.repo));
         // -- THE RUN -- //
         board = new RunnerBoard(o.server, o.runnerToken, o.fetch, () => ({
-            'x-afb-tool-slots': slotsHeader(claimed ? 1 : 0),
-            ...auditHeaders()
+            'x-afb-tool-slots': slotsHeader(),
+            ...auditHeaders(),
+            ...registrationsHeaderFor(o.org)
         }));
         await sweepOrphans(o.log);
         runId = o.claimed?.id ?? o.runId ?? (await requestRunOnBoard(o));
@@ -108,7 +193,7 @@ export async function runCheck(o) {
         if (!job)
             return stop(`The board did not give this machine the run ${runId}. It is not queued for this machine, or this machine does not serve that project (check connect --project), or another tool took it.`, runId);
         claimed = true;
-        appendAudit('run-claimed', { run: runId });
+        auditSafely(o.log, 'run-claimed', { run: runId });
         if (job.item.ref !== o.item || job.check.key !== o.key) {
             await board.release([runId]).catch(() => undefined);
             claimed = false;
@@ -117,30 +202,81 @@ export async function runCheck(o) {
         const thisBoard = board;
         const thisRun = runId;
         const abort = new AbortController();
-        beat = setInterval(() => {
-            thisBoard.beat(thisRun).catch((e) => {
-                // The board gave up on the run: stop working on it
-                if (e instanceof BoardError && e.status === 409)
-                    abort.abort();
-            });
-        }, BEAT_EVERY_MS);
-        beat.unref();
+        // A run the worker's scheduler holds is beaten (and limited) by the scheduler from the moment of its claim; its stop reaches this run through the signal
+        if (o.signal) {
+            if (o.signal.aborted)
+                abort.abort();
+            else
+                o.signal.addEventListener('abort', () => abort.abort(), { once: true });
+        }
+        if (!o.scheduled) {
+            beat = setInterval(() => {
+                thisBoard.beat(thisRun).catch((e) => {
+                    // The board gave up on the run: stop working on it
+                    if (e instanceof BoardError && e.status === 409)
+                        abort.abort();
+                });
+            }, BEAT_EVERY_MS);
+            beat.unref();
+            // A run started by hand has the same limit the worker gives its runs
+            const limit = runLimitMs();
+            limitTimer = setTimeout(() => {
+                limitHit = true;
+                abort.abort();
+            }, limit);
+            limitTimer.unref();
+        }
         scope = new RunScope(runId, o.log);
         scope.start();
         const thisScope = scope;
-        uninstall = installSignalHandlers(scope, () => {
-            void thisBoard
-                .finish(thisRun, { result: 'error', reason: 'The run was stopped before it finished.' })
-                .catch(() => undefined)
-                .finally(() => process.exit(2));
-        });
+        // The worker's runs never install their own handlers: its stop reaches them through the signal, and each closes only its own scope. A handler per run
+        // would finish every run as an error and end the whole process before the scheduler has given the others back
+        if (!o.scheduled)
+            uninstall = installSignalHandlers(scope, () => {
+                void thisBoard
+                    .finish(thisRun, { result: 'error', reason: 'The run was stopped before it finished.' })
+                    .catch(() => undefined)
+                    .finally(() => process.exit(2));
+            });
+        // -- WHICH REGISTRATION, AND A PLACE ON THIS MACHINE -- //
+        // A registration the board or the script names is chosen here, never guessed; a refusal ends the run with its code and the list
+        const routed = configForRun(o, job, source, o.log, Boolean(o.claimed));
+        const cfg = routed.cfg;
+        const registration = routed.registration;
+        // The heartbeat already runs, so a run that waits for a slot, the preflight or another run's build keeps beating and never looks stuck to the board
+        // (a scheduled run already holds its slot)
+        if (!o.scheduled)
+            slot = await acquireSlot({ runId, kind: 'check', registration: registration?.name ?? job.project.key }, { signal: abort.signal });
         await ensureBrowser(o.log);
-        const preview = await startPreview(cfg, { runId, scope, log: o.log });
+        const preview = await startPreview(cfg, {
+            runId,
+            scope,
+            log: o.log,
+            signal: abort.signal,
+            needles: needlesAll
+        });
+        needlesAll.push(...preview.secrets);
         if (preview.note)
             o.log(preview.note);
-        // -- SIGN IN AS THE RECIPE'S TEST USER -- //
+        // -- SIGN IN: A SAVED SIGN IN OF THIS REGISTRATION, ELSE THE RECIPE'S TEST USER -- //
         let state = null;
-        if (preview.testUser) {
+        // Only a sign in the owner SAVED counts for the picture rule: the recipe's test user belongs to a throwaway preview and holds nothing worth hiding
+        let usedSavedSignIn = false;
+        if (registration) {
+            const saved = savedStateFor({
+                org: o.org,
+                registration: registration.name,
+                scriptRegistration: routed.scriptRegistration,
+                bindKey: new URL(preview.baseUrl).origin
+            });
+            if (saved) {
+                state = saved.profile?.state ?? null;
+                usedSavedSignIn = state !== null;
+                if (saved.note)
+                    o.log(saved.note);
+            }
+        }
+        if (!state && preview.testUser) {
             o.log(`Signing in as ${preview.testUser.email.replace(/^(.).*(@.*)$/, '$1***$2')}...`);
             state = await signInWithPassword(preview.baseUrl, preview.testUser);
         }
@@ -149,9 +285,22 @@ export async function runCheck(o) {
             ...(preview.testUser ? [preview.testUser.password, preview.testUser.email] : []),
             ...stateNeedles(state)
         ];
+        needlesAll.push(...needles);
         const runDir = join(runsDir(), runId);
-        const browser = await launchBrowserServer({ headed: o.headed });
-        thisScope.add('browser', () => browser.close());
+        // The browser may reach this machine and the hosts of this registration only (a live site's hosts, the sealed test project's host); a live
+        // site or a signed in run always has its own browser, and a live site never allows writes
+        const extraHosts = [
+            ...new Set([
+                ...(cfg.url ? liveSiteGuardOptions(cfg).extraHosts : (cfg.extraHosts ?? [])),
+                ...(preview.extraHosts ?? [])
+            ])
+        ];
+        const browser = await acquireBrowser({
+            hosts: extraHosts,
+            headed: o.headed,
+            dedicated: Boolean(cfg.url) || state !== null
+        });
+        thisScope.add('browser', () => browser.release());
         const childJob = {
             baseUrl: preview.baseUrl,
             ws: browser.wsEndpoint(),
@@ -159,7 +308,7 @@ export async function runCheck(o) {
             checkFile: script,
             runDir,
             viewport: { width: 1280, height: 800 },
-            extraHosts: [],
+            extraHosts,
             needles
         };
         const ran = await runCheckInSandbox({
@@ -169,21 +318,39 @@ export async function runCheck(o) {
             signal: abort.signal
         });
         if (!ran.result) {
-            const why = redact(ran.stderr || 'The check did not finish.', needles).slice(-1200);
-            await board.finish(runId, {
-                result: 'error',
-                reason: `The check did not finish. ${why}`.slice(0, 1900)
-            });
-            finished = true;
-            claimed = false;
+            const why = limitHit
+                ? limitSentence(runLimitMs())
+                : redact(ran.stderr || 'The check did not finish.', needlesAll).slice(-1200);
+            // A run the scheduler stopped is given back by the scheduler, not reported here
+            if (!schedulerOwns()) {
+                await board.finish(runId, {
+                    result: 'error',
+                    reason: reasonFor(`The check did not finish. ${why}`)
+                });
+                finished = true;
+                claimed = false;
+            }
             return stop(`The check did not finish. ${why}`, runId);
         }
         // -- REPORT -- //
         const ids = [];
-        for (const s of pickShots(ran.result.steps)) {
+        // Pictures of a signed in run are not uploaded unless the owner opted in for the registration: a compressed picture cannot be searched for a secret
+        const uploadPictures = pictureUploadAllowed(registration ?? { uploadSignedInPictures: false }, usedSavedSignIn);
+        if (!uploadPictures)
+            o.log('The pictures of a signed in run are not uploaded for this registration.');
+        for (const s of uploadPictures ? pickShots(ran.result.steps) : []) {
             if (!s.shot)
                 continue;
-            const bytes = readFileSync(join(runDir, 'shots', s.shot));
+            // The child wrote this file, so it is only read when it is a plain JPEG inside the shots folder (never a link it planted to a key file)
+            const read = readPlainFile(join(runDir, 'shots'), s.shot, {
+                maxBytes: MAX_SHOT_BYTES,
+                magic: JPEG_MAGIC
+            });
+            if ('refused' in read) {
+                o.log(`  A picture was not uploaded: ${read.refused}.`);
+                continue;
+            }
+            const bytes = read.bytes;
             // A picture that holds a secret (found as bytes or text) is not uploaded
             if (needles.some((n) => n.length >= 6 && Buffer.from(bytes).includes(n))) {
                 o.log('  A picture held a secret value, so it was not uploaded.');
@@ -196,23 +363,34 @@ export async function runCheck(o) {
             }));
         }
         const result = ran.result;
-        const report = {
+        const wire = registration ? withBranch(registration) : null;
+        const report = sanitiseReport({
             result: result.result,
+            ...(registration
+                ? {
+                    registration: registration.name,
+                    ...(registration.repo ? { repoName: basename(registration.repo) } : {}),
+                    ...(wire?.branch ? { branch: wire.branch } : {})
+                }
+                : {}),
             durationMs: Math.min(result.durationMs, 24 * 3600 * 1000),
             url: preview.baseUrl.slice(0, 300),
             commit: preview.commit,
             diffHash: preview.diffHash,
             ...(result.result === 'pass'
                 ? {}
-                : { reason: redact(result.reason ?? 'The check failed.', needles).slice(0, 1900) }),
+                : { reason: reasonFor(result.reason ?? 'The check failed.') }),
             ...(preview.commit ? {} : { unverified: true }),
-            log: redact(result.log, needles).slice(0, 390_000),
+            log: redact(result.log, needlesAll).slice(0, 390_000),
             evidence: ids
-        };
+        });
+        // A run the scheduler stopped is given back by the scheduler: what it found is not reported
+        if (schedulerOwns())
+            return stop('The run was stopped.', runId);
         await board.finish(runId, report);
         finished = true;
         claimed = false;
-        appendAudit('run-finished', { run: runId, result: result.result });
+        auditSafely(o.log, 'run-finished', { run: runId, result: result.result });
         return {
             exitCode: result.result === 'pass' ? 0 : 1,
             runId,
@@ -223,29 +401,41 @@ export async function runCheck(o) {
         };
     }
     catch (e) {
-        const reason = e instanceof Error ? e.message : String(e);
-        if (board && runId && claimed) {
+        const said = e instanceof Error ? e.message : String(e);
+        const reason = limitHit ? limitSentence(runLimitMs()) : said;
+        // Nothing that reaches the board is unredacted: not a build log tail, not the message of an error
+        if (board && runId && claimed && !schedulerOwns()) {
             await board
-                .finish(runId, { result: 'error', reason: reason.slice(0, 1900) })
+                .finish(runId, { result: 'error', reason: reasonFor(reason) })
                 .catch(() => undefined);
             finished = true;
-            claimed = false;
         }
-        return stop(reason, runId);
+        return stop(reasonFor(reason), runId);
     }
     finally {
         if (beat)
             clearInterval(beat);
+        if (limitTimer)
+            clearTimeout(limitTimer);
         uninstall();
         if (scope)
             await scope.close();
+        // The slot goes back to the machine, and a pool container that no run needs any more is removed (a worker keeps it warm)
+        try {
+            await slot?.release();
+        }
+        catch {
+            /* A slot that cannot be released is cleared by its stale heartbeat */
+        }
+        if (!o.claimed)
+            await closePoolIfIdle().catch(() => undefined);
         // A run that `check watch` already claimed must never be left running when this ends early (no script, a changed folder, a refusal)
-        if (o.claimed && !finished) {
+        if (o.claimed && !finished && !schedulerOwns()) {
             const b = board ?? new RunnerBoard(o.server, o.runnerToken, o.fetch);
             await b
                 .finish(o.claimed.id, {
                 result: 'error',
-                reason: (lastStop || 'The run stopped early.').slice(0, 1900)
+                reason: reasonFor(lastStop || 'The run stopped early.')
             })
                 .catch(() => undefined);
         }

package/dist/checks/sandbox.js

@@ -5,11 +5,12 @@
 // program and no worker, loads no addon, and gets an environment of PATH, SystemRoot, TEMP, TMP and AFB_PLAYWRIGHT_DIR and nothing else.
 // -- DEP-MODULES -- //
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // -- MODULES -- //
 import { playwrightRuntimeDir } from './browser.js';
+import { MAX_RESULT_BYTES, findLink, isPlainFile, readPlainFile } from './evidence.js';
 import { ensureDir, isInside, runsDir } from './paths.js';
 import { redact } from './redact.js';
 import { killTree } from './scope.js';
@@ -105,7 +106,7 @@ export async function runNodeInSandbox(opts) {
 }
 const redactDeep = (text, needles, max) => redact(String(text ?? ''), needles).slice(0, max);
 /** The result the child wrote is data, not trusted: its shape is rebuilt, names are checked and every text goes through the redaction again. */
-function cleanResult(raw, needles) {
+export function cleanResult(raw, needles, shotsDir) {
     if (typeof raw !== 'object' || raw === null)
         return null;
     const r = raw;
@@ -122,7 +123,10 @@ function cleanResult(raw, needles) {
             name: redactDeep(s.name, needles, 200),
             status: s.status === 'pass' || s.status === 'fail' ? s.status : 'shot',
             ms: Number(s.ms) || 0,
-            shot: SHOT.test(String(s.shot ?? '')) ? String(s.shot) : null,
+            // A picture that is not a plain file (a link the child planted) is dropped, not reported
+            shot: SHOT.test(String(s.shot ?? '')) && (!shotsDir || isPlainFile(shotsDir, String(s.shot)))
+                ? String(s.shot)
+                : null,
             ...(s.error ? { error: redactDeep(s.error, needles, 500) } : {})
         })),
         log: redactDeep(r.log, needles, 20_000),
@@ -136,6 +140,12 @@ export async function runCheckInSandbox({ job, scriptsRoot, log, signal }) {
         throw new Error('That check is not inside the scripts folder, so it was not run.');
     if (!isInside(runsDir(), job.runDir))
         throw new Error('The run folder is not inside the runs folder, so the check was not run.');
+    // The permission model follows links, so a link in a folder the check may read or write would reach files outside it: none is allowed there
+    for (const folder of [job.runDir, scriptsRoot]) {
+        const link = findLink(folder);
+        if (link)
+            throw new Error(`There is a link or a file with several names in a folder the check may use (${basename(link)}), so the check was not run. Remove it.`);
+    }
     const pwDir = playwrightRuntimeDir();
     if (!pwDir)
         throw new Error('Playwright is not installed yet. Run "agent-flow-board check setup" and it will install it.');
@@ -169,15 +179,27 @@ export async function runCheckInSandbox({ job, scriptsRoot, log, signal }) {
             }
         }
     });
-    const stderr = redact(run.stderr, needles);
+    let stderr = redact(run.stderr, needles);
+    // A link made during the run is as bad as one made before it: nothing the check wrote is read
+    const planted = [job.runDir, scriptsRoot].map((d) => findLink(d)).find(Boolean);
+    if (planted) {
+        log('A link appeared in a folder the check may use, so what it wrote was not read.');
+        stderr = `A link appeared in the run folder (${basename(planted)}). ${stderr}`.slice(-4000);
+        return { exitCode: run.exitCode, stderr, result: null };
+    }
     const file = join(job.runDir, 'result.json');
     let result = null;
     if (existsSync(file)) {
-        try {
-            result = cleanResult(JSON.parse(readFileSync(file, 'utf8')), needles);
-        }
-        catch {
-            result = null;
+        const read = readPlainFile(job.runDir, 'result.json', { maxBytes: MAX_RESULT_BYTES });
+        if ('refused' in read)
+            log(`The result file of the check was not read: ${read.refused}.`);
+        else {
+            try {
+                result = cleanResult(JSON.parse(read.bytes.toString('utf8')), needles, join(job.runDir, 'shots'));
+            }
+            catch {
+                result = null;
+            }
         }
     }
     if (run.timedOut)