cornfield 0.8.0 → 0.9.0

package/server/db.js

@@ -15,6 +15,9 @@
  *   thread_seen   the (repo, issue, comment) triples whose thread.* hook event was sent, and each thread's last-seen time, so a
  *                 restart sends none twice and a look asks the forge only for what is new (server/hooks.js, server/threads.js);
  *                 a row with `issue = 0` says the repo's threads have been looked at once
+ *   runs          the agent runs cornfield asked for: the request, where it was posted, the latest report, the pull request found for
+ *                 it and when anything last happened (server/agent-runs.js, migration 7); review_tokens also keep a scope
+ *   run_seen      what has been seen of each run (a comment judged, a hook event sent), so a restart sends and judges nothing twice
  *                 sessions also keep a forge refresh token, the access token's expiry and when `session.expiring` was sent (migration 5)
  *
  * The schema is a list of numbered migrations (`MIGRATIONS`); the file's `PRAGMA user_version` is the number of
@@ -148,6 +151,56 @@ export const MIGRATIONS = Object.freeze([
     PRIMARY KEY (repo, issue, comment)
   ) STRICT;
   `,
+  // 7: agent runs (server/agent-runs.js, spec 0005): a table of the runs cornfield asked for, what it has seen of them, and a scope on
+  // the API tokens so one store holds review tokens and agent tokens
+  `
+  ALTER TABLE review_tokens ADD COLUMN scope TEXT NOT NULL DEFAULT 'review' CHECK (scope IN ('review', 'agent'));  -- what the token may call: POST /api/reviews, or POST /api/agent-requests
+
+  CREATE TABLE runs (
+    run_id            TEXT PRIMARY KEY,           -- run-<ulid>, minted with the request
+    repo              TEXT NOT NULL,              -- 'owner/name'
+    kind              TEXT NOT NULL,
+    profile           TEXT,
+    issue             INTEGER,                    -- what the run is about (at least one of the three)
+    proposal          TEXT,
+    thread            INTEGER,
+    target            INTEGER NOT NULL,           -- the issue or pull request the request, and the stop, were posted on
+    comment_id        TEXT NOT NULL DEFAULT '',   -- the request comment; '' while the post is in flight (the row already counts as open)
+    comment_url       TEXT,
+    request           TEXT NOT NULL CHECK (json_valid(request)),   -- the request as posted: no credential in it, ever
+    requested_by      TEXT NOT NULL,
+    requested_by_id   TEXT NOT NULL,
+    requested_at      TEXT NOT NULL,
+    via               TEXT NOT NULL DEFAULT 'dashboard',           -- 'dashboard' | 'api'
+    state             TEXT NOT NULL DEFAULT 'requested' CHECK (state IN ('requested', 'claimed', 'working', 'done', 'failed', 'stopped')),   -- the runner's latest report
+    reported_at       TEXT,
+    reported_by       TEXT,
+    note              TEXT,
+    url               TEXT,
+    tokens            INTEGER,
+    cost              REAL,
+    stop_requested_at TEXT,
+    stop_requested_by TEXT,
+    pull              INTEGER,                    -- the pull request that carries the run's id
+    pull_state        TEXT CHECK (pull_state IS NULL OR pull_state IN ('open', 'merged', 'closed')),
+    pull_url          TEXT,
+    pull_by           TEXT,
+    pull_trusted      INTEGER NOT NULL DEFAULT 0, -- 1 when its author is a runner, a listed agent author or a maintainer: only then does it move the state
+    linked_via        TEXT CHECK (linked_via IS NULL OR linked_via IN ('body', 'commit', 'branch')),
+    branch            TEXT,
+    head_sha          TEXT,
+    checks            TEXT CHECK (checks IS NULL OR checks IN ('success', 'failure', 'running', 'none')),
+    last_activity     TEXT NOT NULL               -- the latest report, push or pull request activity (or the request itself)
+  ) STRICT;
+  CREATE INDEX runs_repo ON runs (repo, requested_at);
+
+  CREATE TABLE run_seen (
+    run_id      TEXT NOT NULL,                    -- '' for what belongs to no run (a pull request's commits already read)
+    key         TEXT NOT NULL,                    -- 'c:<comment>:<n>' a block judged, 'ev:…' a hook event sent, 'commits:<pull>@<sha>'
+    at          TEXT NOT NULL,
+    PRIMARY KEY (run_id, key)
+  ) STRICT;
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

package/server/forge-forgejo.js

@@ -82,6 +82,9 @@ const FILE_STATUS = { added: 'added', copied: 'added', deleted: 'removed', remov
 const toFile = (f) => ({ path: f.filename, status: FILE_STATUS[f.status] || 'modified', previousPath: f.previous_filename || null, additions: f.additions ?? 0, deletions: f.deletions ?? 0 });
 
 /** @returns {import('./forge.js').Comment} */
+/** @returns {import('./forge.js').PullCommit} */
+const toCommit = (c) => ({ sha: String(c.sha ?? ''), message: typeof c.commit?.message === 'string' ? c.commit.message : '' });
+
 const toComment = (c) => ({ id: String(c.id), author: author(c.user), body: c.body ?? '', url: c.html_url, createdAt: c.created_at, updatedAt: c.updated_at });
 
 // A warning does not count as passing, so it stands in the way like a failure
@@ -237,6 +240,10 @@ export function createForgejoForge(forge, { token = null, fetch, apiUrl, timeout
       return (await client.list(`repos/${repo}/pulls/${n}/files?limit=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
+    async pullCommits(n) {
+      return (await client.list(`repos/${repo}/pulls/${n}/commits?limit=${PER_PAGE}`, { what: `the commits of ${pullWhat(n)}` })).map(toCommit);
+    },
+
     async comments(n, { since } = {}) {
       return (await client.list(`repos/${repo}/issues/${n}/comments?limit=${PER_PAGE}${since ? `&since=${enc(since)}` : ''}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
     },

package/server/forge-github.js

@@ -66,6 +66,9 @@ const toPull = (p) => ({
   url: p.html_url, createdAt: p.created_at, updatedAt: p.updated_at, mergedAt: p.merged_at ?? null,
 });
 
+/** @returns {import('./forge.js').PullCommit} */
+const toCommit = (c) => ({ sha: String(c.sha ?? ''), message: typeof c.commit?.message === 'string' ? c.commit.message : '' });
+
 const FILE_STATUS = { added: 'added', copied: 'added', removed: 'removed', renamed: 'renamed', modified: 'modified', changed: 'modified', unchanged: 'modified' };
 /** @returns {import('./forge.js').PullFile} */
 const toFile = (f) => ({ path: f.filename, status: FILE_STATUS[f.status] || 'modified', previousPath: f.previous_filename ?? null, additions: f.additions ?? 0, deletions: f.deletions ?? 0 });
@@ -230,6 +233,10 @@ export function createGitHubForge(forge, { token = null, fetch, apiUrl, timeoutM
       return (await client.list(`repos/${repo}/pulls/${n}/files?per_page=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
+    async pullCommits(n) {
+      return (await client.list(`repos/${repo}/pulls/${n}/commits?per_page=${PER_PAGE}`, { what: `the commits of ${pullWhat(n)}` })).map(toCommit);
+    },
+
     async comments(n, { since } = {}) {
       return (await client.list(`repos/${repo}/issues/${n}/comments?per_page=${PER_PAGE}${since ? `&since=${enc(since)}` : ''}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
     },

package/server/forge.js

@@ -14,6 +14,7 @@
  *   issue(n)                          one issue (not a pull request: that is `not-found`)
  *   searchIssues(words)               the issues whose text holds the words (one page; the forge's search, which can lag a moment)
  *   pullFiles(n)                      the files a pull request changes
+ *   pullCommits(n)                    the commits of a pull request, oldest first: their shas and full messages (a run's trailer may be in one)
  *   comments(n, { since })            the comments on an issue or pull request, oldest first; `since` (an ISO time) only those
  *                                     created or edited after it, which is how a thread is followed without reading it all again
  *   comment(n, body)                  posts one, and answers it
@@ -55,6 +56,7 @@
  * @typedef {{ number: number, title: string, body: string, state: 'open' | 'closed' | 'merged', draft: boolean, author: Author | null, labels: string[], head: { ref: string, sha: string }, base: { ref: string }, url: string, createdAt: string, updatedAt: string, mergedAt: string | null }} Pull
  * @typedef {{ path: string, status: 'added' | 'modified' | 'removed' | 'renamed', previousPath: string | null, additions: number, deletions: number }} PullFile
  * @typedef {{ id: string, author: Author | null, body: string, url: string, createdAt: string, updatedAt: string }} Comment
+ * @typedef {{ sha: string, message: string }} PullCommit
  * @typedef {'queued' | 'running' | 'success' | 'failure' | 'neutral' | 'skipped' | 'cancelled'} CheckState
  * @typedef {{ id: string, name: string, state: CheckState, url: string | null, rerunnable: boolean }} Check
  * @typedef {{ name: string, sha: string, protected: boolean }} Branch
@@ -83,6 +85,7 @@
  *   createPull(pull: { title: string, body: string, head: string, base: string, draft: boolean }): Promise<Pull>,
  *   createIssue(issue: { title: string, body: string, labels?: string[] }): Promise<Issue>,
  *   pullFiles(n: number): Promise<PullFile[]>,
+ *   pullCommits(n: number): Promise<PullCommit[]>,
  *   comments(n: number, opts?: { since?: string }): Promise<Comment[]>,
  *   comment(n: number, body: string): Promise<Comment>,
  *   checks(ref: string): Promise<Check[]>,
@@ -114,7 +117,7 @@ import { ForgeError, FILE_MAX_BYTES } from './forge-http.js';
 export { ForgeError, rateLimitWords } from './forge-http.js';
 
 /** The calls of the interface (spec 0001 section 3, with `pull(n)`), and `rateLimit()`: what the last answer said is left */
-export const FORGE_METHODS = Object.freeze(['me', 'permission', 'issues', 'searchIssues', 'pulls', 'pull', 'issue', 'pullFiles', 'comments', 'comment', 'checks', 'rerun', 'merge', 'runs', 'branches', 'file', 'fileBytes', 'defaultBranch', 'tags', 'tag', 'createReleaseDraft', 'createBranch', 'createFile', 'createPull', 'createIssue', 'rateLimit']);
+export const FORGE_METHODS = Object.freeze(['me', 'permission', 'issues', 'searchIssues', 'pulls', 'pull', 'issue', 'pullFiles', 'pullCommits', 'comments', 'comment', 'checks', 'rerun', 'merge', 'runs', 'branches', 'file', 'fileBytes', 'defaultBranch', 'tags', 'tag', 'createReleaseDraft', 'createBranch', 'createFile', 'createPull', 'createIssue', 'rateLimit']);
 export const PERMISSIONS = Object.freeze(['admin', 'maintain', 'write', 'triage', 'read', 'none']);
 /** A check that has finished and does not stand in the way: success, or one the forge says does not count */
 export const GREEN_STATES = Object.freeze(['success', 'neutral', 'skipped']);
@@ -276,6 +279,7 @@ export function wrap(a, forge) {
       return a.searchIssues(words.trim());
     },
     pullFiles: async (n) => a.pullFiles(number(n)),
+    pullCommits: async (n) => a.pullCommits(number(n)),
     comments: async (n, opts) => {
       if (opts !== undefined && (opts === null || typeof opts !== 'object' || Array.isArray(opts))) throw invalid('The options are an object.');
       const since = opts && opts.since;

package/server/hooks.js

@@ -23,6 +23,11 @@
  *                  what is there and sends nothing; each (repo, thread, comment) is sent once, across restarts (`thread_seen`)
  *   session.expiring  a maintainer's sign-in ends within a day (`watchSessions`, below). Its body is its own:
  *                   `{ 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
+ *   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 }`
  *
  * **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
@@ -46,6 +51,7 @@ import { createHmac, randomUUID } from 'node:crypto';
 import { HOOK_EVENTS } from '../core/config.js';
 import { pullProposals, readPullProposal } from './proposal-pulls.js';
 import { proposalHash } from './reviews.js';
+import { validateRequest } from '../core/agent-contract.js';
 
 /** @typedef {ReturnType<typeof createHooks>} Hooks */
 
@@ -194,6 +200,19 @@ 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 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);
+      if (!checked.ok) throw new Error(checked.error);
+      return JSON.stringify({ event, at: new Date(now()).toISOString(), request: checked.value, actor: p.actor ?? null, mapUrl: publicUrl || null });
+    }
+    // The events of a run (claimed, state, stopRequested, finished) say which run, in what state, and about what
+    if (event.startsWith('run.')) {
+      return JSON.stringify({
+        event, at: new Date(now()).toISOString(), runId: p.runId ?? null, state: p.state ?? null,
+        ...(p.pull != null ? { pull: p.pull } : {}), ...(p.issue != null ? { issue: p.issue } : {}), actor: p.actor ?? null, mapUrl: publicUrl || null,
+      });
+    }
     // A thread's event is only which thread, which comment, who and what it links to: never the words said
     if (event.startsWith('thread.')) {
       const out = { event, at: new Date(now()).toISOString(), thread: p.thread ?? null };

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, ideaLabel } 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';
@@ -158,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;
@@ -198,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) {
@@ -236,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;