@popcorn245/cornfield 0.7.0 → 0.9.0

package/server/db.js

@@ -12,6 +12,12 @@
  *   hook_seen     the (pull request, head, proposal) triples whose `spec.ready` event was sent, so a restart sends none twice;
  *                 a row with `pr = 0` says the repo has been looked at once (server/hooks.js)
  *   landings      the spec PRs an approval is waiting to land (`proposals.approveLands`), so a restart picks them up (server/lander.js)
+ *   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
@@ -133,6 +139,68 @@ export const MIGRATIONS = Object.freeze([
   ALTER TABLE sessions ADD COLUMN token_expires_at TEXT;                   -- when the access token stops working; NULL when it does not expire
   ALTER TABLE sessions ADD COLUMN expiring_sent_at TEXT;                   -- when the \`session.expiring\` hook event was sent; NULL before
   `,
+  // 6: threads (server/threads.js, server/hooks.js): which comments of a thread have been announced. The thread itself is the
+  // forge's (an issue's comments, or a spec PR's conversation); this only remembers what was told, never what was said
+  `
+  CREATE TABLE thread_seen (
+    repo        TEXT NOT NULL,                  -- 'owner/name'
+    issue       INTEGER NOT NULL,               -- the issue or pull request number of the thread; 0 with comment '' says the repo has been looked at once
+    comment     TEXT NOT NULL,                  -- '' the thread itself (opened); a comment's id (message); 'link:<id>' or 'link:body' (linked); 'pr:<n>' a spec PR that names the thread
+    stamp       TEXT NOT NULL DEFAULT '',       -- the forge's own time: the comment's last edit, or (on the '' row) the thread's last update when it was looked at
+    at          TEXT NOT NULL,                  -- when cornfield first saw it
+    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-actions.js

@@ -37,11 +37,17 @@
  * (server/db.js), begun before anything is asked of the forge and finished with the answer after (`auth.begin`,
  * `auth.finish`). Without an audit to write to nothing is done.
  *
+ * One more write is not about a pull request: **a new idea** (docs/threads.md), `POST /api/forge/threads { title, body }`, which opens an issue
+ * with the threads label as the signed-in maintainer (`serveIdea`, below). It goes through the same doors, in the same order:
+ * POST, signed in, the flood ceiling, an audit row begun, same origin, JSON (here up to 32 KB), not twice, the permission asked of
+ * the forge now. The row keeps the title and the text's length, never the text. It only adds: an issue, and on Forgejo the
+ * threads label first when the repo lacks it (the answer, and so the row, says `labelsMade`).
+ *
  * A pull request lands by the config's `forge.mergeMethod` (`merge`, `squash` or `rebase`; `merge` when unset), the way
  * the repo lands its pull requests; the forge refuses a method the repo does not allow, in its own words.
  */
 
-import { ForgeError, RERUN_STATES, canRerun, isMaintainer } from './forge.js';
+import { ForgeError, RERUN_STATES, canRerun, isMaintainer, hasAdapter } from './forge.js';
 import { sameOrigin } from './proposals.js';
 import { planSpec, planBuild, startSpec, openBuildIssue } from './pipeline.js';
 import { PROPOSAL_FILE } from './files.js';
@@ -50,19 +56,22 @@ import { Refused, throttle, countAttempt } from './throttle.js';
 // The limits live in server/throttle.js (reviews share them); these are re-exported for the callers that always had them here
 export { COOLDOWN_MS, PER_MINUTE, ATTEMPTS_PER_MINUTE, countAttempt } from './throttle.js';
 import { proposalPayload, landedPayload } from './hooks.js';
+import { ideaInput, createIdea, threadsOff } from './threads.js';
 
 /** A request body is a sha and a check's id */
 const MAX_BODY = 4096;
+/** A new idea's request: a title and a text of up to 20,000 characters, in JSON (any of it may be escaped) */
+const IDEA_BODY = 96 * 1024;
 
 const STATUS = { unauthorized: 401, forbidden: 403, 'not-found': 404, conflict: 409, invalid: 400, 'rate-limited': 429, unavailable: 502, 'not-green': 409, 'too-large': 413 };
 const SHA = /^[0-9a-f]{7,64}$/i;
 const DIGEST = /^[0-9a-f]{32}$/;
 /** What each action is called in the words of a refusal, and what it asks of the person */
-const DOING = { merge: 'Landing', rerun: 'Re-running', spec: 'Starting a spec', build: 'Opening the build issue' };
-const ONLY_MAINTAINERS = { merge: 'land pull requests or re-run checks', rerun: 'land pull requests or re-run checks', spec: 'start specs', build: 'open build issues' };
+const DOING = { merge: 'Landing', rerun: 'Re-running', spec: 'Starting a spec', build: 'Opening the build issue', idea: 'Opening an idea' };
+const ONLY_MAINTAINERS = { merge: 'land pull requests or re-run checks', rerun: 'land pull requests or re-run checks', spec: 'start specs', build: 'open build issues', idea: 'open ideas' };
 
 /** Reads a small JSON object body, or refuses */
-function readJson(req) {
+function readJson(req, max = MAX_BODY) {
   return new Promise((resolve, reject) => {
     if (!/^application\/json(?:\s*;|$)/i.test(String(req.headers['content-type'] || ''))) {
       req.resume();
@@ -75,7 +84,7 @@ function readJson(req) {
     req.on('data', (c) => {
       if (over) return;
       size += c.length;
-      if (size <= MAX_BODY) { chunks.push(c); return; }
+      if (size <= max) { chunks.push(c); return; }
       // Too large: answered now, and the rest is not read (the connection closes once the answer is sent)
       over = true;
       req.pause();
@@ -289,3 +298,95 @@ export async function serveAction(req, res, what, ctx, send) {
   if (closeAfter) res.on('finish', () => req.destroy());
   send(out.status, out.body, out.headers);
 }
+
+/**
+ * POST /api/forge/threads { title, body }: a new idea, an issue with the threads label, opened as the signed-in maintainer. The
+ * caller has found the path and the method to be this; every refusal is in words and written down, as in `serveAction`.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ config: any, session: { login: string, userId: string } | null, auth: { store: null | (() => Promise<import('node:sqlite').DatabaseSync>), forgeFor: Function, begin: Function, finish: Function }, now?: () => number, publicHost?: string | null }} ctx
+ * @param {(status: number, body: object, headers?: object) => void} send
+ */
+export async function serveIdea(req, res, ctx, send) {
+  const { config, session, auth, now = Date.now } = ctx;
+  if (!config.forge || !hasAdapter(config.forge.type)) {
+    req.resume();
+    return send(config.forge ? 501 : 404, { ok: false, error: config.forge ? `cornfield has no adapter for the forge type ${JSON.stringify(config.forge.type)} yet.` : 'No forge is configured: set `forge` in cornfield.config.js.', code: config.forge ? 'unavailable' : 'not-found' });
+  }
+  if (threadsOff(config)) {
+    req.resume();
+    return send(404, { ok: false, error: 'Threads are off in this config (threads: false).', code: 'not-found' });
+  }
+  if (!session || !auth.store) {
+    req.resume();
+    return send(403, { ok: false, error: `${DOING.idea} is done as the signed-in maintainer: set up sign-in first (docs/sign-in.md).`, code: 'forbidden' });
+  }
+  const flood = countAttempt(ctx, session.userId, now());
+  if (flood) {
+    req.resume();
+    return send(flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+  }
+  const target = config.forge.repo;
+  /** @type {Record<string, unknown>} */
+  const request = { action: 'idea' };
+  let rowId = null;
+  let closeAfter = false;
+  let release = () => {};
+  /** @type {{ status: number, body: object, headers?: object, forgeStatus?: number | null }} */
+  let out;
+  try {
+    try {
+      rowId = await auth.begin({ login: session.login, action: 'idea', target, request });
+    } catch (err) {
+      console.error(`[cornfield] the audit row of idea ${target} could not be written: ${err instanceof Error ? err.message : err}`);
+      throw new Refused(503, 'cornfield cannot write its audit log, so it will not act on the forge.', 'unavailable');
+    }
+    if (!sameOrigin(req, ctx.publicHost ?? null)) {
+      req.resume();
+      throw new Refused(403, 'Do this from cornfield\'s own page.', 'forbidden');
+    }
+    let asked;
+    try {
+      asked = await readJson(req, IDEA_BODY);
+    } catch (err) {
+      closeAfter = Boolean(err && err.closeAfter);
+      throw err;
+    }
+    let idea;
+    try {
+      idea = ideaInput(asked);
+    } catch (err) {
+      throw new Refused(400, err instanceof Error ? err.message : 'That is not an idea.', 'invalid');
+    }
+    // The audit keeps what was asked for, not the words: the title, and how long the text was
+    request.title = idea.title;
+    request.bodyLength = idea.body.length;
+    release = throttle(ctx, session.userId, `idea|${idea.title.toLowerCase().slice(0, 80)}`, now());
+    const forge = auth.forgeFor(session);
+    await assertMaintainerNow(forge, session, config, 'idea');
+    const issue = await createIdea(forge, config, idea);
+    await forgetKept(auth, config);
+    // A label the forge did not have yet and that cornfield made for it (Forgejo) is part of the answer, and so of the audit row
+    out = { status: 201, body: { ok: true, action: 'idea', created: true, number: issue.number, issue: { number: issue.number, title: issue.title, url: issue.url }, ...(issue.labelsMade ? { labelsMade: issue.labelsMade } : {}) } };
+  } catch (err) {
+    if (err instanceof Refused) out = { status: err.status, body: { ok: false, error: err.message, code: err.code }, headers: err.headers };
+    else if (err instanceof ForgeError) {
+      const wait = err.rateLimit && err.rateLimit.retryAfter != null ? { 'Retry-After': String(Math.ceil(err.rateLimit.retryAfter)) } : {};
+      out = { status: STATUS[err.code] || 502, body: { ok: false, error: err.message, code: err.code }, headers: wait, forgeStatus: err.status ?? (err.code === 'unavailable' ? null : STATUS[err.code] || null) };
+    } else {
+      out = { status: 500, body: { ok: false, error: 'Something went wrong in cornfield; the log says what.', code: 'unavailable' } };
+      console.error(`[cornfield] idea ${target}: ${err instanceof Error ? err.stack || err.message : err}`);
+    }
+  } finally {
+    release();
+  }
+  if (rowId !== null) {
+    try {
+      await auth.finish(rowId, { target, request, status: 'forgeStatus' in out ? out.forgeStatus ?? null : out.status, answer: out.body });
+    } catch (err) {
+      console.error(`[cornfield] the audit row of idea ${target} could not be finished: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  if (closeAfter) res.on('finish', () => req.destroy());
+  send(out.status, out.body, out.headers);
+}

package/server/forge-forgejo.js

@@ -9,7 +9,8 @@
  *   - **Permission.** Forgejo has three levels, so a repo's people are `admin`, `write` or `read` and never
  *     `maintain` or `triage`; its admins are cornfield's. The signed-in user's own comes from the repo itself
  *     (`permissions`); anyone else's from the collaborator endpoint, which only a repo admin may ask (else 403).
- *   - **Issues.** `type=issues` leaves the pull requests out.
+ *   - **Issues.** `type=issues` leaves the pull requests out. A new issue's labels are given as ids (Forgejo's API takes no names),
+ *     so each is looked up and made when the repo lacks it.
  *   - **Checks.** Forgejo Actions reports each job as a commit status, so the commit's statuses are all the checks
  *     there are. Its API cannot re-run one: none is `rerunnable`.
  *   - **Runs.** `actions/runs` (Forgejo 11 and later, Gitea 1.24 and later), where Actions is on for the repo; an older
