toolroll 0.9.104 → 0.9.105

package/dist/agent-board.js

@@ -1,49 +1,14 @@
-/**
- * The Agents board's saved state (one place to check on running agents).
- *
- * Every builder run is admitted with an opaque attempt key (run.attempt_key).
- * The stream observer (agent-turns.ts) records each turn change — busy, idle,
- * crashed — as one append-only agent_turn row, and moves the task's current
- * snapshot (agent_now) only when the writer is the task's newest build
- * attempt AND presents that run's own key: a late event from an earlier or
- * replaced attempt is kept as history and never repaints the row. A protocol
- * repair (role 'repair') mends its parent build and never owns the row: the
- * board shows it as the parent's own activity ("Fixing the handoff").
- * The same stream says which tool calls are open, so a long command reads
- * as Working (Stuck only after TOOL_STUCK_AFTER_MS) rather than as silence.
- *
- * The rest rides the build's existing minute pulse (agent-pulse.ts): the
- * transcript's size, the changed-file count, the agent's own status lines
- * (working, needs-decision, blocked, done) and the four-minute Stuck mark.
- * A needs-decision line is an agent_question; Reply closes exactly that key
- * and files the answer as an ordinary verified steering note, which the
- * steering mailbox delivers to the running agent.
- *
- * Who has seen a finished run (agent_seen) makes Done "not viewed yet"; who
- * is watching a run right now (agent_view, short leases kept by the open
- * page's live stream) holds that person's Needs you and Done pings: they stay
- * pending in their delivery ledgers and go out once the watch lapses, only
- * if the question is still open or the run still unseen (watchedPing).
- * Display state, never evidence: nothing here changes a run's outcome.
- */
 import { randomBytes } from "node:crypto";
-/** A busy run whose transcript and activity are both this old is Stuck. */
 export const STUCK_AFTER_MS = 4 * 60_000;
-/** With a tool call still open (a long test run is silent), it is Stuck only after this long. */
 export const TOOL_STUCK_AFTER_MS = 15 * 60_000;
-/** A page's watch on one run lapses this long after its last keep-alive (the stream's keep-alive is every 15 s). */
 export const VIEW_LEASE_MS = 20_000;
 export const QUESTION_KEY = /^[a-z0-9][a-z0-9-]{0,39}$/;
 export const QUESTION_MAX = 300;
 export const NOTE_MAX = 200;
 export const ANSWER_MAX = 1500;
-/** An agent is untrusted: at most this many of its questions are open at once per run… */
 export const QUESTIONS_OPEN_MAX = 3;
-/** …and at most this many are ever opened per attempt. A needs-decision past either opens nothing and pages no one. */
 export const QUESTIONS_PER_ATTEMPT = 10;
-/** At most one question page per run in this long; questions asked meanwhile wait for the next page. */
 export const QUESTION_PAGE_EVERY_MS = 5 * 60_000;
-/** The board's one note on a run whose agent asked past the caps (set once). */
 export const QUESTIONS_OVERFLOW_NOTE = "The agent asked more questions than the board takes; see its transcript.";
 export const AGENT_BOARD_SCHEMA = `
 CREATE TABLE IF NOT EXISTS agent_turn (
@@ -102,28 +67,21 @@ CREATE INDEX IF NOT EXISTS agent_board_open ON run (task_ref, id) WHERE role = '
 CREATE INDEX IF NOT EXISTS agent_board_recent ON run (finished_at, task_ref, id) WHERE role = 'builder' AND outcome IS NOT NULL;
 CREATE INDEX IF NOT EXISTS agent_board_repair ON run (parent_run, id) WHERE role = 'repair';
 `;
-/** Added to agent_now after the table first shipped (store.ts addColumn): the oldest open tool call's kind and start. */
 export const AGENT_NOW_COLUMNS = [["tool_kind", "TEXT"], ["tool_at", "TEXT"],
-    // The questions cap's note (set once), and the last question page: when it went and the newest question it covered.
     ["question_note", "TEXT"], ["paged_at", "TEXT"], ["paged_upto", "INTEGER"]];
-/** Unpredictable per attempt: the run row is the only place it is written down. */
 export function mintAttemptKey() {
     return randomBytes(12).toString("hex");
 }
 const text = (value) => value === null || value === undefined ? null : String(value);
