toolroll 0.9.104 → 0.9.105

package/dist/chat-live.js

@@ -1,50 +1,18 @@
-/**
- * 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 { createLiveReply, createLiveSender, LIVE_STATUS } from "./live-reply.js";
 import { renderReply, shapeReplyParts } from "./reply-shape.js";
 import { unsent } from "./chat-message-states.js";
-/** The live message's fixed words. */
 export const LIVE_WORDS = {
     working: "Working on it…",
     notFinal: "(still writing — not final)",
     continues: "(continues…)",
     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 const LIVE_SPACING_MS = { slack: 1_500, discord: 1_250, teams: 2_000 };
 const MOST_SPACING_MS = 10_000;
-/** A message older than this when the 👀 would go gets none. */
 const ACK_WINDOW_MS = 60_000;
-/** One 👀 per person a second; a burst waits its turn. */
 const ACK_SPACING_MS = 1_000;
-/** After an app refused reactions (a missing permission), ask again at most this often (one quiet try a minute). */
 const ACK_REFUSED_RETRY_MS = 60_000;
-/** The chat_meta key that says reactions were refused, and when. */
 export const ACK_REFUSED_META = "reactions-refused";
-/** The transport's spacing for that switch (undefined: the app's own start). */
 export const liveSpacingOf = (on) => typeof on === "object" ? on.spacingMs : undefined;
 const gates = new Map();
 function gateOf(state, installation, base) {
@@ -54,27 +22,18 @@ function gateOf(state, installation, base) {
         gates.set(key, gate = { spacing: base, base, liveNext: 0 });
     return gate;
 }
-/** The app asked everyone to wait (shared with durable delivery). */
 const coolingDown = (state, installation, now) => state.retryAt(installation) > now.toISOString();
-/** A "slow down" on a cosmetic send: the whole connection waits, and live edits space out further. */
 function slowDown(state, installation, gate, retryMs, now) {
     state.deferUntil(installation, new Date(now.getTime() + Math.max(1_000, retryMs)).toISOString());
     if (gate !== null)
         gate.spacing = Math.min(MOST_SPACING_MS, Math.max(gate.base, gate.spacing * 2, 500));
 }
 const easeBack = (gate) => { gate.spacing = Math.max(gate.base, gate.spacing - (gate.spacing - gate.base) / 4); };
-/** Forget every connection's live spacing (tests). */
 export function resetLiveGates() { gates.clear(); }
-// ---- rendering --------------------------------------------------------------------------------------------------
 const italic = (platform, plain) => {
     const words = renderReply(plain, platform);
     return platform === "discord" ? `*${words}*` : `_${words}_`;
 };
-/**
- * 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 function liveText(view, platform, limit, shape = {}) {
     switch (view.phase) {
         case "closed": return null;
@@ -95,8 +54,6 @@ export function liveRow(state, event) {
     return row === undefined ? null : { state: String(row["state"]), message: row["message"] == null ? null : String(row["message"]),
         generation: Number(row["generation"]), problem: row["problem"] == null ? null : String(row["problem"]), created: String(row["created"]) };
 }
-/** The message an unconfirmed create left: found, not among the recent messages (absent), or the lookup failed (a
- * "slow down" is shared). */
 async function recoverLive(state, installation, transport, now) {
     try {
         const found = await transport.recover();
@@ -112,27 +69,19 @@ async function recoverLive(state, installation, transport, now) {
 const setLive = (state, event, from, to, now, extra = {}) => Number(state.prepare(`UPDATE chat_live SET state = ?, message = COALESCE(?, message), problem = COALESCE(?, problem), updated = ?
     WHERE provider = :provider AND event = ? AND state IN (SELECT value FROM json_each(?))`)
     .run(to, extra.message ?? null, extra.problem ?? null, now.toISOString(), event, JSON.stringify(from)).changes) === 1;
-/** Is this message id the live message of that event (the one its reply's first part edits)? */
 export function isLiveMessage(state, event, message) {
     if (message === undefined)
         return false;
     const row = liveRow(state, event);
     return row !== null && row.message === message;
 }
-/** A first reply part that may replace the live message: words only, to the person's own chat. */
 const editable = (part) => part !== undefined && part.edit === undefined && part.channel === undefined && part.proposal === undefined && part.image === undefined &&
     part.rich === undefined && part.ask === undefined && part.decide === undefined && part.flow === undefined && part.choose === undefined &&
     part.note === undefined && part.question === undefined && part.prompt === undefined;
-/**
- * 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 function planWithLive(state, event, parts, now) {
     state.store.transact(() => {
         const row = liveRow(state, event);
         const onto = row !== null && row.message !== null && (row.state === "placed" || row.state === "abandoned") && editable(parts[0]);
-        // A dropped event gets no reply, so its live message is left as it is.
         if (!state.plan(event, onto ? [{ ...parts[0], edit: row.message }, ...parts.slice(1)] : parts, now))
             return;
         if (row === null)
@@ -150,9 +99,7 @@ export function openChatLive(input) {
     const gate = gateOf(state, input.installation, transport.spacingMs ?? LIVE_SPACING_MS[transport.platform]);
     const live = createLiveReply(input.shape);
     let row = liveRow(state, event.id);
-    // Off for good: an uncertain or finished message, a refused create, or lost standing.
     let off = row !== null && row.state !== "placed" && !(row.state === "creating" && transport.recover !== undefined);
-    // A create from before a restart on an app that can't tell whether it landed: uncertain, never posted again.
     if (row?.state === "creating" && transport.recover === undefined)
         setLive(state, event.id, ["creating"], "uncertain", input.now(), { problem: LIVE_WORDS.maybeLeft });
     let message = row?.state === "placed" ? row.message : null;
@@ -175,15 +122,12 @@ export function openChatLive(input) {
                         .run(event.id, input.now().toISOString(), input.now().toISOString());
                 }
                 else if (row.state === "creating") {
-                    // A create from before a restart: Discord finds it by its nonce, or repeats it under the same nonce while
-                    // that is known to return the same message; Slack and Teams can't know, so it is never posted again.
                     if (transport.recover === undefined) {
                         off = true;
                         setLive(state, event.id, ["creating"], "uncertain", input.now(), { problem: LIVE_WORDS.maybeLeft });
                         return;
                     }
                     const found = await recoverLive(state, input.installation, transport, input.now);
-                    // The lookup failed: undecided, so nothing is posted; the row stays creating for a later look.
                     if ("failed" in found)
                         return;
                     if ("found" in found) {
@@ -222,7 +166,6 @@ export function openChatLive(input) {
                     setLive(state, event.id, ["creating"], "uncertain", input.now(), { problem: LIVE_WORDS.maybeLeft });
                 }
                 else if (transport.uncertain(error)) {
-                    // Discord: the row stays creating, so the reply's planning looks for it by nonce once more (settleLive).
                     const found = await recoverLive(state, input.installation, transport, input.now);
                     if ("found" in found) {
                         message = found.found;
@@ -232,7 +175,6 @@ export function openChatLive(input) {
                         off = true;
                 }
                 else {
-                    // Refused outright: nothing was posted. The reply goes out as a new message.
                     off = true;
                     state.prepare("DELETE FROM chat_live WHERE provider = :provider AND event = ? AND state = 'creating'").run(event.id);
                 }
@@ -257,7 +199,6 @@ export function openChatLive(input) {
                 await placing;
             if (off || message === null || stopped.signal.aborted)
                 return;
-            // Spacing: the app's current pace, and a 👀 just sent goes first.
             await pause(gate.liveNext - input.now().getTime());
             if (off || stopped.signal.aborted)
                 return;
@@ -268,7 +209,6 @@ export function openChatLive(input) {
                 standing = await input.standing();
             }
             catch (error) {
-                // Not a refusal, only no answer now (a "slow down", a lost answer): this view is dropped and the message stays.
                 const wait = transport.rateLimited(error);
                 if (wait !== null)
                     slowDown(state, input.installation, gate, wait, input.now());
@@ -276,10 +216,8 @@ export function openChatLive(input) {
             }
             if (!standing)
                 return abandon("Chat access changed");
-            // Re-read after the awaits: the turn may have ended, or the lease moved, meanwhile.
             if (off || stopped.signal.aborted || !input.fenced())
                 return;
-            // A cooldown holds: this view is dropped (a later one may go).
             if (coolingDown(state, input.installation, input.now()))
                 return;
             gate.liveNext = input.now().getTime() + gate.spacing;
@@ -293,12 +231,10 @@ export function openChatLive(input) {
                 const wait = transport.rateLimited(error);
                 if (wait !== null)
                     slowDown(state, input.installation, gate, wait, input.now());
-                // Anything else: this view is dropped, previews are best effort.
             }
         },
     });
     const show = (view) => {
-        // A blocked preview clears at once back to the status line; the turn may still answer.
         const shown = view.phase === "closed" && view.why === "blocked" ? { phase: "working", status: live.status() } : view;
         const text = liveText(shown, transport.platform, transport.limit, input.shape);
         if (text === null)
@@ -316,7 +252,7 @@ export function openChatLive(input) {
                 else if (message === null && placing === null)
                     void place(italic(transport.platform, LIVE_WORDS.working));
             }
-            catch { /* a live message never breaks the turn */ }
+            catch { }
         },
         async queued() {
             if (off || message !== null)
@@ -335,23 +271,17 @@ const setAck = (state, event, ack, now) => {
     state.prepare(`INSERT INTO chat_ack (provider, event, state, created, updated) VALUES (:provider, ?, ?, ?, ?)
     ON CONFLICT (provider, event) DO UPDATE SET state = excluded.state, updated = excluded.updated`).run(event, ack, now.toISOString(), now.toISOString());
 };
-/** Did this install refuse reactions within the last minute? Then no 👀 is asked for (no error after error). */
 export function reactionsRefused(state, installation, now) {
     const at = state.meta(installation, ACK_REFUSED_META);
     return at !== null && Date.parse(at) + ACK_REFUSED_RETRY_MS > now.getTime();
 }
 const lastAck = new Map();
-/**
- * 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 async function ackPass(input) {
     const { state, installation, hooks } = input;
     const fenced = () => input.current() && state.owns(installation, input.owner, input.now());
     if (!fenced() || coolingDown(state, installation, input.now()))
         return false;
     const eventOf = (row) => (row === undefined ? null : state.event(String(row["event"])));
-    // Taking one off: its event is handled and nothing of its reply waits to send.
     if (hooks.unreact !== undefined) {
         const done = eventOf(state.prepare(`SELECT a.event FROM chat_ack a JOIN chat_event e ON e.provider = a.provider AND e.id = a.event
       WHERE a.provider = :provider AND a.state = 'sent' AND e.installation = ? AND e.state IN ('done','dropped')
@@ -366,7 +296,6 @@ export async function ackPass(input) {
                 const wait = hooks.rateLimited(error);
                 if (wait !== null)
                     slowDown(state, installation, null, wait, input.now());
-                // Gone already, or not ours to take off any more: settled. Anything else is tried again on a later pass.
                 else if (hooks.settled(error) || hooks.refused(error))
                     setAck(state, done.id, "done", input.now());
                 else
@@ -375,7 +304,6 @@ export async function ackPass(input) {
             return true;
         }
     }
-    // Putting one on: the owner's own direct message, saved and not yet acknowledged, recent enough to matter.
     const since = new Date(input.now().getTime() - ACK_WINDOW_MS).toISOString();
     const event = eventOf(state.prepare(`SELECT e.id AS event FROM chat_event e JOIN chat_binding b ON b.provider = e.provider AND b.id = e.binding
     WHERE e.provider = :provider AND e.installation = ? AND e.kind = 'message' AND e.state = 'queued' AND e.created >= ?
@@ -403,9 +331,7 @@ export async function ackPass(input) {
     if (!fenced())
         return false;
     lastAck.set(key, input.now().getTime());
-    // Saved as on before it is asked for: a crash in between can only leave a take-off with nothing to take off.
     setAck(state, event.id, hooks.react !== undefined ? "sent" : "done", input.now());
-    // A 👀 goes before the next live edit.
     for (const [name, gate] of gates)
         if (name === `${state.provider}:${installation}`)
             gate.liveNext = Math.max(gate.liveNext, input.now().getTime() + gate.spacing / 2);
@@ -429,11 +355,6 @@ export async function ackPass(input) {
     }
     return true;
 }
-/**
- * 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 async function settleLive(state, event, transport, now) {
     const row = liveRow(state, event);
     if (row?.state !== "creating")
@@ -447,7 +368,6 @@ export async function settleLive(state, event, transport, now) {
         setLive(state, event, ["creating"], "uncertain", now(), { problem: LIVE_WORDS.maybeLeft });
     return true;
 }
-/** A cosmetic send (typing…) under the app's shared cooldown: skipped while it holds, and a "slow down" sets it. */
 export function underCooldown(state, installation, rateLimited, now, call) {
     return async () => {
         if (coolingDown(state, installation, now()))
@@ -463,12 +383,7 @@ export function underCooldown(state, installation, rateLimited, now, call) {
         }
     };
 }
-/** Forget who was acknowledged when (tests). */
 export function resetAckSpacing() { lastAck.clear(); }
-/**
- * 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 function runChatAcks(input) {
     let wakeUp = null;
     const wake = () => { wakeUp?.(); };
@@ -479,7 +394,7 @@ export function runChatAcks(input) {
                 for (let steps = 0; steps < 8 && await ackPass({ ...input, now: input.now ?? (() => new Date()) }); steps++)
                     ;
             }
-            catch { /* quiet: a 👀 is a courtesy */ }
+            catch { }
             if (!input.same() || input.signal.aborted)
                 break;
             await new Promise(resolve => {

package/dist/chat-message-states.js

@@ -1,55 +1,34 @@
-/**
- * Every fixed result word a message row can be written with. These are stored in `chat_event.result`, so each one
- * must stay byte-identical: renaming one would change what older rows mean.
- */
 export const CHAT_MESSAGE_OUTCOMES = [
-    // done: the reply was sent (Telegram)
-    "answered", // a fresh turn's reply
-    "replayed", // the reply of a turn found again after a restart, or sent on a later pass
-    "typed-start", // Toolroll's own reply to a typed yes on a Start card
-    // queued: waiting for the lead, with no age bound or the bounds in telegram-lead.ts
-    "busy", // the lead is answering something else
-    "backlog", // the person's own earlier messages wait first
-    "replayed:running", // a turn was already admitted for it and is still working
-    "registry-unavailable", // the project records could not be read
-    "registry-unavailable:admitted", // the same, but a turn already took the message
-    // queued: the reply is planned and only sending remains
+    "answered",
+    "replayed",
+    "typed-start",
+    "busy",
+    "backlog",
+    "replayed:running",
+    "registry-unavailable",
+    "registry-unavailable:admitted",
     "delivering",
-    "answered:sending", // a fresh turn's reply, handed to the bridge's cycle to send
-    // failed
-    "unpaired", // the chat's pairing changed before the turn
-    "unsent:no-session", // the session ended before the reply went out
-    "replayed:missing", // the turn its receipt names is gone
-    "typed-start:not-counted", // a typed yes whose card's turn is gone
-    // dropped: the chat was disconnected while the message waited (chat-core.ts)
+    "answered:sending",
+    "unpaired",
+    "unsent:no-session",
+    "replayed:missing",
+    "typed-start:not-counted",
     "revoked",
 ];
-/** Words a message is queued under while it waits for another attempt (telegram-lead.ts `requeue`). */
 export const CHAT_WAIT_OUTCOMES = ["busy", "backlog", "replayed:running", "registry-unavailable", "registry-unavailable:admitted"];
-/** Waiting for the lead itself (it is answering, or earlier messages wait first): the two-hour bound applies. */
 export const CHAT_LEAD_WAITS = ["busy", "backlog"];
-/** Waiting on a turn that was already admitted: no age bound (the turn's own deadline ends it). */
 export const CHAT_ADMITTED_WAITS = ["replayed:running", "registry-unavailable:admitted"];
-/** Builders for the result words that carry a detail. The stored text is exactly what the old string joins wrote. */
 export const chatOutcome = {
-    /** A wait that ran past its age bound. */
     gaveUp: (wait) => `${wait}:gave-up`,
-    /** The lead refused the turn, or no session could be resolved for it. */
     refused: (reason) => `refused:${reason}`,
-    /** The turn ran and failed. */
     failed: (reason) => `failed:${reason}`,
-    /** The recovered turn had ended without an answer: its failure reason as the turn row stores it ("failed" when none). */
     replayedFailed: (reason) => `replayed:${reason ?? "failed"}`,
-    /** The reply could not go out: the chat or its projects changed (the problem in words). */
     unsent: (problem) => `unsent:${problem}`,
-    /** The reply was still unsent a day after it was planned (the last send error, or "unsent"). */
     unsentGaveUp: (error) => `unsent:gave-up:${error ?? "unsent"}`,
 };
-/** Is this word one of the waits for the lead itself (busy or backlog)? */
 export function isLeadWait(outcome) {
     return CHAT_LEAD_WAITS.includes(outcome ?? "");
 }
-/** Is this word a wait on a turn that was already admitted (no age bound)? */
 export function isAdmittedWait(outcome) {
     return CHAT_ADMITTED_WAITS.includes(outcome ?? "");
 }
@@ -59,15 +38,9 @@ function alias(name) {
         throw new Error(`not a table alias: ${name}`);
     return name;
 }
-/** SQL: this `chat_part` row (by its alias) has not reached the person: planned and neither sent nor dropped. */
 export function unsentPart(part) {
     return `${alias(part)}.state = 'pending'`;
 }
-/**
- * SQL: the `chat_event` row (by its alias or table name) has a reply part that has not reached the person yet.
- * The one answer to "is anything of this reply unsent?" on every app; wrap it in NOT for "everything reached them
- * or was dropped". `part` names the inner alias when the caller's query already uses the default.
- */
 export function unsent(event, part = "unsent_part") {
     const e = alias(event), p = alias(part);
     return `EXISTS (SELECT 1 FROM chat_part ${p} WHERE ${p}.provider = ${e}.provider AND ${p}.event = ${e}.id AND ${unsentPart(p)})`;