@popcorn245/cornfield 0.8.0 → 0.10.0

package/explorer/index.html

@@ -265,6 +265,13 @@
             </div>
           </div>
         </section>
+        <!-- Agent runs (forge-panel.js, runs-model.js): shown on the Agents tab; each run's state, what it is about, links, and Stop -->
+        <section id="forge-runs" class="hx-forge-runs" aria-labelledby="forge-runs-title" hidden>
+          <h3 id="forge-runs-title" class="hx-forge-runs-title">Agent runs</h3>
+          <p id="forge-runs-status" class="hx-forge-meta hx-faint"></p>
+          <p id="forge-runs-note" class="hx-forge-notice" hidden></p>
+          <ul id="forge-runs-list" class="hx-forge-files" aria-label="Runs"></ul>
+        </section>
         <section id="forge-detail" class="hx-forge-detail" aria-label="Selected pull request" hidden></section>
         <ul id="forge-list" class="hx-forge-list" aria-label="Results"></ul>
         <p id="forge-rate" class="hx-forge-rate hx-faint"></p>
@@ -339,6 +346,26 @@
     </div>
   </div>
 
+  <!-- Start an agent (forge-panel.js): kind, profile, a brief, and a confirm step; a modal dialog over a scrim, the focus stays in it -->
+  <div id="agent-start" class="hx-confirm-scrim" hidden>
+    <div class="hx-confirm glass" role="dialog" aria-modal="true" aria-labelledby="agent-start-title" aria-describedby="agent-start-words">
+      <h2 id="agent-start-title" class="hx-confirm-title">Start an agent</h2>
+      <p id="agent-start-about" class="hx-forge-meta"></p>
+      <form id="agent-start-form" class="hx-forge-confirm" novalidate>
+      <label class="hx-forge-field">Kind of run<select id="agent-kind" class="hx-forge-select"></select></label>
+      <label id="agent-profile-field" class="hx-forge-field" hidden>Profile<select id="agent-profile" class="hx-forge-select"></select></label>
+      <label class="hx-forge-field">Brief for the runner<textarea id="agent-brief" class="hx-forge-preview" rows="6" maxlength="20000" spellcheck="true"></textarea></label>
+      <label id="agent-force-field" class="hx-forge-toggle" hidden><input type="checkbox" id="agent-force" /> Ask for another run on purpose</label>
+      <p id="agent-start-words" class="hx-confirm-note"></p>
+      <p id="agent-start-msg" class="hx-forge-msg hx-forge-msg--bad" role="alert" hidden></p>
+      <div class="hx-confirm-actions">
+        <button type="button" class="hx-btn" data-action="agent-start-cancel">Cancel</button>
+        <button type="submit" class="hx-btn hx-btn--approve" id="agent-start-go">Ask the runner</button>
+      </div>
+      </form>
+    </div>
+  </div>
+
   <!-- Review tokens (review-tokens.js): make one (shown once), list them, revoke; a modal dialog over a scrim, the focus stays in it -->
   <div id="tokens-dialog" class="hx-confirm-scrim" hidden>
     <div class="hx-confirm glass" role="dialog" aria-modal="true" aria-labelledby="tokens-title" aria-describedby="tokens-intro">
@@ -354,6 +381,7 @@
       </div>
       <ul id="tokens-list" class="hx-tokens-list" aria-label="Your review tokens"></ul>
       <form id="tokens-form" class="hx-tokens-form" autocomplete="off">
+        <label class="hx-forge-field">Kind of token<select id="tokens-scope" class="hx-forge-select"><option value="review">Review: approve or send back proposals</option><option value="agent">Agent: ask for agent runs (POST /api/agent-requests)</option><option value="runner">Runner: pull, claim and report on runs (GET /api/agent-requests)</option></select></label>
         <label class="hx-forge-field">Label<input id="tokens-label" class="hx-forge-input" type="text" maxlength="60" placeholder="chat bot" /></label>
         <label class="hx-forge-field">Days<input id="tokens-days" class="hx-forge-input" type="text" inputmode="numeric" maxlength="2" aria-describedby="tokens-days-hint" /></label>
         <span id="tokens-days-hint" class="hx-sr-only"></span>

