toolroll 0.9.103 → 0.9.105

package/dist/chat-evidence.js

@@ -1,26 +1,6 @@
-/**
- * Shared, authorized evidence selection for the chat engine: the saved
- * screenshots of one EXACT finished result, for every chat surface.
- *
- * The one road a chat tool takes to a result's images. It proves the same
- * things `readChatResult` proves — the task is in the approver's projects,
- * the run belongs to that task and finished — but it does not require the
- * revision snapshot's terminal diff: a scout's report, a read-only or a
- * no-image result is answered honestly as "no images here" rather than
- * refused or silently swapped for a builder's result. Every image it names
- * was read through `readVerifiedArtifact` and passed `validateScreenshotBytes`
- * this instant; a failed, shortened or redacted capture is named as
- * unavailable, in plain words that carry no path, digest or credential.
- *
- * Nothing here is authority for a send: a channel that delivers files
- * re-proves access and re-reads the bytes with `verifyResultImage`
- * immediately before every upload, including retries.
- */
 import { createHash } from "node:crypto";
 import { readVerifiedArtifact, scanForSecrets, SCREENSHOT_BYTE_CAP, validateScreenshotBytes } from "./evidence.js";
-/** How many images one turn may select for delivery; more is a flood, not an answer. The rest are one more ask away, by offset or by id. */
 export const RESULT_IMAGES_PER_TURN_CAP = 8;
