toolroll 0.9.103 → 0.9.105

package/dist/stream-scope.js

@@ -1,23 +1,7 @@
-/**
- * Whose event is this (docs/plans/agents-view.md §2.1): Claude's `stream-json` interleaves the session's own events
- * with its subagents', and a subagent's carry `parent_tool_use_id` (the parent's Task/Agent call). Only the session's
- * own events drive its lifecycle, identity and accounting: the receipt, the primary result, the saved session, live
- * input, the turn and activity marks, and the billing observations. A subagent's init, words or result prove nothing
- * about the main query.
- *
- * Unknown shapes fail toward "not the parent": any present, non-null `parent_tool_use_id` (an id, `""`, a number)
- * makes the event a subagent's. Pure, no imports: every reader shares this one copy.
- */
-/** The session's own event: `parent_tool_use_id` absent or null. */
 export function topLevelEvent(event) {
     const parent = event["parent_tool_use_id"];
     return parent === undefined || parent === null;
 }
-/**
- * The main query's `result`, selected structurally (finding 10): top-level, and its `origin` absent, null or
- * `{kind: "human"}`. An allowlist, so a background task's result, a subagent's result, or any future origin kind is
- * never the run's envelope.
- */
 export function primaryResultEvent(event) {
     if (event["type"] !== "result" || !topLevelEvent(event))
         return false;

package/dist/structured-output.js

@@ -1,22 +1,10 @@
-/**
- * Shared structured-output recovery primitives for planner and reviewer.
- *
- * The normalizer is deliberately syntax-only. It may remove transport
- * wrappers that carry no meaning; it never extracts a likely-looking object
- * from prose, fills a field, truncates a note, changes an id, or chooses a
- * judgement. Semantic repair belongs to the same agent session and remains
- * subject to the phase's strict parser.
- */
 import { redactSecretLines, scanForSecrets, storeEvidence } from "./evidence.js";
 import { TEXT_LIMITS } from "./text-limits.js";
 export const STRUCTURED_REPAIR_ATTEMPTS = 2;
 export const STRUCTURED_REPAIR_MAX_TURNS = 4;
 export const STRUCTURED_REPAIR_TIMEOUT_MS = 5 * 60_000;
-/** Native parsing counts UTF-16 code units. A shorter writing target keeps
- * notes concise without imposing a second, stricter transport contract. */
 export const REVIEW_OUTPUT_LIMITS = { comments: 40, criteria: 12, note: TEXT_LIMITS.reviewNote, path: TEXT_LIMITS.reviewPath };
 export const REVIEW_NOTE_CODE_POINTS = Math.floor(REVIEW_OUTPUT_LIMITS.note / 2);
-/** Strip only unambiguous, whole-payload wrappers. */
 export function normalizeStructuredJson(raw) {
     let text = raw;
     const changes = [];
@@ -26,12 +14,6 @@ export function normalizeStructuredJson(raw) {
     }
     const trimmed = text.trim();
     const fenced = /^```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n```$/i.exec(trimmed);
-    // A pair of complete fenced blocks also matches the outer anchors above
-    // (the first opener and final closer). Never collapse that ambiguous
-    // payload into one: the strict phase parser should reject it and ask the
-    // author to emit one response. A fence marker inside JSON source cannot
-    // occur on its own line without making that JSON invalid, so this is a
-    // conservative false-negative rather than a semantic rewrite.
     if (fenced !== null && !(fenced[1] ?? "").includes("```")) {
         text = fenced[1] ?? "";
         changes.push("json-fence");
@@ -41,16 +23,10 @@ export function normalizeStructuredJson(raw) {
             changes.push("whitespace");
         text = trimmed;
     }
-    // Some harness/model pairs double-encode the complete JSON reply as one
-    // JSON string. Unwrap exactly one layer only when the decoded value is a
-    // string containing one object/array-shaped payload. No brace searching.
     try {
         const once = JSON.parse(text);
         if (typeof once === "string") {
             const candidate = once.trim();
-            // Shape alone is not enough: `"{not json}"` is content, not an
-            // unambiguous transport wrapper. Verify the decoded layer is itself a
-            // complete JSON object or array before removing the one string layer.
             let decoded;
             try {
                 decoded = JSON.parse(candidate);
@@ -65,28 +41,14 @@ export function normalizeStructuredJson(raw) {
         }
     }
     catch {
-        // The phase parser owns the useful error; normalization never guesses.
     }
     return { text, changed: changes.length > 0, changes };
 }
-/**
- * Keep the exact emitted payload unless it contains a high-confidence secret
- * shape, in which case the same line-redaction discipline as terminal diffs
- * keeps the audit record useful without creating a second credential copy.
- */
 export function storeStructuredAttempt(store, root, logicalRunId, args) {
     const rawBytes = Buffer.isBuffer(args.raw) ? args.raw : Buffer.from(args.raw, "utf8");
     const rawText = rawBytes.toString("utf8");
     const hits = scanForSecrets(rawText);
     const content = hits.length === 0 ? rawBytes : Buffer.from(redactSecretLines(rawText, hits), "utf8");
-    // `accepted: false` can mean strict validation, provider status, session
-    // identity, or another provenance gate rejected the bytes. Keep the
-    // evidence wording honest without pretending every refusal was a parser
-    // error; the run's typed reason records which gate failed.
-    // Do not call a pre-finalization candidate simply "accepted": this
-    // artifact must remain truthful if a later custody/binding transaction
-    // refuses it. Parser acceptance and final workflow acceptance are separate
-    // facts; the latter lives on the terminal run.
     const normalization = args.normalized ? ", syntax normalized" : "";
     const state = args.accepted
         ? `parser accepted${normalization}; workflow pending`
@@ -97,7 +59,6 @@ export function storeStructuredAttempt(store, root, logicalRunId, args) {
         sourceBytesOriginal: args.sourceBytesOriginal ?? rawBytes.length,
     });
 }
-/** JSON-quote parser errors so agent-authored ids/paths remain data. */
 export function validationErrorsJson(problems) {
     return JSON.stringify(problems.map(problem => ({ reason: problem.reason, ...(problem.message === undefined ? {} : { message: problem.message }) })), null, 2);
 }

package/dist/style-asset.js

@@ -1,7 +1,5 @@
 import { createHash } from "node:crypto";
 import { gzipSync } from "node:zlib";
-/** Only application-owned CSS belongs here. Never pass rendered HTML or
- * session data: this asset is public, immutable and compressed. */
 export function styleAsset(css) {
     const body = Buffer.from(css);
     const digest = createHash("sha256").update(body).digest("hex");

package/dist/subagent-admin.js

@@ -1,11 +1,9 @@
 import { flowDefinitionOf } from "./flow-engine.js";
 import { handleOf, parseSoul, SUBAGENT_TEMPLATES, subagentLabel } from "./subagents.js";
 export const SUBAGENT_MODELS = ["default", "sonnet", "opus", "haiku"];
-/** A soul file with a different name: the template's, renamed. */
 export function renamedSoul(soul, name) {
     return soul.replace(/^name:.*$/m, `name: ${name.replace(/[\r\n]/g, " ").trim()}`);
 }
-/** A new subagent in a project, from a template (optionally renamed) or a whole soul file. */
 export function createSubagentFrom(store, input, now) {
     const template = SUBAGENT_TEMPLATES.find(one => one.id === input.template);
     let soul = input.soul?.trim() ? input.soul : template?.soul ?? null;
@@ -23,7 +21,6 @@ export function createSubagentFrom(store, input, now) {
     store.addSubagentEvent({ subagent: id, kind: "note", said: `${input.by} brought ${read.soul.name} onto the team.`, by: input.by }, now);
     return { ok: true, said: `${subagentLabel(read.soul)} is on the team. Put ${read.soul.name} on a zone to start.`, id };
 }
-/** Save a new version of a subagent's soul file. Its name stays: zones name it by handle. */
 export function saveSoul(store, mate, soul, by, now) {
     const read = parseSoul(soul);
     if (!read.ok)
@@ -33,7 +30,6 @@ export function saveSoul(store, mate, soul, by, now) {
     const saved = store.saveSubagentSoul(mate.id, soul.replace(/\r\n?/g, "\n").trim() + "\n", by, now);
     return { ok: true, said: saved ? `Saved. ${read.soul.name} works from version ${mate.version + 1} now.` : "No changes to save." };
 }
-/** Pause, resume or remove. Paused, its decisions go to people and the zones it handles wait. */
 export function setSubagentState(store, mate, state, by, now) {
     const name = nameOf(mate);
     if (state === mate.state)
@@ -41,7 +37,6 @@ export function setSubagentState(store, mate, state, by, now) {
     if (state === "removed") {
         for (const question of store.openSubagentQuestions([mate.id]))
             store.dropSubagentQuestion(question.id, now);
-        // v94: calls waiting for approval, or approved and not made yet, are never made.
         for (const call of store.subagentCallsOf(mate.id, 500).filter(one => one.state === "asked" || one.state === "approved"))
             store.moveSubagentCall(call.id, ["asked", "approved"], { state: "refused", result: `${name} left the team before the call was made.` }, now);
         store.updateSubagent(mate.id, { state }, by, now);
@@ -64,19 +59,16 @@ export function subagentSettings(store, mate, change, by, now) {
 }
 export const nameOf = (mate) => { const read = parseSoul(mate.soul); return read.ok ? read.soul.name : mate.handle; };
 export const labelOf = (mate) => { const read = parseSoul(mate.soul); return read.ok ? subagentLabel(read.soul) : mate.handle; };
-/** Every zone a subagent works, in every flow of its project. */
 export function zonesOf(store, mate) {
     return store.listFlows([mate.repo]).flatMap(flow => (flowDefinitionOf(flow)?.stages ?? []).filter(one => one.subagent === mate.handle)
         .map(one => ({ flow: flow.id, flowName: flow.name, zone: one.id, title: one.title, kind: one.kind === "approval" ? "decides" : "handles" })));
 }
-/** What a subagent did since a time, in words its manager reads at a glance. */
 export function summaryOf(store, mate, since) {
     const name = nameOf(mate);
     const events = store.subagentEvents(mate.id, 500, since);
     const count = (kind) => events.filter(one => one.kind === kind).length;
     const decided = count("decided"), handled = count("handled"), handed = count("handed"), asked = count("asked"), failed = count("failed");
     const open = store.openSubagentQuestions([mate.id]).length;
-    // v94: its tool calls — made, approved first, and what its people said no to.
     const calls = store.subagentCallsOf(mate.id, 1000, since);
     const made = calls.filter(one => one.state === "done" || one.state === "failed").length, approved = calls.filter(one => one.decidedBy !== null && one.state !== "denied").length, denied = calls.filter(one => one.state === "denied").length;
     const quiet = decided + handled + handed + asked + failed + calls.length === 0;
@@ -88,7 +80,6 @@ export function summaryOf(store, mate, since) {
     ];
     return { said: lines.join("\n"), quiet };
 }
-/** The daily summary, to each subagent's manager, once a day after 5 pm (this computer's time), or now when asked. */
 export function sendSubagentSummaries(store, repo, now, only = null) {
     const evening = new Date(now);
     evening.setHours(17, 0, 0, 0);

package/dist/subagent-desk.js

@@ -1,29 +1,14 @@
-/**
- * A subagent's desk (v96): its own flow, where anything asked of it directly
- * lands as a card — the lead asking it for its person ("ask Rosa where order
- * 2201 is", D5), or one of its routines ("every weekday at 9:00: …") — and
- * its answer goes back to whoever asked.
- *
- * The desk is an ordinary flow its manager owns and can redraw. The subagent
- * handles each card there within its rules and tools (asking first when they
- * say to), writes its answer, and picks where the card goes: Done, a code
- * change (the Build zone files an ordinary task that a person approves as
- * usual), or its manager. Nothing here gives it more than its rules do.
- */
 import { flowCardHref, flowDefinitionOf } from "./flow-engine.js";
 import { flowFromSteps } from "./flows.js";
 import { addFlowTriggerTo, removeFlowTrigger, runScheduleNow, scheduleFromWords, triggerConfigOf } from "./flow-triggers.js";
 import { describeSchedule, parseSchedule } from "./flow-schedule.js";
 import { labelOf, nameOf } from "./subagent-admin.js";
-/** The zone on a desk where the subagent handles what it's asked. */
 export const DESK_ZONE = "handle";
 const DESK_INSTRUCTIONS = "Someone asked you this directly, or it's one of your routines. Do what they ask within your rules, using your tools when it needs them, and write your answer to them in \"text\": it goes back to whoever asked. Pick Done when you've answered, Needs a code change when what they want is a change to this project's code (it's filed as a task for a person to approve), and Needs a person when it's beyond you.";
-/** Its desk, when it has one. */
 export function deskOf(store, mate) {
     const flow = mate.deskFlow === null ? null : store.getFlow(mate.deskFlow);
     return flow !== null && flow.state === "active" ? flow : null;
 }
-/** Its desk, made the first time it's needed: owned by its manager, drawn like any flow. */
 export function ensureDesk(store, mate, now) {
     const had = deskOf(store, mate);
     if (had !== null)
@@ -41,23 +26,15 @@ export function ensureDesk(store, mate, now) {
     store.setSubagentDesk(mate.id, id);
     return store.getFlow(id);
 }
-/** Who a desk card's answer goes to: the person who asked (when they can see the project), else its manager. */
 export function askerOf(store, flow, card, mate) {
     return store.accountOf(card.createdBy) !== null && store.accountCanAccess(card.createdBy, flow.repo) ? card.createdBy : mate.manager;
 }
-/** The answer a subagent wrote, back to whoever asked, under its name. Once per visit. */
 export function replyToAsker(store, flow, card, mate, text, now) {
     const to = askerOf(store, flow, card, mate);
     store.enqueueNotification({ dedupeKey: `teammate-reply:${card.id}:${card.entry}`, kind: "teammate-reply", recipient: to, subject: `${labelOf(mate)}: ${card.title}`.slice(0, 200),
         body: text.slice(0, 3500), link: flowCardHref(flow.id, card.id), source: { project: flow.repo } }, now);
 }
-/**
- * The lead delegates (D5): "ask Rosa to …", once its person confirms the card, is a card on Rosa's desk from that
- * person. Rosa works it within her own rules and tools (asking them first where her rules say to), and her answer goes
- * back to whoever asked. It gives her nothing her rules don't: a code change is still a task a person approves.
- */
 export function askSubagent(store, given, from, text, now) {
-    // As it is now (its desk may have been made since the caller read it), never as the caller last saw it.
     const mate = store.getSubagent(given.id) ?? given;
     const name = nameOf(mate);
     if (mate.state !== "active")
@@ -78,7 +55,6 @@ export function askSubagent(store, given, from, text, now) {
     store.setFlowCardWatcher(card, from.who, true, now);
     return { ok: true, said: `${name} has it. The answer comes to you when it's done.`, card, link: { label: "Open the card", path: flowCardHref(desk.id, card) } };
 }
-/** Its routines: the schedules on its desk that start in its zone. */
 export function routinesOf(store, mate) {
     const desk = deskOf(store, mate);
     if (desk === null)
@@ -90,22 +66,18 @@ export function routinesOf(store, mate) {
         return [{ id: trigger.id, schedule: config.schedule, text: config.title, state: trigger.state, lastAt: trigger.lastAt, lastOutcome: trigger.lastOutcome, nextAt: trigger.nextAt }];
     });
 }
-/** This computer's time zone: what a routine's time means when it names none. */
 export const localZone = () => { try {
     return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
 }
 catch {
     return "UTC";
 } };
-/** A routine's schedule as kept: a calendar time with no zone is this computer's time, not UTC. */
 export function routineSchedule(words) {
     const read = scheduleFromWords(words);
-    // A zone the person named, UTC included, stays theirs.
     if (read === null || read.startsWith("every:") || read.includes("@") || /\b(utc|gmt)$/i.test(words.trim()))
         return read;
     return scheduleFromWords(`${words.trim()} ${localZone()}`) ?? read;
 }
-/** A routine: on this schedule ("weekdays 09:00", "daily 17:00 Europe/London", "every 2 hours"), a card on its desk saying what to do. */
 export function addRoutine(store, mate, schedule, text, by, now, dir) {
     const what = text.replace(/\s+/g, " ").trim();
     if (what === "")
@@ -133,7 +105,6 @@ export function removeRoutine(store, mate, id, now, dir) {
     removeFlowTrigger(store, trigger, now, dir);
     return { ok: true, said: "Removed. It won't do that any more." };
 }
-/** Try a routine now: its card lands on the desk at once. */
 export function runRoutine(store, mate, id, by, now) {
     const trigger = routineOf(store, mate, id);
     if (trigger === null)

package/dist/subagent-memory.js

@@ -1,35 +1,15 @@
-/**
- * What a subagent remembers (v95), and how it learns from its people.
- *
- * Memory is short facts, each a line: what its people told it ("this week,
- * offer free shipping instead of a refund" — v92's notes), and what it kept
- * from its own turns ("Sam prefers email to phone"). Every turn reads what
- * its people said lately, and what it kept that fits the card. People search,
- * edit and forget any of it on the subagent's page or through the lead.
- *
- * Learning: when its manager approves the same ask-first tool action again
- * and again (five in a row, none denied), the subagent suggests loosening
- * that one rule — "You approved my last 5 refunds (amount 55 to 70): may I
- * make them on my own up to 75?" — as a question its manager accepts or
- * not, in their chat app or on its page. Accepting changes only that rule,
- * and only if it is still what it was when suggested.
- */
 import { scanForSecrets } from "./evidence.js";
 import { notifyPeople } from "./flow-people.js";
 import { labelOf, nameOf } from "./subagent-admin.js";
 import { defaultRule, numberFields, setToolRules } from "./subagent-tools.js";
 export const MEMORY_CHARS = 300;
-/** Facts a subagent keeps on its own: past this, its oldest are forgotten. What people told it is never dropped this way. */
 export const MEMORY_CAP = 300;
-/** Approvals in a row of one action before the subagent suggests loosening its rule. */
 export const SUGGEST_AFTER = 5;
 export const ACCEPT = "accept", DISMISS = "dismiss";
 const STOP = new Set("about after again also been before being could does doing from have here into just like more most much must only other over same some such than that their them then there these they this those through very want were what when where which while will with would your yours please thanks thank hello".split(" "));
-/** The words a text is about: lower case, four letters or more, no filler. */
 export function wordsOf(text) {
     return [...new Set(text.toLowerCase().normalize("NFKD").split(/[^\p{L}\p{N}]+/u).filter(one => one.length >= 4 && !STOP.has(one)))].slice(0, 60);
 }
-/** Two lines about the same thing: most of their words are shared. */
 export function similar(a, b) {
     const left = new Set(wordsOf(a)), right = new Set(wordsOf(b));
     if (left.size === 0 || right.size === 0)
@@ -37,7 +17,6 @@ export function similar(a, b) {
     const shared = [...left].filter(one => right.has(one)).length;
     return shared / new Set([...left, ...right]).size >= 0.6;
 }
-/** A memory as it may be kept: one line, plain, short, no secrets. */
 export function cleanMemory(text) {
     const line = text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
     if (line === "")
@@ -48,7 +27,6 @@ export function cleanMemory(text) {
         return { ok: false, said: "That looks like a key or password. Keep secrets out of a subagent's memory." };
     return { ok: true, text: line };
 }
-/** Keep one thing: from a person (what they told it), or from the subagent itself on a turn. The same words twice are kept once. */
 export function remember(store, mate, text, from, now) {
     const clean = cleanMemory(from.source === "subagent" ? text.slice(0, MEMORY_CHARS) : text);
     if (!clean.ok)
@@ -56,7 +34,6 @@ export function remember(store, mate, text, from, now) {
     const same = store.subagentMemories(mate.id).find(one => one.text.toLowerCase() === clean.text.toLowerCase());
     if (same !== undefined)
         return { ok: true, said: `${nameOf(mate)} already remembers that.`, id: same.id };
-    // Saying nearly the same thing again on the same card (another turn of the same visit) refreshes what it kept instead of adding a second line.
     if (from.source === "subagent" && from.card !== undefined && from.card !== null) {
         const near = store.subagentMemories(mate.id, { source: "subagent" }).find(one => one.card === from.card && similar(one.text, clean.text));
         if (near !== undefined) {
@@ -70,7 +47,6 @@ export function remember(store, mate, text, from, now) {
             store.forgetSubagentMemory(old.id, "limit", now);
     return { ok: true, said: `${nameOf(mate)} will remember that.`, id };
 }
-/** Something a person tells a subagent (the page's "Tell Maya something", or the lead): kept in its memory, read by every turn while it's among the latest ten. */
 export function tellSubagent(store, mate, note, by, now) {
     const kept = remember(store, mate, note, { source: "person", by }, now);
     return kept.ok ? { ok: true, said: `${nameOf(mate)} will keep that in mind.` } : kept;
@@ -92,16 +68,10 @@ export function forgetMemory(store, mate, id, by, now) {
     store.forgetSubagentMemory(id, by, now);
     return { ok: true, said: `${nameOf(mate)} forgot it.` };
 }
-/** Memories whose text holds every word searched for. */
 export function searchMemories(store, mate, query) {
     const words = query.toLowerCase().split(/[^\p{L}\p{N}$]+/u).filter(one => one.length >= 2);
     return store.subagentMemories(mate.id, { words, limit: 100 });
 }
-/**
- * What one turn reads: what its people told it lately (oldest first), and
- * what it kept that fits the card — the facts sharing most of the card's
- * words, then its newest — up to eight.
- */
 export function memoriesFor(store, mate, cardText, now) {
     const told = store.subagentMemories(mate.id, { source: "person", limit: 10 }).reverse();
     const own = store.subagentMemories(mate.id, { source: "subagent", limit: MEMORY_CAP });
@@ -114,13 +84,7 @@ export function memoriesFor(store, mate, cardText, now) {
 }
 const numberOf = (value) => typeof value === "number" && Number.isFinite(value) ? value
     : typeof value === "string" && /^\s*\$?\d+(\.\d+)?\s*$/.test(value) ? Number(value.replace(/[$\s]/g, "")) : null;
-/** A limit a person would pick: rounded up to a round number. */
 export const roundUp = (value) => { const step = value < 20 ? 1 : value < 100 ? 5 : value < 1000 ? 25 : 100; return Math.ceil(value / step) * step; };
-/**
- * After a person approves an ask-first call: when they have approved this
- * action enough times in a row since it last suggested anything about it,
- * the subagent suggests the rule that would have let it make them all.
- */
 export function considerSuggestion(store, mate, approved, now) {
     const grant = store.subagentGrant(mate.id, approved.tool);
     const info = grant?.actions.find(one => one.name === approved.action);
@@ -141,7 +105,6 @@ export function considerSuggestion(store, mate, approved, now) {
     }
     if (run.length < SUGGEST_AFTER)
         return null;
-    // The number the rule is limited on (or, with none, the one every approved call gave).
     const field = rule.limit?.field ?? numberFields(info).find(name => run.every(call => numberOf(call.input[name]) !== null)) ?? null;
     const values = field === null ? [] : run.map(call => numberOf(call.input[field])).filter((one) => one !== null);
     let suggested, range = "";
@@ -170,7 +133,6 @@ export function considerSuggestion(store, mate, approved, now) {
         body: `${said}\n\nThis changes only that one rule; you can change it back on ${nameOf(mate)}'s page.` }, now);
     return id;
 }
-/** Its manager answers a suggestion: accept changes the one rule (if it is still what it was), anything else leaves it; their words are remembered. */
 export function answerSuggestion(store, mate, suggestion, answer, now) {
     const offered = store.subagentSuggestion(suggestion);
     if (offered === null || offered.state !== "open")

package/dist/subagent-question.js

@@ -1,40 +1,23 @@
-/**
- * A subagent's question, answered in the chat app (v93).
- *
- * When a subagent asks its person something ("Refund all $200, or half?"),
- * the notice reaches them in their chat app under the subagent's name, with
- * one button per option and one to answer in their own words. A tap answers
- * at once; "Answer in words" opens a prompt: on Telegram, a reply to it; in
- * Slack, Discord and Teams, their next message in their chat with Standing
- * Orders ("cancel" leaves it). Either way the answer goes through the same
- * door as the card's own panel (answerSubagentQuestion): once, and only from
- * the person it was asked of. Answered anywhere, every button retires.
- */
 import { randomBytes } from "node:crypto";
 import { partContent } from "./chat-delivery-state.js";
 import { answerSubagentQuestion } from "./subagent-work.js";
 import { labelOf } from "./subagent-admin.js";
 import { telegramButton } from "./contracts/telegram-callback.js";
-/** The key notifyPeople gives a subagent's question: flow-card:<card>:teammate-q:<question>:<person>. */
 export const SUBAGENT_Q_KEY = /^flow-card:[1-9][0-9]{0,14}:teammate-q:([1-9][0-9]{0,14}):/;
 export const IN_WORDS = "Answer in words";
 const PROMPT_MS = 30 * 60_000;
 const ANSWER_CHARS = 2000;
-/** The question a notice is about, while it is still open. */
 export function openQuestionOf(store, dedupeKey) {
     const match = SUBAGENT_Q_KEY.exec(dedupeKey);
     const question = match === null ? null : store.subagentQuestion(Number(match[1]));
     return question !== null && question.state === "open" ? question : null;
 }
 const who = (store, question) => { const mate = store.getSubagent(question.subagent); return mate === null ? "Your subagent" : labelOf(mate).split(" · ")[0]; };
-/** Everyone else's buttons retire once a question is answered anywhere. */
 function retireEverywhere(store, question, now, state) {
     store.retireTelegramQuestion(question, now);
     state?.prepare("UPDATE chat_question_action SET consumed=? WHERE provider=:provider AND question=? AND consumed IS NULL").run(now.toISOString(), question);
     state?.prepare("UPDATE chat_question_prompt SET consumed=? WHERE provider=:provider AND question=? AND consumed IS NULL").run(now.toISOString(), question);
 }
-// ---- Telegram ----------------------------------------------------------------------
-/** Buttons for the question, minted before the send (for the person it asks only); `place` stamps the message they land on. */
 export function telegramQuestionButtons(store, binding, question, now) {
     if (binding.approver !== question.askedOf)
         return null;
@@ -47,7 +30,6 @@ export function telegramQuestionButtons(store, binding, question, now) {
     rows.push([telegramButton(choices.at(-1).label, choices.at(-1).token)]);
     return { keyboard: rows, tokens: choices.map(one => one.token) };
 }
-/** A tapped question button, inside the update's transaction. */
 export function applyTelegramQuestionTap(store, binding, action, message, now) {
     if (action.consumedAt !== null || action.expiresAt <= now.toISOString())
         return [{ kind: "ack", text: "That was already answered, or these buttons are too old." }];
@@ -66,7 +48,6 @@ export function applyTelegramQuestionTap(store, binding, action, message, now) {
     const label = question.options.find(one => one.id === action.choice)?.label ?? action.choice;
     return [{ kind: "ack", text: "Answered" }, { kind: "edit", text: `${message.text}\n\n✅ You answered: ${label}. ${answered.said}`.slice(0, 4000) }];
 }
-/** A reply to the "answer in words" prompt, inside the update's transaction. */
 export function applyTelegramQuestionReply(store, binding, prompt, text, now) {
     if (prompt.binding !== binding.id)
         return null;
@@ -79,8 +60,6 @@ export function applyTelegramQuestionReply(store, binding, prompt, text, now) {
     retireEverywhere(store, prompt.question, now);
     return answered.ok ? `✅ ${answered.said}` : answered.said;
 }
-// ---- Slack, Discord, Teams ---------------------------------------------------------
-/** A question notice as chat parts (the buttons on the last), or null when it isn't one, isn't for this person, or was answered. */
 export function questionParts(store, notification, binding) {
     const question = openQuestionOf(store, notification.dedupeKey);
     if (question === null || question.askedOf !== binding.approver)
@@ -89,7 +68,6 @@ export function questionParts(store, notification, binding) {
             question: { id: question.id, choices: [...question.options.map(one => ({ choice: one.id, label: one.label })), { choice: null, label: IN_WORDS }] },
             ...(notification.link === null ? {} : { link: { label: "Open", path: notification.link } }) }];
 }
-/** The live buttons on one part, in the order they were minted. */
 export function chatQuestionButtons(state, part, now) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE provider=:provider AND id=?").get(part);
     const content = row === undefined ? null : partContent(String(row["payload"]));
@@ -97,8 +75,6 @@ export function chatQuestionButtons(state, part, now) {
     return state.prepare("SELECT token,choice FROM chat_question_action WHERE provider=:provider AND part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
         .map(one => ({ token: String(one.token), label: (labels.get(one.choice ?? "") ?? IN_WORDS).slice(0, 75), words: one.choice === null }));
 }
-/** Show the tapped notice again with the answer, and without its buttons. A notice that was dropped isn't brought back:
- * the line goes as a new message. */
 function repaint(state, part, event, line, now) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE provider=:provider AND id=?").get(part);
     const before = row === undefined ? { text: "" } : partContent(String(row["payload"]));
@@ -106,14 +82,12 @@ function repaint(state, part, event, line, now) {
     if (!state.repaint(part, content))
         state.plan(event.id, [{ text: line }], now);
 }
-/** A tapped question button, inside the action's transaction; false when the token isn't one. */
 export function applyChatQuestionTap(options, event, binding, token, now) {
     const { store, state } = options;
     const action = state.prepare("SELECT a.token,a.part,a.question,a.choice,a.expires,a.consumed,p.message,e.binding AS owner,e.channel FROM chat_question_action a JOIN chat_part p ON p.provider=a.provider AND p.id=a.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event WHERE a.provider=:provider AND a.token=?").get(token);
     if (action === undefined)
         return false;
     const say = (text) => state.plan(event.id, [{ text }], now);
-    // Bound to the person, the chat and the exact message the button rode.
     if (Number(action["owner"]) !== binding.id || action["channel"] !== event.channel || action["message"] !== event.ts) {
         say("That button expired or was already used.");
         return true;
@@ -127,7 +101,6 @@ export function applyChatQuestionTap(options, event, binding, token, now) {
         return true;
     }
     if (action["choice"] === null) {
-        // One open prompt per person, across flow decisions and questions: the newest is the one the next message answers.
         state.prepare("UPDATE chat_question_prompt SET consumed=? WHERE provider=:provider AND binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
         state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE provider=:provider AND binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
         state.prepare("INSERT INTO chat_question_prompt(provider,id,binding,question,created,expires) VALUES(:provider,(SELECT COALESCE(MAX(id),0)+1 FROM chat_question_prompt WHERE provider=:provider),?,?,?,?)").run(binding.id, questionId, now.toISOString(), new Date(now.getTime() + PROMPT_MS).toISOString());
@@ -145,7 +118,6 @@ export function applyChatQuestionTap(options, event, binding, token, now) {
     state.finish(event.id);
     return true;
 }
-/** The person's message while an "answer in words" prompt is open: the answer. false when none is open. */
 export function answerChatQuestionPrompt(options, event, binding, input, now) {
     const { store, state } = options;
     if (event.channel !== binding.channel)
@@ -166,7 +138,6 @@ export function answerChatQuestionPrompt(options, event, binding, input, now) {
             say("Send the answer itself, or “cancel”.");
             return true;
         }
-        // A message the chat cut short is never taken as part of an answer.
         if ((input.originalLength ?? 0) > input.text.length || said.length > ANSWER_CHARS) {
             say(`That's too long to take from here. Keep it under ${ANSWER_CHARS.toLocaleString("en-US")} characters, or answer on the card.`);
             return true;