@popcorn245/cornfield 0.8.0 → 0.10.0

package/server/runner-api.js

@@ -0,0 +1,270 @@
+/**
+ * @module server/runner-api
+ *
+ * The runner's side of the pull and push transports (issue #81, spec 0005 D2, D3, D5). The engine is server/agent-runs.js, the contract is
+ * core/agent-contract.js, and docs/agents.md says how a runner uses these routes. A runner behind NAT asks cornfield for work, claims it, and
+ * reports on it; a runner that was pushed a request (the `agent.requested` hook event) reports the same way.
+ *
+ *   GET  /api/agent-requests?state=queued      the queued requests (the contract's request JSON), oldest first, at most `QUEUE_LIMIT`
+ *   POST /api/agent-requests/<runId>/claim     claims one; a second claim of it is 409. Answers the request and the run
+ *   GET  /api/runs/<runId>                     { state, stopRequested, … } of a run this token holds: how a runner learns it was asked to stop
+ *   POST /api/runs/<runId>                     the report JSON ({ state, note?, url?, tokens?, cost? }), checked by the contract's `validateReport`
+ *
+ * **These routes take a runner token (`Authorization: Bearer cf_nt_…`) and nothing else,** as the review API takes a review token
+ * (server/review-api.js): they run before the sign-in guard (a runner has no cookie), read no cookie (a cookie is never a substitute, and a
+ * request that sends only one is 401), need no same-origin check (a browser never adds an `Authorization` header itself), and keep the `Host`
+ * check in front of every route. **The three scopes are kept apart both ways:** a review or an agent token here is 403 whatever else is true
+ * of it, and a runner token on any other route (the review API, the agent API, the dashboard's routes, the page itself) is 403 too
+ * (`serveStrayRunner`, which `server.js` calls before anything else is looked at).
+ *
+ * What a runner token may do, and nothing more: read the queue, claim, and read and report on **the runs it holds**. A pull run is held by the
+ * token that claimed it; a push run by the first token to report on it (nothing else tells a push run apart: the hook went to a URL, not a
+ * token). A run asked for on the forge is nobody's: its reports are `cornfield-run` comments. A token never reads a request it did not claim,
+ * and never anything of cornfield's besides.
+ *
+ * **Token states, the anonymous flood ceiling and the rows in `actions` follow the review API.** Every call is a row (`runner-list`,
+ * `runner-claim`, `runner-run`, `runner-report`, and `runner-call` for a token on the wrong route), with the token's id and label and the
+ * run id in the request, and the status and error in the answer, **never the token and never a note's words**. Two bounds keep the table from
+ * growing without end: past `RUNNER_PER_MINUTE` calls a minute a token is 429 and nothing is written, and an empty queue read is written down
+ * at most once every `EMPTY_LIST_ROW_MS` per token (a runner polls; a poll that finds nothing says little).
+ *
+ *   no token, or one that no row has    401 (`WWW-Authenticate: Bearer`), logged under `(no token)`; past `ANONYMOUS_PER_MINUTE` a minute 429 and no row
+ *   a review or an agent token          403, under its owner
+ *   a token that is revoked or expired  403, under its owner
+ *   a live runner token                 whatever the engine answers: 200, or 400, 403, 404, 409, 429
+ *
+ * **The token is not asked of the forge.** A runner has its own identity, and cornfield's forge sign-in of the token's owner may well have
+ * ended by the time a runner polls. What bounds a runner token is its scope, its expiry (90 days at most), that its owner revokes it in
+ * the dashboard at once, and that **an owner who stops maintaining the repo loses it**: whenever cornfield learns that (their sign-in, the
+ * 15-minute re-check, any question it puts to the forge with their token) all their API tokens are revoked (`auth.demoted`), and each call
+ * here also refuses, and revokes, when the owner's newest sign-in says they are not a maintainer (`auth.knownPermission`). No sign-in on
+ * record is no answer: the token goes on. (Review and agent tokens, which act as their owner on the forge, are checked against the forge on
+ * every call.)
+ *
+ * Nothing in an answer is a credential: the request is the contract's (validated again on the way out), and a run shows its state.
+ */
+
+import { readBody } from './proposals.js';
+import { ANONYMOUS_PER_MINUTE, NO_TOKEN_LOGIN } from './review-api.js';
+import { bearerOf, findToken, scopeOfShape, touchToken } from './review-tokens.js';
+import { QUEUE_LIMIT } from './agent-runs.js';
+import { refusal } from './submit-review.js';
+import { Refused, countAttempt } from './throttle.js';
+import { ForgeError, isMaintainer } from './forge.js';
+
+export const REQUESTS_PATH = '/api/agent-requests';
+/** Calls one runner token may make in a minute: a runner polls, so this is well over a person's ceiling */
+export const RUNNER_PER_MINUTE = 120;
+/** An empty queue read is written down at most this often per token */
+export const EMPTY_LIST_ROW_MS = 10 * 60_000;
+/** A report's body, in bytes: a note, a link and two numbers, with room */
+export const REPORT_LIMIT = 16 * 1024;
+const HEADERS = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' };
+const RUN_ID = '(run-[0-9A-Za-z]{26})';
+const CLAIM = new RegExp(`^/api/agent-requests/${RUN_ID}/claim$`);
+const RUN = new RegExp(`^/api/runs/${RUN_ID}$`);
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { ...HEADERS, ...headers });
+  res.end(JSON.stringify(body));
+}
+
+/** The routes of this module: the action each is audited as, the run it names, and the methods it answers. Null for any other path. */
+export function runnerRoute(reqPath) {
+  let m;
+  if (reqPath === REQUESTS_PATH) return { action: 'runner-list', runId: null, allow: ['GET', 'HEAD'] };
+  if ((m = CLAIM.exec(reqPath))) return { action: 'runner-claim', runId: m[1], allow: ['POST'] };
+  if ((m = RUN.exec(reqPath))) return { action: 'runner-run', runId: m[1], allow: ['GET', 'HEAD', 'POST'] };
+  return null;
+}
+
+/** Whether a path is one that takes a bearer token of some scope (so a runner token on it is answered by that route, not as a stray) */
+export const takesTokens = (reqPath, { reviews }) => reqPath === reviews || reqPath === REQUESTS_PATH || runnerRoute(reqPath) !== null;
+
+/** The scope of a bearer token as the request presents it, by its shape alone (the row decides what it is worth) */
+export const presentedScope = (req) => scopeOfShape(bearerOf(req.headers.authorization));
+
+/** @type {WeakMap<object, Map<number, number>>} when each token's empty queue read was last written down */
+const emptyReads = new WeakMap();
+
+function emptyReadDue(auth, id, at) {
+  let m = emptyReads.get(auth);
+  if (!m) emptyReads.set(auth, (m = new Map()));
+  for (const [k, when] of m) if (at - when >= EMPTY_LIST_ROW_MS) m.delete(k);
+  if (m.has(id)) return false;
+  m.set(id, at);
+  return true;
+}
+
+/** What to answer for an error out of the engine: a refusal in words, or a plain 500 that says nothing of what went wrong */
+function answerFor(err) {
+  if (err instanceof Refused || err instanceof ForgeError) return refusal(err);
+  console.error(`[cornfield] a runner call failed: ${err instanceof Error ? err.stack || err.message : err}`);
+  return { status: 500, body: { error: 'Something went wrong in cornfield; the log says what.', code: 'unavailable' }, headers: {} };
+}
+
+/** @typedef {{ config: any, auth: any, runs: import('./agent-runs.js').Runs | null, now?: () => number }} RunnerContext */
+
+/**
+ * The runner routes. The caller has found the path to be one of `runnerRoute`'s; this runs before the sign-in guard.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {NonNullable<ReturnType<typeof runnerRoute>>} route
+ * @param {URL} url
+ * @param {RunnerContext} ctx
+ */
+export async function serveRunnerCall(req, res, route, url, ctx) {
+  const { config, auth, runs } = ctx;
+  const now = ctx.now ?? Date.now;
+  const method = req.method || 'GET';
+  if (!route.allow.includes(method)) {
+    req.resume();
+    return send(res, 405, { ok: false, error: 'Method not allowed.', code: 'invalid' }, { Allow: route.allow.join(', ') });
+  }
+  if (!auth.enabled || !runs) {
+    req.resume();
+    return send(res, 403, { ok: false, error: 'Runner tokens need sign-in and a forge: set them up first (docs/sign-in.md, docs/config.md#forge).', code: 'forbidden' });
+  }
+  const repo = config.forge.repo;
+  const audit = async (login, request, status, answer, target = repo) => {
+    try {
+      await auth.record({ login, action: route.action, target, request: { via: 'api', ...(route.runId ? { runId: route.runId } : {}), ...request }, status, answer });
+    } catch (err) {
+      console.error(`[cornfield] a runner call could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+    }
+  };
+  const refuse = async (login, request, status, body, headers = {}) => {
+    await audit(login, request, status, { error: body.error, code: body.code });
+    return send(res, status, { ok: false, ...body }, headers);
+  };
+
+  const presented = bearerOf(req.headers.authorization);
+  const db = presented ? await auth.store() : null;
+  const found = presented && db ? findToken(db, presented, now(), 'runner') : null;
+  if (!found) {
+    req.resume();
+    const flood = countAttempt(ctx, NO_TOKEN_LOGIN, now(), ANONYMOUS_PER_MINUTE);
+    if (flood) return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+    return refuse(NO_TOKEN_LOGIN, { reason: presented ? 'unknown-token' : 'no-token' }, 401,
+      { error: 'A runner token is needed: send "Authorization: Bearer cf_nt_…". A token is made in the dashboard; a sign-in is not taken in its place.', code: 'unauthorized' },
+      { 'WWW-Authenticate': 'Bearer realm="cornfield"' });
+  }
+
+  const { row, state } = found;
+  const token = { id: row.id, label: row.label };
+  if (state !== 'active') {
+    req.resume();
+    const flood = countAttempt(ctx, row.user_id, now());
+    if (flood) return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+    const wrong = state === 'wrong-scope';
+    return refuse(row.login, { reason: wrong ? 'wrong-scope' : state, token, ...(wrong ? { scope: row.scope } : {}) }, 403, {
+      error: wrong ? `This is ${row.scope === 'agent' ? 'an' : 'a'} ${row.scope} token. Runners take a runner token; make one in the dashboard.`
+        : state === 'revoked' ? 'This runner token was revoked; make a new one in the dashboard.' : 'This runner token has expired; make a new one in the dashboard.',
+      code: 'forbidden',
+    });
+  }
+  const flood = countAttempt(ctx, `runner|${row.id}`, now(), RUNNER_PER_MINUTE);
+  if (flood) {
+    req.resume();
+    return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+  }
+  // The cheap guard: what cornfield last heard of the owner's permission (their newest sign-in's). A runner needs no live sign-in, so no sign-in
+  // at all is no answer; one that says they no longer maintain the repo refuses the call and revokes their tokens there and then
+  const known = await auth.knownPermission(row.user_id);
+  if (known !== null && !isMaintainer(known)) {
+    req.resume();
+    await auth.demoted(row.user_id, row.login, known);
+    return refuse(row.login, { reason: 'owner-not-maintainer', token }, 403, { error: `This runner token's owner, ${row.login}, does not maintain ${repo} any more, so it is revoked.`, code: 'forbidden' });
+  }
+  touchToken(/** @type {import('node:sqlite').DatabaseSync} */ (db), row.id, now());
+  const who = row.login;
+
+  try {
+    if (route.action === 'runner-list') {
+      req.resume();
+      if (url.searchParams.get('state') !== 'queued') throw new Refused(400, 'The only listing is ?state=queued: the requests waiting for a runner.', 'invalid');
+      const requests = await runs.queued();
+      if (requests.length || emptyReadDue(auth, row.id, now())) await audit(who, { token }, 200, { ok: true, count: requests.length });
+      return send(res, 200, { ok: true, requests, limit: QUEUE_LIMIT });
+    }
+    if (route.action === 'runner-claim') {
+      req.resume();
+      const claimed = await runs.claim(token, route.runId);
+      await audit(who, { token }, 200, { ok: true, claimed: true }, `${repo}#${claimed.row.target}`);
+      return send(res, 200, { ok: true, request: claimed.request, run: claimed.run });
+    }
+    if (method === 'POST') {
+      let body;
+      let problem = null;
+      try {
+        const read = await readBody(req, REPORT_LIMIT);
+        if (read.tooLarge) problem = new Refused(413, `A report is at most ${REPORT_LIMIT / 1024} KB.`, 'invalid');
+        else {
+          try {
+            body = JSON.parse(read.text);
+          } catch {
+            // Not the parser's words: they quote the body, which the audit row would keep (a credential pasted in by mistake)
+            problem = new Refused(400, 'The body is not valid JSON.', 'invalid');
+          }
+        }
+      } catch {
+        problem = new Refused(400, 'The report could not be read.', 'invalid');
+      }
+      const shape = body && typeof body === 'object' && !Array.isArray(body) ? { ...(typeof body.state === 'string' && body.state.length <= 20 ? { state: body.state } : {}), ...(typeof body.note === 'string' ? { noteChars: body.note.length } : {}) } : {};
+      try {
+        if (problem) throw problem;
+        const done = await runs.report(token, route.runId, body);
+        await audit(who, { token, ...shape }, 200, { ok: true, state: done.row.state }, `${repo}#${done.row.target}`);
+        return send(res, 200, { ok: true, run: done.run });
+      } catch (err) {
+        const out = answerFor(err);
+        await audit(who, { token, ...shape }, out.status, { error: out.body.error, code: out.body.code });
+        return send(res, out.status, { ok: false, ...out.body }, out.headers);
+      }
+    }
+    req.resume();
+    const view = await runs.runnerGet(token, route.runId);
+    await audit(who, { token }, 200, { ok: true, state: view.state });
+    return send(res, 200, { ok: true, run: view });
+  } catch (err) {
+    const out = answerFor(err);
+    await audit(who, { token }, out.status, { error: out.body.error, code: out.body.code });
+    return send(res, out.status, { ok: false, ...out.body }, out.headers);
+  }
+}
+
+/**
+ * A runner token on a route that is not a runner's: 403, whatever the route would have said (even a path that does not exist). Called by
+ * `server.js` for any request that presents something shaped like a runner token on a path outside `takesTokens`, before the guard, the proxies
+ * and the page. A token that is a live runner's is counted under its own id, anything else under the anonymous ceiling; either way one row.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} reqPath
+ * @param {RunnerContext} ctx
+ */
+export async function serveStrayRunner(req, res, reqPath, ctx) {
+  const { config, auth } = ctx;
+  const now = ctx.now ?? Date.now;
+  req.resume();
+  const body = { ok: false, error: 'A runner token is good for the runner routes only (docs/agents.md#pull): listing, claiming and reporting on runs. Nothing else of cornfield takes it.', code: 'forbidden' };
+  const presented = bearerOf(req.headers.authorization);
+  let owner = null;
+  let token;
+  if (presented && auth.enabled) {
+    const found = findToken(await auth.store(), presented, now(), 'runner');
+    if (found && found.state !== 'wrong-scope') { owner = found.row.login; token = { id: found.row.id, label: found.row.label }; }
+  }
+  const flood = owner === null ? countAttempt(ctx, NO_TOKEN_LOGIN, now(), ANONYMOUS_PER_MINUTE) : countAttempt(ctx, `runner|${token.id}`, now(), RUNNER_PER_MINUTE);
+  if (flood) return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+  if (auth.enabled) {
+    try {
+      await auth.record({
+        login: owner ?? NO_TOKEN_LOGIN, action: 'runner-call', target: config.forge?.repo ?? '',
+        request: { via: 'api', reason: 'wrong-route', method: String(req.method).slice(0, 10), path: reqPath.slice(0, 80), ...(token ? { token } : {}) }, status: 403, answer: { error: body.error, code: body.code },
+      });
+    } catch (err) {
+      console.error(`[cornfield] a runner call could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  return send(res, 403, body);
+}

package/server/server.js

@@ -22,7 +22,13 @@
  *   POST /api/forge/release-drafts      the release notes kept as a DRAFT release on the forge (never published, no tag made)
  *   POST /api/reviews                   Approve or Send back with a review token (`Authorization: Bearer cf_rt_…`), no cookie: the one
  *                                       route that answers before the sign-in guard, and takes the token alone (server/review-api.js)
- *   *    /api/review-tokens…            make, list and revoke review tokens: the signed-in maintainer only (server/review-api.js)
+ *   *    /api/review-tokens…, /api/agent-tokens…
+ *                                       make, list and revoke review tokens, and agent tokens: the signed-in maintainer only (server/review-api.js)
+ *   POST /api/agent-requests            ask for an agent run with an agent token (`Authorization: Bearer cf_at_…`), no cookie: before the guard too (server/agent-api.js)
+ *   GET  /api/agent-requests, POST /api/agent-requests/<run>/claim, GET and POST /api/runs/<run>
+ *                                       a runner's: list the queue, claim, read and report, with a runner token (`cf_nt_…`) and no cookie, before the guard
+ *                                       too; a runner token on any other route is 403 (server/runner-api.js)
+ *   *    /api/agent-runs…               the dashboard's runs: list, one, start, stop; the signed-in maintainer only (server/agent-api.js, server/agent-runs.js)
  *   *    /proposals…                    server/proposals.js (with sign-in, the open spec PRs too: server/proposal-pulls.js,
  *                                       and a review is a comment on one: server/reviews.js)
  *   *    <proxy path>/…                 server/proxy.js, for each path the config's `proxy` names
@@ -42,11 +48,15 @@ import http from 'node:http';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { browserSources, BUILTIN_SOURCES, specPollMs, ideaLabel } from '../core/config.js';
+import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, DEFAULTS, hookWants, ideaLabel } from '../core/config.js';
 import { CLOUD_FILE } from '../core/cloud.js';
 import { decodePath, inside, notFound, sendFile } from './files.js';
 import { serveProposals } from './proposals.js';
 import { serveForge } from './forge-routes.js';
+import { hasAdapter } from './forge.js';
+import { createRuns } from './agent-runs.js';
+import { REQUESTS_PATH, serveAgentCall, serveRunRoutes } from './agent-api.js';
+import { presentedScope, runnerRoute, serveRunnerCall, serveStrayRunner, takesTokens } from './runner-api.js';
 import { REVIEWS_PATH, serveReviewCall, serveTokenRoutes } from './review-api.js';
 import { proxyTo } from './proxy.js';
 import { HA_ENV, homeAssistantHouse } from '../plugins/house/home-assistant.js';
@@ -158,9 +168,20 @@ export function createCornfieldServer(config, opts = {}) {
     // What a restart left waiting: looked at again, in the background
     lander.resume().catch((err) => console.error(`[cornfield] pending landings could not be picked up: ${err instanceof Error ? err.message : err}`));
   }
-  // Looks at the open spec PRs on a timer when a hook wants spec.ready (config `hookPoll`); started when the server listens
-  const pollMs = hooks ? specPollMs(config) : null;
-  const specPoll = pollMs ? createSpecPoll({ config, where, auth, hooks, intervalMs: pollMs, now: opts.now, timer: opts.specPollTimer }) : null;
+  // Agent runs (server/agent-runs.js) need a signed-in maintainer to ask as and a forge to ask on; the runs are followed on the spec poll's tick
+  const runs = config.forge && auth.enabled && hasAdapter(config.forge.type) ? createRuns({ config, where, auth, hooks, now: opts.now, onAsk: () => specPoll?.start() }) : null;
+  // Push and pull need the same two things a request on the forge does (a maintainer's sign-in to ask as, a forge to check against), and push needs the hook that delivers it
+  const transport = config.agents?.transport ?? 'forge';
+  if (transport !== 'forge' && !runs) throw new Error(`agents.transport is "${transport}", which needs sign-in and a forge to ask as a maintainer and to check them: set them up (docs/sign-in.md, docs/config.md#forge).`);
+  if (transport === 'push' && !hookWants(config, ['agent.requested'])) throw new Error('agents.transport is "push", so a hook must subscribe to agent.requested: add { url, events: ["agent.requested"] } to "hooks" (docs/config.md#hooks). Without one a request would go nowhere.');
+  runs?.resume().catch((err) => console.error(`[cornfield] agent runs could not be picked up: ${err instanceof Error ? err.message : err}`));
+  // Looks at the open spec PRs on a timer when a hook wants spec.ready (config `hookPoll`); started when the server listens. The same timer follows
+  // agent runs: it is started for them when there is a run to follow, or as one is asked for, and does nothing while there is none
+  const specMs = hooks ? specPollMs(config) : null;
+  const runsEvery = config.hookPoll === undefined ? DEFAULTS.hookPoll.specs : config.hookPoll.specs;
+  const pollMs = specMs ?? (runs && runsEvery !== false ? parseDuration(runsEvery) : null);
+  const specPoll = pollMs ? createSpecPoll({ config, where, auth, hooks, runs, specs: specMs !== null, intervalMs: pollMs, now: opts.now, timer: opts.specPollTimer }) : null;
+  let serverClosed = false;
   const proxies = Object.entries(config.proxy || {});
   const houseSource = config.sources.house && (config.sources.house === 'house' || config.sources.house.use === 'house') ? config.sources.house : null;
   const houseFile = houseSource && houseSource.options && houseSource.options.file ? inside(root, houseSource.options.file) : null;
@@ -198,8 +219,14 @@ export function createCornfieldServer(config, opts = {}) {
       else res.end();
     }
   });
-  server.on('listening', () => specPoll?.start());
-  server.on('close', () => { specPoll?.close(); lander?.close(); hooks?.close(); auth.close(); });
+  server.on('listening', () => {
+    if (specMs !== null) specPoll?.start();
+    else if (specPoll && runs) {
+      // Runs asked for before a restart are followed again from the start
+      runs.hasWork().then((work) => { if (work && !serverClosed) specPoll.start(); }).catch(() => {});
+    }
+  });
+  server.on('close', () => { serverClosed = true; specPoll?.close(); lander?.close(); hooks?.close(); auth.close(); });
   return server;
 
   async function answer(req, res) {
@@ -230,18 +257,27 @@ export function createCornfieldServer(config, opts = {}) {
       return res.end('400 Bad Request');
     }
 
+    // A runner token is good for the runner routes only: on any other route it is refused here, before anything else is looked at
+    if (presentedScope(req) === 'runner' && !takesTokens(reqPath, { reviews: REVIEWS_PATH })) return serveStrayRunner(req, res, reqPath, { config, auth, now: opts.now });
+
     if (reqPath === '/healthz') {
       req.resume();
       return sendJson(res, 200, { ok: true });
     }
     // The review API takes a token, not a session: it is the one route before the guard (and it reads no cookie)
     if (reqPath === REVIEWS_PATH) return serveReviewCall(req, res, { config, where, auth, hooks, lander, now: opts.now });
+    // …and so does asking for a run: an agent token, not a session
+    // …and a runner asks for work and reports on it with a runner token (the GET of the same path lists the queue)
+    const runner = runnerRoute(reqPath);
+    if (runner && !(reqPath === REQUESTS_PATH && req.method !== 'GET' && req.method !== 'HEAD')) return serveRunnerCall(req, res, runner, url, { config, auth, runs, now: opts.now });
+    if (reqPath === REQUESTS_PATH) return serveAgentCall(req, res, { config, auth, runs, now: opts.now });
     const gate = await auth.gate(req, res, reqPath, url);
     if (gate.done) return;
     const signedIn = gate.session ? { login: gate.session.login } : false;
 
     // Before the proxies: a repo's `/api/` proxy must not swallow the panel's own routes
     if (await serveTokenRoutes(req, res, reqPath, { config, where, auth, session: gate.session, now: opts.now, publicHost })) return;
+    if (await serveRunRoutes(req, res, reqPath, { config, auth, runs, session: gate.session, now: opts.now, publicHost })) return;
     if (await serveForge(req, res, reqPath, url, { config, where, session: gate.session, auth, hooks, lander, now: opts.now, publicHost })) return;
     for (const [prefix, target] of proxies) if (reqPath.startsWith(prefix)) return proxyTo(req, res, target);
     const session = gate.session;

package/server/spec-poll.js

@@ -24,6 +24,10 @@
  * token is only ever asked those two questions, never used to list. With no such session the tick does nothing and says so
  * once for the stretch (and once more when a session is back). Whose sign-in it looks with is logged each time that changes.
  *
+ * **It also follows agent runs** (issue #80, server/agent-runs.js): when there is a run to look at (`runs.hasWork()`, a question of the
+ * database alone, so an idle repo costs the forge nothing), the same tick hands the same maintainer's forge to `runs.follow`, which reads the
+ * runs' comments and pull requests. A server with no `spec.ready` hook still polls for runs (`specs: false`) and then does nothing else.
+ *
  * **Never in the way.** One tick runs at a time (the next is scheduled when one ends, so a slow forge cannot pile them up).
  * A forge error is logged and never thrown; the next tick waits twice the interval until one succeeds. The timer is
  * unref'd and `close()` clears it.
@@ -48,14 +52,17 @@ const words = (err) => (err instanceof Error ? err.message : String(err));
  *   config: any,
  *   where: { proposals: string },
  *   auth: { store: () => Promise<import('node:sqlite').DatabaseSync>, forgeForUser: (userId: string) => Promise<import('./forge.js').Forge> },
- *   hooks: import('./hooks.js').Hooks,
+ *   hooks: import('./hooks.js').Hooks | null,
+ *   runs?: { hasWork: () => Promise<boolean>, follow: (forge: import('./forge.js').Forge) => Promise<unknown> } | null,
+ *   specs?: boolean,
  *   intervalMs: number,
  *   now?: () => number,
  *   timer?: { setTimeout: Function, clearTimeout: Function },
  *   firstMs?: number,
- * }} opts `now`, `timer` and `firstMs` are the tests' clock
+ * }} opts `now`, `timer` and `firstMs` are the tests' clock; `runs` is the agent runs engine, whose runs are followed on the same tick, and
+ *   `specs: false` leaves the spec PRs alone (no hook wants `spec.ready`), so only the runs are looked at
  */
-export function createSpecPoll({ config, where, auth, hooks, intervalMs, now = Date.now, timer = { setTimeout, clearTimeout }, firstMs = FIRST_MS }) {
+export function createSpecPoll({ config, where, auth, hooks, runs = null, specs = true, intervalMs, now = Date.now, timer = { setTimeout, clearTimeout }, firstMs = FIRST_MS }) {
   const repo = config.forge.repo;
   const log = (what) => console.error(`[cornfield] spec.ready poll: ${what}`);
   let handle = null;
@@ -101,6 +108,14 @@ export function createSpecPoll({ config, where, auth, hooks, intervalMs, now = D
 
   /** One look. Resolves to what happened; never rejects. */
   async function look() {
+    // Nothing to look at: no forge call is made (an idle repo with only runs to follow costs nothing)
+    let followRuns = false;
+    try {
+      followRuns = Boolean(runs) && await /** @type {NonNullable<typeof runs>} */ (runs).hasWork();
+    } catch (err) {
+      log(`the runs could not be counted: ${words(err)}`);
+    }
+    if (!specs && !followRuns) return 'ok';
     let found;
     try {
       found = await maintainerForge();
@@ -120,20 +135,31 @@ export function createSpecPoll({ config, where, auth, hooks, intervalMs, now = D
     noSession = false;
     if (found.login !== lookingAs) log(`looking at the open spec PRs${threadsOn(config) && hookWants(config, THREAD_EVENTS) ? ' and threads' : ''} with the sign-in of @${found.login}, a maintainer`);
     lookingAs = found.login;
-    try {
-      const specs = hookWants(config, ['spec.ready']);
-      const threads = threadsOn(config) && hookWants(config, THREAD_EVENTS);
-      // One listing of the open PRs serves both: the threads' look makes it itself when it runs
-      const problem = threads ? await lookAtThreads(found.forge, specs) : (await listPullProposals(found.forge, where, { hooks })).problem;
-      if (problem) {
-        log(`the forge could not be asked: ${problem}`);
-        return 'error';
+    let out = 'ok';
+    if (specs) {
+      try {
+        const specReady = hookWants(config, ['spec.ready']);
+        const threads = threadsOn(config) && hookWants(config, THREAD_EVENTS);
+        // One listing of the open PRs serves both: the threads' look makes it itself when it runs
+        const problem = threads ? await lookAtThreads(found.forge, specReady) : (await listPullProposals(found.forge, where, { hooks })).problem;
+        if (problem) {
+          log(`the forge could not be asked: ${problem}`);
+          out = 'error';
+        }
+      } catch (err) {
+        log(`failed: ${words(err)}`);
+        out = 'error';
+      }
+    }
+    if (followRuns && !closed) {
+      try {
+        await /** @type {NonNullable<typeof runs>} */ (runs).follow(found.forge);
+      } catch (err) {
+        log(`the runs could not be followed: ${words(err)}`);
+        out = 'error';
       }
-      return 'ok';
-    } catch (err) {
-      log(`failed: ${words(err)}`);
-      return 'error';
     }
+    return out;
   }
 
   function schedule(ms) {