toolroll 0.5.0

package/dist/chat-display.d.ts

@@ -0,0 +1 @@
+export declare function publicChatText(value: string, cap: number): string;

package/dist/chat-display.js

@@ -0,0 +1,18 @@
+/** Shared privacy-preserving plain text for external conversations. */
+import { scanForSecrets } from "./evidence.js";
+export function publicChatText(value, cap) {
+    if (scanForSecrets(value).length > 0 ||
+        /\b\d{5,}:[A-Za-z0-9_-]{20,}\b/.test(value))
+        return "[sensitive text hidden]";
+    const text = value
+        .replace(/(?:[A-Za-z]:[\\/]|\\\\)[^\s"'<>]+/g, "[path]")
+        .replace(/(^|[\s"'`(<[=:,])\/(?:[A-Za-z0-9._~-]+\/)*[A-Za-z0-9._~-]+/g, "$1[path]")
+        .replace(/\b[0-9a-f]{32,}\b/gi, "[digest]")
+        .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]$/, "") + "…";
+}

package/dist/chat-evidence.d.ts

@@ -0,0 +1,123 @@
+import type { Artifact, Run, Store } from "./store.js";
+import type { VerifiedApprover } from "./principal.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 declare const RESULT_IMAGES_PER_TURN_CAP = 8;
+/** Which of a result's images one ask selects: a page from an offset, or exact image ids from an earlier listing. Absent: the first page. */
+export type ResultImagePick = {
+    offset?: number;
+    images?: readonly number[];
+};
+export type ResultImage = {
+    artifact: number;
+    sha256: string;
+    format: "png" | "jpeg";
+    bytes: number;
+    /** 1-based position among the result's deliverable images, and their count. */
+    ordinal: number;
+    total: number;
+    /** The short caption a channel sends with the file: task, result, position. No title, path or prose. */
+    caption: string;
+    /** The file name a channel uploads under: task and result identity, never a path. */
+    fileName: string;
+};
+export type ResultImageSelection = {
+    task: string;
+    /** The task as a caption or file name shows it: the id when it is plain, a stable opaque label when it is credential-shaped. */
+    label: string;
+    root: string;
+    currentExecution: string;
+    run: number;
+    role: Run["role"];
+    title: string;
+    /** Every deliverable image of the result, in evidence order, each with its position. */
+    images: ResultImage[];
+    /** The images THIS ask selects for delivery: at most the per-turn cap, in evidence order. */
+    selected: ResultImage[];
+    /** Where the next page starts when the selection stopped short of the last image; null when nothing remains after it. */
+    nextOffset: number | null;
+    /** Screenshot records that exist but cannot be delivered, each with its plain reason. */
+    unavailable: {
+        artifact: number;
+        problem: string;
+    }[];
+    /** The run delivered a report (a scout): images are not the point of this result. */
+    report: boolean;
+};
+type Problem = {
+    ok: false;
+    message: string;
+};
+/** The plain words for a screenshot record that must not travel. Null means the record itself is fine. */
+export declare function screenshotRecordProblem(artifact: Artifact): string | null;
+/** Telegram's own caption ceiling for a document (Bot API sendDocument, checked 2026-09-16). Ours are far shorter by construction. */
+export declare const RESULT_IMAGE_CAPTION_MAX_CHARS = 1024;
+/**
+ * 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 declare function displayIdentityProblem(text: string): string | 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 declare function resultTaskLabel(taskId: string): string;
+/** 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 declare function resultImageCaption(task: string, run: number, ordinal: number, total: number, current: boolean): string;
+/** The upload name: task label, result and artifact identity — derivable from the typed part alone, never a path. */
+export declare function resultImageFileName(task: string, run: number, artifact: number, format: "png" | "jpeg"): string;
+/**
+ * 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 declare function safeResultImageCaption(text: string, taskId: string, run: number): string;
+/** The page or the exact ids one ask selects from a result's images; a refusal names what to choose instead. */
+export declare function pickResultImages(images: readonly ResultImage[], pick: ResultImagePick | undefined, cap: number): {
+    ok: true;
+    selected: ResultImage[];
+    nextOffset: number | null;
+} | Problem;
+/**
+ * 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 declare function selectResultImages(store: Store, who: VerifiedApprover, evidenceRoot: string | undefined, task: string, run?: number, pick?: ResultImagePick): {
+    ok: true;
+    selection: ResultImageSelection;
+} | Problem;
+/**
+ * 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 declare function verifyResultImage(store: Store, evidenceRoot: string, repos: readonly string[], part: {
+    taskId: string;
+    run: number;
+    artifact: number;
+    sha256: string;
+}): {
+    ok: true;
+    bytes: Buffer;
+    format: "png" | "jpeg";
+    artifact: Artifact;
+} | {
+    ok: false;
+    problem: string;
+};
+export {};

package/dist/chat-evidence.js

@@ -0,0 +1,207 @@
+/**
+ * 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";
+    if (artifact.captureStatus === "failed")
+        return "the capture failed";
+    if (artifact.truncated)
+        return "the saved file was shortened";
+    if (artifact.redacted)
+        return "sensitive text was hidden from the saved file";
+    if (artifact.bytesStored === 0)
+        return "the saved file is empty";
+    if (artifact.bytesStored > SCREENSHOT_BYTE_CAP)
+        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)
+        return { ok: false, problem };
+    const proven = readVerifiedArtifact(evidenceRoot, artifact);
+    if (!proven.ok)
+        return { ok: false, problem: "the saved file is missing or changed" };
+    const checked = validateScreenshotBytes(proven.content);
+    if (!checked.ok)
+        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";
+    if (scanForSecrets(text).length > 0 || BOT_TOKEN_SHAPE.test(text))
+        return "credential-shaped";
+    if (/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f\s]/.test(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)
+            return { ok: false, message: "Choose image ids or an offset, not both." };
+        if (pick.images.length === 0)
+            return { ok: false, message: "Choose at least one image id from this result's list." };
+        if (pick.images.length > cap)
+            return { ok: false, message: `Choose at most ${cap} images per request.` };
+        const wanted = new Set(pick.images);
+        if (wanted.size !== pick.images.length)
+            return { ok: false, message: "Each image id once." };
+        const known = new Set(images.map(one => one.artifact));
+        if ([...wanted].some(id => !known.has(id)))
+            return { ok: false, message: "Choose image ids from this result's list of deliverable images." };
+        return { ok: true, selected: images.filter(one => wanted.has(one.artifact)), nextOffset: null };
+    }
+    const offset = pick?.offset ?? 0;
+    if (offset > 0 && offset >= images.length)
+        return { ok: false, message: images.length === 0 ? "This result has no deliverable images." : `Choose an image offset below ${images.length}.` };
+    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))
+        return { ok: false, message: "That task is not in your projects." };
+    const family = store.taskFamilyOf(task, who.repos, false);
+    if (family === null || family.problem !== null)
+        return { ok: false, message: "This task's revision history needs repair." };
+    const current = family.current.id === task;
+    if (run === undefined && !current)
+        return { ok: false, message: "A newer revision of this task is current. Say which result you mean before images are selected: this version or the newer one." };
+    const found = run === undefined
+        ? store.runsFor(ref.id).find(one => one.outcome !== null && (one.role === "builder" || one.role === "repair" || one.role === "scout"))
+        : store.getRun(run);
+    if (found == null || found.taskRef !== ref.id || found.outcome === null || (found.role !== "builder" && found.role !== "repair" && found.role !== "scout")) {
+        return { ok: false, message: "There is no finished result for that version yet." };
+    }
+    if (evidenceRoot === undefined)
+        return { ok: false, message: "Saved images cannot be read from here." };
+    const artifacts = store.artifactsFor(found.id);
+    const shots = artifacts.filter(one => one.kind === "screenshot");
+    const images = [];
+    const unavailable = [];
+    const readable = [];
+    for (const artifact of shots) {
+        const read = readScreenshot(evidenceRoot, artifact);
+        if (read.ok)
+            readable.push({ artifact, bytes: read.bytes.length, format: read.format });
+        else
+            unavailable.push({ artifact: artifact.id, problem: read.problem });
+    }
+    readable.forEach((one, index) => {
+        const ordinal = index + 1;
+        images.push({
+            artifact: one.artifact.id, sha256: one.artifact.sha256, format: one.format, bytes: one.bytes, ordinal, total: readable.length,
+            caption: resultImageCaption(task, found.id, ordinal, readable.length, current),
+            fileName: resultImageFileName(task, found.id, one.artifact.id, one.format),
+        });
+    });
+    const picked = pickResultImages(images, pick, RESULT_IMAGES_PER_TURN_CAP);
+    if (!picked.ok)
+        return picked;
+    return { ok: true, selection: {
+            task, label: resultTaskLabel(task), root: family.root.id, currentExecution: family.current.id, run: found.id, role: found.role,
+            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))
+        return { ok: false, problem: "the result is outside your connected projects now" };
+    const run = store.getRun(part.run);
+    if (run === null || run.taskRef !== ref.id || run.outcome === null)
+        return { ok: false, problem: "the result is no longer recorded" };
+    const artifact = store.artifactForRun(part.run, part.artifact);
+    if (artifact === null || artifact.kind !== "screenshot" || artifact.sha256 !== part.sha256)
+        return { ok: false, problem: "the saved file's record changed" };
+    const read = readScreenshot(evidenceRoot, artifact);
+    if (!read.ok)
+        return read;
+    return { ok: true, bytes: read.bytes, format: read.format, artifact };
+}

package/dist/chat-flow.d.ts

@@ -0,0 +1,44 @@
+import type { ChatBinding, ChatContent, ChatEvent, ChatState } from "./chat-delivery-state.js";
+import type { Store } from "./store.js";
+export type ChatFlowAction = "approve" | "edit" | "send-back";
+export declare const CHAT_FLOW_LABELS: Record<ChatFlowAction, string>;
+/** Words kept as written, line breaks and all; only control characters go. */
+export declare function chatFlowText(text: string): string;
+/**
+ * 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 declare function flowDecisionParts(store: Store, notification: {
+    dedupeKey: string;
+    subject: string;
+    body: string;
+    link: string | null;
+}): ChatContent[] | null;
+/** The live buttons on one part, in the order they were minted. */
+export declare function chatFlowButtons(state: ChatState, part: number, now: Date): Array<{
+    token: string;
+    action: ChatFlowAction;
+    label: string;
+}>;
+/**
+ * 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 declare function applyChatFlowTap(options: {
+    store: Store;
+    state: ChatState;
+    label: string;
+}, event: ChatEvent, binding: ChatBinding, token: string, repos: readonly string[], now: Date): boolean;
+/**
+ * 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 declare function answerChatFlowPrompt(options: {
+    store: Store;
+    state: ChatState;
+    label: string;
+}, event: ChatEvent, binding: ChatBinding, input: {
+    text: string;
+    originalLength?: number;
+}, repos: readonly string[], now: Date): boolean;

package/dist/chat-flow.js

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ */
+import { keptDraft } from "./flow-draft.js";
+import { decideFlowCard, flowCardHref, flowDefinitionOf } from "./flow-engine.js";
+import { deciderOf } from "./flows.js";
+import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
+import { verifyApproverStanding } from "./principal.js";
+import { FLOW_DECIDE_KEY, flowDecisionAt } from "./telegram-flow.js";
+export const CHAT_FLOW_LABELS = { approve: "Approve", edit: "Edit", "send-back": "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;
+    while (rest.length > PART_CHARS) {
+        const cut = rest.lastIndexOf("\n", PART_CHARS);
+        let at = cut > PART_CHARS / 2 ? cut : PART_CHARS;
+        if (/[\uD800-\uDBFF]/.test(rest[at - 1]))
+            at -= 1;
+        out.push(rest.slice(0, at).trimEnd());
+        rest = rest.slice(at).trimStart();
+    }
+    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"] : []),
+        ...(waiting.stage.onFail !== null ? ["send-back"] : [])];
+}
+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 "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) {
+    const visit = FLOW_DECIDE_KEY.exec(notification.dedupeKey);
+    const waiting = visit === null ? null : flowDecisionAt(store, Number(visit[1]), Number(visit[2]));
+    if (waiting === null)
+        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. */
+export function chatFlowButtons(state, part, now) {
+    return state.prepare("SELECT token,action FROM chat_flow_action WHERE 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] }));
+}
+const retire = (state, card, entry, now) => {
+    state.prepare("UPDATE chat_flow_action SET consumed=? WHERE card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
+    state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE card=? AND entry=? AND consumed IS NULL").run(now.toISOString(), card, entry);
+};
+/** Show the tapped notice again with what happened, and without its buttons. */
+function repaint(state, part, event, line) {
+    const row = state.prepare("SELECT payload FROM chat_part WHERE id=?").get(part);
+    const before = row === undefined ? { text: "" } : JSON.parse(String(row["payload"]));
+    const content = { text: `${before.text}\n\n${line}`.slice(0, PART_CHARS + 400), edit: event.ts, ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
+    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(JSON.stringify(content), part);
+}
+/**
+ * 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.*,p.message,e.binding AS owner,e.channel FROM chat_flow_action a JOIN chat_part p ON p.id=a.part JOIN chat_event e ON e.id=p.event WHERE 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. Ask for the current state before trying again.");
+        return true;
+    }
+    if (action["consumed"] !== null || String(action["expires"]) <= now.toISOString()) {
+        say("That was already decided, or these buttons are too old.");
+        return true;
+    }
+    const card = Number(action["card"]), entry = Number(action["entry"]), part = Number(action["part"]);
+    const waiting = flowDecisionAt(store, card, entry);
+    if (waiting === null) {
+        retire(state, card, entry, now);
+        repaint(state, part, event, "This card has moved on since; nothing was changed.");
+        state.finish(event.id);
+        return true;
+    }
+    const decider = deciderOf(waiting.stage, waiting.flow);
+    if (decider !== null && decider !== binding.approver) {
+        say(`Only ${decider} decides here.`);
+        return true;
+    }
+    if (!verifyApproverStanding(store, binding.approver, binding.generation, repos).ok) {
+        state.finish(event.id, true);
+        return true;
+    }
+    const kind = String(action["action"]);
+    if (kind === "approve") {
+        const decided = decideFlowCard(store, { card, decision: "approve", note: null, actor: binding.approver, repos, entry }, now);
+        if (!decided.ok) {
+            say(decided.message);
+            return true;
+        }
+        retire(state, card, entry, now);
+        store.retireTelegramFlowVisit(card, entry, now);
+        repaint(state, part, event, `✅ You approved it. ${decided.said}`);
+        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 binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
+    state.prepare("UPDATE chat_question_prompt SET consumed=? WHERE binding=? AND consumed IS NULL").run(now.toISOString(), binding.id);
+    state.prepare("INSERT INTO chat_flow_prompt(binding,card,entry,mode,created,expires) VALUES(?,?,?,?,?,?)")
+        .run(binding.id, card, entry, kind, now.toISOString(), new Date(now.getTime() + PROMPT_MS).toISOString());
+    const back = waiting.stage.onFail === null ? "the zone before" : flowDefinitionOf(waiting.flow)?.stages.find(one => one.id === waiting.stage.onFail)?.title ?? waiting.stage.onFail;
+    say(kind === "edit"
+        ? `Send your version of the draft for “${waiting.card.title}” as your next message here. It replaces the draft and comes back here for you to approve. Send “cancel” to leave it as it is.`
+        : `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 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)
+        return false;
+    return store.transact(() => {
+        const prompt = state.prepare("SELECT * FROM chat_flow_prompt WHERE binding=? AND consumed IS NULL AND expires>? ORDER BY id DESC LIMIT 1").get(binding.id, now.toISOString());
+        if (prompt === undefined)
+            return false;
+        const id = Number(prompt["id"]), card = Number(prompt["card"]), entry = Number(prompt["entry"]), mode = String(prompt["mode"]);
+        const say = (text) => state.plan(event.id, [{ text }], now);
+        const close = () => state.prepare("UPDATE chat_flow_prompt SET consumed=? WHERE id=?").run(now.toISOString(), id);
+        const said = input.text.trim();
+        if (/^cancel\.?$/i.test(said)) {
+            close();
+            say(mode === "edit" ? "Left the draft as it is. The buttons on the notice still work." : "Left it where it is. The buttons on the notice still work.");
+            return true;
+        }
+        const waiting = flowDecisionAt(store, card, entry);
+        if (waiting === null) {
+            retire(state, card, entry, now);
+            say("That card has moved on since; nothing was changed.");
+            return true;
+        }
+        if (said === "") {
+            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.
+        const limit = (input.originalLength ?? 0) > input.text.length ? MATE_MESSAGE_MAX_CHARS : DRAFT_LIMIT;
+        if ((input.originalLength ?? 0) > input.text.length || said.length > DRAFT_LIMIT) {
+            say(`That's too long to take from here. Keep it under ${limit.toLocaleString("en-US")} characters, or change it in Toolroll.`);
+            return true;
+        }
+        if (!verifyApproverStanding(store, binding.approver, binding.generation, repos).ok) {
+            close();
+            state.finish(event.id, true);
+            return true;
+        }
+        if (mode === "edit") {
+            if (waiting.draft === null) {
+                close();
+                say("This decision has no draft to edit.");
+                return true;
+            }
+            const kept = keptDraft(said);
+            store.updateFlowCard(card, { outputs: { ...waiting.card.outputs, [waiting.draft.id]: kept } }, now);
+            store.addFlowComment({ card, author: binding.approver, body: `Edited the draft in ${options.label}.`, mentions: [] }, now);
+            retire(state, card, entry, now);
+            store.retireTelegramFlowVisit(card, entry, now);
+            const fresh = flowDecisionAt(store, card, entry);
+            state.plan(event.id, decisionParts(`${waiting.flow.name}: your version of the draft for “${waiting.card.title}”\n\n${kept}\n\nApprove to send it as written.`, { card, entry, actions: actionsFor(fresh) }, { label: "Open", path: flowCardHref(waiting.flow.id, card) }), now);
+            return true;
+        }
+        const decided = decideFlowCard(store, { card, decision: "send-back", note: said.slice(0, 2000), actor: binding.approver, repos, entry }, now);
+        if (!decided.ok) {
+            close();
+            say(decided.message);
+            return true;
+        }
+        retire(state, card, entry, now);
+        store.retireTelegramFlowVisit(card, entry, now);
+        say(`↩️ ${decided.said}`);
+        return true;
+    });
+}