toolroll 0.9.103 → 0.9.105

package/dist/chat-delivery.js

@@ -1,4 +1,3 @@
-/** Shared saved replies, explicit confirmations and progress for private chat transports. */
 import { answerChatQuestionPrompt, applyChatQuestionTap, questionParts } from "./subagent-question.js";
 import { applyChatAskTap, chatAskText } from "./chat-ask.js";
 import { channelRepos, resolveChannelLead, proposalPreview, proposalOutcomeText, confirmedLink, confirmedCardText, replyContextFor, mirrorToTaskChat, focusContextFor, taskInCeiling, tooLongText, } from "./chat-channel.js";
@@ -30,18 +29,9 @@ import { isShotsKind, resultShotsFor } from "./result-shots.js";
 import { answersPrompt, applyDecideFeedback, applyDecideTap, decideFallbackLink, decideOffer, decideTargetOf, hasLiveDecideTokens, linksFor, mergedText, mintDecideButtons, offerFingerprint, openPromptFor, recordChatMerge } from "./chat-decide.js";
 import { mergePullRequest } from "./pull-request-flow.js";
 import { attentionSubjectOf, neverHeld, watchedPing } from "./agent-board.js";
-/**
- * The watch at a chat app's final fence (cockpit §3, R11), right before the network: a notice about an agent its
- * person has open now waits, as a held part, until the watch ends; then it is delivered as usual. The subject is the
- * part's own run, or its task's live build. Only a part planned with `watch` (never a security alert or the digest)
- * can be held. True: held, so nothing is sent now.
- */
 export function heldForWatch(state, store, part, event, approver, content, now) {
-    // Fail closed: only a notice planned as holdable (a kind a watch may hold) is ever held here.
     if (event.kind !== "notice" || content.watch !== true)
         return false;
-    // One part may cover several tasks (a grouped card, a batch): it waits only while every one of them is watched,
-    // until the first of those watches ends.
     const subjects = content.subjects ?? [{ ref: content.task ? store.lookupRef(content.task)?.id ?? null : null, run: content.run ?? null }];
     if (subjects.length === 0)
         return false;
@@ -86,7 +76,6 @@ export async function channelAccess(options, binding, ceiling) {
         state.revoke(options.identity.installation, nowOf(options));
         throw new ChatDeliveryError(`${options.label} account access changed`);
     }
-    // The network wait above can outlive a local disconnect or lease.
     if (!options.current() ||
         !state.live(binding) ||
         !state.owns(options.identity.installation, options.owner, nowOf(options)))
@@ -100,32 +89,20 @@ export async function channelAccess(options, binding, ceiling) {
         throw new ChatDeliveryError("Chat access changed");
     return latest;
 }
-// ---- decisions that finish in the chat (chat-decide.ts), the same in every app --------------------------------------
-/** Where a paired person taps: their binding, and the chat the card is in. */
 const decideSeat = (state, binding, chat = binding.channel) => ({ channel: state.provider, binding: binding.id, chat, approver: binding.approver, generation: binding.generation });
-/** What a card about one result, plan, failure or pull request may act on in this person's chat now, under their
- * current ceiling; null keeps its link. Reads only. */
 function decideOfferFor(options, binding, target, repos, now) {
     if (target == null)
         return null;
     const principal = verifyApproverStanding(options.store, binding.approver, binding.generation, repos);
     return principal.ok ? decideOffer(options.store, target, principal.who, now, options.state.provider, options.evidenceRoot) : null;
 }
-/** A card's buttons as a part carries them. */
 const decideRows = (rows) => rows.map(row => row.map(one => "token" in one ? { label: one.label, token: one.token } : { label: one.label, link: one.link }));
-/** The offer's buttons, minted now: they ride the part's message once it is sent (ChatState.partSent). */
 function mintDecide(options, binding, target, offer, now) {
     return { rows: decideRows(mintDecideButtons(options.store, decideSeat(options.state, binding), target, offer, now).rows) };
 }
-/** Said when a card that still waits for a tap can no longer be shown again in the chat. */
 const CARD_GONE = "This card can't be updated here now. Open Toolroll to finish this.";
-/**
- * A decide button (chat-decide.ts), inside the tap's transaction: the same door, words and two taps as on Telegram.
- * The card it rode is repainted in place; Request changes asks for the next message; a merge goes out after.
- */
 function applyChatDecideTap(options, event, binding, token, repos, now) {
     const { store, state } = options;
-    // The card the button rode: this person's part on that message.
     const row = state.prepare(`SELECT p.id, p.payload FROM chat_part p JOIN chat_event e ON e.provider = p.provider AND e.id = p.event
     WHERE p.provider = :provider AND e.binding = ? AND p.message = ? ORDER BY p.id DESC LIMIT 1`).get(binding.id, event.ts);
     const read = row === undefined ? null : readChatPart(String(row["payload"]));
@@ -140,8 +117,6 @@ function applyChatDecideTap(options, event, binding, token, repos, now) {
     if (tapped.edit !== undefined && row !== undefined && card !== null) {
         const { decide: _decide, link: _link, also: _also, edit: _edit, ...kept } = card;
         repainted = { ...kept, text: tapped.edit.text, ...(tapped.edit.rows.length === 0 ? {} : { decide: { rows: decideRows(tapped.edit.rows) } }) };
-        // A card that was dropped isn't brought back: what happened goes as a new message. A step that waits for a second
-        // tap can't be shown on it, so the person is sent to the task.
         if (!state.repaint(Number(row["id"]), repainted))
             replies.push({ text: tapped.edit.tokens.length === 0 ? tapped.ack : CARD_GONE });
     }
@@ -153,7 +128,6 @@ function applyChatDecideTap(options, event, binding, token, repos, now) {
     return tapped.merge === undefined || row === undefined || repainted === null ? null
         : { merge: tapped.merge, part: Number(row["id"]), shown: tapped.edit?.text ?? card?.text ?? "", content: repainted };
 }
-/** GitHub is a network call: after the tap's transaction, then the card says how it went, and the ledger too. */
 async function mergeFromChat(options, pending) {
     const { merge } = pending;
     let merged;
@@ -167,7 +141,6 @@ async function mergeFromChat(options, pending) {
     }
     recordChatMerge(options.store, merge, merged, nowOf(options));
     const { decide: _decide, ...kept } = pending.content;
-    // A merge that didn't land keeps a way to the task.
     options.state.repaint(pending.part, { ...kept, text: mergedText(pending.shown, merged),
         ...(merged.ok ? {} : { decide: { rows: decideRows(linksFor({ kind: "merge", taskId: merge.taskId, run: merge.runId })) } }) });
 }
@@ -179,9 +152,7 @@ export async function processChatEvent(options) {
     const event = state.next(identity.installation, now);
     if (!event)
         return false;
-    // The live message for this pass's turn, if any (chat-live.ts). Closed before any reply is planned.
     let live = null;
-    // Every reply planned from here lands on the event's live message when it has one (its first part edits it).
     const plan = (parts, at) => planWithLive(state, event.id, parts, at);
     try {
         if (event.kind === "pair") {
@@ -210,7 +181,6 @@ export async function processChatEvent(options) {
             ], nowOf(options));
             return true;
         }
-        // A channel as a flow's inbox (v89): "flow 12" connects it, and after that its messages are cards.
         if (event.kind === "message" && await channelInboxEvent(options, event))
             return true;
         const binding = event.binding === null ? null : state.bindingById(event.binding);
@@ -236,14 +206,10 @@ export async function processChatEvent(options) {
             return true;
         }
         const text = String(input.text ?? "");
-        // A subagent's question asked for this person's next message (v93): it is the answer.
         if (answerChatQuestionPrompt({ store, state, label: options.label }, event, binding, { text, ...(typeof input.originalLength === "number" ? { originalLength: input.originalLength } : {}) }, nowOf(options)))
             return true;
-        // A flow decision asked for this person's next message (Edit, Send back): it is the draft or the note.
         if (answerChatFlowPrompt({ store, state, label: options.label }, event, binding, { text, ...(typeof input.originalLength === "number" ? { originalLength: input.originalLength } : {}) }, repos, nowOf(options)))
             return true;
-        // After Request changes asked "What should change?": the person's next message in their own chat is the feedback
-        // (a reply in another message's thread keeps its own meaning).
         if (event.channel === binding.channel && text.trim() !== "" && phoneCommand(text) === null) {
             const prompt = openPromptFor(store, { channel: state.provider, binding: binding.id, chat: binding.channel }, nowOf(options));
             if (prompt !== null && answersPrompt(prompt, event.thread !== "" && event.thread !== event.ts ? event.thread : null)) {
@@ -252,19 +218,12 @@ export async function processChatEvent(options) {
                 return true;
             }
         }
-        // A "Person chooses" notice's thread reply is the note; the first other message after it is asked about (chat-flow.ts).
         if (answerChoiceMessage({ store, state, label: options.label }, event, binding, { text, ...(typeof input.originalLength === "number" ? { originalLength: input.originalLength } : {}), lead: input.lead === true }, nowOf(options), repos))
             return true;
-        // D5: a message naming a subagent ("@rosa …") is the lead's to read like any other: it asks the subagent for its
-        // person with a card they confirm (propose_subagent ask), never by the transport passing it on unseen.
-        // The task this message's turn is about, once chosen (kept on the event,
-        // so a reply planned after a restart names the same task).
         let about = typeof object(input.about).task === "string" ? { task: String(object(input.about).task), run: typeof object(input.about).run === "number" ? Number(object(input.about).run) : null } : null;
-        // Read-only commands answer from the database, never from a model.
         const command = phoneCommand(text);
         if (command !== null) {
             const now_ = nowOf(options);
-            // The task this chat chose to talk about (/tasks, /task <name>), if any.
             const surface = options.label.toLowerCase();
             const focusedId = store.chatFocus(surface, binding.id);
             const focusedTitle = focusedId === null ? null : phoneText(store.getTask(focusedId)?.title ?? focusedId, 64);
@@ -283,7 +242,6 @@ export async function processChatEvent(options) {
                 if (pick.kind === "one") {
                     store.setChatFocus(surface, binding.id, pick.id, now_);
                     const view = phoneTaskView(store, repos, pick.view, now_, options.evidenceRoot);
-                    // The status names its task (and result): a reply to it is about that task.
                     plan([{ text: phoneFocusText(view.text), ...(view.link === null ? {} : { link: view.link }), task: pick.view, ...(view.run === null ? {} : { run: view.run }) }], now_);
                 }
                 else if (pick.kind === "many") {
@@ -294,8 +252,6 @@ export async function processChatEvent(options) {
             }
             return true;
         }
-        // The team layer: `/team` anywhere, everything in a followed room, and a
-        // DM that chose a conversation. Its replies are planned like any other.
         const room = state.room(identity.installation, event.channel);
         const isRoom = event.channel !== binding.channel;
         if (isRoom || room !== null || roomCommand(text) !== null) {
@@ -321,17 +277,14 @@ export async function processChatEvent(options) {
             return true;
         }
         const request = chatHash(`${options.state.provider}:${binding.id}:${event.id}`).slice(0, 32);
-        // The live message answers only the owner's own message in their own chat: never the bot's, never a room.
         const ownMessage = event.kind === "message" && event.member !== identity.bot && event.member === binding.member && event.channel === binding.channel;
         const transport = ownMessage ? options.live?.(event, binding) ?? null : null;
-        // `ceiling`: the turn's; without one (still waiting) only the fixed "Waiting…" words may go, never the turn's.
         const openLive = (ceiling) => {
             if (transport === null)
                 return null;
             live ??= openChatLive({
                 state, event, installation: identity.installation, transport, shape: { asked: text, appOrigin: options.origin() },
                 fenced: () => options.current() && state.owns(identity.installation, options.owner, nowOf(options)) && state.live(binding),
-                // False only on a definite refusal; a failed proof (a "slow down", a lost answer) throws: that view is dropped.
                 standing: async () => {
                     if (ceiling === null)
                         return false;
@@ -387,9 +340,7 @@ export async function processChatEvent(options) {
             const contexts = state
                 .prepare("SELECT p.payload FROM chat_part p JOIN chat_event e ON e.provider=p.provider AND e.id=p.event WHERE p.provider=:provider AND e.binding=? AND e.channel=? AND (p.message=? OR e.thread=?) AND p.state='sent' ORDER BY p.id DESC LIMIT 100")
                 .all(binding.id, binding.channel, event.thread, event.thread)
-                // Context only: a part that can't be read adds none.
                 .flatMap((row) => { const read = readChatPart(String(row.payload)); return read.ok ? [read.value] : []; })
-                // A card is about the task it names, or the one confirming it filed.
                 .map((c) => {
                 if (c.task || c.proposal === undefined)
                     return c;
@@ -409,7 +360,6 @@ export async function processChatEvent(options) {
                 ], nowOf(options));
                 return true;
             }
-            // No reply target: the task this chat chose, when it still exists here.
             const focused = targets.length === 0 ? store.chatFocus(options.label.toLowerCase(), binding.id) : null;
             const focusTask = focused !== null && taskInCeiling(store, focused, repos) ? focused : null;
             const context = targets[0] ?? (focusTask === null ? null : { text: "", task: focusTask, run: null });
@@ -419,9 +369,7 @@ export async function processChatEvent(options) {
                     .prepare("UPDATE chat_event SET payload=? WHERE provider=:provider AND id=? AND state='queued'")
                     .run(JSON.stringify({ ...input, about }), event.id);
             }
-            // An unknown surface names no channel rather than a guess.
             const channel = leadChannelOf(options.label);
-            // Only ever the owner's own message in their own chat: never the bot's, never a room.
             const warm = warmTurn(options.warm !== undefined && ownMessage ? options.warm(event, binding) : {});
             const turnLive = openLive(resolved.who.ceilingDigest);
             const outcome = await runLeadTurn({
@@ -458,7 +406,6 @@ export async function processChatEvent(options) {
                 },
             }).finally(async () => {
                 warm.stop();
-                // Live edits end, and the one in flight settles, before anything of the reply is planned.
                 await turnLive?.close();
             });
             if (outcome.ok && !outcome.replayed && context?.task)
@@ -469,7 +416,6 @@ export async function processChatEvent(options) {
             if (!outcome.ok &&
                 "refused" in outcome &&
                 (outcome.refused === "concurrent" || outcome.refused === "backlog")) {
-                // The lead is answering, or messages sent earlier wait in the person's lead queue: this one waits its turn.
                 state.defer(event.id, outcome.refused === "backlog" ? "Waiting behind earlier messages" : "Assistant is answering another message", new Date(nowOf(options).getTime() + 5000));
                 await turnLive?.queued();
                 return true;
@@ -486,11 +432,7 @@ export async function processChatEvent(options) {
                 return true;
             }
         }
-        // A live message whose create never confirmed (this pass, or before a restart) is found first (Discord, by its
-        // nonce) or marked uncertain, so the reply edits the right message or none.
         if (!(await settleLive(state, event.id, transport, () => nowOf(options)))) {
-            // Whether the live message was posted is still unknown (its lookup failed): the reply waits, so it edits that
-            // message rather than leaving it behind.
             state.defer(event.id, "Reply is waiting to send", new Date(Math.max(nowOf(options).getTime() + 5000, Date.parse(state.retryAt(identity.installation)) || 0)));
             return true;
         }
@@ -517,12 +459,8 @@ export async function processChatEvent(options) {
         const reply = store
             .listLeadMessages(turn.thread, 200)
             .find((message) => message.turn === turn.id && message.role === "assistant")?.text ?? "The reply is no longer in the saved thread.";
-        // The lead's answer about one task names it: a reply to it stays on that task.
-        // Split as written, then shape each part: no cut ever lands inside a link, code or a bold anchor.
         const shapedParts = shapeReplyParts(reply, options.partSize ?? CHAT_PART_SIZE, { asked: text, appOrigin: options.origin() });
         const parts = (shapedParts.length > 0 ? shapedParts : splitChatText("")).map((text) => (about === null ? { text, voice: true } : { text, voice: true, task: about.task, ...(about.run === null ? {} : { run: about.run }) }));
-        // The lead's question to its owner: its options as buttons, then "Something else", in their own chat (any thread);
-        // in a room a tap is not their message, so the question and its options go out as text.
         const ask = store.leadAsk(turn.id);
         if (ask !== null)
             parts.push({ ...(event.channel === binding.channel ? { text: phoneText(ask.question, 1000), ask: { turn: ask.turn, options: ask.options } } : { text: phoneText(chatAskText(ask), 1000) }),
@@ -539,14 +477,12 @@ export async function processChatEvent(options) {
                 task: image.taskId,
                 run: image.run,
             });
-        // Cards first, so what a card leads to sits right under it. A card is an ordinary part: it confirms nothing.
         for (const proposal of cardsFirst(store.listLeadProposals(turn.thread, ["pending"]).filter((p) => p.turn === turn.id)))
             parts.push(isCardProposal(proposal) ? cardPart(proposal) : { text: "", proposal: proposal.id });
         plan(parts, nowOf(options));
         return true;
     }
     catch (error) {
-        // Nothing is planned while a live edit could still land.
         await live?.close();
         const problem = error instanceof ChatDeliveryError
             ? error
@@ -567,22 +503,16 @@ export async function processChatEvent(options) {
         return true;
     }
 }
-/**
- * A message in a channel (never a DM) that connects the channel to a flow,
- * or that the channel's flow takes as a card. False: not for an inbox.
- */
 async function channelInboxEvent(options, event) {
     const { store, identity } = options, state = options.state, app = state.provider;
     const binding = event.binding === null ? null : state.bindingById(event.binding);
     if (binding !== null && event.channel === binding.channel)
         return false;
     const body = readChatMessageBody(event.payload);
-    // One that can't be read is answered, by path, on the ordinary path.
     if (!body.ok)
         return false;
     const text = body.value.text ?? "";
     if (FLOW_WORDS.test(text.trim())) {
-        // Only a paired approver connects a channel, and only to a flow in their projects.
         if (binding === null || !state.live(binding)) {
             state.finish(event.id, true);
             return true;
@@ -597,13 +527,11 @@ async function channelInboxEvent(options, event) {
     const config = trigger === null ? null : triggerConfigOf(trigger);
     if (trigger === null || config?.kind !== "chat")
         return false;
-    // What the bot says goes through the chat of whoever connected the channel; if they're gone, nothing is taken.
     const grant = state.bindingById(config.binding);
     if (grant === null || !state.live(grant)) {
         state.finish(event.id, true);
         return true;
     }
-    // Teams names a thread by its first message on the conversation; Slack and Discord on the event.
     const root = app === "teams" ? /;messageid=([0-9]+)$/.exec(event.channel)?.[1] ?? event.ts : event.thread;
     const taken = takeChannelMessage(store, trigger, { app, conversation: event.channel, ts: event.ts, thread: root, text, who: binding?.approver ?? "someone" }, nowOf(options));
     if (taken.said === null) {
@@ -614,7 +542,6 @@ async function channelInboxEvent(options, event) {
     state.plan(event.id, [{ text: taken.said, channel: event.channel, ...(taken.link === undefined ? {} : { link: taken.link }) }], nowOf(options));
     return true;
 }
-/** Bound to the paired member, exact channel/message, pending proposal and current ceiling. */
 export function applyChatAction(options, event, binding, repos) {
     const state = options.state, { store } = options, now = nowOf(options), signals = [];
     let merging = null;
@@ -625,7 +552,6 @@ export function applyChatAction(options, event, binding, repos) {
             event.member !== binding.member ||
             (event.channel !== binding.channel && state.room(options.identity.installation, event.channel)?.kind !== "group"))
             return;
-        // A button the paired person tapped whose data couldn't be read is answered plainly: what was wrong, and that nothing was done.
         const body = readChatActionBody(event.payload);
         if (!body.ok || "problem" in body.value) {
             const problem = body.ok ? ("problem" in body.value ? body.value.problem : "") : body.issues.map(issue => issue.line).join("; ");
@@ -633,24 +559,19 @@ export function applyChatAction(options, event, binding, repos) {
             return;
         }
         const token = body.value.token;
-        // A result's, plan's, failure's or pull request's own button (chat-decide.ts).
         if (token.startsWith("d:")) {
             merging = applyChatDecideTap(options, event, binding, token, repos, now);
             return;
         }
-        // A flow decision's button (v88) is answered by the flow's own door.
         if (applyChatFlowTap({ store, state, label: options.label }, event, binding, token, repos, now))
             return;
-        // A subagent's question's button (v93) is answered by the question's own door.
         if (applyChatQuestionTap({ store, state, label: options.label }, event, binding, token, now))
             return;
-        // The lead's question to its owner: the tapped option becomes their next message.
         if (applyChatAskTap({ store, state }, event, binding, token, now))
             return;
         const saved = state
             .prepare("SELECT a.token,a.part,a.proposal,a.phase,a.expires,a.consumed,p.message,e.binding,e.channel,e.thread FROM chat_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);
-        // The saved button, read by its schema: one that can't be read is a spent button, never a guess.
         const read = saved === undefined ? null : readProposalActionRow({ ...saved });
         const action = read?.ok === true ? read.value : null;
         const invalid = !action ||
@@ -708,7 +629,6 @@ export function applyChatAction(options, event, binding, repos) {
         }
         else {
             const outcome = confirmLeadProposal(store, verified.who, proposal.id, now, {
-                // A paired chat seat speaks for its account's full authority (pairing is a full session's act).
                 authority: "full",
                 via: options.state.provider,
                 binding: binding.id,
@@ -731,8 +651,6 @@ export function applyChatAction(options, event, binding, repos) {
                     content.link = link;
             }
         }
-        // Repaint the original persisted card; retain one placement and fresh tokens. A card that was dropped isn't brought
-        // back: an outcome goes as a new message, and a card that still waits for a tap sends the person to Toolroll.
         if (!state.repaint(action.part, content)) {
             const { edit: _edit, proposal: _proposal, phase: _phase, ...asNew } = content;
             state.plan(event.id, [content.proposal === undefined ? asNew : { text: CARD_GONE }], now);
@@ -751,13 +669,6 @@ export function applyChatAction(options, event, binding, repos) {
         signal();
     return merging;
 }
-/**
- * Carry new conversation messages to every room that follows one: the
- * lead's replies, teammates' messages (never the room's own), and each
- * reply's pending cards, as ordinary parts sent to the room's channel. A
- * room is a grant from one exact pairing and is rechecked before each
- * message; a room nobody paired can carry waits.
- */
 export async function planRoomMessages(options) {
     const state = options.state, { store, identity } = options, now = nowOf(options);
     if (!state.owns(identity.installation, options.owner, now) || !options.current())
@@ -811,8 +722,6 @@ export async function planRoomMessages(options) {
         }
     }
 }
-/** Quiet mode: the task's one card (or its group's) in this person's chat, planned once and then repainted in
- * place whenever what it says changes. */
 function planQuietCard(options, binding, notification, now) {
     const { state, store, identity } = options;
     if (notification.taskRef === null || notification.taskId === null)
@@ -821,9 +730,6 @@ function planQuietCard(options, binding, notification, now) {
     const view = quietCardView(store, card.tasks, now, options.evidenceRoot, binding.approver);
     if (view === null)
         return;
-    // A card about one task is that task's: its person's watch may hold it at the final fence (never a security kind).
-    // A card about its tasks is theirs: its person's watch may hold it at the final fence while every one of them is
-    // watched (never for a security kind).
     const content = { text: view.text, link: view.link, ...(card.tasks.length === 1 ? { task: notification.taskId } : {}),
         ...(card.tasks.length > 0 && !neverHeld(notification.kind) ? { watch: true } : {}),
         ...(card.tasks.length > 1 && !neverHeld(notification.kind) ? { subjects: card.tasks.slice(0, 100).map(ref => ({ ref, run: null })) } : {}) };
@@ -843,26 +749,18 @@ function planQuietCard(options, binding, notification, now) {
     if (part !== undefined)
         store.setChatCardMessage(card.id, String(part.id), shown);
 }
-/** Any update for this person joins their open batch (two minutes from its first), and the batch's one message
- * is planned once, then repainted in place as more updates land. `notification`: an update that is not a finished
- * result (null for one that is). False when nothing in the batch reads as a line, so the update goes out on its own. */
 function planFinished(options, binding, taskRef, run, now, notification = null, repos = []) {
     const { state, store, identity } = options;
     const batch = store.chatBatchFor(`${state.provider}:${binding.id}`, taskRef, run, now, BATCH_MS, notification);
     const view = finishedView(store, batch, now, options.evidenceRoot, binding.approver);
     if (view === null)
         return false;
-    // A single update keeps its task and run, so a reply to it names that work.
     const single = batch.items.length === 1 ? batch.items[0] : null;
     const task = single === null ? null : store.refById(single.taskRef)?.externalId ?? null;
-    // Holdable when its fact is a kind a watch may hold (the batch line for a finished run, or the notification joining
-    // it); a batch of several holds only while every one of them is watched.
     const joining = notification === null ? null : options.store.notificationById(notification);
     const holdable = batch.items.length > 0 && (joining === null || !neverHeld(joining.kind));
     const about = { ...(task === null ? {} : { task }), ...(single?.run == null ? {} : { run: single.run }), ...(holdable ? { watch: true } : {}),
         ...(holdable && batch.items.length > 1 ? { subjects: batch.items.slice(0, 100).map(one => ({ ref: one.taskRef, run: one.run })) } : {}) };
-    // A message about one result, plan, failure or pull request acts in place (chat-decide.ts), as on Telegram: its
-    // buttons are minted only when what it offers changed, or its own were spent (Not now), so an unchanged repaint keeps them.
     const offer = decideOfferFor(options, binding, view.target, repos, now);
     const content = offer === null
         ? { text: view.text, link: view.link, ...(view.also === undefined ? {} : { also: view.also }), ...about }
@@ -887,18 +785,13 @@ function planFinished(options, binding, taskRef, run, now, notification = null,
         store.setChatBatchMessage(batch.id, String(part.id), shown);
     return true;
 }
-/** Screenshots with a result (result-shots.ts), planned after the result's own message: each an upload that follows
- * it in its thread (Slack, Discord), or one link to them (Teams). A failed check is one plain line instead. */
 function planResultShots(options, binding, notification, repos, id, now) {
     const { state, store, identity } = options;
     const plan = resultShotsFor(store, options.evidenceRoot, repos, notification);
     if (plan.kind === "none" || notification.taskId === null || notification.run === null)
         return;
     const where = { task: notification.taskId, run: notification.run };
-    // The result's message here: its finished-work batch (quiet), its progress card (every step), or the result's own
-    // notice. The transport threads the screenshots under it once it is posted, and holds them until then.
     const follows = (() => {
-        // A flow's screenshots follow the "Send to me" or "Person chooses" notice they go with.
         const visit = /^flow-shots:([1-9][0-9]*):([1-9][0-9]*)$/.exec(notification.dedupeKey);
         if (visit !== null) {
             for (const key of [`flow-send:${visit[1]}:${visit[2]}`, `flow-choose:${visit[1]}:${visit[2]}`]) {
@@ -924,7 +817,6 @@ function planResultShots(options, binding, notification, repos, id, now) {
     })();
     const image = (artifact, sha256) => ({ taskId: where.task, run: where.run, artifact, sha256 });
     const parts = plan.kind === "line" ? [{ text: plan.text, ...where }]
-        // Teams has no file upload here: one message that links to the saved result.
         : state.provider === "teams" ? [{ text: plan.shots.length === 1 ? plan.shots[0].caption : `${plan.shots[0].caption} · ${plan.shots.length} screenshots`,
                 image: image(plan.shots[0].artifact, plan.shots[0].sha256), shot: { follows: null }, ...where }]
             : plan.shots.map(one => ({ text: one.caption, image: image(one.artifact, one.sha256), shot: { follows }, ...where }));
@@ -932,7 +824,6 @@ function planResultShots(options, binding, notification, repos, id, now) {
         ts: "", thread: "", payload: {}, created: now.toISOString() });
     state.plan(id, parts, now);
 }
-/** One progress card per exact result; separate urgent facts retain their own review link. */
 export async function planChatNotifications(options) {
     const state = options.state, { store, identity } = options, bindings = state.bindings(identity.installation).filter(one => state.live(one));
     if (bindings.length === 0 ||
@@ -940,17 +831,14 @@ export async function planChatNotifications(options) {
         !options.current())
         return;
     const registry = await options.readProjects();
-    // An evening digest someone asked for is due: record it as their own notification, delivered below.
     try {
         enqueueEveningDigests(store, nowOf(options), options.evidenceRoot);
     }
-    catch { /* Retried on the next pass. */ }
+    catch { }
     enqueueLeadLapses(store, nowOf(options));
     const cursor = Number(state
         .prepare("SELECT notification FROM chat_runtime WHERE provider=:provider AND installation=?")
         .get(identity.installation)?.notification ?? 0);
-    // A person who paired after the cursor passed is still owed what wanted them before: once per pairing, their
-    // unresolved attention notices and open decisions from before it, through the same door as every new one.
     for (const binding of bindings) {
         const owed = `owed-before-pairing:${binding.id}`;
         if (state.meta(identity.installation, owed) !== null)
@@ -959,7 +847,6 @@ export async function planChatNotifications(options) {
             offerNotice(options, notification, binding, registry);
         state.setMeta(identity.installation, owed, "offered", nowOf(options));
     }
-    // A ping held while its person watched the run (agent-board.ts watchedPing) is offered again once the watch lapses.
     for (const held of state.metaStartingWith(identity.installation, WATCH_HELD)) {
         if (held.value > nowOf(options).toISOString())
             continue;
@@ -969,7 +856,6 @@ export async function planChatNotifications(options) {
         if (binding !== undefined && notification !== null)
             offerNotice(options, notification, binding, registry);
     }
-    // Every paired person is a destination of their own, under their own ceiling.
     for (const notification of store.notificationsAfter(cursor, 100)) {
         for (const binding of bindings)
             offerNotice(options, notification, binding, registry);
@@ -978,33 +864,19 @@ export async function planChatNotifications(options) {
             .run(notification.id, identity.installation);
     }
 }
-/** A held ping's small fact: `watch-held:<binding>:<notification>` → when the watch lapses. */
 const WATCH_HELD = "watch-held:";
-/** One notification for one paired person: planned as their parts, or nothing. Never twice: each plan's event id is
- * the notification's for this binding. */
 function offerNotice(options, notification, binding, registry) {
     const { state, store, identity } = options;
     const repos = channelRepos(store, binding.approver, registry);
     store.transact(() => {
-        // One person's notification (v83) goes to that person alone, task or not.
         const personal = notification.recipient !== null;
-        if (
-        // From before the pairing, only what still wants a person (the rule every chat app shares, wantedBeforePairing).
-        (notification.createdAt >= binding.created || wantedBeforePairing(notification)) &&
+        if ((notification.createdAt >= binding.created || wantedBeforePairing(notification)) &&
             notification.resolvedAt === null &&
-            // A promise the lead made on another chat is reported there (lead-commitments.ts); one its owner asked for on
-            // this chat is always said here, however quiet the lead's own work is kept.
             (promiseChannelOf(notification) ?? state.provider) === state.provider &&
-            // Pings follow responsibility: the lead's work, this person's own act and a muted project stay in the console.
             (promiseChannelOf(notification) === state.provider || store.pingAllowed(notification, binding.approver)) &&
-            // A flow decision for "anyone who approves" reaches every approver who can see the project.
-            // A notification addressed to this person reaches them whatever project
-            // their channel follows (a sign-in pause is the installation's, v108).
             (personal
                 ? notification.recipient === binding.approver && (notification.project === null || repos.includes(notification.project))
                 : (notification.taskId || notification.kind === "flow-decision") && notification.project !== null && repos.includes(notification.project))) {
-            // Watching the run on the Agents board holds this ping (re-offered above once the watch lapses); a finished
-            // run they have since opened needs no ping at all.
             const watched = watchedPing(store, notification, binding.approver, nowOf(options));
             if (watched === "skip")
                 return;
@@ -1014,15 +886,12 @@ function offerNotice(options, notification, binding, registry) {
             }
             const run = store.telegramProgressRun(notification);
             const id = chatHash(`${options.state.provider}:notice:${binding.id}:${notification.id}`), now = nowOf(options);
-            // Only when I'm needed (the default): the task's one card is edited in place, and a new message
-            // follows only when this person is needed. Every step keeps the branches below unchanged.
             const quiet = !personal && isTaskFact(notification) && store.notificationPreference(binding.approver).mode === "quiet";
             if (isShotsKind(notification.kind)) {
                 planResultShots(options, binding, notification, repos, id, now);
                 return;
             }
             if (notification.kind === LEAD_SAY_KIND) {
-                // The lead's words (lead-voice.ts): one message, repainted in place when a later say joins it.
                 const content = { text: leadSayText(store, notification, binding.approver),
                     ...(notification.link ? { link: { label: "Open", path: notification.link } } : {}) };
                 const earlier = leadSayEarlier(store, notification).map(one => state.prepare("SELECT id FROM chat_part WHERE provider=:provider AND event=?")
@@ -1041,12 +910,9 @@ function offerNotice(options, notification, binding, registry) {
                 if (!needsPerson(notification))
                     return;
                 if (notification.kind === "run-finished" && run) {
-                    // Finished work goes out only as the batch line; one left out on purpose (a release check, a replaced
-                    // task, the reader's own completion) stays quiet rather than falling through to another message.
                     planFinished(options, binding, notification.taskRef, run.id, now, null, repos);
                     return;
                 }
-                // Every other update for this person within two minutes joins the same one message.
                 else if (notification.kind !== "run-finished" && joinsBatch(notification)) {
                     if (planFinished(options, binding, notification.taskRef, run?.id ?? null, now, notification.id, repos))
                         return;
@@ -1098,7 +964,6 @@ function offerNotice(options, notification, binding, registry) {
                 }
             }
             else if (notification.kind === "flow-decision") {
-                // The draft as written, and Approve / Edit / Send back on its last part; a card that moved on is not news.
                 const parts = flowDecisionParts(store, notification, state.provider);
                 if (parts !== null) {
                     state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
@@ -1107,19 +972,16 @@ function offerNotice(options, notification, binding, registry) {
                 }
             }
             else if (personal && flowSendParts(store, notification, state.provider) !== null) {
-                // A flow's "Send to me" (flow-send.ts): what was done, with its links as buttons.
                 state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
                     ts: "", thread: "", payload: {}, created: now.toISOString() });
                 state.plan(id, flowSendParts(store, notification, state.provider), now);
             }
             else if (personal && flowDoneCard(store, notification, now) !== null) {
-                // A card that reached Done: what it went through, as a card with its links.
                 state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
                     ts: "", thread: "", payload: {}, created: now.toISOString() });
                 state.plan(id, [cardContent(flowDoneCard(store, notification, now))], now);
             }
             else if (notification.kind === "flow-card" && questionParts(store, notification, binding) !== null) {
-                // A subagent's question (v93): its options and "Answer in words" on the notice, for the person it asks.
                 state.enqueue({ id, installation: identity.installation, binding: binding.id, kind: "notice", channel: binding.channel, member: binding.member,
                     ts: "", thread: "", payload: {}, created: now.toISOString() });
                 state.plan(id, questionParts(store, notification, binding), now);
@@ -1137,14 +999,11 @@ function offerNotice(options, notification, binding, registry) {
                     payload: {},
                     created: now.toISOString(),
                 });
-                // A result, plan, failure or ready pull request acts in place (chat-decide.ts); otherwise its one link (a plan's
-                // is Review & start, where the password step lives).
                 const target = decideTargetOf(notification);
                 const offer = decideOfferFor(options, binding, target, repos, now);
                 const fallback = offer === null ? decideFallbackLink(target) : null;
                 state.plan(id, [
                     {
-                        // Never the task's id or a "— revision" suffix (chat-voice.ts).
                         text: offer?.text ?? chatText(phoneText(notification.body === "" ? leadSubjectOf(store, notification, binding.approver) : `${leadSubjectOf(store, notification, binding.approver)}\n\n${notification.body}`, 2500), notification.taskId === null ? [] : [{ id: notification.taskId, title: chatTitle(store, notification.taskId) }]),
                         ...(notification.taskId ? { task: notification.taskId } : {}),
                         ...(run ? { run: run.id } : {}),

package/dist/chat-display.js

@@ -1,4 +1,3 @@
-/** Shared privacy-preserving plain text for external conversations. */
 import { scanForSecrets } from "./evidence.js";
 export function publicChatText(value, cap) {
     if (scanForSecrets(value).length > 0 ||
@@ -11,7 +10,6 @@ export function publicChatText(value, cap) {
         .replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f]/g, " ")
         .replace(/\s+/g, " ")
         .trim();
-    // Keep surrogate pairs intact while bounding Telegram's UTF-16 ceiling.
     return text.length <= cap
         ? text
         : text.slice(0, cap - 2).replace(/[\uD800-\uDBFF]$/, "") + "…";