-/** A run's attempt key; null for a run admitted before the board existed (or no such run). */
 export function attemptKeyOf(store, run) {
     const row = store.handle.prepare("SELECT attempt_key FROM run WHERE id = ?").get(run);
     return row === undefined ? null : text(row["attempt_key"]);
 }
-/** The task's newest build attempt: a repair mends its parent and never stands in for it. */
 export const NEWEST_BUILDER = (task) => `(SELECT MAX(id) FROM run n WHERE n.task_ref = ${task} AND n.role = 'builder')`;
-/** The build attempt a run belongs to on the board: a repair's parent, otherwise itself. */
 export function boardRunOf(store, run) {
     const row = store.handle.prepare("SELECT role, parent_run FROM run WHERE id = ?").get(run);
     return row !== undefined && row["role"] === "repair" && row["parent_run"] != null ? Number(row["parent_run"]) : run;
 }
-/** The writer's own run, proved: it exists, carries exactly this key, and is the task's newest build attempt. */
 function provedRun(store, run, attemptKey) {
     const row = store.handle.prepare(`SELECT r.task_ref, r.attempt_key, ${NEWEST_BUILDER("r.task_ref")} AS newest
     FROM run r WHERE r.id = ?`).get(run);
@@ -131,13 +89,7 @@ function provedRun(store, run, attemptKey) {
         return null;
     return { taskRef: Number(row["task_ref"]), newest: Number(row["newest"]) === run };
 }
-/** The current snapshot moves only for the same attempt, or a strictly newer run; never back. */
 const SAME_ATTEMPT = "agent_now.run = ?2 AND agent_now.attempt_key = ?3";
-/**
- * Record one turn change. Always appended to the run's own history (under its
- * key); the task's current snapshot moves only when this run is the task's
- * newest and is not already newer-owned. Returns whether the snapshot moved.
- */
 export function recordAgentTurn(store, fact) {
     return store.transact(() => {
         const proved = provedRun(store, fact.run, fact.attemptKey);
@@ -171,7 +123,6 @@ export function recordAgentTurn(store, fact) {
         return Number(moved.changes) > 0;
     });
 }
-/** One run's turn history, oldest first. */
 export function agentTurnHistory(store, run) {
     return store.handle.prepare("SELECT attempt_key, state, at FROM agent_turn WHERE run = ? ORDER BY id").all(run)
         .map(row => ({ attemptKey: String(row["attempt_key"]), state: String(row["state"]), at: String(row["at"]) }));
@@ -186,48 +137,36 @@ function readNow(row) {
         questionNote: text(row["question_note"]), pagedAt: text(row["paged_at"]), pagedUpto: Number(row["paged_upto"] ?? 0),
     };
 }
-/** The task's current snapshot, whichever run owns it. */
 export function agentNowForTask(store, taskRef) {
     const row = store.handle.prepare("SELECT * FROM agent_now WHERE task_ref = ?").get(taskRef);
     return row === undefined ? null : readNow(row);
 }
-/** The snapshot this attempt owns, or null when another (newer) attempt does or none was recorded. */
 export function agentNowForRun(store, run, attemptKey) {
     const row = store.handle.prepare("SELECT * FROM agent_now WHERE run = ? AND attempt_key = ?").get(run, attemptKey);
     return row === undefined ? null : readNow(row);
 }
-/** Fields the pulse may move, for the attempt that owns the snapshot only. */
 function updateOwned(store, run, attemptKey, set, values) {
     const moved = store.handle.prepare(`UPDATE agent_now SET ${set} WHERE run = ? AND attempt_key = ?`).run(...values, run, attemptKey);
     return Number(moved.changes) > 0;
 }
-/** The pulse saw the live transcript's size: new bytes are news, and news is not Stuck. */
 export function noteTranscript(store, run, attemptKey, bytes, at) {
     const now = agentNowForRun(store, run, attemptKey);
     if (now === null || now.transcriptBytes === bytes)
         return false;
     return updateOwned(store, run, attemptKey, "transcript_bytes = ?, transcript_at = ?, stuck_at = NULL", [bytes, at.toISOString()]);
 }
-/** The changed-file count the pulse observed (null: it could not look). */
 export function noteDiff(store, run, attemptKey, files, at) {
     const now = agentNowForRun(store, run, attemptKey);
     if (now === null || now.diffFiles === files)
         return false;
     return updateOwned(store, run, attemptKey, "diff_files = ?, diff_at = ?", [files, at.toISOString()]);
 }
-/** The stream opened or closed a tool call: the oldest still open, or null. The stream moved, so it clears Stuck. */
 export function noteOpenTool(store, run, attemptKey, open, at) {
     return updateOwned(store, run, attemptKey, "tool_kind = ?, tool_at = ?, transcript_at = max(transcript_at, ?), stuck_at = NULL", [open?.kind ?? null, open === null ? null : open.at.toISOString(), at.toISOString()]);
 }
-/** When the agent last showed a sign of life: its turn, transcript, recorded activity or the tool it opened. */
 export function quietSince(now, activityAt) {
     return Math.max(...[now.stateAt, now.transcriptAt, activityAt, now.toolAt ?? null].filter((one) => one !== null).map(one => Date.parse(one)));
 }
-/**
- * Stuck, from saved facts and the clock alone (no model, no tokens): busy, and
- * neither the transcript, the recorded activity nor the turn itself has moved
- * for STUCK_AFTER_MS — or for TOOL_STUCK_AFTER_MS while a tool call is open.
- */
 export function stuckSince(now, activityAt, clock) {
     if (now.state !== "busy")
         return null;
@@ -236,14 +175,12 @@ export function stuckSince(now, activityAt, clock) {
     const quiet = clock.getTime() - latest;
     return Number.isFinite(quiet) && quiet >= after ? new Date(latest + after).toISOString() : null;
 }
-/** The newest recorded activity of a run: its last kind, or its newest progress checkpoint. */
 function activityAtOf(store, run) {
     const row = store.handle.prepare(`SELECT max(coalesce((SELECT at FROM run_activity WHERE run = ?1), ''),
       coalesce((SELECT created_at FROM run_checkpoint WHERE run = ?1 ORDER BY id DESC LIMIT 1), '')) AS at`).get(run);
     const at = row === undefined ? "" : String(row["at"] ?? "");
     return at === "" ? null : at;
 }
-/** The pulse persists the Stuck crossing (and its clearing), so open boards hear it through /live. */
 export function markStuck(store, run, attemptKey, clock) {
     const now = agentNowForRun(store, run, attemptKey);
     if (now === null)
@@ -253,14 +190,6 @@ export function markStuck(store, run, attemptKey, clock) {
         return false;
     return updateOwned(store, run, attemptKey, "stuck_at = ?", [stuck]);
 }
-/**
- * The agent's status lines since the saved offset, for the attempt that owns
- * the snapshot. The offset only moves forward; a needs-decision opens its key
- * once (a key already asked this run is never reopened), within the caps:
- * QUESTIONS_OPEN_MAX open at once and QUESTIONS_PER_ATTEMPT in all. One past
- * either opens nothing and pages no one; the run gets QUESTIONS_OVERFLOW_NOTE,
- * once. New questions page the people the task reaches (pageQuestions).
- */
 export function ingestStatus(store, run, attemptKey, read, at) {
     return store.transact(() => {
         const now = agentNowForRun(store, run, attemptKey);
@@ -296,13 +225,6 @@ export function ingestStatus(store, run, attemptKey, read, at) {
         return { asked, moved: said !== null || asked.length > 0 || noted };
     });
 }
-/**
- * Page the run's open questions no page has covered yet, at most once per
- * QUESTION_PAGE_EVERY_MS. A question asked outside that window, alone, pages
- * at once with its own words; questions asked inside it wait, and the next
- * page after the window says how many are waiting. The pulse calls this every
- * beat, so the waiting ones go out when the window ends.
- */
 export function pageQuestions(store, run, attemptKey, at) {
     const due = () => {
         const now = agentNowForRun(store, run, attemptKey);
@@ -317,7 +239,6 @@ export function pageQuestions(store, run, attemptKey, at) {
         const waiting = rows.filter(row => Number(row["id"]) > now.pagedUpto);
         return waiting.length === 0 ? null : { lastPage, rows, waiting };
     };
-    // Read first: most beats have nothing waiting, and need no write.
     if (due() === null)
         return false;
     return store.transact(() => {
@@ -334,7 +255,6 @@ export function pageQuestions(store, run, attemptKey, at) {
                 subject: `${title}: the agent has a question`, body: String(newest["question"]) }, at);
         }
         else {
-            // "~" never starts a question key, so this never takes a question's own dedupe key.
             store.enqueueNotification({ ...page, dedupeKey: `agent-question:${run}:~${Number(newest["id"])}`,
                 subject: `${title}: the agent has questions`, body: questionsWaiting(rows.length) }, at);
         }
@@ -345,7 +265,6 @@ export function pageQuestions(store, run, attemptKey, at) {
 export const questionsWaiting = (count) => `${count} ${count === 1 ? "question" : "questions"} waiting`;
 const readQuestion = (row) => ({ id: Number(row["id"]), run: Number(row["run"]), taskRef: Number(row["task_ref"]),
     key: String(row["key"]), question: String(row["question"]), askedAt: String(row["asked_at"]) });
-/** A task's open questions, oldest first: only its newest run's, and only while that run is open. */
 export function openAgentQuestions(store, taskRef) {
     return store.handle.prepare(`SELECT q.* FROM agent_question q JOIN run r ON r.id = q.run
     WHERE q.task_ref = ? AND q.closed_at IS NULL AND r.outcome IS NULL AND r.attempt_key = q.attempt_key ORDER BY q.id`).all(taskRef).map(readQuestion);
@@ -355,7 +274,6 @@ export function agentQuestion(store, id) {
     return row === undefined ? null : { ...readQuestion(row), closedAt: text(row["closed_at"]), closedHow: text(row["closed_how"]),
         answerNote: row["answer_note"] == null ? null : Number(row["answer_note"]) };
 }
-/** A run ended: every question it still had open is closed unanswered (its answer would reach no one). */
 export function closeRunQuestions(store, run, at) {
     const closed = Number(store.handle.prepare("UPDATE agent_question SET closed_at = ?, closed_how = 'ended' WHERE run = ? AND closed_at IS NULL")
         .run(at.toISOString(), run).changes);
@@ -365,16 +283,9 @@ export function closeRunQuestions(store, run, at) {
     }
     return closed;
 }
-/** The steering note a reply becomes: the agent reads it in its steering folder, under its own key. */
 export function replyNoteText(key, answer) {
     return `Reply to your question "${key}": ${answer}`;
 }
-/**
- * Reply to one open question, atomically: the question is still open, its run
- * is still the task's open newest attempt under the same key, the answer saves
- * as an ordinary verified steering note (the mailbox pulse delivers it), and
- * exactly that key closes. Anything stale changes nothing.
- */
 export function answerAgentQuestion(store, reply) {
     return store.transact(() => {
         const answer = reply.answer.trim();
@@ -400,7 +311,6 @@ export function answerAgentQuestion(store, reply) {
             throw new Error("the question closed while the reply was saved");
         store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE dedupe_key = ? AND resolved_at IS NULL")
             .run(reply.at.toISOString(), `agent-question:${String(row["run"])}:${key}`);
-        // The last open question answered: a "questions waiting" page has nothing left to wait on.
         const left = store.handle.prepare("SELECT 1 AS hit FROM agent_question WHERE run = ? AND closed_at IS NULL LIMIT 1").get(row["run"]);
         if (left === undefined) {
             const head = `agent-question:${String(row["run"])}:~`;
@@ -409,12 +319,9 @@ export function answerAgentQuestion(store, reply) {
         return { ok: true, note: filed.id, key };
     });
 }
-// ---- who has seen, who is watching ------------------------------------------
-/** This person opened a finished run (on the board or its result page): it leaves their unread Done. */
 export function markAgentSeen(store, account, run, at) {
     return Number(store.handle.prepare("INSERT OR IGNORE INTO agent_seen (account, run, seen_at) VALUES (?, ?, ?)").run(account, boardRunOf(store, run), at.toISOString()).changes) > 0;
 }
-/** A page is watching a run: hold (or renew) its short lease. */
 export function holdAgentView(store, view, account, run, at) {
     store.handle.prepare(`INSERT INTO agent_view (view, account, run, expires_at) VALUES (?, ?, ?, ?)
     ON CONFLICT (view) DO UPDATE SET expires_at = excluded.expires_at`).run(view, account, run, new Date(at.getTime() + VIEW_LEASE_MS).toISOString());
@@ -422,28 +329,17 @@ export function holdAgentView(store, view, account, run, at) {
 export function releaseAgentView(store, view, at) {
     store.handle.prepare("DELETE FROM agent_view WHERE view = ? OR expires_at < ?").run(view, at.toISOString());
 }
-/** Until when this person has this exact run open (its repairs count as the run); null when they do not. */
 export function watchingAgentUntil(store, account, run, at) {
     const row = store.handle.prepare("SELECT max(expires_at) AS until FROM agent_view WHERE run = ? AND account = ? AND expires_at > ?")
         .get(boardRunOf(store, run), account, at.toISOString());
     return row === undefined || row["until"] == null ? null : String(row["until"]);
 }
-/** Someone has this exact run open right now. */
 export function watchingAgent(store, account, run, at) {
     return watchingAgentUntil(store, account, run, at) !== null;
 }
-/** Kinds no watch ever holds: a security alert and the evening digest reach people as they are (store.pingAllowed).
- * Nothing held may delay them either: a channel's ordering never keeps one behind a held ping (neverHeld). */
 const NEVER_HELD = new Set(["secret-detected", "security-release", "evening-digest"]);
 export const neverHeld = (kind) => NEVER_HELD.has(kind);
-/** Kinds that are news only until the finished run is seen: a ping about one already opened is not sent at all. */
 const SEEN_SETTLES = new Set(["run-finished", "build-failed"]);
-/**
- * A notification's subject (cockpit §3, R11): the run it is about — its own, or for a ping about a task the task's
- * live build — so any ping, not only the agent's own kinds, can be held while its person watches that agent. Null:
- * about nothing a person watches. Its version is the notification's own identity (its dedupe key), so a newer fact
- * about the same subject is a new ping.
- */
 export function attentionSubjectOf(store, row) {
     if (NEVER_HELD.has(row.kind))
         return null;
@@ -454,12 +350,6 @@ export function attentionSubjectOf(store, row) {
     const live = store.handle.prepare("SELECT id FROM run WHERE task_ref = ? AND role = 'builder' AND outcome IS NULL ORDER BY id DESC LIMIT 1").get(row.taskRef);
     return live === undefined ? null : { run: Number(live["id"]) };
 }
-/**
- * A watched ping (cockpit §3, R11), decided when its delivery is claimed AND again at every channel's final send
- * fence, after the permanent rules in store.pingAllowed: held until the watch lapses while this person has its
- * subject's agent open; then skipped when it was news about a finished run they have since seen; otherwise sent.
- * A ping about nothing anyone watches is sent. (A delivery already handed to the network can't be recalled.)
- */
 export function watchedPing(store, row, account, now) {
     const subject = attentionSubjectOf(store, row);
     if (subject === null)
@@ -472,13 +362,7 @@ export function watchedPing(store, row, account, now) {
     const seen = store.handle.prepare("SELECT 1 AS hit FROM agent_seen WHERE account = ? AND run = ?").get(account, boardRunOf(store, row.run));
     return seen === undefined ? "send" : "skip";
 }
-// ---- easy-start C1 (N1): the watch lease and the seen mark, from keyed POSTs only -------------------------------------
-/** A page's own watch id: 24 hex characters the shell makes (never a database row id). */
 export const AGENT_VIEW_ID = /^[0-9a-f]{24}$/;
-/**
- * POST /agents/watch, hold: this person's page watches a run (renewed on each keep-alive). A view id another person
- * already holds is never taken over or renewed: only the holder's own row moves. False when nothing was held.
- */
 export function holdOwnAgentView(store, view, account, run, at) {
     if (!AGENT_VIEW_ID.test(view))
         return false;
@@ -486,7 +370,6 @@ export function holdOwnAgentView(store, view, account, run, at) {
     ON CONFLICT (view) DO UPDATE SET expires_at = excluded.expires_at WHERE agent_view.account = excluded.account AND agent_view.run = excluded.run`)
         .run(view, account, boardRunOf(store, run), new Date(at.getTime() + VIEW_LEASE_MS).toISOString()).changes) > 0;
 }
-/** POST /agents/watch, release: this person's page went away. Only their own view is released (and lapsed ones swept). */
 export function releaseOwnAgentView(store, view, account, at) {
     if (!AGENT_VIEW_ID.test(view))
         return;