cornfield 0.7.0 → 0.9.0

package/server/proposal-pulls.js

@@ -84,7 +84,7 @@ function entryOf(pull, file) {
  * @param {import('./forge.js').Forge} forge
  * @param {{ proposals: string }} where
  * @param {{ hooks?: { specsSeen: Function } | null }} [opts]
- * @returns {Promise<{ entries: PullEntry[], problem: string | null }>}
+ * @returns {Promise<{ entries: PullEntry[], problem: string | null, pulls: import('./forge.js').Pull[] }>} `pulls`: the open pull requests listed (a thread look reads their text, server/threads.js)
  */
 export async function listPullProposals(forge, where, { hooks = null } = {}) {
   const folder = folderOf(where);
@@ -92,7 +92,7 @@ export async function listPullProposals(forge, where, { hooks = null } = {}) {
   try {
     pulls = await forge.pulls({ state: 'open' });
   } catch (err) {
-    return { entries: [], problem: forgeWords(err) };
+    return { entries: [], problem: forgeWords(err), pulls: [] };
   }
   let problem = null;
   const found = pulls.map(() => []);
@@ -112,7 +112,7 @@ export async function listPullProposals(forge, where, { hooks = null } = {}) {
   if (hooks) {
     try { hooks.specsSeen(forge.repo, entries, (entry) => readPullProposal(forge, where, entry)); } catch { /* a hook never gets in the way */ }
   }
-  return { entries, problem };
+  return { entries, problem, pulls };
 }
 
 /**

package/server/review-api.js

@@ -8,6 +8,8 @@
  *   GET  /api/review-tokens              the signed-in maintainer's tokens: id, label, made, expires, revoked, last used (never a secret)
  *   POST /api/review-tokens              { label, days? } -> the new token, in this answer only
  *   POST /api/review-tokens/<id>/revoke  ends one of theirs for good
+ *   *    /api/agent-tokens…                  the same three for tokens of the other scope: an agent token asks for runs
+ *                                        (`POST /api/agent-requests`, server/agent-api.js) and is no good here, as a review token is no good there
  *
  * **The call takes the token and nothing else.** It runs before the sign-in guard (a script has no cookie) and reads no
  * cookie: a session cookie is never a substitute for the token, and a request that sends only one is 401. Being no
@@ -41,6 +43,7 @@ import { Refused, countAttempt } from './throttle.js';
 
 export const REVIEWS_PATH = '/api/reviews';
 export const TOKENS_PATH = '/api/review-tokens';
+export const AGENT_TOKENS_PATH = '/api/agent-tokens';
 /** Calls with no token, or one nobody holds, that are written down in a minute, all callers together */
 export const ANONYMOUS_PER_MINUTE = 20;
 /** What the audit row of a call nobody could name says in place of a login */
@@ -88,7 +91,7 @@ export async function serveReviewCall(req, res, ctx) {
   // The token, from the header alone; a cookie is not looked at
   const presented = bearerOf(req.headers.authorization);
   const db = presented ? await auth.store() : null;
-  const found = presented && db ? findToken(db, presented, now()) : null;
+  const found = presented && db ? findToken(db, presented, now(), 'review') : null;
   if (!found) {
     req.resume();
     const reason = presented ? 'unknown-token' : 'no-token';
@@ -101,6 +104,15 @@ export async function serveReviewCall(req, res, ctx) {
 
   const { row, state } = found;
   const token = { id: row.id, label: row.label };
+  // An agent token asks for runs and is no review token: refused whatever its state, and not counted as used
+  if (state === 'wrong-scope') {
+    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 body = { error: `This is an ${row.scope} token. Reviews take a review token; make one in the dashboard.`, code: 'forbidden' };
+    await audit(row.login, { reason: 'wrong-scope', token, scope: row.scope }, 403, body);
+    return send(res, 403, { ok: false, ...body });
+  }
   if (state !== 'active') {
     req.resume();
     const flood = countAttempt(ctx, row.user_id, now());
@@ -125,7 +137,7 @@ export async function serveReviewCall(req, res, ctx) {
       forge: () => auth.forgeForUser(row.user_id), where, repo, who: { login: row.login, userId: row.user_id },
       record: (entry) => auth.record(entry), limits: { auth, now: ctx.now }, via: { token }, requireSha256: true, hooks: ctx.hooks, lander: ctx.lander,
       stillAllowed: async () => {
-        const again = findToken(await auth.store(), /** @type {string} */ (presented), now());
+        const again = findToken(await auth.store(), /** @type {string} */ (presented), now(), 'review');
         if (again && again.state === 'active') return null;
         return again && again.state === 'expired' ? 'This review token expired while the review was being checked; nothing was posted.' : 'This review token was revoked while the review was being checked; nothing was posted.';
       },
@@ -159,7 +171,7 @@ function inputOf(text) {
 // ---------------------------------------------------------------------------
 
 /** What a token looks like to the dashboard: no hash, no secret */
-const publicToken = ({ id, login, label, created_at, expires_at, revoked_at, last_used, state }) => ({ id, login, label, created: created_at, expires: expires_at, revoked: revoked_at, lastUsed: last_used, state });
+const publicToken = ({ id, login, label, scope, created_at, expires_at, revoked_at, last_used, state }) => ({ id, login, label, scope, created: created_at, expires: expires_at, revoked: revoked_at, lastUsed: last_used, state });
 
 /**
  * The `/api/review-tokens` routes. The caller has passed the sign-in guard, so `session` is a maintainer's.
@@ -170,8 +182,10 @@ const publicToken = ({ id, login, label, created_at, expires_at, revoked_at, las
  * @returns {Promise<boolean>} whether the path was one of these
  */
 export async function serveTokenRoutes(req, res, reqPath, ctx) {
-  const revoke = /^\/api\/review-tokens\/([1-9]\d{0,9})\/revoke$/.exec(reqPath);
-  if (reqPath !== TOKENS_PATH && !revoke) return false;
+  const revoke = /^\/api\/(review|agent)-tokens\/([1-9]\d{0,9})\/revoke$/.exec(reqPath);
+  if (reqPath !== TOKENS_PATH && reqPath !== AGENT_TOKENS_PATH && !revoke) return false;
+  /** @type {'review' | 'agent'} the scope of the tokens this path is about */
+  const scope = revoke ? /** @type {'review' | 'agent'} */ (revoke[1]) : reqPath === AGENT_TOKENS_PATH ? 'agent' : 'review';
   const { config, auth, session } = ctx;
   const now = ctx.now ?? Date.now;
   const allow = revoke ? 'POST' : 'GET, POST';
@@ -183,12 +197,12 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
   }
   if (!session || !auth.store) {
     req.resume();
-    send(res, 403, { ok: false, error: 'Review tokens belong to a signed-in maintainer: set up sign-in first (docs/sign-in.md).', code: 'forbidden' });
+    send(res, 403, { ok: false, error: `${scope === 'agent' ? 'Agent' : 'Review'} tokens belong to a signed-in maintainer: set up sign-in first (docs/sign-in.md).`, code: 'forbidden' });
     return true;
   }
   const db = await auth.store();
   if (method === 'GET') {
-    send(res, 200, { ok: true, tokens: listTokens(db, session.userId, now()).map(publicToken), defaultDays: DEFAULT_DAYS, maxDays: MAX_DAYS, maxActive: MAX_ACTIVE });
+    send(res, 200, { ok: true, tokens: listTokens(db, session.userId, now(), scope).map(publicToken), defaultDays: DEFAULT_DAYS, maxDays: MAX_DAYS, maxActive: MAX_ACTIVE });
     return true;
   }
 
@@ -200,7 +214,7 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
     return true;
   }
   const what = revoke ? 'revoke' : 'mint';
-  const request = /** @type {Record<string, unknown>} */ ({ op: what, ...(revoke ? { id: Number(revoke[1]) } : {}) });
+  const request = /** @type {Record<string, unknown>} */ ({ op: what, ...(scope === 'agent' ? { scope } : {}), ...(revoke ? { id: Number(revoke[2]) } : {}) });
   let rowId = null;
   /** @type {{ status: number, body: object }} */
   let out;
@@ -219,10 +233,10 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
     const forge = auth.forgeFor(session);
     const me = await forge.me();
     if (String(me.id) !== String(session.userId)) throw new Refused(403, 'The forge says this sign-in is someone else now; sign in again.', 'forbidden');
-    if (!isMaintainer(await forge.permission(config.forge.repo, me.login))) throw new Refused(403, `Only the repo's maintainers make review tokens; ${me.login} is not one now.`, 'forbidden');
+    if (!isMaintainer(await forge.permission(config.forge.repo, me.login))) throw new Refused(403, `Only the repo's maintainers make ${scope} tokens; ${me.login} is not one now.`, 'forbidden');
     if (revoke) {
-      const done = revokeToken(db, session.userId, Number(revoke[1]), now());
-      if (!done) throw new Refused(404, 'You have no review token by that number.', 'not-found');
+      const done = revokeToken(db, session.userId, Number(revoke[2]), now(), scope);
+      if (!done) throw new Refused(404, `You have no ${scope} token by that number.`, 'not-found');
       request.label = done.label;
       out = { status: 200, body: { ok: true, token: publicToken(done) } };
     } else {
@@ -239,7 +253,7 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
       Object.assign(request, { label: body.label, days });
       let made;
       try {
-        made = mintToken(db, { userId: session.userId, login: me.login, label: body.label, days }, now());
+        made = mintToken(db, { userId: session.userId, login: me.login, label: body.label, days, scope }, now());
       } catch (err) {
         if (err instanceof RangeError) throw new Refused(409, err.message, 'conflict');
         throw err;

package/server/review-tokens.js

@@ -1,11 +1,16 @@
 /**
  * @module server/review-tokens
  *
- * Review tokens: what a maintainer hands a script or a chat bot so it can Approve or Send back a proposal through
- * `POST /api/reviews` (server/review-api.js). The store over the `review_tokens` table of `cornfield.db`
- * (server/db.js); nothing here knows about HTTP.
+ * API tokens: what a maintainer hands a script or a chat bot so it can Approve or Send back a proposal through
+ * `POST /api/reviews` (server/review-api.js), or ask for an agent run through `POST /api/agent-requests`
+ * (server/agent-api.js). The store over the `review_tokens` table of `cornfield.db` (server/db.js); nothing here knows
+ * about HTTP.
  *
- *   - A token is `cf_rt_` and 32 random bytes in base64url. It is shown once, when it is made; only its SHA-256 is
+ *   - **A token has a scope,** `review` or `agent`, and is good for the one API its scope names; each API refuses the other's
+ *     token (403) and says so. One store serves both, so hashing, expiry, revoking, `last_used` and the limits are written
+ *     once and cannot drift. A review token is `cf_rt_…` and an agent token `cf_at_…`, so a leaked one is told apart on
+ *     sight (and by a secret scanner). Rows from before scopes existed are review tokens.
+ *   - A token is its prefix and 32 random bytes in base64url. It is shown once, when it is made; only its SHA-256 is
  *     kept. A presented token is found by the hash of what was presented (an indexed equality on a hash of a 256-bit
  *     secret, so there is no secret-dependent comparison to time); the token itself is never stored, logged or
  *     returned again.
@@ -17,14 +22,18 @@
  *
  * Times are ISO strings, as everywhere in the file; `now` is milliseconds and is passed in, so tests need no clock.
  *
- * @typedef {{ id: number, user_id: string, login: string, label: string, created_at: string, expires_at: string, revoked_at: string | null, last_used: string | null }} TokenRow
- * @typedef {'active' | 'expired' | 'revoked'} TokenState
+ * @typedef {'review' | 'agent'} TokenScope
+ * @typedef {{ id: number, user_id: string, login: string, label: string, scope: TokenScope, created_at: string, expires_at: string, revoked_at: string | null, last_used: string | null }} TokenRow
+ * @typedef {'active' | 'expired' | 'revoked' | 'wrong-scope'} TokenState  `wrong-scope` only from `findToken` asked for a scope
  */
 
 import { createHash, randomBytes } from 'node:crypto';
 
-/** What every token starts with, so a leaked one is recognised (by a secret scanner too) */
-export const TOKEN_PREFIX = 'cf_rt_';
+/** The scopes a token may have, and what each one's tokens start with, so a leaked one is recognised (by a secret scanner too) */
+export const SCOPES = Object.freeze(['review', 'agent']);
+export const PREFIXES = Object.freeze({ review: 'cf_rt_', agent: 'cf_at_' });
+/** What a review token starts with (the original, kept for the callers that always had it) */
+export const TOKEN_PREFIX = PREFIXES.review;
 /** Random bytes in a token */
 export const TOKEN_BYTES = 32;
 export const DEFAULT_DAYS = 30;
@@ -34,10 +43,10 @@ export const MAX_ACTIVE = 20;
 export const MAX_LABEL = 60;
 const DAY_MS = 24 * 60 * 60 * 1000;
 /** A token as presented: the prefix and base64url (43 characters for 32 bytes); anything else is not one */
-const TOKEN_SHAPE = /^cf_rt_[A-Za-z0-9_-]{43,128}$/;
+const TOKEN_SHAPE = /^cf_(?:rt|at)_[A-Za-z0-9_-]{43,128}$/;
 /** A label is words: letters, digits, spaces and a little punctuation. No backtick, no @, no newline: the comment quotes it */
 const LABEL = /^[\p{L}\p{N}][\p{L}\p{N} ._:/()-]*$/u;
-const COLUMNS = 'id, user_id, login, label, created_at, expires_at, revoked_at, last_used';
+const COLUMNS = 'id, user_id, login, label, scope, created_at, expires_at, revoked_at, last_used';
 
 const iso = (ms) => new Date(ms).toISOString();
 
@@ -48,7 +57,7 @@ export function hashToken(token) {
 
 /**
  * The token a request presents: the value of `Authorization: Bearer <token>`, or null when there is none, or it is
- * not shaped like one of ours (the scheme is matched in any case, as RFC 9110 says).
+ * not shaped like one of ours (either scope's; which API it is good for is the row's `scope`) (the scheme is matched in any case, as RFC 9110 says).
  * @param {string | string[] | undefined} header
  * @returns {string | null}
  */
@@ -96,21 +105,22 @@ export function stateOf(row, now) {
  * for a label or a number of days that is not allowed, or when the owner holds `MAX_ACTIVE` live tokens already.
  * Tokens that ended (expired or revoked) more than `MAX_DAYS` days ago are dropped on the way.
  * @param {import('node:sqlite').DatabaseSync} db
- * @param {{ userId: string, login: string, label: string, days?: number }} owner
+ * @param {{ userId: string, login: string, label: string, days?: number, scope?: TokenScope }} owner `scope`: `review` unless said
  * @param {number} now
  * @returns {{ token: string, row: TokenRow }}
  */
-export function mintToken(db, { userId, login, label, days }, now) {
+export function mintToken(db, { userId, login, label, days, scope = 'review' }, now) {
+  if (!SCOPES.includes(scope)) throw new RangeError(`A token's scope is one of ${SCOPES.join(', ')}.`);
   const problem = labelProblem(label);
   if (problem) throw new RangeError(problem);
   const lasts = daysOf(days);
   const nowIso = iso(now);
   db.prepare('DELETE FROM review_tokens WHERE COALESCE(revoked_at, expires_at) <= ?').run(iso(now - MAX_DAYS * DAY_MS));
-  const live = /** @type {{ n: number }} */ (db.prepare('SELECT COUNT(*) AS n FROM review_tokens WHERE user_id = ? AND revoked_at IS NULL AND expires_at > ?').get(String(userId), nowIso)).n;
-  if (live >= MAX_ACTIVE) throw new RangeError(`You hold ${MAX_ACTIVE} live tokens; revoke one you do not use before making another.`);
-  const token = `${TOKEN_PREFIX}${randomBytes(TOKEN_BYTES).toString('base64url')}`;
-  const id = Number(db.prepare('INSERT INTO review_tokens (token_hash, user_id, login, label, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?)')
-    .run(hashToken(token), String(userId), login, label, nowIso, iso(now + lasts * DAY_MS)).lastInsertRowid);
+  const live = /** @type {{ n: number }} */ (db.prepare('SELECT COUNT(*) AS n FROM review_tokens WHERE user_id = ? AND scope = ? AND revoked_at IS NULL AND expires_at > ?').get(String(userId), scope, nowIso)).n;
+  if (live >= MAX_ACTIVE) throw new RangeError(`You hold ${MAX_ACTIVE} live ${scope === 'review' ? '' : `${scope} `}tokens; revoke one you do not use before making another.`);
+  const token = `${PREFIXES[scope]}${randomBytes(TOKEN_BYTES).toString('base64url')}`;
+  const id = Number(db.prepare('INSERT INTO review_tokens (token_hash, user_id, login, label, scope, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+    .run(hashToken(token), String(userId), login, label, scope, nowIso, iso(now + lasts * DAY_MS)).lastInsertRowid);
   return { token, row: /** @type {TokenRow} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE id = ?`).get(id)) };
 }
 
@@ -121,9 +131,12 @@ export function mintToken(db, { userId, login, label, days }, now) {
  * @param {number} now
  * @returns {{ row: TokenRow, state: TokenState } | null}
  */
-export function findToken(db, token, now) {
+export function findToken(db, token, now, scope) {
   const row = /** @type {TokenRow | undefined} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE token_hash = ?`).get(hashToken(token)));
-  return row ? { row, state: stateOf(row, now) } : null;
+  if (!row) return null;
+  // The scope is part of the lookup, not of each route: a token found for another API, or whose prefix is not its scope's, is no token here
+  if (scope !== undefined && (row.scope !== scope || !String(token).startsWith(PREFIXES[row.scope]))) return { row, state: /** @type {const} */ ('wrong-scope') };
+  return { row, state: stateOf(row, now) };
 }
 
 /** Notes that a token was presented (and valid) just now */
@@ -132,14 +145,17 @@ export function touchToken(db, id, now) {
 }
 
 /**
- * An owner's tokens, newest first, each with its state. Never the hash, never the token.
+ * An owner's tokens of one scope (all of them when none is named), newest first, each with its state. Never the hash, never the token.
  * @param {import('node:sqlite').DatabaseSync} db
  * @param {string} userId
  * @param {number} now
+ * @param {TokenScope} [scope]
  * @returns {(TokenRow & { state: TokenState })[]}
  */
-export function listTokens(db, userId, now) {
-  return /** @type {TokenRow[]} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE user_id = ? ORDER BY id DESC`).all(String(userId)))
+export function listTokens(db, userId, now, scope) {
+  return /** @type {TokenRow[]} */ (scope
+    ? db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE user_id = ? AND scope = ? ORDER BY id DESC`).all(String(userId), scope)
+    : db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE user_id = ? ORDER BY id DESC`).all(String(userId)))
     .map((row) => ({ ...row, state: stateOf(row, now) }));
 }
 
@@ -150,11 +166,12 @@ export function listTokens(db, userId, now) {
  * @param {string} userId
  * @param {number} id
  * @param {number} now
+ * @param {TokenScope} [scope] when named, a token of the other scope is no token to them here
  * @returns {(TokenRow & { state: TokenState }) | null} the token as it is now, or null when the owner has none by that id
  */
-export function revokeToken(db, userId, id, now) {
+export function revokeToken(db, userId, id, now, scope) {
   const row = /** @type {TokenRow | undefined} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE id = ? AND user_id = ?`).get(id, String(userId)));
-  if (!row) return null;
+  if (!row || (scope && row.scope !== scope)) return null;
   if (!row.revoked_at) db.prepare('UPDATE review_tokens SET revoked_at = ? WHERE id = ?').run(iso(now), id);
   const after = /** @type {TokenRow} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE id = ?`).get(id));
   return { ...after, state: stateOf(after, now) };

package/server/server.js

@@ -22,7 +22,10 @@
  *   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)
+ *   *    /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 +45,14 @@ 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 } from '../core/config.js';
+import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, DEFAULTS, 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 { REVIEWS_PATH, serveReviewCall, serveTokenRoutes } from './review-api.js';
 import { proxyTo } from './proxy.js';
 import { HA_ENV, homeAssistantHouse } from '../plugins/house/home-assistant.js';
@@ -59,7 +65,7 @@ import { createSpecPoll } from './spec-poll.js';
 export const CORNFIELD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EXPLORER_DIR = path.join(CORNFIELD_DIR, 'explorer');
 /** The pure core modules the explorer imports (no Node built-ins, no files): the only ones of core/ served */
-export const BROWSER_CORE = ['schema.js', 'proposal.js', 'personas.js', 'cloud.js', 'text.js'];
+export const BROWSER_CORE = ['schema.js', 'proposal.js', 'personas.js', 'cloud.js', 'text.js', 'mentions.js'];
 /** cornfield's own browser sources, by request path */
 const BROWSER_PLUGINS = new Map(Object.values(BUILTIN_SOURCES).map((p) => [p, path.join(CORNFIELD_DIR, p)]));
 const PKG = JSON.parse(fs.readFileSync(path.join(CORNFIELD_DIR, 'package.json'), 'utf8'));
@@ -109,6 +115,8 @@ export function clientConfig(config, signIn = false) {
     title: config.title,
     links: config.links || [],
     forge: config.forge ? { type: config.forge.type, url: config.forge.url || (config.forge.type === 'github' ? 'https://github.com' : null), repo: config.forge.repo, mergeMethod: config.forge.mergeMethod || 'merge', ...(config.approveLands ? { approveLands: true } : {}) } : null,
+    // Threads (docs/threads.md): the idea label, or false when `threads: false` turns the Threads tab off
+    threads: config.threads === false ? false : { label: ideaLabel(config) },
     sources: browserSources(config),
     signIn,
   };
@@ -156,9 +164,16 @@ 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;
+  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;
@@ -196,8 +211,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) {
@@ -234,12 +255,15 @@ export function createCornfieldServer(config, opts = {}) {
     }
     // 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
+    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

@@ -1,7 +1,8 @@
 /**
  * @module server/spec-poll
  *
- * `spec.ready` without anyone at the dashboard (PIPE-10, docs/config.md#hook-poll). cornfield notices a spec PR when it
+ * `spec.ready` and the `thread.*` events without anyone at the dashboard (PIPE-10, docs/config.md#hook-poll, docs/threads.md).
+ * cornfield notices a spec PR when it
  * lists the open ones, and that listing used to run only when a maintainer opened the proposals menu or the issues and PRs
  * panel. A team that reviews from chat never does, so this lists them on a timer.
  *
@@ -11,12 +12,22 @@
  * nothing here decides what is news. The forge answers come through the same per-head cache, so a tick with nothing new
  * costs the open-PR listing (a call a page) plus the two calls that check the token's owner; see the docs for the count.
  *
+ * **Threads ride the same tick.** When a hook wants `thread.opened`, `thread.message` or `thread.linked` (and threads are on),
+ * the look also reads the ideas and the spec PRs' conversations (server/threads.js) with the same sign-in, the same timer and
+ * the same backoff: one look, one set of calls to the forge for the open PRs, then what the database says is new
+ * (`hooks.threadCursors`: an idea whose update time is the one last seen is not read again, and the rest are read from their
+ * newest seen comment on). A failure in either half is the tick's failure.
+ *
  * **Whose token.** Never one from the config. The newest live sign-in of a user the forge confirms is a maintainer now
  * (`auth.forgeForUser`, then `me()` and `permission()` with that token; the same check the review API and the lander make).
  * A user who is not, or whose token the forge refuses, is passed over for the next newest, at most `MAX_CANDIDATES`; their
  * 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.
@@ -24,6 +35,9 @@
 
 import { isMaintainer } from './forge.js';
 import { listPullProposals } from './proposal-pulls.js';
+import { gatherThreads, snapshotOf, POLL_LIMIT } from './threads.js';
+import { hookWants, threadsOn, THREAD_EVENTS } from '../core/config.js';
+import { readTopology } from '../core/validate.js';
 
 /** How long after start the first look is made: soon, so the repo's silent first look is not left to the first interval */
 export const FIRST_MS = 15_000;
@@ -38,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;
@@ -71,8 +88,34 @@ export function createSpecPoll({ config, where, auth, hooks, intervalMs, now = D
     return null;
   }
 
+  /** The checkout's nodes, for a hook's `nodes` to be the ones a mention resolves to; none when there is no map */
+  function mapNodes() {
+    try {
+      const topology = readTopology(config);
+      return topology && Array.isArray(topology.nodes) ? topology.nodes : [];
+    } catch {
+      return [];
+    }
+  }
+
+  /** The ideas and the spec PRs' conversations, read from where the database left off and handed to the hooks */
+  async function lookAtThreads(forge, withSpecs) {
+    const cursors = await hooks.threadCursors(repo);
+    const got = await gatherThreads(forge, config, where, { state: 'all', limit: POLL_LIMIT, hooks: withSpecs ? hooks : null, cursors: cursors.looked ? cursors.threads : null });
+    await hooks.threadsSeen(repo, snapshotOf(got, mapNodes()));
+    return got.problem;
+  }
+
   /** 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();
@@ -90,19 +133,33 @@ export function createSpecPoll({ config, where, auth, hooks, intervalMs, now = D
     }
     if (noSession) log('a signed-in maintainer is back; checking the open spec PRs again');
     noSession = false;
-    if (found.login !== lookingAs) log(`looking at the open spec PRs with the sign-in of @${found.login}, a maintainer`);
+    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 { problem } = await listPullProposals(found.forge, where, { hooks });
-      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) {