@@ -81,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
@@ -142,6 +146,17 @@ export function createForgejoForge(forge, { token = null, fetch, apiUrl, timeout
     return meOnce;
   };
 
+  /**
+   * The id of the repo's label called `name`, making the label (plain grey) when it is not there: `{ id, made }`. Only
+   * `createIssue` calls this, so a label is only ever made on a write the maintainer asked for, never on a read.
+   */
+  async function labelId(name) {
+    const have = (await client.list(`repos/${repo}/labels?limit=${PER_PAGE}`, { what: `the labels of ${forge.repo}` })).find((l) => typeof l.name === 'string' && l.name.toLowerCase() === name.toLowerCase());
+    if (have) return { id: have.id, made: false };
+    const { body } = await client.request('POST', `repos/${repo}/labels`, { body: { name, color: '#ededed' }, what: `the label ${name} in ${forge.repo}` });
+    return { id: body.id, made: true };
+  }
+
   return {
     me,
 
@@ -208,16 +223,29 @@ export function createForgejoForge(forge, { token = null, fetch, apiUrl, timeout
       return toPull((await client.request('POST', `repos/${repo}/pulls`, { body: { title: draft ? `WIP: ${title}` : title, body, head, base }, what: `a pull request in ${forge.repo}` })).body);
     },
 
-    async createIssue({ title, body }) {
-      return toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body }, what: `an issue in ${forge.repo}` })).body);
+    async createIssue({ title, body, labels = [] }) {
+      // Forgejo takes label ids, not names: each is looked up, and made when the repo lacks it; the issue says which were made
+      const ids = [];
+      const made = [];
+      for (const name of labels) {
+        const label = await labelId(name);
+        ids.push(label.id);
+        if (label.made) made.push(name);
+      }
+      const issue = toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body, ...(ids.length ? { labels: ids } : {}) }, what: `an issue in ${forge.repo}` })).body);
+      return made.length ? { ...issue, labelsMade: made } : issue;
     },
 
     async pullFiles(n) {
       return (await client.list(`repos/${repo}/pulls/${n}/files?limit=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
-    async comments(n) {
-      return (await client.list(`repos/${repo}/issues/${n}/comments?limit=${PER_PAGE}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
+    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);
     },
 
     async comment(n, body) {

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 });
@@ -221,16 +224,21 @@ export function createGitHubForge(forge, { token = null, fetch, apiUrl, timeoutM
       return toPull((await client.request('POST', `repos/${repo}/pulls`, { body: { title, body, head, base, draft }, what: `a pull request in ${forge.repo}` })).body);
     },
 
-    async createIssue({ title, body }) {
-      return toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body }, what: `an issue in ${forge.repo}` })).body);
+    async createIssue({ title, body, labels = [] }) {
+      // GitHub makes a label that is not there yet when the label's name comes with a new issue (the user pushes to the repo)
+      return toIssue((await client.request('POST', `repos/${repo}/issues`, { body: { title, body, ...(labels.length ? { labels } : {}) }, what: `an issue in ${forge.repo}` })).body);
     },
 
     async pullFiles(n) {
       return (await client.list(`repos/${repo}/pulls/${n}/files?per_page=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
-    async comments(n) {
-      return (await client.list(`repos/${repo}/issues/${n}/comments?per_page=${PER_PAGE}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
+    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);
     },
 
     async comment(n, body) {

package/server/forge-routes.js

@@ -19,6 +19,10 @@
  *   GET  /api/forge/issues/<n>/spec                                    the plan of step 1: what starting a spec on the issue would make (server/pipeline.js), never kept
  *   GET  /api/forge/pulls/<n>/build?slug=<proposal>                    the plan of step 2: the build issue of an approved proposal, never kept
  *   POST /api/forge/issues/<n>/spec | /pulls/<n>/build                 do them, with the plan's digest (server/forge-actions.js)
+ *   GET /api/forge/threads?state=open|closed|all&limit=100             the threads (docs/threads.md): ideas (issues with the threads label) and spec PRs' conversations,
+ *                                                                      newest activity first, each with the `[[mentions]]` its text holds, as written (404 when `threads: false`)
+ *   GET /api/forge/threads/<n>                                         one thread's messages, as written, to read; replying is on the forge
+ *   POST /api/forge/threads                                            { title, body }: a new idea, an issue with the label, as the maintainer (server/forge-actions.js `serveIdea`)
  *   GET /api/forge/work                                                what the agents view groups: pull requests and issues (any state), branches, open spec PRs, and the config's `agents` rules
  *   GET /api/forge/deploys?limit=100                                   the latest workflow runs that are deploys, each with what the
  *                                                                      config says it restarted (server/deploys.js, docs/deploys.md)
@@ -47,7 +51,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { ForgeError, canRerun, hasAdapter, isMaintainer, isTagName, rateLimitWords } from './forge.js';
-import { actionOf, countAttempt, serveAction } from './forge-actions.js';
+import { actionOf, countAttempt, serveAction, serveIdea } from './forge-actions.js';
+import { listThreads, readThread, snapshotOf, threadsOff } from './threads.js';
+import { ideaLabel } from '../core/config.js';
 import { landingOf, serveLanding } from './lander.js';
 import { planSpec, planBuild, pullSpecs } from './pipeline.js';
 import { listPullProposals } from './proposal-pulls.js';
@@ -133,6 +139,28 @@ function routeOf(reqPath, url, config, where, hooks = null) {
     const mapping = createHash('sha256').update(JSON.stringify(config.deploys || null)).digest('hex').slice(0, 12);
     return { key: `deploys?limit=${limit}&config=${mapping}`, load: async (forge) => ({ items: deploysOf(await forge.runs({ limit }), config.deploys) }) };
   }
+  if (reqPath === '/api/forge/threads' || /^\/api\/forge\/threads\/[1-9]\d{0,8}$/.test(reqPath)) {
+    if (threadsOff(config)) throw new ForgeError('Threads are off in this config (threads: false).', { code: 'not-found' });
+    const label = ideaLabel(config);
+    if (reqPath === '/api/forge/threads') {
+      const q = listQuery(url, false);
+      return {
+        key: `threads?state=${q.state}&limit=${q.limit}&label=${label}`,
+        load: async (forge) => {
+          const found = await listThreads(forge, config, where || config, { state: q.state, limit: q.limit, hooks });
+          // Whatever a look reads is news to the hooks once (thread.opened, thread.message, thread.linked), as the spec PRs are
+          if (hooks) {
+            let nodes = [];
+            try { nodes = readTopology(config)?.nodes || []; } catch { nodes = []; }
+            hooks.threadsSeen(forge.repo, snapshotOf(found.gathered, nodes)).catch(() => {});
+          }
+          return { items: found.items, label, problem: found.problem };
+        },
+      };
+    }
+    const n = Number(reqPath.split('/').pop());
+    return { key: `threads/${n}&label=${label}`, load: async (forge) => ({ thread: await readThread(forge, config, where || config, n) }) };
+  }
   if (reqPath === '/api/forge/work') {
     return {
       key: 'work',
@@ -236,6 +264,10 @@ export async function serveForge(req, res, reqPath, url, ctx) {
     send(req, res, out.status, out.body, out.headers);
     return true;
   }
+  if (reqPath === '/api/forge/threads' && req.method === 'POST') {
+    await serveIdea(req, res, ctx, (status, body, headers) => send(req, res, status, body, headers));
+    return true;
+  }
   const act = actionOf(reqPath);
   if (act) {
     if (!config.forge || !hasAdapter(config.forge.type)) {

package/server/forge.js

@@ -14,7 +14,9 @@
  *   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
- *   comments(n)                       the comments on an issue or pull request, oldest first
+ *   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
  *   checks(ref)                       the checks on a commit (a branch, a tag or a sha)
  *   rerun(check)                      re-runs one that can be (`check.rerunnable`)
@@ -36,7 +38,9 @@
  *   createBranch(name, { from })      a branch at the head of the branch `from` (`conflict` when it exists)
  *   createFile({ branch, path, content, message })   one new file on a branch, as one commit (`invalid` when it exists)
  *   createPull({ title, body, head, base, draft })   a pull request; a draft one is `draft: true` (Forgejo: the "WIP: " title it uses)
- *   createIssue({ title, body })      an issue
+ *   createIssue({ title, body, labels })   an issue; `labels` (names) are put on it, a label the repo lacks is made first (an idea is
+ *                                     an issue with the threads label, docs/threads.md). Where cornfield makes the label itself
+ *                                     (Forgejo), the issue carries `labelsMade: [names]`; GitHub makes it on its own and says nothing
  *
  * An adapter module (server/forge-github.js, server/forge-forgejo.js) implements these at its forge's level, with
  * `mergeAt(n, { sha, method })` in place of `merge`; `wrap` checks the arguments and builds `merge` once for every
@@ -52,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
@@ -78,9 +83,10 @@
  *   createBranch(name: string, opts: { from: string }): Promise<{ name: string, sha: string }>,
  *   createFile(file: { branch: string, path: string, content: string, message: string }): Promise<{ sha: string }>,
  *   createPull(pull: { title: string, body: string, head: string, base: string, draft: boolean }): Promise<Pull>,
- *   createIssue(issue: { title: string, body: string }): Promise<Issue>,
+ *   createIssue(issue: { title: string, body: string, labels?: string[] }): Promise<Issue>,
  *   pullFiles(n: number): Promise<PullFile[]>,
- *   comments(n: number): Promise<Comment[]>,
+ *   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[]>,
  *   rerun(check: Check): Promise<void>,
@@ -111,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']);
@@ -120,6 +126,9 @@ export const DEFAULT_LIMIT = 1000;
 /** The runs a listing returns unless asked for fewer: one forge page */
 export const DEFAULT_RUN_LIMIT = 100;
 
+/** The most labels one new issue is given */
+const MAX_LABELS = 5;
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
 const MERGE_METHODS = ['merge', 'squash', 'rebase'];
 const STATES = ['open', 'closed', 'all'];
 const REPO = /^[\w.-]+\/[\w.-]+$/;
@@ -270,7 +279,13 @@ export function wrap(a, forge) {
       return a.searchIssues(words.trim());
     },
     pullFiles: async (n) => a.pullFiles(number(n)),
-    comments: async (n) => a.comments(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;
+      if (since !== undefined && (typeof since !== 'string' || !ISO_TIME.test(since) || Number.isNaN(Date.parse(since)))) throw invalid('since is a time like 2026-11-05T09:00:00Z.');
+      return a.comments(number(n), since === undefined ? {} : { since: new Date(since).toISOString() });
+    },
     comment: async (n, body) => a.comment(number(n), text(body, 'The comment')),
     checks: async (ref) => a.checks(text(ref, 'The commit')),
     rerun: async (check) => {
@@ -339,7 +354,9 @@ export function wrap(a, forge) {
     },
     createIssue: async (issue) => {
       if (!issue || typeof issue !== 'object') throw invalid('Open which issue?');
-      return a.createIssue({ title: bounded(issue.title, 'The title', MAX_TITLE), body: bounded(issue.body ?? ' ', 'The description', MAX_BODY) });
+      const labels = issue.labels ?? [];
+      if (!Array.isArray(labels) || labels.length > MAX_LABELS || labels.some((l) => typeof l !== 'string' || l.trim() === '' || l.trim() !== l || l.length > 50 || l.includes(',') || l.includes('\0'))) throw invalid(`The labels are at most ${MAX_LABELS} names, without commas.`);
+      return a.createIssue({ title: bounded(issue.title, 'The title', MAX_TITLE), body: bounded(issue.body ?? ' ', 'The description', MAX_BODY), labels: [...new Set(labels)] });
     },
     defaultBranch: async () => a.defaultBranch(),
     tags: async () => a.tags(),

package/server/hooks.js

@@ -13,8 +13,21 @@
  *   spec.approved   a maintainer approved a proposal          spec.sentBack   a maintainer sent one back
  *   build.opened    the build issue of an approved proposal was opened
  *   pr.landed       a pull request was landed through cornfield (its Land it); a merge made on the forge sends nothing
+ *   thread.opened  a new idea (an issue with the threads label, docs/threads.md) was first seen
+ *   thread.message a comment was added to a thread: an idea's, or a spec PR's conversation. Once per comment
+ *   thread.linked  a thread now points at the map: a message holds a `[[node]]` mention or a `cornfield-thread` block that
+ *                  resolves, or a spec PR names the thread with `Thread: #n`. Its body adds `nodes` and `proposal`
+ *                  Like `spec.ready`, these fire when cornfield next looks (the dashboard's threads list, or the poll,
+ *                  server/spec-poll.js); a comment's text is never in the payload: `{ event, at, thread, comment?, actor, nodes?,
+ *                  proposal?, mapUrl }`, so the receiver reads the words from the forge itself. The first look at a repo records
+ *                  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
@@ -38,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 */
 
@@ -186,6 +200,29 @@ 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 };
+      if (p.comment !== undefined) out.comment = p.comment;
+      out.actor = p.actor ?? null;
+      if (p.nodes !== undefined) out.nodes = p.nodes;
+      if (p.proposal !== undefined) out.proposal = p.proposal;
+      out.mapUrl = publicUrl || null;
+      return JSON.stringify(out);
+    }
     const out = {
       event, at: new Date(now()).toISOString(), slug: p.slug ?? null, pull: p.pull ?? null, headSha: p.headSha ?? null,
       proposalSha256: p.proposalSha256 ?? null, actor: p.actor ?? null,
@@ -261,6 +298,68 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     })().catch((err) => console.error(`[cornfield] the spec PRs could not be checked for spec.ready: ${err instanceof Error ? err.message : err}`));
   }
 
+  /**
+   * Where each thread was last looked at: for the poll to ask the forge only for what is new. `looked` is whether the repo's
+   * threads have been looked at before (the first look sends nothing); `threads` maps a thread's number to the forge's
+   * last-update time when it was looked at (`stamp`) and the time of the newest comment seen (`since`, '' for none).
+   * @param {string} repo
+   * @returns {Promise<{ looked: boolean, threads: Map<number, { stamp: string, since: string }> }>}
+   */
+  async function threadCursors(repo) {
+    const none = { looked: false, threads: new Map() };
+    if (!store) return none;
+    const db = await store();
+    const rows = db.prepare('SELECT issue, comment, stamp FROM thread_seen WHERE repo = ?').all(repo);
+    const threads = new Map();
+    for (const r of rows) {
+      if (r.issue === 0) continue;
+      const t = threads.get(r.issue) || { stamp: '', since: '' };
+      if (r.comment === '') t.stamp = r.stamp;
+      else if (!r.comment.includes(':') && r.stamp > t.since) t.since = r.stamp;
+      threads.set(r.issue, t);
+    }
+    return { looked: rows.some((r) => r.issue === 0 && r.comment === ''), threads };
+  }
+
+  /**
+   * `thread.opened`, `thread.message` and `thread.linked`: the threads a look just read (server/threads.js `snapshotOf`).
+   * Everything is recorded in `thread_seen` (repo, thread, comment) before it is announced, so a restart sends none twice,
+   * and the first look at a repo records what is there and announces nothing. Returns a promise that resolves once the
+   * events are queued; it never rejects.
+   * @param {string} repo 'owner/name'
+   * @param {{ threads: any[], pulls: { pull: number, thread: number, slug: string }[] }} snapshot
+   */
+  async function threadsSeen(repo, snapshot) {
+    if (closed || !store || !snapshot || !Array.isArray(snapshot.threads)) return;
+    try {
+      const db = await store();
+      const at = new Date(now()).toISOString();
+      const looked = db.prepare("SELECT 1 FROM thread_seen WHERE repo = ? AND issue = 0 AND comment = ''").get(repo) !== undefined;
+      const insert = db.prepare('INSERT OR IGNORE INTO thread_seen (repo, issue, comment, stamp, at) VALUES (?, ?, ?, ?, ?)');
+      const move = db.prepare("INSERT INTO thread_seen (repo, issue, comment, stamp, at) VALUES (?, ?, '', ?, ?) ON CONFLICT(repo, issue, comment) DO UPDATE SET stamp = excluded.stamp");
+      /** Whether this (thread, key) is news: new to the table, and not the silent first look */
+      const fresh = (thread, key, stamp = '') => insert.run(repo, thread, key, stamp, at).changes === 1 && looked;
+      for (const t of snapshot.threads) {
+        if (t.opened && fresh(t.number, '', t.stamp)) emit('thread.opened', { thread: t.number, actor: t.opened.actor });
+        if (t.opened && t.opened.linked && fresh(t.number, 'link:body')) {
+          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 (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
+        move.run(repo, t.number, t.stamp, at);
+      }
+      for (const p of snapshot.pulls || []) {
+        if (fresh(p.thread, `pr:${p.pull}`)) emit('thread.linked', { thread: p.thread, actor: null, nodes: [], proposal: p.slug });
+      }
+      if (!looked) insert.run(repo, 0, '', '', at);
+    } catch (err) {
+      console.error(`[cornfield] the threads could not be checked for thread events: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
   /**
    * `session.expiring`: once an hour (and once now), the live sessions of maintainers (the ones that keep a forge token)
    * that end within 24 hours are announced, each once: the row's `expiring_sent_at` is set before the event is
@@ -296,7 +395,7 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     timers.clear();
   }
 
-  return { emit, specsSeen, watchSessions, close };
+  return { emit, 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) */