toolroll 0.9.96 → 0.9.97

package/dist/browser-workspace.d.ts

@@ -158,6 +158,8 @@ export type BrowserConversation = {
     previous?: {
         messages: BrowserMessage[];
     } | null;
+    /** How the last reply failed, from its saved turn (docs/plans/responsive-chat.md §3.4); absent or null otherwise. */
+    failure?: string | null;
 };
 /** A page rebuilt as React components (shadcn/ui). The server still renders
  * its HTML as the no-JavaScript fallback; forms post to the same routes. */

package/dist/chat-delivery.d.ts

@@ -1,4 +1,5 @@
 import { type WarmHooks } from "./chat-warmth.js";
+import { type ChatLiveTransport } from "./chat-live.js";
 import { ChatState, type ChatBinding, type ChatContent, type ChatEvent, type ChatIdentity } from "./chat-delivery-state.js";
 import { type Store } from "./store.js";
 import type { SubscriptionLeadRunner } from "./subscription-chat.js";
@@ -29,8 +30,11 @@ export type ChatDeliveryOptions = {
     clock?: () => Date;
     partSize?: number;
     maxProposal?: number;
-    /** The app's warm touches for one owner message (a 👍, typing), where the app and the bot's permissions allow them. */
+    /** The app's warm touch while the lead works on one owner message (typing), where the app and the bot's permissions allow it. */
     warm?: (event: ChatEvent, binding: ChatBinding) => WarmHooks;
+    /** Live replies (docs/plans/responsive-chat.md §3.2): the app's transport for the live message that answers the
+     * owner's own direct message; absent or null: the reply goes out whole at the end, as before. */
+    live?: (event: ChatEvent, binding: ChatBinding) => ChatLiveTransport | null;
     /** Merges a pull request approved in chat (tests script it); otherwise the project's own merge. */
     merge?: (input: {
         runId: number;

package/dist/chat-delivery.js

@@ -5,6 +5,7 @@ import { channelRepos, resolveChannelLead, proposalPreview, proposalOutcomeText,
 import { LEAD_MESSAGE_MAX_CHARS, leadFailureText, runLeadTurn } from "./lead.js";
 import { shapeReplyParts } from "./reply-shape.js";
 import { warmTurn } from "./chat-warmth.js";
+import { openChatLive, planWithLive, settleLive } from "./chat-live.js";
 import { confirmLeadProposal, dismissLeadProposal, } from "./lead-doors.js";
 import { ceilingDigestOf, verifyApproverStanding } from "./principal.js";
 import { ChatState, ChatDeliveryError, chatHash, savedChatPart, } from "./chat-delivery-state.js";
@@ -173,6 +174,10 @@ 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") {
             if (!(await options.member(event.member, event.channel))) {
@@ -217,12 +222,12 @@ export async function processChatEvent(options) {
         }
         const body = readChatMessageBody(event.payload);
         if (!body.ok) {
-            state.plan(event.id, [{ text: `That message couldn't be read (${body.issues.map(issue => issue.line).join("; ")}). Send it again.` }], nowOf(options));
+            plan([{ text: `That message couldn't be read (${body.issues.map(issue => issue.line).join("; ")}). Send it again.` }], nowOf(options));
             return true;
         }
         const input = body.value;
         if (typeof input.unsupported === "string") {
-            state.plan(event.id, [{ text: input.unsupported }], nowOf(options));
+            plan([{ text: input.unsupported }], nowOf(options));
             return true;
         }
         const text = String(input.text ?? "");
@@ -238,7 +243,7 @@ export async function processChatEvent(options) {
             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)) {
                 const answer = applyDecideFeedback(store, decideSeat(state, binding), prompt, text, repos, options.evidenceRoot, nowOf(options));
-                state.plan(event.id, [{ text: answer.said, ...(answer.link === null ? {} : { link: answer.link }) }], nowOf(options));
+                plan([{ text: answer.said, ...(answer.link === null ? {} : { link: answer.link }) }], nowOf(options));
                 return true;
             }
         }
@@ -259,14 +264,14 @@ export async function processChatEvent(options) {
             const focusedId = store.chatFocus(surface, binding.id);
             const focusedTitle = focusedId === null ? null : phoneText(store.getTask(focusedId)?.title ?? focusedId, 64);
             if (command.kind === "help")
-                state.plan(event.id, [{ text: PHONE_HELP }], now_);
+                plan([{ text: PHONE_HELP }], now_);
             else if (command.kind === "status")
-                state.plan(event.id, [{ text: phoneStatus(store, repos, now_, focusedTitle, options.evidenceRoot) }], now_);
+                plan([{ text: phoneStatus(store, repos, now_, focusedTitle, options.evidenceRoot) }], now_);
             else if (command.kind === "tasks")
-                state.plan(event.id, [{ text: phoneTaskListText(phoneTaskChoices(store, repos, now_, null, 8, options.evidenceRoot), focusedTitle) }], now_);
+                plan([{ text: phoneTaskListText(phoneTaskChoices(store, repos, now_, null, 8, options.evidenceRoot), focusedTitle) }], now_);
             else if (command.kind === "lead") {
                 store.setChatFocus(surface, binding.id, null, now_);
-                state.plan(event.id, [{ text: PHONE_BACK_TO_LEAD }], now_);
+                plan([{ text: PHONE_BACK_TO_LEAD }], now_);
             }
             else {
                 const pick = resolvePhoneTask(store, repos, now_, command.id);
@@ -274,13 +279,13 @@ export async function processChatEvent(options) {
                     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.
-                    state.plan(event.id, [{ text: phoneFocusText(view.text), ...(view.link === null ? {} : { link: view.link }), task: pick.view, ...(view.run === null ? {} : { run: view.run }) }], now_);
+                    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") {
-                    state.plan(event.id, [{ text: ["Several tasks match. Add a word from the title, or send one of these:", ...pick.choices.map(one => `• ${one.title} — /task ${one.id}`)].join("\n") }], now_);
+                    plan([{ text: ["Several tasks match. Add a word from the title, or send one of these:", ...pick.choices.map(one => `• ${one.title} — /task ${one.id}`)].join("\n") }], now_);
                 }
                 else
-                    state.plan(event.id, [{ text: PHONE_NO_MATCH }], now_);
+                    plan([{ text: PHONE_NO_MATCH }], now_);
             }
             return true;
         }
@@ -298,12 +303,12 @@ export async function processChatEvent(options) {
                 say: (reply, link) => replies.push({ text: reply, ...(link ? { link } : {}), ...(isRoom ? { channel: event.channel } : {}) }),
             });
             if (consumed) {
-                state.plan(event.id, replies, now);
+                plan(replies, now);
                 return true;
             }
         }
         if (text.length > LEAD_MESSAGE_MAX_CHARS) {
-            state.plan(event.id, [
+            plan([
                 {
                     text: tooLongText(input.originalLength || text.length),
                 },
@@ -311,12 +316,40 @@ 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;
+                    try {
+                        await channelAccess(options, binding, ceiling);
+                        return true;
+                    }
+                    catch (error) {
+                        if (error instanceof ChatDeliveryError && ["Chat access changed", "Connected projects changed", `${options.label} account access changed`].includes(error.code))
+                            return false;
+                        throw error;
+                    }
+                },
+                now: () => nowOf(options),
+            });
+            return live;
+        };
         let receipt = event.session === null
             ? null
             : store.leadRequestReceipt(event.session, request);
         if (!receipt) {
             if (new Date(event.created).getTime() + 600_000 < now.getTime()) {
-                state.plan(event.id, [
+                plan([
                     {
                         text: "This message waited too long to start. Send it again when you’re ready.",
                     },
@@ -326,10 +359,11 @@ export async function processChatEvent(options) {
             const resolved = resolveChannelLead(store, { approver: binding.approver, approverGeneration: binding.generation }, repos, now);
             if (!resolved.ok && resolved.reason === "busy") {
                 state.defer(event.id, "Assistant is answering another message", new Date(now.getTime() + 5000));
+                await openLive(null)?.queued();
                 return true;
             }
             if (!resolved.ok) {
-                state.plan(event.id, [
+                plan([
                     {
                         text: (resolved.said ?? "This chat is no longer paired.")
                             .replaceAll("this phone", options.label)
@@ -339,7 +373,7 @@ export async function processChatEvent(options) {
                 return true;
             }
             if (event.session !== null && event.session !== resolved.session.id) {
-                state.plan(event.id, [{ text: "This conversation was restarted after you sent that, so it wasn't answered. Send your message again." }], now);
+                plan([{ text: "This conversation was restarted after you sent that, so it wasn't answered. Send your message again." }], now);
                 return true;
             }
             state
@@ -363,7 +397,7 @@ export async function processChatEvent(options) {
                     .map((c) => [`${c.task}:${c.run ?? ""}`, c])).values(),
             ];
             if (targets.length > 1) {
-                state.plan(event.id, [
+                plan([
                     {
                         text: "This thread is about more than one task. Reply to the message about the one you mean, or send /tasks to pick one.",
                     },
@@ -383,8 +417,8 @@ export async function processChatEvent(options) {
             // 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 && event.kind === "message" && event.member !== identity.bot && event.member === binding.member && event.channel === binding.channel
-                ? options.warm(event, binding) : {});
+            const warm = warmTurn(options.warm !== undefined && ownMessage ? options.warm(event, binding) : {});
+            const turnLive = openLive(resolved.who.ceilingDigest);
             const outcome = await runLeadTurn({
                 store,
                 who: resolved.who,
@@ -404,7 +438,7 @@ export async function processChatEvent(options) {
                 evidenceRoot: options.evidenceRoot,
                 mediaDelivery: "documents",
                 ...(channel === undefined ? {} : { channel }),
-                onProgress: warm.onProgress,
+                onProgress: (progress) => { warm.onProgress(progress); turnLive?.push(progress); },
                 revalidate: async () => {
                     try {
                         await channelAccess(options, binding, resolved.who.ceilingDigest);
@@ -417,7 +451,11 @@ export async function processChatEvent(options) {
                         return { ok: false, reason };
                     }
                 },
-            }).finally(warm.stop);
+            }).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)
                 mirrorToTaskChat(store, resolved.who, context.task, options.label, text, outcome.reply, nowOf(options));
             if (!state.owns(identity.installation, options.owner, nowOf(options)) ||
@@ -428,11 +466,12 @@ export async function processChatEvent(options) {
                 (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;
             }
             receipt = store.leadRequestReceipt(resolved.session.id, request);
             if (!receipt) {
-                state.plan(event.id, [
+                plan([
                     {
                         text: !outcome.ok
                             ? phoneText(outcome.message, 1000)
@@ -442,6 +481,14 @@ 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;
+        }
         store.sweepStaleLeadTurns(nowOf(options));
         const turn = store.getLeadTurn(receipt.turn);
         if (turn?.state === "running" || turn?.state === "queued") {
@@ -449,9 +496,9 @@ export async function processChatEvent(options) {
             return true;
         }
         if (turn?.state !== "answered") {
-            state.plan(event.id, [
+            plan([
                 {
-                    text: leadFailureText(turn?.failureReason ?? null, turn != null && store.leadTurnCostUnconfirmed(turn.id)),
+                    text: leadFailureText(turn?.failureReason ?? null, turn != null && store.leadTurnCostUnconfirmed(turn.id), turn?.failureDetail ?? null),
                 },
             ], nowOf(options));
             return true;
@@ -490,15 +537,17 @@ export async function processChatEvent(options) {
         // 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 });
-        state.plan(event.id, parts, nowOf(options));
+        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
             : new ChatDeliveryError(`${options.label} is waiting to retry`);
         if (problem.permanent) {
-            state.plan(event.id, [{ text: problem.message }], nowOf(options));
+            plan([{ text: problem.message }], nowOf(options));
             state.prepare("UPDATE chat_event SET next_at=NULL,problem=? WHERE provider=:provider AND id=?").run(problem.message, event.id);
             return true;
         }

package/dist/chat-follow.d.ts

@@ -1,8 +1,11 @@
 /** A pause that ends early, and quietly, when `signal` aborts. */
 export declare const abortablePause: (signal: AbortSignal) => (ms: number) => Promise<void>;
+/** The most parts one pass delivers (docs/plans/responsive-chat.md §3.5): a reply's parts go together, bounded. */
+export declare const DELIVER_PER_PASS = 5;
 /**
- * Works the queue while this connection stays the current, leased one: each pass takes in saved events, plans room
- * messages, delivers one part and plans notifications (when they are on), checking it is still current between steps.
+ * 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 declare function workChatQueue(steps: {
@@ -12,6 +15,6 @@ export declare function workChatQueue(steps: {
     notifications: () => boolean;
     process: () => Promise<unknown>;
     rooms: () => Promise<unknown>;
-    deliver: () => Promise<unknown>;
+    deliver: () => Promise<boolean>;
     notify: () => Promise<unknown>;
 }): Promise<void>;

package/dist/chat-follow.js

@@ -9,9 +9,12 @@ export const abortablePause = (signal) => async (ms) => {
         /* 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 takes in saved events, plans room
- * messages, delivers one part and plans notifications (when they are on), checking it is still current between steps.
+ * 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) {
@@ -20,11 +23,24 @@ export async function workChatQueue(steps) {
             await steps.pause(1000);
             continue;
         }
-        await steps.process();
-        if (steps.same())
-            await steps.rooms();
-        if (steps.same())
-            await steps.deliver();
+        // 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()) {
+                if (!(await steps.deliver()))
+                    return true;
+                parts += 1;
+            }
+            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())
+                await steps.rooms();
+            await drain();
+        }
         if (steps.same() && steps.notifications())
             await steps.notify();
         await steps.pause(1000);

package/dist/chat-live-schema.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare const V157_SCHEMA = "\nCREATE TABLE IF NOT EXISTS chat_live (\n provider TEXT NOT NULL CHECK (provider IN ('slack','discord','teams')), event TEXT NOT NULL,\n state TEXT NOT NULL CHECK (state IN ('creating','uncertain','placed','finalized','abandoned')),\n message TEXT, generation INTEGER NOT NULL DEFAULT 0, problem TEXT, created TEXT NOT NULL, updated TEXT NOT NULL,\n PRIMARY KEY (provider, event),\n FOREIGN KEY (provider, event) REFERENCES chat_event(provider, id)\n);\nCREATE TABLE IF NOT EXISTS chat_ack (\n provider TEXT NOT NULL CHECK (provider IN ('slack','discord','teams')), event TEXT NOT NULL,\n state TEXT NOT NULL CHECK (state IN ('sent','done','skipped')), created TEXT NOT NULL, updated TEXT NOT NULL,\n PRIMARY KEY (provider, event),\n FOREIGN KEY (provider, event) REFERENCES chat_event(provider, id)\n);\nCREATE INDEX IF NOT EXISTS chat_ack_sent ON chat_ack(provider, state);\n";
+export declare const V157_TABLES: readonly ["chat_live", "chat_ack"];
+export declare const V157_STEPS: readonly ["chat-live-tables"];

package/dist/chat-live-schema.js

@@ -0,0 +1,32 @@
+/**
+ * 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,
+ state TEXT NOT NULL CHECK (state IN ('creating','uncertain','placed','finalized','abandoned')),
+ message TEXT, generation INTEGER NOT NULL DEFAULT 0, problem TEXT, created TEXT NOT NULL, updated TEXT NOT NULL,
+ PRIMARY KEY (provider, event),
+ FOREIGN KEY (provider, event) REFERENCES chat_event(provider, id)
+);
+CREATE TABLE IF NOT EXISTS chat_ack (
+ provider TEXT NOT NULL CHECK (provider IN ('slack','discord','teams')), event TEXT NOT NULL,
+ state TEXT NOT NULL CHECK (state IN ('sent','done','skipped')), created TEXT NOT NULL, updated TEXT NOT NULL,
+ PRIMARY KEY (provider, event),
+ FOREIGN KEY (provider, event) REFERENCES chat_event(provider, id)
+);
+CREATE INDEX IF NOT EXISTS chat_ack_sent ON chat_ack(provider, state);
+`;
+export const V157_TABLES = Object.freeze(["chat_live", "chat_ack"]);
+export const V157_STEPS = Object.freeze(["chat-live-tables"]);

package/dist/chat-live.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Live replies in Slack, Discord and Teams (docs/plans/responsive-chat.md §3.2, §3.5, slice 3): the 👀 on a person's
+ * message when it arrives, and one "Working on it…" message per turn that shows the lead's status and its reply as it
+ * is written, then becomes the answer.
+ *
+ * - The 👀 is put on beside the serial chat queue (a turn there can take a minute), from the saved event, for the
+ *   owner's own direct message only, and taken off once the answer or the failure notice is delivered. It carries no
+ *   project data: the lease and a live binding are its fence.
+ * - The live message is its own `chat_live` row (v157), never a `chat_part`: planning the reply still adds its own
+ *   parts, and the first of them edits this message, so the event stays queued until then. Creation is
+ *   creating → placed. On Discord a nonce makes a repeated create within its window return the same message, and
+ *   a lookup that fails decides nothing; on Slack and Teams an answer that never came leaves the row uncertain, as
+ *   does an older Discord create not found among the recent messages. An uncertain message is never posted again (the
+ *   reply then posts fresh, and the event's problem says a "Working on it…" may be left above it). That is the
+ *   promise: no duplicate, except after an uncertain create.
+ * - Edits go through one serialized sender per message (live-reply.ts): one request in flight, the newest view
+ *   waiting, closed (and the request in flight settled) before the reply is planned. Every edit re-proves the chat's
+ *   standing (`standing`, the same proof final delivery uses), then the lease after it. Once that fails, nothing more is
+ *   edited, cleanup included: the last text already ends "(still writing — not final)".
+ * - Cosmetic sends share the app's cooldown with durable delivery: none goes while it holds, and a "slow down" on one
+ *   sets it for everything. Final parts come first (they never wait on these), then the 👀, then live edits, which
+ *   start each app's spacing conservatively and widen it on every "slow down".
+ *
+ * No live payload carries a button, a card or an ask: those exist only on the planned reply.
+ */
+import { type LiveView } from "./live-reply.js";
+import type { LeadProgress } from "./lead-progress.js";
+import { type ShapeOptions } from "./reply-shape.js";
+import type { ChatContent, ChatEvent, ChatState } from "./chat-delivery-state.js";
+export type LivePlatform = "slack" | "discord" | "teams";
+/** The live message's fixed words. */
+export declare const LIVE_WORDS: {
+    readonly working: "Working on it…";
+    readonly notFinal: "(still writing — not final)";
+    readonly continues: "(continues…)";
+    readonly maybeLeft: "A “Working on it…” message may be left above this reply.";
+};
+/** Each app's starting least time between two live edits (§3.5); a "slow down" doubles it, up to the most. */
+export declare const LIVE_SPACING_MS: Readonly<Record<LivePlatform, number>>;
+/** The chat_meta key that says reactions were refused, and when. */
+export declare const ACK_REFUSED_META = "reactions-refused";
+/** What one app does for a live message. Text arrives already rendered in the app's format (`liveText`). */
+export type ChatLiveTransport = {
+    platform: LivePlatform;
+    /** The longest rendered text one live message carries (the reply's first window plus the marker). */
+    limit: number;
+    /** Starting spacing; tests pass 0. */
+    spacingMs?: number;
+    /** Post the live message; resolves its id. Discord sends its nonce, so a repeat returns the same message. */
+    create(text: string): Promise<string>;
+    /** Discord only: the message an unconfirmed create left, found by its nonce, or null (not among the recent ones).
+     * Throws when the lookup itself failed: that is not absence. */
+    recover?(): Promise<string | null>;
+    /** With `recover`: how long after a create a repeat under the same nonce is known to return the same message. */
+    nonceMs?: number;
+    /** Replace the live message's whole text (every field, as the final edit does). */
+    edit(message: string, text: string): Promise<void>;
+    /** The wait an error asks for when it means "slow down", else null. */
+    rateLimited(error: unknown): number | null;
+    /** True when the app may not have done it (the answer was lost). */
+    uncertain(error: unknown): boolean;
+};
+/** A worker's live-reply switch: on, or on with a least spacing between edits (tests pass 0). */
+export type LiveReplies = boolean | {
+    spacingMs: number;
+};
+/** The transport's spacing for that switch (undefined: the app's own start). */
+export declare const liveSpacingOf: (on: LiveReplies | undefined) => number | undefined;
+/** Forget every connection's live spacing (tests). */
+export declare function resetLiveGates(): void;
+/**
+ * A view as one live message's text, rendered for the app and measured after rendering: the shaped reply's first
+ * window that fits (cut where the final split would cut, never inside a link, code or bold), "(continues…)" when
+ * more follows, then the status and the "not final" marker. Null: nothing to show (the turn ended).
+ */
+export declare function liveText(view: LiveView, platform: LivePlatform, limit: number, shape?: ShapeOptions): string | null;
+export type LiveRow = {
+    state: "creating" | "uncertain" | "placed" | "finalized" | "abandoned";
+    message: string | null;
+    generation: number;
+    problem: string | null;
+    created: string;
+};
+export declare function liveRow(state: ChatState, event: string): LiveRow | null;
+/** Is this message id the live message of that event (the one its reply's first part edits)? */
+export declare function isLiveMessage(state: ChatState, event: string, message: string | undefined): boolean;
+/**
+ * Plan an event's reply (ChatState.plan) onto its live message: when one was placed, the first part edits it, and the
+ * row is finalized in the same transaction. An uncertain create (Slack, Teams) leaves the reply to post fresh, and
+ * the event's problem says a "Working on it…" may be left above it.
+ */
+export declare function planWithLive(state: ChatState, event: string, parts: ChatContent[], now: Date): void;
+export type ChatLiveTurn = {
+    /** Feed one engine event (synchronous, never throws). The first one posts "Working on it…". */
+    push(event: LeadProgress): void;
+    /** The message waits behind earlier ones: post "Waiting for your earlier messages…" unless a live message is up. */
+    queued(): Promise<void>;
+    /** Stop editing: drop the waiting view and settle the request in flight. Resolves before the reply may be planned. */
+    close(): Promise<void>;
+};
+export declare function openChatLive(input: {
+    state: ChatState;
+    event: ChatEvent;
+    installation: string;
+    transport: ChatLiveTransport;
+    /** The owner's message and this app's origin, as the final reply is shaped. */
+    shape: ShapeOptions;
+    /** The lease, the connection and the binding, read locally (no network): the fence for words that carry no data. */
+    fenced: () => boolean;
+    /** The chat's full standing (channelAccess under the turn's ceiling) before an edit that carries the turn's words.
+     * False: refused (nothing more is edited). Throws: no answer now (that view is dropped). */
+    standing: () => Promise<boolean>;
+    now: () => Date;
+}): ChatLiveTurn;
+/** What one app does for the 👀. Teams gives bots no reactions: its ack is "typing…", with nothing to take off. */
+export type ChatAckHooks = {
+    react?: (event: ChatEvent) => Promise<unknown>;
+    unreact?: (event: ChatEvent) => Promise<unknown>;
+    typing?: (event: ChatEvent) => Promise<unknown>;
+    /** This install may not react (a missing permission or scope): stop asking for a while, quietly. */
+    refused: (error: unknown) => boolean;
+    /** Already so: the reaction is already on (when adding) or already gone, with its message (when taking it off). */
+    settled: (error: unknown) => boolean;
+    rateLimited: (error: unknown) => number | null;
+};
+/** Did this install refuse reactions within the last minute? Then no 👀 is asked for (no error after error). */
+export declare function reactionsRefused(state: ChatState, installation: string, now: Date): boolean;
+/**
+ * One step of the 👀 work for an installation, beside the queue: take one 👀 off a message whose reply (or failure
+ * notice) is delivered, else put one on the next owner's message that arrived. True: it did something (call again).
+ */
+export declare function ackPass(input: {
+    state: ChatState;
+    installation: string;
+    owner: string;
+    current: () => boolean;
+    hooks: ChatAckHooks;
+    now: () => Date;
+}): Promise<boolean>;
+/**
+ * Before an event's reply is planned: a create that never confirmed (this pass, or before a restart) is found by its
+ * nonce on Discord, else marked uncertain, so planning edits the right message or none. False: the lookup failed, so
+ * it is still undecided and planning waits (a "slow down" is shared).
+ */
+export declare function settleLive(state: ChatState, event: string, transport: ChatLiveTransport | null, now: () => Date): Promise<boolean>;
+/** A cosmetic send (typing…) under the app's shared cooldown: skipped while it holds, and a "slow down" sets it. */
+export declare function underCooldown(state: ChatState, installation: string, rateLimited: (error: unknown) => number | null, now: () => Date, call: () => Promise<unknown>): () => Promise<unknown>;
+/** Forget who was acknowledged when (tests). */
+export declare function resetAckSpacing(): void;
+/**
+ * The 👀 loop a worker runs beside its queue while its connection is the current one: a pass every quarter second,
+ * and at once when `wake` is called (a message just arrived). Never throws.
+ */
+export declare function runChatAcks(input: Omit<Parameters<typeof ackPass>[0], "now"> & {
+    same: () => boolean;
+    signal: AbortSignal;
+    now?: () => Date;
+}): {
+    wake: () => void;
+    done: Promise<void>;
+};