-/** The plain words for a screenshot record that must not travel. Null means the record itself is fine. */
 export function screenshotRecordProblem(artifact) {
     if (artifact.kind !== "screenshot")
         return "the saved file is not a screenshot";
@@ -36,7 +16,6 @@ export function screenshotRecordProblem(artifact) {
         return "the saved file is too large to send";
     return null;
 }
-/** The record, then the bytes: verified against the row read now, and proved to be a bounded PNG or JPEG. */
 function readScreenshot(evidenceRoot, artifact) {
     const problem = screenshotRecordProblem(artifact);
     if (problem !== null)
@@ -49,17 +28,9 @@ function readScreenshot(evidenceRoot, artifact) {
         return { ok: false, problem: proven.content.length > SCREENSHOT_BYTE_CAP ? "the saved file is too large to send" : "the saved file is not a PNG or JPEG" };
     return { ok: true, bytes: proven.content, format: checked.kind };
 }
-/** Telegram's own caption ceiling for a document (Bot API sendDocument, checked 2026-09-16). Ours are far shorter by construction. */
 export const RESULT_IMAGE_CAPTION_MAX_CHARS = 1_024;
-/** The longest task label a caption or file name carries. A task id is at most 64 characters at every tool boundary. */
 const RESULT_TASK_LABEL_MAX_CHARS = 64;
-/** A bot token's shape, the one credential the secret scanner does not know. */
 const BOT_TOKEN_SHAPE = /\b\d{5,}:[A-Za-z0-9_-]{20,}\b/;
-/**
- * Is this text safe to show a third-party transport as identity? Nothing
- * credential-shaped, nothing that steers a terminal or a renderer, nothing
- * longer than an id may be. A caption or file name shows only what passes.
- */
 export function displayIdentityProblem(text) {
     if (text.length === 0 || text.length > RESULT_TASK_LABEL_MAX_CHARS)
         return "too long";
@@ -69,40 +40,23 @@ export function displayIdentityProblem(text) {
         return "control or space characters";
     return null;
 }
-/**
- * The task as a caption or file name may show it. A plain id is itself,
- * with any character a file name cannot hold replaced. A credential-shaped
- * id (a task filed under a token-like name, on purpose or by accident) is
- * never repeated to Telegram: it shows as a stable opaque label instead,
- * while the exact id stays in the typed part, the bindings and the link.
- */
 export function resultTaskLabel(taskId) {
     if (displayIdentityProblem(taskId) !== null)
         return `task-${createHash("sha256").update(taskId).digest("hex").slice(0, 12)}`;
     return taskId.replace(/[^A-Za-z0-9._-]/g, "-");
 }
-/** The caption: the task's display label, the exact result and the position — identity a person can read, nothing a person or a model typed. */
 export function resultImageCaption(task, run, ordinal, total, current) {
     return `${resultTaskLabel(task)} · result #${run} · screenshot ${ordinal} of ${total}${current ? "" : " · older version"}`.slice(0, RESULT_IMAGE_CAPTION_MAX_CHARS);
 }
-/** The upload name: task label, result and artifact identity — derivable from the typed part alone, never a path. */
 export function resultImageFileName(task, run, artifact, format) {
     return `${resultTaskLabel(task)}-result-${run}-${artifact}.${format === "png" ? "png" : "jpg"}`;
 }
-/**
- * A persisted caption, checked again at send and retry time: a row planned
- * before this rule, or one edited by hand, may carry the raw task id. A
- * caption that would show a credential, a control character or more than
- * Telegram's ceiling is rebuilt from the part's typed identity instead —
- * the exact task and run stay bound; only the words on the wire change.
- */
 export function safeResultImageCaption(text, taskId, run) {
     const safe = text.length > 0 && text.length <= RESULT_IMAGE_CAPTION_MAX_CHARS
         && scanForSecrets(text).length === 0 && !BOT_TOKEN_SHAPE.test(text)
         && !/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f]/.test(text);
     return safe ? text : `${resultTaskLabel(taskId)} · result #${run} · screenshot`;
 }
-/** The page or the exact ids one ask selects from a result's images; a refusal names what to choose instead. */
 export function pickResultImages(images, pick, cap) {
     if (pick?.images !== undefined) {
         if (pick.offset !== undefined)
@@ -125,16 +79,6 @@ export function pickResultImages(images, pick, cap) {
     const selected = images.slice(offset, offset + cap);
     return { ok: true, selected, nextOffset: offset + selected.length < images.length ? offset + selected.length : null };
 }
-/**
- * Select the images of precisely the result named. With no run, the latest
- * finished result of THAT execution — and only while it is the current
- * version: a newer revision is said, never switched to. A run must belong
- * to the task and have finished; a role that delivers no images (a
- * reviewer, a planner) is not a result at all. Every deliverable image is
- * listed with its position; `selected` is the page (or the exact ids) this
- * ask delivers, at most the per-turn cap, and `nextOffset` says where the
- * rest begins so the remaining images are one more ask away, never lost.
- */
 export function selectResultImages(store, who, evidenceRoot, task, run, pick) {
     const ref = store.lookupRef(task);
     if (ref?.repo == null || !who.repos.includes(ref.repo))
@@ -181,15 +125,6 @@ export function selectResultImages(store, who, evidenceRoot, task, run, pick) {
             title: store.getTask(task)?.title ?? task, images, selected: picked.selected, nextOffset: picked.nextOffset, unavailable, report: artifacts.some(one => one.kind === "report"),
         } };
 }
-/**
- * The send-time proof, run immediately before EVERY upload including
- * retries: the task is still in the projects this channel may reach now,
- * the run still belongs to it and finished, the artifact row is still the
- * one the part was planned from (same run, same recorded hash — a changed
- * record is a changed provenance, refused), and the bytes read now still
- * verify and are still a bounded PNG or JPEG. Returns the original bytes;
- * nothing is transformed.
- */
 export function verifyResultImage(store, evidenceRoot, repos, part) {
     const ref = store.lookupRef(part.taskId);
     if (ref?.repo == null || !repos.includes(ref.repo))

package/dist/chat-flow.js

@@ -1,30 +1,3 @@
-/**
- * Flow decisions in Slack, Discord and Teams (v88): the Approve / Edit /
- * Send back that Telegram has (telegram-flow.ts), on the notice itself.
- *
- * - The notice carries the draft (split over as many parts as it needs, so
- *   what is approved is what was read) and the buttons on its last part.
- * - Approve decides through the same door as the console (decideFlowCard),
- *   as the paired person, for exactly the visit the notice was about, then
- *   repaints the notice with what happened and no buttons.
- * - Edit and Send back open a prompt: the person's next message in their
- *   chat with Toolroll is the new draft (which comes back with fresh
- *   buttons) or the note. "cancel" leaves it, and a prompt lapses after
- *   30 minutes. Chat apps can't all name the message a reply answers, so
- *   the prompt says plainly what the next message does.
- *
- * Every button is one opaque token for one visit of one card, on the part it
- * rides: a tap on any other message, from anyone but the paired person, or
- * for a card that moved on, changes nothing.
- *
- * A "Send to me" visit (flow-send.ts) is one notice with its links; a "Person
- * chooses" visit is the same with the zone's own options as buttons. Instead
- * of a tap, a reply in the notice's thread is the note for where replies go;
- * the first other message in their chat is asked about once ("Use this as
- * your note?"), and everything else goes to the lead as usual. Choices are
- * made through chooseFlowCard, by that person alone, for exactly that visit,
- * and spend that visit's buttons in every chat app.
- */
 import { cardContent } from "./chat-card-part.js";
 import { LIMITS } from "./decision.js";
 import { keptDraft } from "./flow-draft.js";
@@ -43,11 +16,9 @@ export const CHAT_FLOW_LABELS = { approve: "Approve", edit: "Edit", "send-back":
 const PART_CHARS = 2800;
 const PROMPT_MS = 30 * 60_000;
 const DRAFT_LIMIT = 4000;
-/** Words kept as written, line breaks and all; only control characters go. */
 export function chatFlowText(text) {
     return text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").replace(/\n{3,}/g, "\n\n").trim();
 }
-/** Split on line breaks where it can, so a draft reads as written. */
 function pieces(text) {
     const out = [];
     let rest = text;
@@ -62,7 +33,6 @@ function pieces(text) {
     out.push(rest);
     return out;
 }
-/** The buttons a visit gets: Approve always, Edit when there is a draft, Send back when the zone sends back somewhere. */
 function actionsFor(waiting) {
     return ["approve",
         ...(waiting.draft !== null && waiting.card.outputs[waiting.draft.id] !== undefined ? ["edit"] : []),
@@ -72,22 +42,16 @@ function decisionParts(text, visit, link) {
     const all = pieces(chatFlowText(text));
     return all.map((piece, index) => index < all.length - 1 ? { text: piece } : { text: piece, flow: visit, ...(link === null ? {} : { link }) });
 }
-/** A sent visit's links as a part's buttons: the first as its link, the rest beside it. */
 function sendLinks(paths) {
     return { ...(paths[0] === undefined ? {} : { link: paths[0] }), ...(paths.length > 1 ? { also: paths.slice(1) } : {}) };
 }
-/** The most an item list's part carries here, as the app renders it — a Slack section (2,800), Discord's plain message
- * content (2,000), a Teams message as long as Telegram's — less room for the line a tap adds under it. */
 const ITEMS_LIMIT = { slack: PART_CHARS - 300, discord: 2000 - 300, teams: 4096 - 300, telegram: 4096 - 300 };
-/** After research (flow-items.ts): the message with each item numbered under the summary, its words cleaned as every
- * other flow message's are, in as few parts as the app's limit allows (one, unless head, links and tail alone overflow). */
 function itemsText(content, subject, app) {
     if (app === undefined || content.items === undefined || content.items.length === 0)
         return null;
     const message = cleanFlowMessage({ head: subject, summary: content.summary, items: content.items, tail: flowSendTail(content) }, chatFlowText);
     return fitFlowMessage(message, ITEMS_LIMIT[app], shaped => renderReply(shaped, app).length);
 }
-/** A "Send to me" notice as chat parts: what was done, then its links; null when it isn't one. */
 export function flowSendParts(store, notification, app) {
     const visit = FLOW_SEND_KEY.exec(notification.dedupeKey);
     const kept = visit === null ? null : store.flowSend(Number(visit[1]), Number(visit[2]));
@@ -101,10 +65,6 @@ export function flowSendParts(store, notification, app) {
     const all = pieces(chatFlowText(`${notification.subject}\n\n${notification.body}`));
     return [...all.map((piece, index) => index < all.length - 1 ? { text: piece } : { text: piece, ...sendLinks(flowSendPaths(content)) }), ...card];
 }
-/**
- * A "flow-decision" notice as chat parts, or null when it isn't one (or the
- * card has already moved on, and there is nothing left to decide).
- */
 export function flowDecisionParts(store, notification, app) {
     const choose = FLOW_CHOOSE_KEY.exec(notification.dedupeKey);
     if (choose !== null) {
@@ -128,8 +88,6 @@ export function flowDecisionParts(store, notification, app) {
         return null;
     return decisionParts(`${notification.subject}\n\n${notification.body}`, { card: waiting.card.id, entry: waiting.card.entry, actions: actionsFor(waiting) }, notification.link === null ? null : { label: "Open", path: notification.link });
 }
-/** The live buttons on one part, in the order they were minted: a decision's, a choice's options in their order, or
- * "Use this as your note?" Yes / No. `key` is unique on the part (Slack names each button by it). */
 export function chatFlowButtons(state, part, now) {
     const decide = state.prepare("SELECT token,action FROM chat_flow_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), action: one.action, label: CHAT_FLOW_LABELS[one.action], key: one.action.replace("-", "_") }));
@@ -144,29 +102,20 @@ const retire = (state, card, entry, now) => {
     state.prepare("UPDATE chat_flow_choice SET consumed=? WHERE provider=:provider AND card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
     state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE provider=:provider AND card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
 };
-/** Show the tapped notice again with what happened, 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"]));
-    // An item list (flow-items.ts) stays whole and keeps its bold titles and labelled links; only plain text is capped.
     const content = { text: before.voice === true ? `${before.text}\n\n${line}` : `${before.text}\n\n${line}`.slice(0, PART_CHARS + 400), edit: event.ts, ...(before.voice === true ? { voice: true } : {}),
         ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
     if (!state.repaint(part, content))
         state.plan(event.id, [{ text: line }], now);
 }
-/**
- * A tapped flow button, inside the action's transaction. false when the
- * token isn't a flow button (the caller looks for a proposal's); otherwise
- * the event is finished and anything to say is planned on it.
- */
 export function applyChatFlowTap(options, event, binding, token, repos, now) {
     const { store, state } = options;
     const action = state.prepare("SELECT a.token,a.part,a.card,a.entry,a.action,a.expires,a.consumed,p.message,e.binding AS owner,e.channel FROM chat_flow_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 applyChatChoiceTap(options, event, binding, token, repos, now) || applyChatNoteTap(options, event, binding, token, repos, now);
     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. Ask for the current state before trying again.");
         return true;
@@ -205,7 +154,6 @@ export function applyChatFlowTap(options, event, binding, token, repos, now) {
         state.finish(event.id);
         return true;
     }
-    // One open prompt per person: the newest question is the one the next message answers.
     state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE provider=:provider AND binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
     state.prepare("UPDATE chat_question_prompt SET consumed=? WHERE provider=:provider AND binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
     state.prepare("INSERT INTO chat_flow_prompt(provider,id,binding,card,entry,mode,created,expires) VALUES(:provider,(SELECT COALESCE(MAX(id),0)+1 FROM chat_flow_prompt WHERE provider=:provider),?,?,?,?,?,?)")
@@ -216,14 +164,12 @@ export function applyChatFlowTap(options, event, binding, token, repos, now) {
         : `What should change on “${waiting.card.title}”? Your next message here is the note, and the card goes back to ${back} with it. Send “cancel” to leave it where it is.`);
     return true;
 }
-/** A tapped option of a "Person chooses" notice; false when the token isn't one. */
 function applyChatChoiceTap(options, event, binding, token, repos, now) {
     const { store, state } = options;
     const tapped = state.prepare("SELECT c.token,c.part,c.card,c.entry,c.choice,c.label,c.expires,c.consumed,p.message,e.binding AS owner,e.channel FROM chat_flow_choice c JOIN chat_part p ON p.provider=c.provider AND p.id=c.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event WHERE c.provider=:provider AND c.token=?").get(token);
     if (tapped === 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(tapped["owner"]) !== binding.id || tapped["channel"] !== event.channel || tapped["message"] !== event.ts) {
         say("That button expired or was already used. Ask for the current state before trying again.");
         return true;
@@ -260,7 +206,6 @@ function applyChatChoiceTap(options, event, binding, token, repos, now) {
     state.finish(event.id);
     return true;
 }
-/** A reply that is the note for where a choice's replies go; `say` answers on the message it came from. */
 function replyAsNote(options, binding, said, cutShort, visit, repos, now) {
     const { store } = options;
     if (said === "")
@@ -272,7 +217,6 @@ function replyAsNote(options, binding, said, cutShort, visit, repos, now) {
     const chosen = chooseFlowCard(store, { card: visit.card, entry: visit.entry, choice: null, note: said, actor: binding.approver, where: options.label, repos }, now);
     return chosen.ok ? { ok: true, said: chosen.said } : { ok: false, said: chosen.message };
 }
-/** The choice a part's message carries, by the message any of its parts was posted as (a long notice is several). */
 function choiceOnMessage(state, binding, channel, message) {
     const row = state.prepare(`SELECT c.card,c.entry,MAX(c.consumed IS NULL) AS live FROM chat_part p JOIN chat_event e ON e.provider=p.provider AND e.id=p.event
     JOIN chat_part q ON q.provider=p.provider AND q.event=p.event JOIN chat_flow_choice c ON c.provider=q.provider AND c.part=q.id
@@ -280,12 +224,6 @@ function choiceOnMessage(state, binding, channel, message) {
         .get(binding.id, channel, message);
     return row === undefined ? null : { card: Number(row["card"]), entry: Number(row["entry"]), live: Number(row["live"]) === 1 };
 }
-/**
- * A message in the person's own chat while one of their choices waits. Only a reply in the Choose notice's thread (Slack,
- * Discord) is the note. Any other message there is the lead's, except the first one after a choice that takes replies:
- * that one is asked about, once — "Use this as your note?" — and only Yes makes it the note (No passes it on to the lead).
- * false when the message isn't about a choice at all.
- */
 export function answerChoiceMessage(options, event, binding, input, now, repos) {
     const { store, state } = options;
     if (event.kind !== "message" || event.channel !== binding.channel || input.lead === true)
@@ -319,7 +257,6 @@ export function answerChoiceMessage(options, event, binding, input, now, repos)
         }
         if (said === "" || phoneCommand(said) !== null)
             return false;
-        // The newest choice of theirs still open here that takes a reply and hasn't asked yet.
         const open = state.prepare(`SELECT DISTINCT c.card,c.entry FROM chat_flow_choice c JOIN chat_part p ON p.provider=c.provider AND p.id=c.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event
       WHERE c.provider=:provider AND e.binding=? AND c.consumed IS NULL AND c.expires>? AND NOT EXISTS (SELECT 1 FROM chat_flow_note n WHERE n.provider=c.provider AND n.card=c.card AND n.entry=c.entry) ORDER BY c.rowid DESC`)
             .all(binding.id, now.toISOString());
@@ -331,14 +268,12 @@ export function answerChoiceMessage(options, event, binding, input, now, repos)
             const to = visit.definition.stages.find(stage => stage.id === target)?.title ?? target;
             state.plan(event.id, [{ text: `Use this as your note on “${visit.card.title}”?\nYes sends it to ${to}. No passes it to the lead.`,
                     note: { card: visit.card.id, entry: visit.card.entry, held: event.id } }], now);
-            // What it said is kept beside its question until answered: the event's own copy is cleared once it is handled.
             state.prepare("UPDATE chat_flow_note SET words=? WHERE provider=:provider AND held=?").run(JSON.stringify({ text: input.text, ...(input.originalLength === undefined ? {} : { originalLength: input.originalLength }) }), event.id);
             return true;
         }
         return false;
     });
 }
-/** Yes or No to "Use this as your note?"; false when the token isn't one. */
 function applyChatNoteTap(options, event, binding, token, repos, now) {
     const { store, state } = options;
     const tapped = state.prepare("SELECT n.token,n.part,n.card,n.entry,n.held,n.words,n.answer,n.expires,n.consumed,p.message,e.binding AS owner,e.channel FROM chat_flow_note n JOIN chat_part p ON p.provider=n.provider AND p.id=n.part JOIN chat_event e ON e.provider=p.provider AND e.id=p.event WHERE n.provider=:provider AND n.token=?").get(token);
@@ -365,7 +300,6 @@ function applyChatNoteTap(options, event, binding, token, repos, now) {
         return true;
     }
     if (tapped["answer"] === "no") {
-        // Passed on as the message it was, to the lead, once.
         state.enqueue({ id: chatHash(`${held.id}:lead`), installation: held.installation, binding: held.binding, kind: "message", channel: held.channel, member: held.member,
             ts: held.ts, thread: held.thread, payload: { ...words, lead: true }, created: now.toISOString() });
         repaint(state, part, event, "Passed to the lead.", now);
@@ -386,10 +320,6 @@ function applyChatNoteTap(options, event, binding, token, repos, now) {
     state.finish(event.id);
     return true;
 }
-/**
- * A message from the person while a prompt is open: the new draft or the
- * note. false when no prompt is open (the message goes on as usual).
- */
 export function answerChatFlowPrompt(options, event, binding, input, repos, now) {
     const { store, state } = options;
     if (event.channel !== binding.channel)
@@ -417,8 +347,6 @@ export function answerChatFlowPrompt(options, event, binding, input, repos, now)
             say(mode === "edit" ? "Send the text itself, or “cancel”." : "Say what should change, or send “cancel”.");
             return true;
         }
-        // A long message arrives cut short (the chat keeps its first 2,000 characters): never take part of one as the draft.
-        // An edit is a draft (DRAFT_LIMIT); a send-back is a note (LIMITS.note). Over it is refused with the limit, never cut.
         const cutShort = (input.originalLength ?? 0) > input.text.length;
         const most = mode === "edit" ? DRAFT_LIMIT : LIMITS.note;
         const limit = cutShort ? Math.min(LEAD_MESSAGE_MAX_CHARS, most) : most;

package/dist/chat-follow.js

@@ -1,30 +1,18 @@
-/** The loop every hosted chat connection (Slack, Discord, Teams) runs over its saved queue. */
 import { setTimeout as sleep } from "node:timers/promises";
-/** A pause that ends early, and quietly, when `signal` aborts. */
 export const abortablePause = (signal) => async (ms) => {
     try {
         await sleep(ms, undefined, { signal });
     }
     catch {
-        /* shutdown */
     }
 };
-/** The most parts one pass delivers (docs/plans/responsive-chat.md §3.5): a reply's parts go together, bounded. */
 export const DELIVER_PER_PASS = 5;
-/**
- * Works the queue while this connection stays the current, leased one: each pass first delivers parts already due,
- * then, only when none remain, takes in saved events and plans room messages, delivering up to DELIVER_PER_PASS parts
- * in all, and plans notifications (when they are on), checking it is still current between steps.
- * A pass waits while the connection isn't ready (offline, or the provider asked to retry later).
- */
 export async function workChatQueue(steps) {
     while (steps.same()) {
         if (!steps.ready()) {
             await steps.pause(1000);
             continue;
         }
-        // Up to five parts a pass (one event's whole reply, usually), stopping at the first rate signal (`ready`). True
-        // when nothing more was due.
         let parts = 0;
         const drain = async () => {
             while (parts < DELIVER_PER_PASS && steps.same() && steps.ready()) {
@@ -34,7 +22,6 @@ export async function workChatQueue(steps) {
             }
             return false;
         };
-        // Parts already due go first (§3.5): a new event's turn starts only once nothing earlier waits to be delivered.
         if (await drain() && steps.same()) {
             await steps.process();
             if (steps.same())

package/dist/chat-inbox.js

@@ -1,37 +1,15 @@
-/**
- * Chat channels as inboxes (v89): a Slack, Discord or Teams channel feeds a
- * flow.
- *
- * - Connecting happens in the channel itself: a paired approver sends
- *   "flow 12" (or "flow off"), which proves the channel is one they are in
- *   and that the flow is one they can change. One channel feeds one flow; a
- *   channel that follows a team conversation is left as it is.
- * - From then on every new message there — from anyone the app lets the bot
- *   see — is a card in that flow, and the bot says so in the message's
- *   thread. A reply in that thread joins the card's discussion.
- * - The card remembers where it came from, so an Update zone can answer in
- *   that same thread, through the chat of the person who connected it.
- *
- * Nothing here gives a message any authority: a card's work waits for the
- * usual approvals, and text that looks like a key never becomes a card.
- */
 import { flowCardHref, flowDefinitionOf } from "./flow-engine.js";
 import { addTriggerCard, CHAT_APP_NAMES, triggerConfigOf } from "./flow-triggers.js";
 import { ChatState, chatHash } from "./chat-delivery-state.js";
-/** "flow 12" or "flow off", after any mention of the bot; Telegram's "/flow 12" or "/flow@bot 12" too. */
 export const FLOW_WORDS = /^(?:<@[^>]+>\s*)?\/?flow(?:@[A-Za-z0-9_]{1,64})?\s+(off|[1-9][0-9]{0,9})\s*$/i;
 const TITLE_CHARS = 120;
-/** A channel's own id: Teams puts the thread's message id on the end of a channel conversation. */
 export const channelOf = (app, conversation) => app === "teams" ? conversation.replace(/;messageid=[0-9]+$/, "") : conversation;
-/** The flow a channel feeds, if it feeds one. */
 export function watchedChannel(store, app, installation, conversation) {
     return store.chatTriggerFor(app, installation, channelOf(app, conversation));
 }
-/** What a receiver needs to know about a channel message: whether the channel feeds a flow, and whether these are the words that connect one. */
 export function channelInbox(store, app, installation, conversation, text) {
     return { watched: watchedChannel(store, app, installation, conversation) !== null, command: FLOW_WORDS.test(text.trim()) };
 }
-/** "flow 12" / "flow off" from a paired approver in a channel: connect it to the flow, or stop it feeding one. */
 export function connectChannel(store, input, now) {
     const words = FLOW_WORDS.exec(input.text.trim());
     if (words === null)
@@ -64,18 +42,12 @@ export function connectChannel(store, input, now) {
     });
     return `This channel now feeds ${flow.name}: each new message here becomes a card, and replies in its thread join the card's discussion. Send “flow off” to stop.`;
 }
-/** A message's words as a card: the first line is the title, all of it the details when there's more. */
 function cardWords(text) {
     const clean = text.replace(/<@[A-Z0-9]+>/g, "").replace(/\r\n?/g, "\n").trim();
     const first = clean.split("\n")[0].trim();
     const title = first.length > TITLE_CHARS ? `${first.slice(0, TITLE_CHARS - 1).trimEnd()}…` : first;
     return { title: title || "Message", description: clean === title ? null : clean.slice(0, 4000) };
 }
-/**
- * A message in a channel that feeds a flow: a new card (and what to say in
- * its thread), a reply that joins a card's discussion (nothing to say), or
- * why it was left out.
- */
 export function takeChannelMessage(store, trigger, message, now) {
     const config = triggerConfigOf(trigger);
     if (config?.kind !== "chat")
@@ -84,7 +56,6 @@ export function takeChannelMessage(store, trigger, message, now) {
     if (message.text.trim() === "")
         return { said: null };
     if (message.thread !== message.ts) {
-        // A reply in the thread of a message that became a card: it joins that card's discussion.
         const card = store.flowTriggerCard(trigger.id, `msg:${message.thread}`);
         if (card !== null && store.getFlowCard(card)?.state === "active")
             store.addFlowComment({ card, author: `${message.who} (${name})`.slice(0, 64), body: message.text.slice(0, 2000), mentions: [] }, now);
@@ -101,11 +72,6 @@ export function takeChannelMessage(store, trigger, message, now) {
     }
     return { said: made.made === "skipped" && made.note !== null ? `Not added: ${made.note.replace(/^[^:]+: /, "")}.` : null };
 }
-/**
- * Answer in the thread a card came from (an Update zone): one message,
- * through the chat of whoever connected the channel. Idempotent per card
- * visit, so a retried step never answers twice.
- */
 export function replyInChannel(store, source, visit, text, now) {
     if (source.app !== "slack" && source.app !== "discord" && source.app !== "teams")
         return { ok: false, said: `Answering in a ${CHAT_APP_NAMES[source.app] ?? source.app} group isn't supported yet, so nothing was posted. The card's link is in the group.` };

package/dist/chat-live-schema.js

@@ -1,17 +1,3 @@
-/**
- * v157: live replies in Slack, Discord and Teams (docs/plans/responsive-chat.md §3.2). New tables only, so a saved row
- * reads as it did. Kept beside nothing else so the update road can read the list without loading the store.
- *
- * chat_live: one "Working on it…" message per received event, so the final answer can replace it. Separate from
- * chat_part: planning the reply still adds its own parts (the first one edits this message), and the event stays
- * queued until then. state: creating (asked the app to post it, no answer yet) → placed (its id is known), or
- * uncertain (a crash or a lost answer left it unknown whether it was posted: never posted again), then finalized
- * (the reply was planned onto it) or abandoned (live edits stopped: access changed or the app refused).
- *
- * chat_ack: the 👀 on a person's message, put on when it arrives and taken off once the answer (or the failure
- * notice) is delivered. state: sent (on, to take off later), done (taken off, or nothing to take off: Teams typing),
- * skipped (not put on: the app refused, or it waited too long).
- */
 export const V157_SCHEMA = `
 CREATE TABLE IF NOT EXISTS chat_live (
  provider TEXT NOT NULL CHECK (provider IN ('slack','discord','teams')), event TEXT NOT NULL,