package/explorer/review-tokens-model.js

@@ -25,8 +25,19 @@ const DAY = 24 * 60 * 60 * 1000;
 const HOUR = 60 * 60 * 1000;
 const LABEL = /^[\p{L}\p{N}][\p{L}\p{N} ._:/()-]*$/u;
 
+/** Tokens come in three scopes (server/review-tokens.js): `review` approves proposals, `agent` asks for agent runs, `runner` pulls and reports on them. Each has its own address. */
+export const SCOPES = Object.freeze([['review', 'Review: approve or send back proposals'], ['agent', 'Agent: ask for agent runs'], ['runner', 'Runner: pull, claim and report on runs']]);
+export const tokensUrl = (scope) => (scope === 'agent' ? '/api/agent-tokens' : scope === 'runner' ? '/api/runner-tokens' : TOKENS_URL);
+
+/** What the dialog says a token of this scope is for */
+export function introWords(scope) {
+  if (scope === 'agent') return 'An agent token lets a script or a chat bot ask for an agent run as you (POST /api/agent-requests). It works while you are signed in here and still maintain the repo; it expires, and you can revoke it below.';
+  if (scope === 'runner') return 'A runner token lets your own runner, wherever it runs, list the queued requests, claim one and report on it (GET /api/agent-requests, POST /api/agent-requests/<run>/claim, POST /api/runs/<run>). It reaches nothing else, and works until it expires or you revoke it below, even after you sign out.';
+  return 'A review token lets a script or a chat bot approve or send back a proposal as you (POST /api/reviews). It works while you are signed in here and still maintain the repo; it expires, and you can revoke it below.';
+}
+
 /** The address that revokes token `id` */
