@popcorn245/cornfield 0.9.0 → 0.11.0

package/server/hooks.js

@@ -25,10 +25,18 @@
  *                   `{ event, at, actor, expiresAt, mapUrl }`
  *   agent.requested  a maintainer asked for an agent run (server/agent-runs.js). Its body is its own: `{ event, at, request, actor, mapUrl }`,
  *                   `request` being the whole request JSON of the contract (docs/agent-contract.md), which holds no credential by construction
+ *   trigger.skipped  an opt-in trigger (`agents.on`, server/triggers.js) was going to request a run and did not: the maintainer whose act caused it has no
+ *                   live sign-in (`reason: 'no-session'`), or the request was refused (the cap, the one-run-per-subject rule, the rate limit: the refusal's code).
+ *                   Its body is its own: `{ event, at, trigger: { event, by, ref }, by, reason, mapUrl }`
  *   run.claimed  run.state  run.stopRequested  run.finished   a run was claimed by its runner, changed state, was asked to stop, ended. They are
  *                   seen when cornfield looks (the spec poll, server/spec-poll.js), each once. Their body is their own:
  *                   `{ event, at, runId, state, pull?, issue?, actor, mapUrl }`
  *
+ * **Triggers listen in-process.** `subscribe(fn)` hands a function the same moments the hooks fire at, with the payload resolved, whether or not
+ * any hook asks for them (server/triggers.js: `spec.approved`, `build.opened`, `thread.message`). A thread's payload then also holds the
+ * comment's text and times for that function alone; `bodyOf` picks fixed fields, so none of it can leave through a hook. A subscriber never
+ * slows or breaks a delivery, and a failing one is only logged.
+ *
  * **A hook never gets in the way.** `emit` returns at once and never throws; the delivery runs in the background, from a
  * queue in memory. A failed delivery (a network error, a timeout, anything but a 2xx) is tried again after 1s, 5s and 30s
  * (four attempts in all) and every attempt is a row in the `actions` audit table (`action: 'hook'`). A hook that is
@@ -135,6 +143,9 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
   if (typeof secret !== 'string' || secret.length < MIN_HOOK_SECRET) throw new Error(`${HOOK_SECRET_ENV} must be at least ${MIN_HOOK_SECRET} characters.`);
   const targets = hooks.map((h, i) => ({ index: i, url: h.url, origin: originOf(h.url), events: h.events === '*' ? HOOK_EVENTS : h.events }));
   const timers = new Set();
+  /** @type {{ fn: (event: string, payload: any) => unknown, events: string[] | null }[]} */
+  const subscribers = [];
+  const listeners = (event) => subscribers.filter((s) => s.events === null || s.events.includes(event));
   let pending = 0;
   let closed = false;
 
@@ -200,6 +211,11 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
   function bodyOf(event, p) {
     // A session's end has no spec, pull request or proposal: its body is only who, until when, and where cornfield is
     if (event === 'session.expiring') return JSON.stringify({ event, at: new Date(now()).toISOString(), actor: p.actor ?? null, expiresAt: p.expiresAt ?? null, mapUrl: publicUrl || null });
+    // A skipped trigger says which trigger, who caused it and why it did nothing: never a brief or any text
+    if (event === 'trigger.skipped') {
+      const t = p.trigger && typeof p.trigger === 'object' ? { event: p.trigger.event ?? null, by: p.trigger.by ?? null, ref: p.trigger.ref ?? null } : null;
+      return JSON.stringify({ event, at: new Date(now()).toISOString(), trigger: t, by: p.by ?? null, reason: p.reason ?? null, mapUrl: publicUrl || null });
+    }
     // A request goes out as it was posted, and is checked once more on the way: nothing like a credential can leave through a hook
     if (event === 'agent.requested') {
       const checked = validateRequest(p.request);
@@ -244,10 +260,17 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     try {
       if (closed || !HOOK_EVENTS.includes(event)) return;
       const to = targets.filter((t) => t.events.includes(event));
-      if (!to.length) return;
+      // Nobody wants it: the payload is not even worked out (it may read the forge)
+      const local = listeners(event);
+      if (!to.length && !local.length) return;
       Promise.resolve()
         .then(() => (typeof payload === 'function' ? payload() : payload))
         .then((p) => {
+          // In-process listeners first, each on its own: they cannot hold up or break a delivery
+          for (const { fn } of local) {
+            Promise.resolve().then(() => fn(event, p || {})).catch((err) => console.error(`[cornfield] a listener of ${event} failed: ${err instanceof Error ? err.message : err}`));
+          }
+          if (!to.length) return;
           const body = bodyOf(event, p || {});
           for (const t of to) {
             if (pending >= MAX_PENDING) {
@@ -267,6 +290,17 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     }
   }
 
+  /**
+   * Listens in-process to every event `emit` is given (a trigger does: server/triggers.js). `fn(event, payload)` gets the payload
+   * resolved; it may be async, is never awaited and its failure is only logged. With `events`, only those: an event nobody listens to and no
+   * hook asks for has its payload left unworked out.
+   * @param {(event: string, payload: any) => unknown} fn
+   * @param {string[]} [events]
+   */
+  function subscribe(fn, events) {
+    if (typeof fn === 'function') subscribers.push({ fn, events: Array.isArray(events) ? [...events] : null });
+  }
+
   /**
    * `spec.ready`: the spec PRs a listing just showed. A (pull request, head, proposal) that is not a draft and was not
    * seen before is announced once, and remembered in the SQLite file so a restart does not announce it again. A draft is
@@ -345,7 +379,7 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
           emit('thread.linked', { thread: t.number, actor: t.opened.actor, nodes: t.opened.linked.nodes, proposal: t.opened.linked.proposal });
         }
         for (const m of t.messages) {
-          if (fresh(t.number, String(m.id), m.stamp)) emit('thread.message', { thread: t.number, comment: m.id, actor: m.actor });
+          if (fresh(t.number, String(m.id), m.stamp)) emit('thread.message', { thread: t.number, comment: m.id, actor: m.actor, message: m.text });
           if (m.linked && fresh(t.number, `link:${m.id}`)) emit('thread.linked', { thread: t.number, comment: m.id, actor: m.actor, nodes: m.linked.nodes, proposal: m.linked.proposal });
         }
         // The last-update time moves with every look that read the thread, so the next look can skip it when nothing changed
@@ -395,7 +429,7 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     timers.clear();
   }
 
-  return { emit, specsSeen, threadCursors, threadsSeen, watchSessions, close };
+  return { emit, subscribe, specsSeen, threadCursors, threadsSeen, watchSessions, close };
 }
 
 /** The SHA-256 of a proposal file as `read` gives it, or null when it cannot be read (an event still goes out) */

package/server/review-api.js

@@ -8,8 +8,9 @@
  *   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
+ *   *    /api/agent-tokens…                  the same three for tokens of another 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
+ *   *    /api/runner-tokens…                 and for a runner token, which lists, claims and reports on runs (server/runner-api.js)
  *
  * **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
@@ -44,6 +45,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';
+export const RUNNER_TOKENS_PATH = '/api/runner-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 */
@@ -109,7 +111,7 @@ export async function serveReviewCall(req, res, ctx) {
     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' };
+    const body = { error: `This is ${row.scope === 'agent' ? 'an' : 'a'} ${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 });
   }
@@ -182,10 +184,10 @@ const publicToken = ({ id, login, label, scope, created_at, expires_at, revoked_
  * @returns {Promise<boolean>} whether the path was one of these
  */
 export async function serveTokenRoutes(req, res, reqPath, ctx) {
-  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 revoke = /^\/api\/(review|agent|runner)-tokens\/([1-9]\d{0,9})\/revoke$/.exec(reqPath);
+  if (reqPath !== TOKENS_PATH && reqPath !== AGENT_TOKENS_PATH && reqPath !== RUNNER_TOKENS_PATH && !revoke) return false;
+  /** @type {import('./review-tokens.js').TokenScope} the scope of the tokens this path is about */
+  const scope = revoke ? /** @type {import('./review-tokens.js').TokenScope} */ (revoke[1]) : reqPath === AGENT_TOKENS_PATH ? 'agent' : reqPath === RUNNER_TOKENS_PATH ? 'runner' : 'review';
   const { config, auth, session } = ctx;
   const now = ctx.now ?? Date.now;
   const allow = revoke ? 'POST' : 'GET, POST';
@@ -197,7 +199,7 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
   }
   if (!session || !auth.store) {
     req.resume();
-    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' });
+    send(res, 403, { ok: false, error: `${scope === 'agent' ? 'Agent' : scope === 'runner' ? 'Runner' : '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();
@@ -214,7 +216,7 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
     return true;
   }
   const what = revoke ? 'revoke' : 'mint';
-  const request = /** @type {Record<string, unknown>} */ ({ op: what, ...(scope === 'agent' ? { scope } : {}), ...(revoke ? { id: Number(revoke[2]) } : {}) });
+  const request = /** @type {Record<string, unknown>} */ ({ op: what, ...(scope !== 'review' ? { scope } : {}), ...(revoke ? { id: Number(revoke[2]) } : {}) });
   let rowId = null;
   /** @type {{ status: number, body: object }} */
   let out;

package/server/review-tokens.js

@@ -6,9 +6,9 @@
  * (server/agent-api.js). The store over the `review_tokens` table of `cornfield.db` (server/db.js); nothing here knows
  * about HTTP.
  *
- *   - **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
+ *   - **A token has a scope,** `review`, `agent` or `runner`, and is good for the one API its scope names; each API refuses the
+ *     others' tokens (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_…`, an agent token `cf_at_…` and a runner token `cf_nt_…`, 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
@@ -22,7 +22,7 @@
  *
  * Times are ISO strings, as everywhere in the file; `now` is milliseconds and is passed in, so tests need no clock.
  *
- * @typedef {'review' | 'agent'} TokenScope
+ * @typedef {'review' | 'agent' | 'runner'} 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
  */
@@ -30,8 +30,8 @@
 import { createHash, randomBytes } from 'node:crypto';
 
 /** 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_' });
+export const SCOPES = Object.freeze(['review', 'agent', 'runner']);
+export const PREFIXES = Object.freeze({ review: 'cf_rt_', agent: 'cf_at_', runner: 'cf_nt_' });
 /** 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 */
@@ -43,7 +43,7 @@ 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|at)_[A-Za-z0-9_-]{43,128}$/;
+const TOKEN_SHAPE = /^cf_(?:rt|at|nt)_[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, scope, created_at, expires_at, revoked_at, last_used';
@@ -55,6 +55,12 @@ export function hashToken(token) {
   return createHash('sha256').update(String(token)).digest('hex');
 }
 
+/** Which scope a presented token's shape names (by its prefix; the row's `scope` is what counts), or null when it is not shaped like one of ours */
+export function scopeOfShape(token) {
+  if (typeof token !== 'string' || !TOKEN_SHAPE.test(token)) return null;
+  return /** @type {TokenScope} */ (Object.keys(PREFIXES).find((k) => token.startsWith(PREFIXES[k])) ?? null);
+}
+
 /**
  * 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 (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).
@@ -159,6 +165,17 @@ export function listTokens(db, userId, now, scope) {
     .map((row) => ({ ...row, state: stateOf(row, now) }));
 }
 
+/**
+ * Revokes every live token of an owner, of every scope (review, agent, runner): what is done when cornfield learns they no longer maintain the
+ * repo. A token revoked already keeps its first time. Answers how many were revoked.
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} userId
+ * @param {number} now
+ */
+export function revokeOwnerTokens(db, userId, now) {
+  return Number(db.prepare('UPDATE review_tokens SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL').run(iso(now), String(userId)).changes);
+}
+
 /**
  * Revokes one of an owner's tokens, for good. Another owner's id is no token to them. Revoking a token that is
  * revoked already keeps the first time.

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

@@ -25,6 +25,9 @@
  *   *    /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)
@@ -43,9 +46,9 @@
 import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, DEFAULTS, ideaLabel } from '../core/config.js';
+import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, triggersOf, 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';
@@ -53,6 +56,7 @@ 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';
@@ -61,6 +65,7 @@ import { createAuth, signInSettings } from './auth.js';
 import { createHooks, hooksSettings } from './hooks.js';
 import { createLander } from './lander.js';
 import { createSpecPoll } from './spec-poll.js';
+import { createTriggers } from './triggers.js';
 
 export const CORNFIELD_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const EXPLORER_DIR = path.join(CORNFIELD_DIR, 'explorer');
@@ -146,8 +151,13 @@ export function createCornfieldServer(config, opts = {}) {
   const auth = createAuth(config, opts);
   // Hooks listed without a secret (or without sign-in) are a startup error, like a half-configured sign-in
   const hookSettings = hooksSettings(config, env, auth.enabled);
-  const hooks = hookSettings
-    ? createHooks({ hooks: config.hooks, secret: hookSettings.secret, fetch: opts.hookFetch, record: (entry) => auth.record(entry), store: auth.store, now: opts.now, publicUrl: config.publicUrl, timer: opts.hookTimer })
+  // Opt-in triggers (agents.on, server/triggers.js) act as the maintainer whose act caused them and read the forge: both need sign-in and a forge
+  const triggerList = triggersOf(config);
+  if (triggerList.length && !auth.enabled) throw new Error('The config says agents.on, but sign-in is not set up. A trigger requests a run as the maintainer whose act caused it, with their own sign-in, so without sign-in nothing would ever fire: set up sign-in (docs/sign-in.md), or remove agents.on.');
+  if (triggerList.length && !(config.forge && hasAdapter(config.forge.type))) throw new Error('The config says agents.on, but there is no forge to ask on. Set up `forge` (docs/config.md#forge), or remove agents.on.');
+  // With triggers and no hook listed, the hooks object has no destination: it is only the moments the triggers subscribe to (and the thread look's memory)
+  const hooks = hookSettings || triggerList.length
+    ? createHooks({ hooks: hookSettings ? config.hooks : [], secret: hookSettings ? hookSettings.secret : randomBytes(32).toString('hex'), fetch: opts.hookFetch, record: (entry) => auth.record(entry), store: auth.store, now: opts.now, publicUrl: config.publicUrl, timer: opts.hookTimer })
     : null;
   hooks?.watchSessions();
   // Landing on approval needs somebody signed in to land as, like the hooks' events: a half-set key is a startup error
@@ -166,6 +176,12 @@ export function createCornfieldServer(config, opts = {}) {
   }
   // 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.');
+  // Triggers subscribe to the hooks' moments and call the runs' own request path; nothing a run produces is wired to them (server/triggers.js)
+  if (runs && hooks && triggerList.length) createTriggers({ config, auth, runs, hooks, now: opts.now });
   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
@@ -249,6 +265,9 @@ 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 });
@@ -256,6 +275,9 @@ 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
+    // …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;