-export const revokeUrl = (id) => `${TOKENS_URL}/${encodeURIComponent(String(id))}/revoke`;
+export const revokeUrl = (id, scope = 'review') => `${tokensUrl(scope)}/${encodeURIComponent(String(id))}/revoke`;
 
 /**
  * What the form sends: the label, and the days when they were given. The server checks everything again.

package/explorer/review-tokens.js

@@ -20,12 +20,12 @@
 
 import { escHtml } from './state.js';
 import { announce } from './keyboard.js';
-import { TOKENS_URL, DEFAULT_DAYS, MAX_DAYS, makeRequest, revokeUrl, tokenLine, errorWords } from './review-tokens-model.js';
+import { tokensUrl, introWords, DEFAULT_DAYS, MAX_DAYS, makeRequest, revokeUrl, tokenLine, errorWords } from './review-tokens-model.js';
 
 const $ = (id) => document.getElementById(id);
 let wired = false;
 let now = () => Date.now();
-const ui = { open: false, busy: false, tokens: [], loaded: false, message: null };
+const ui = { open: false, busy: false, tokens: [], loaded: false, message: null, scope: 'review' };
 
 const dialog = () => $('tokens-dialog');
 
@@ -51,13 +51,15 @@ function paint() {
   if (!dialog()) return;
   const list = $('tokens-list');
   if (!ui.loaded) list.innerHTML = '<li class="hx-faint">Loading …</li>';
-  else if (!ui.tokens.length) list.innerHTML = '<li class="hx-faint">You have no review tokens yet.</li>';
+  else if (!ui.tokens.length) list.innerHTML = `<li class="hx-faint">You have no ${ui.scope} tokens yet.</li>`;
   else {
     list.innerHTML = ui.tokens.map((t) => {
       const line = tokenLine(t, now());
       return `<li class="hx-tokens-item" data-state="${line.state}"><span class="hx-tokens-label">${escHtml(line.label)}</span> <span class="hx-tokens-meta hx-faint">${escHtml(line.status)} · ${escHtml(line.used)}</span> ${line.canRevoke ? `<button type="button" class="hx-btn hx-btn--quiet" data-revoke="${escHtml(String(line.id))}" aria-label="Revoke ${escHtml(line.label)}"${ui.busy ? ' disabled' : ''}>Revoke</button>` : ''}</li>`;
     }).join('');
   }
+  const intro = $('tokens-intro');
+  if (intro) intro.textContent = introWords(ui.scope);
   const msg = $('tokens-msg');
   msg.hidden = !ui.message;
   msg.textContent = ui.message ? ui.message.text : '';
@@ -66,7 +68,7 @@ function paint() {
 }
 
 async function load() {
-  const res = await request('GET', TOKENS_URL);
+  const res = await request('GET', tokensUrl(ui.scope));
   if (res.ok && Array.isArray(res.body.tokens)) {
     ui.tokens = res.body.tokens;
     ui.loaded = true;
@@ -92,7 +94,7 @@ async function make(e) {
   clearSecret();
   ui.busy = true;
   say('');
-  const res = await request('POST', TOKENS_URL, checked.body);
+  const res = await request('POST', tokensUrl(ui.scope), checked.body);
   ui.busy = false;
   if (!res.ok || typeof res.body.secret !== 'string') { say(errorWords(res.status, res.body), false); return; }
   // The one time the secret is seen: in the field, and not in a live region
@@ -110,7 +112,7 @@ async function revoke(id) {
   if (ui.busy) return;
   ui.busy = true;
   paint();
-  const res = await request('POST', revokeUrl(id), {});
+  const res = await request('POST', revokeUrl(id, ui.scope), {});
   ui.busy = false;
   if (!res.ok) say(errorWords(res.status, res.body), false);
   else say(`Revoked "${res.body.token.label}". It no longer works.`);
@@ -203,6 +205,8 @@ export function initReviewTokens(config, opts = {}) {
     dialog().addEventListener('click', onClick);
     dialog().addEventListener('keydown', onKey);
     $('tokens-form').addEventListener('submit', make);
+    const scope = $('tokens-scope');
+    if (scope) scope.addEventListener('change', () => { ui.scope = scope.value === 'agent' || scope.value === 'runner' ? scope.value : 'review'; ui.loaded = false; ui.tokens = []; clearSecret(); paint(); load(); });
   }
   return true;
 }
@@ -212,5 +216,7 @@ export function resetReviewTokensForTests(clock = () => Date.now()) {
   if (ui.open) closeTokens({ restoreFocus: false });
   wired = false;
   now = clock;
-  Object.assign(ui, { open: false, busy: false, tokens: [], loaded: false, message: null });
+  Object.assign(ui, { open: false, busy: false, tokens: [], loaded: false, message: null, scope: 'review' });
+  const scope = $('tokens-scope');
+  if (scope) scope.value = 'review';
 }

package/explorer/runs-model.js

@@ -0,0 +1,107 @@
+/**
+ * @module explorer/runs-model
+ *
+ * Agent runs in the issues and PRs panel, the pure half (issue #80, spec 0005): no DOM, no `window`, no clock. It words what the server
+ * (server/agent-runs.js, server/agent-api.js) answers, and makes the body of a start. cornfield only asks: a run is a request on the
+ * forge, the runner does the work, and these words say so.
+ */
+
+import { relativeTime } from './review-model.js';
+
+export const RUNS_URL = '/api/agent-runs';
+export const runsUrl = (follow) => (follow ? `${RUNS_URL}?follow=1` : RUNS_URL);
+export const stopUrl = (runId) => `${RUNS_URL}/${encodeURIComponent(runId)}/stop`;
+
+/** The kinds of run (the contract's), and what each asks the runner for */
+export const KINDS = Object.freeze([
+  ['code', 'Code: a branch and a pull request'],
+  ['summary', 'Summary of the conversation'],
+  ['brief', 'A brief for another run'],
+  ['proposal', 'A proposal drafted from the thread'],
+]);
+
+/** What a run is about, in words: "issue #12", "proposal 0040-meals" */
+export function aboutWords(refs) {
+  const out = [];
+  if (refs && refs.issue != null) out.push(`issue #${refs.issue}`);
+  if (refs && refs.thread != null && refs.thread !== refs.issue) out.push(`thread #${refs.thread}`);
+  if (refs && refs.proposal != null) out.push(`proposal ${refs.proposal}`);
+  return out.join(' and ') || 'nothing';
+}
+
+/** The state of a run, said short */
+export function statusWords(run) {
+  const words = {
+    requested: 'Requested', claimed: 'Claimed', working: 'Working', done: 'Done', failed: 'Failed', stopped: 'Stopped',
+    'stop-requested': 'Stop requested', quiet: 'Quiet', merged: 'Merged', closed: 'Closed',
+  };
+  return words[run.status] || run.status;
+}
+
+/** Why a state is what it is, for people who ask: one line under the state */
+export function statusWhy(run) {
+  switch (run.status) {
+    case 'quiet': return 'Nothing reported or pushed for a while, so it no longer counts toward the limit. A report or a push brings it back.';
+    case 'stop-requested': return `${run.stopRequested && run.stopRequested.by ? run.stopRequested.by : 'A maintainer'} asked it to stop. The runner decides what that means; this stays until it says stopped, or the run goes quiet.`;
+    case 'requested': return 'Waiting for a runner to pick it up. cornfield only asks; it starts nothing.';
+    default: return '';
+  }
+}
+
+/** A line of facts: who asked and when, the profile, the limits asked for beside what the runner reported */
+export function runMeta(run, nowMs) {
+  const parts = [`asked ${relativeTime(run.requestedAt, nowMs)} by ${run.requestedBy}`];
+  if (run.profile) parts.push(`profile ${run.profile}`);
+  const l = run.limits || {};
+  const limits = [l.minutes != null && `${l.minutes} min`, l.turns != null && `${l.turns} turns`, l.cost != null && `cost ${l.cost}`].filter(Boolean);
+  if (limits.length) parts.push(`limits ${limits.join(', ')}`);
+  const r = run.report;
+  if (r) {
+    const said = [r.tokens != null && `${r.tokens} tokens`, r.cost != null && `cost ${r.cost}`].filter(Boolean);
+    if (said.length) parts.push(`reported ${said.join(', ')}`);
+  }
+  if (run.checks && run.checks !== 'none') parts.push(`checks ${run.checks === 'success' ? 'passing' : run.checks === 'failure' ? 'failing' : 'running'}`);
+  return parts.join(' · ');
+}
+
+/** Whether a Stop is offered: the run is open and nobody has asked it to stop yet */
+export const canStop = (run) => run.open === true && !run.stopRequested;
+
+/** The summary line over the list: "2 open of 3 allowed, 5 runs" */
+export function runsStatus(data) {
+  const n = data.runs.length;
+  return `${data.open} open of ${data.maxOpen} allowed, ${n} ${n === 1 ? 'run' : 'runs'}`;
+}
+
+/**
+ * The body of a start. Only what the person chose; the server writes the run id, the time and who asked, and checks the rest.
+ * @param {{ kind: string, profile?: string, brief?: string, refs: object, force?: boolean }} input
+ */
+export function startBody({ kind, profile, brief, refs, force }) {
+  const out = { kind, refs, brief: (brief || '').trim() };
+  if (profile) out.profile = profile;
+  if (force) out.force = true;
+  return out;
+}
+
+/** What a start came to, in words */
+export function startWords(status, body) {
+  if (status === null) return 'cornfield did not answer; nothing was asked.';
+  if (status === 401) return 'Your sign-in has ended. Sign in again to start an agent.';
+  if (body && body.ok) return `Asked. The request is posted on the forge as run ${body.request.runId}; a runner picks it up from there.`;
+  return (body && body.error) || `The request was refused (${status}).`;
+}
+
+/** What a stop came to */
+export function stopWords(status, body, runId) {
+  if (status === null) return 'cornfield did not answer; nothing was asked.';
+  if (status === 401) return 'Your sign-in has ended. Sign in again to stop a run.';
+  if (body && body.ok) return `Asked ${runId} to stop. The runner decides what that means.`;
+  return (body && body.error) || `The stop was refused (${status}).`;
+}
+
+/** What the dialog tells the person before they confirm: where the request goes and what it does and does not do */
+export function confirmStartWords(refs, forgeName) {
+  const where = refs.proposal != null ? `the spec pull request of proposal ${refs.proposal}` : refs.thread != null ? `thread #${refs.thread}` : `issue #${refs.issue}`;
+  return `This posts a request as a comment on ${where} on ${forgeName}, as you. Your runner picks it up. cornfield starts nothing and sends no credentials.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcorn245/cornfield",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "A self-hostable dev dashboard with the topology map at its centre: proposals on the map, scenarios, outages and what-if edits, for any repo.",
   "license": "MIT",
   "author": "popcorn245 (https://github.com/popcorn245)",

package/server/agent-api.js

@@ -0,0 +1,228 @@
+/**
+ * @module server/agent-api
+ *
+ * The routes that ask for agent runs and show them (issue #80, spec 0005 D10; the engine is server/agent-runs.js).
+ *
+ *   POST /api/agent-requests             { kind, refs, profile?, brief?, branch?, limits?, nodes?, force? }, with `Authorization: Bearer cf_at_…`
+ *   GET  /api/agent-requests             the queue, for a runner token: server/runner-api.js (and the pull transport's claim and report routes)
+ *   GET  /api/agent-tokens               the signed-in maintainer's agent tokens (and POST, and /<id>/revoke: server/review-api.js)
+ *   GET  /api/agent-runs[?follow=1]      the runs, newest first, with the cap and how many are open; `follow=1` looks at the forge first
+ *   GET  /api/agent-runs/<runId>         one run
+ *   POST /api/agent-runs                 the dashboard's Start an agent: the same body as the API
+ *   POST /api/agent-runs/<runId>/stop    { note? } asks the runner to stop
+ *
+ * **The call takes an agent token and nothing else,** exactly as the review API takes a review token (server/review-api.js): it runs
+ * before the sign-in guard (a script has no cookie), reads no cookie, needs no same-origin check (a browser never adds an `Authorization`
+ * header itself), and keeps the `Host` check in front of every route. **The two scopes are kept apart:** a review token on this route is 403
+ * (and an agent token on `POST /api/reviews` is 403, and a runner token on either), whatever else is true of it. Token states, the anonymous flood ceiling and the rows
+ * in `actions` are the review API's, under the action `agent-request`:
+ *
+ *   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 token                      403, under its owner
+ *   a token that is revoked or expired  403, under its owner
+ *   a live agent token                  whatever `runs.request` answers: 201 with the run, or 400, 401, 403, 404, 409, 429, 502
+ *
+ * The request is made **as the token's owner**: the forge is asked now who that is and whether they still maintain the repo (a demoted owner
+ * is 403), and the request comment is posted with their own kept sign-in (`auth.forgeForUser`; without a live one, 401). `requestedBy` is
+ * theirs and is never taken from the body. A body that carries a credential, by key or by value, is 400 and nothing is posted.
+ *
+ * The `/api/agent-runs` routes are the signed-in maintainer's, behind the sign-in guard like every other action. The POSTs take a request
+ * from cornfield's own page only (`sameOrigin`) with a JSON body and count toward the flood ceiling (server/throttle.js); a token is no way
+ * to them (the guard reads cookies, never `Authorization`). They post with the session's own forge token (`auth.forgeFor`).
+ */
+
+import { isRunId } from '../core/agent-contract.js';
+import { sameOrigin, readBody } from './proposals.js';
+import { ANONYMOUS_PER_MINUTE, NO_TOKEN_LOGIN } from './review-api.js';
+import { bearerOf, findToken, touchToken } from './review-tokens.js';
+import { refusal } from './submit-review.js';
+import { Refused, countAttempt } from './throttle.js';
+import { ForgeError } from './forge.js';
+
+export const REQUESTS_PATH = '/api/agent-requests';
+export const RUNS_PATH = '/api/agent-runs';
+/** A request's body, in bytes: a brief of the contract's size, with room */
+export const REQUEST_LIMIT = 96 * 1024;
+const STOP_LIMIT = 8 * 1024;
+const HEADERS = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' };
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { ...HEADERS, ...headers });
+  res.end(JSON.stringify(body));
+}
+
+/** 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);
+  return { status: 500, body: { error: 'Something went wrong in cornfield; the log says what.', code: 'unavailable' }, headers: {} };
+}
+
+/** A JSON object from a body text, or a `problem` the engine refuses with a row */
+function parseBody(body, what) {
+  if (body.tooLarge) return { problem: { status: 413, message: `${what} is too large.` } };
+  try {
+    return { body: JSON.parse(body.text) };
+  } catch {
+    // Not the parser's words: they quote the body, which a row would then keep (a credential pasted in by mistake)
+    return { problem: { status: 400, message: 'The body is not valid JSON.' } };
+  }
+}
+
+/** @typedef {{ config: any, auth: any, runs: import('./agent-runs.js').Runs | null, now?: () => number, publicHost?: string | null }} AgentContext */
+
+/**
+ * `POST /api/agent-requests`. The caller has found the path to be this one; this runs before the sign-in guard.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {AgentContext} ctx
+ */
+export async function serveAgentCall(req, res, ctx) {
+  const { config, auth, runs } = ctx;
+  const now = ctx.now ?? Date.now;
+  if (!auth.enabled || !runs) {
+    req.resume();
+    return send(res, 403, { ok: false, error: 'Agent tokens need sign-in and a forge: set them up first (docs/sign-in.md, docs/config.md#forge).', code: 'forbidden' });
+  }
+  if (req.method !== 'POST') {
+    req.resume();
+    return send(res, 405, { ok: false, error: 'A run is asked for with POST (an agent token); a runner lists the queue with GET (a runner token).', code: 'invalid' }, { Allow: 'GET, HEAD, POST' });
+  }
+  const repo = config.forge.repo;
+  const audit = async (login, request, status, body) => {
+    try {
+      await auth.record({ login, action: 'agent-request', target: repo, request: { via: 'api', ...request }, status, answer: { error: body.error, code: body.code } });
+    } catch (err) {
+      console.error(`[cornfield] a refused agent request could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+    }
+  };
+
+  const presented = bearerOf(req.headers.authorization);
+  const db = presented ? await auth.store() : null;
+  const found = presented && db ? findToken(db, presented, now(), 'agent') : 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);
+    const body = { error: 'An agent token is needed: send "Authorization: Bearer cf_at_…". A token is made in the dashboard; a sign-in is not taken in its place.', code: 'unauthorized' };
+    await audit(NO_TOKEN_LOGIN, { reason: presented ? 'unknown-token' : 'no-token' }, 401, body);
+    return send(res, 401, { ok: false, ...body }, { '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';
+    const body = {
+      error: wrong ? `This is ${row.scope === 'agent' ? 'an' : 'a'} ${row.scope} token. Asking for a run takes an agent token; make one in the dashboard.`
+        : state === 'revoked' ? 'This agent token was revoked; make a new one in the dashboard.' : 'This agent token has expired; make a new one in the dashboard.',
+      code: 'forbidden',
+    };
+    await audit(row.login, { reason: wrong ? 'wrong-scope' : state, token, ...(wrong ? { scope: row.scope } : {}) }, 403, body);
+    return send(res, 403, { ok: false, ...body });
+  }
+  touchToken(/** @type {import('node:sqlite').DatabaseSync} */ (db), row.id, now());
+
+  let input;
+  try {
+    input = parseBody(await readBody(req, REQUEST_LIMIT), 'A request');
+  } catch {
+    input = { problem: { status: 400, message: 'The request could not be read.' } };
+  }
+  try {
+    const made = await runs.request({
+      forge: () => auth.forgeForUser(row.user_id), who: { login: row.login, userId: row.user_id }, limits: { auth, now: ctx.now }, via: { token },
+      stillAllowed: async () => {
+        const again = findToken(await auth.store(), /** @type {string} */ (presented), now(), 'agent');
+        if (again && again.state === 'active') return null;
+        return again && again.state === 'expired' ? 'This agent token expired while the request was being checked; nothing was posted.' : 'This agent token was revoked while the request was being checked; nothing was posted.';
+      },
+    }, input);
+    return send(res, 201, { ok: true, ...made });
+  } catch (err) {
+    const out = answerFor(err);
+    return send(res, out.status, { ok: false, ...out.body }, out.headers);
+  }
+}
+
+/**
+ * The `/api/agent-runs` routes. The caller has passed the sign-in guard, so `session` is a maintainer's.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} reqPath
+ * @param {AgentContext & { session: { login: string, userId: string } | null }} ctx
+ * @returns {Promise<boolean>} whether the path was one of these
+ */
+export async function serveRunRoutes(req, res, reqPath, ctx) {
+  const m = /^\/api\/agent-runs(?:\/(run-[0-9A-Za-z]{26}))?(\/stop)?$/.exec(reqPath);
+  if (!m || (m[2] && !m[1])) return false;
+  const { auth, runs, session } = ctx;
+  const runId = m[1] ?? null;
+  const allow = m[2] ? 'POST' : runId ? 'GET, HEAD' : 'GET, HEAD, POST';
+  if (!allow.split(', ').includes(req.method || '')) {
+    req.resume();
+    send(res, 405, { ok: false, error: 'Method not allowed.', code: 'invalid' }, { Allow: allow });
+    return true;
+  }
+  if (!session || !auth.store || !runs) {
+    req.resume();
+    send(res, 403, { ok: false, error: 'Agent runs belong to a signed-in maintainer on a repo with a forge: set up sign-in first (docs/sign-in.md).', code: 'forbidden' });
+    return true;
+  }
+
+  if (req.method === 'GET' || req.method === 'HEAD') {
+    req.resume();
+    if (runId) {
+      const run = isRunId(runId) ? await runs.get(runId) : null;
+      send(res, run ? 200 : 404, run ? { ok: true, run } : { ok: false, error: 'cornfield has no such run.', code: 'not-found' });
+      return true;
+    }
+    // Refresh: look at the forge first, as the person asking, so the list is as of now (never an error: the list is still the list)
+    const url = new URL(req.url || '/', 'http://localhost');
+    if (url.searchParams.get('follow') === '1') {
+      try {
+        await runs.follow(auth.forgeFor(session));
+      } catch (err) {
+        console.error(`[cornfield] agent runs: the dashboard's look at the forge could not begin: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+    send(res, 200, { ok: true, ...(await runs.list()) });
+    return true;
+  }
+
+  // A change: from cornfield's own page, as JSON; the engine counts the flood first and writes a row for everything after
+  const ask = { forge: () => auth.forgeFor(session), who: { login: session.login, userId: session.userId }, limits: { auth, now: ctx.now } };
+  let problem;
+  let body = {};
+  if (!sameOrigin(req, ctx.publicHost ?? null)) {
+    req.resume();
+    problem = { status: 403, message: 'Do this from cornfield\'s own page.' };
+  } else if (!/^application\/json(?:\s*;|$)/i.test(String(req.headers['content-type'] || ''))) {
+    req.resume();
+    problem = { status: 415, message: 'Send the request as JSON (Content-Type: application/json).' };
+  } else {
+    try {
+      const parsed = parseBody(await readBody(req, runId ? STOP_LIMIT : REQUEST_LIMIT), 'The request');
+      if (parsed.problem) problem = parsed.problem;
+      else body = parsed.body;
+    } catch {
+      problem = { status: 400, message: 'The request could not be read.' };
+    }
+  }
+  if (runId && !problem && (body === null || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some((k) => k !== 'note'))) problem = { status: 400, message: 'A stop request is { note? }.' };
+  try {
+    if (runId) {
+      const stopped = await runs.stop(ask, { runId, note: /** @type {any} */ (body)?.note, problem });
+      send(res, 200, { ok: true, ...stopped });
+    } else {
+      const made = await runs.request(ask, { body, problem });
+      send(res, 201, { ok: true, ...made });
+    }
+  } catch (err) {
+    const out = answerFor(err);
+    send(res, out.status, { ok: false, ...out.body }, out.headers);
+  }
+  return true;
+}