toolroll 0.9.95 → 0.9.97

package/dist/telegram-live.js

@@ -0,0 +1,224 @@
+import { createLiveReply, createLiveSender, LIVE_STATUS } from "./live-reply.js";
+import { shapedWindow, telegramReply } from "./reply-shape.js";
+/** The acknowledgement on the owner's message: "seen, working on it". Removed once the answer or the failure notice is
+ * delivered; never replaced by a "done" mark (an answer isn't finished work). */
+export const ACK_EMOJI = "👀";
+/** At most one reaction change per chat this often; a burst waits its turn, in order. */
+export const ACK_GAP_MS = 1_000;
+/** A reaction change that meets Telegram's pause waits it out when it is this short; a longer pause skips it. */
+const ACK_MAX_WAIT_MS = 30_000;
+/** Drafts start this far apart and widen (doubling, up to the cap) whenever Telegram asks for a pause. */
+export const DRAFT_SPACING_MS = 1_200;
+const DRAFT_MAX_SPACING_MS = 10_000;
+/** Telegram keeps a draft about 30 seconds: one that has not changed is sent again after this long. */
+export const DRAFT_KEEPALIVE_MS = 25_000;
+/** Telegram's message limit, counted after entities (UTF-16 units, as JS strings are). */
+export const TELEGRAM_TEXT_MAX = 4_096;
+/** The body of a writing draft within `budget` characters once rendered: cut at a safe place in the shaped text first
+ * (never inside code, a link, a bold anchor or an emoji), rendered, measured, and cut smaller if it still doesn't fit.
+ * A body that can't fit (a single link longer than the budget) shows nothing. */
+export function draftBody(shaped, budget) {
+    if (budget <= 0)
+        return { text: "", entities: [] };
+    let size = budget;
+    for (let attempt = 0; attempt < 8 && size >= 1; attempt += 1) {
+        const window = shapedWindow(shaped, size);
+        const cut = window.length < shaped.length;
+        const rendered = telegramReply(cut ? window.trimEnd() : window);
+        const text = cut ? `${rendered.text} …` : rendered.text;
+        if (text.length <= budget)
+            return { text, entities: rendered.entities };
+        size = Math.min(size - 1, Math.floor(size * budget / text.length) - 2);
+    }
+    return { text: "", entities: [] };
+}
+/**
+ * One live view as a draft: the status line in italics, then (once text exists) the partial reply as text plus
+ * entities, never Markdown. Plain "Thinking…" is Telegram's own empty-text placeholder. Closed views send nothing.
+ */
+export function telegramDraftOf(view) {
+    if (view.phase === "closed")
+        return null;
+    if (view.phase === "queued")
+        return { text: LIVE_STATUS.queued, entities: [{ type: "italic", offset: 0, length: LIVE_STATUS.queued.length }] };
+    if (view.phase === "working") {
+        if (view.status === LIVE_STATUS.thinking)
+            return { text: "", entities: [] };
+        return { text: view.status, entities: [{ type: "italic", offset: 0, length: view.status.length }] };
+    }
+    const head = view.status;
+    const gap = "\n\n";
+    const body = draftBody(view.text, TELEGRAM_TEXT_MAX - head.length - gap.length);
+    if (body.text === "")
+        return { text: head, entities: [{ type: "italic", offset: 0, length: head.length }] };
+    const shift = head.length + gap.length;
+    return {
+        text: `${head}${gap}${body.text}`,
+        entities: [{ type: "italic", offset: 0, length: head.length }, ...body.entities.map(one => ({ ...one, offset: one.offset + shift }))],
+    };
+}
+/** One draft on the wire, under the shared pause. A retry_after is recorded for every sender of this bot. */
+async function sendDraft(store, botId, transport, clock, chatId, draftId, payload) {
+    if (store.telegramRetryAt(botId) > clock().toISOString())
+        return "paused";
+    let answer;
+    try {
+        answer = await transport("sendMessageDraft", { chat_id: Number(chatId), draft_id: draftId, text: payload.text, ...(payload.entities.length === 0 ? {} : { entities: payload.entities }) });
+    }
+    catch {
+        return "lost";
+    }
+    if (answer.ok)
+        return "sent";
+    const retry = answer.parameters?.retry_after;
+    if (typeof retry === "number" && Number.isFinite(retry) && retry > 0) {
+        store.deferTelegram(botId, new Date(clock().getTime() + Math.ceil(retry) * 1_000).toISOString());
+        return "paused";
+    }
+    return answer.uncertain === true ? "lost" : "refused";
+}
+// ---- the 👀 acknowledgement ----------------------------------------------------------
+/** One lane per chat: reaction changes go out in order (an ack never lands after its own removal), spaced. */
+const ackLanes = new Map();
+const pause = (ms) => new Promise(resolve => { const timer = setTimeout(resolve, ms); timer.unref?.(); });
+/**
+ * Put 👀 on the owner's message (`on`) or take it off. Best effort and never awaited by the caller's durable work: a
+ * missing pairing, a failure or a long pause skips it silently. `paired` is re-checked at the moment of sending; a
+ * reaction carries no project data, so the pairing alone fences it. Resolves once this change was tried.
+ */
+export function telegramAck(args) {
+    const key = `${args.botId}:${args.chatId}`;
+    const lane = ackLanes.get(key) ?? { tail: Promise.resolve(), lastAt: Number.NEGATIVE_INFINITY };
+    ackLanes.set(key, lane);
+    const gap = args.gapMs ?? ACK_GAP_MS;
+    // Never throws: a store closed meanwhile (a stop) or anything else skips the change.
+    const run = () => change().catch(() => undefined);
+    const change = async () => {
+        const spaced = lane.lastAt + gap - Date.now();
+        if (spaced > 0)
+            await pause(spaced);
+        const held = Date.parse(args.store.telegramRetryAt(args.botId)) - args.clock().getTime();
+        if (Number.isFinite(held) && held > 0) {
+            if (held > ACK_MAX_WAIT_MS)
+                return;
+            await pause(held);
+        }
+        if (!args.paired())
+            return;
+        lane.lastAt = Date.now();
+        try {
+            const answer = await args.transport("setMessageReaction", {
+                chat_id: Number(args.chatId), message_id: Number(args.messageId), reaction: args.on ? [{ type: "emoji", emoji: ACK_EMOJI }] : [],
+            });
+            const retry = answer.ok ? undefined : answer.parameters?.retry_after;
+            if (typeof retry === "number" && Number.isFinite(retry) && retry > 0)
+                args.store.deferTelegram(args.botId, new Date(args.clock().getTime() + Math.ceil(retry) * 1_000).toISOString());
+        }
+        catch { /* skipped silently */ }
+    };
+    const done = lane.tail.then(run, run);
+    lane.tail = done;
+    // A finished lane is forgotten; the next change starts a fresh one (spacing restarts from now).
+    void done.then(() => { if (ackLanes.get(key) === lane && lane.tail === done && Date.now() - lane.lastAt >= gap)
+        ackLanes.delete(key); });
+    return done;
+}
+// ---- the draft --------------------------------------------------------------------------
+/** Chats (bot:binding) whose turn has a live draft in this process: a waiting message's draft never covers it. */
+const liveChats = new Set();
+/** When each waiting message last had its "Waiting for your earlier messages…" draft (bot:row). */
+const waitingDrafts = new Map();
+/**
+ * One running turn's draft. `standing` is the caller's full proof for a draft that carries words (it may await; the
+ * close is re-checked after it); `paired` is enough for Telegram's empty "Thinking…". A draft Telegram refuses outright
+ * (not a pause, not a lost answer) turns this turn's drafts off; previews are best effort.
+ */
+export function createTelegramLiveDraft(args) {
+    const reply = createLiveReply(args.shape);
+    const keepAlive = args.timing?.keepAliveMs ?? DRAFT_KEEPALIVE_MS;
+    const base = args.timing?.draftSpacingMs ?? DRAFT_SPACING_MS;
+    const chat = `${args.botId}:${args.binding}`;
+    let spacing = base;
+    let lastSentAt = Date.now();
+    let off = false;
+    liveChats.add(chat);
+    /** What the draft shows now: a preview closed as a possible password or key keeps only the status line. */
+    const current = () => {
+        const view = reply.view();
+        if (view.phase !== "closed")
+            return view;
+        return view.why === "blocked" ? { phase: "working", status: LIVE_STATUS.held } : null;
+    };
+    const sender = createLiveSender({
+        spacingMs: () => spacing,
+        send: async (view) => {
+            if (off)
+                return;
+            const payload = telegramDraftOf(view);
+            const turn = reply.turn;
+            if (payload === null || turn === null)
+                return;
+            const allowed = payload.text === "" ? args.paired() : await args.standing(turn);
+            if (!allowed || sender.closed)
+                return;
+            const outcome = await sendDraft(args.store, args.botId, args.transport, args.clock, args.chatId, args.draftId, payload);
+            if (outcome === "sent")
+                lastSentAt = Date.now();
+            else if (outcome === "paused")
+                spacing = Math.min(DRAFT_MAX_SPACING_MS, spacing * 2);
+            else if (outcome === "refused")
+                off = true;
+        },
+    });
+    const timer = setInterval(() => {
+        if (sender.closed || Date.now() - lastSentAt < keepAlive)
+            return;
+        const view = current();
+        if (view !== null)
+            sender.offer(view);
+    }, Math.max(50, Math.min(keepAlive, 5_000)));
+    timer.unref?.();
+    return {
+        get turn() { return reply.turn; },
+        onProgress: event => {
+            // The first event names the turn: Telegram's "Thinking…" shows at once, even before the view changes.
+            const first = reply.turn === null;
+            if (!reply.push(event) && !first)
+                return;
+            const view = current();
+            if (view !== null)
+                sender.offer(view);
+        },
+        close: async () => {
+            clearInterval(timer);
+            liveChats.delete(chat);
+            await sender.close();
+        },
+    };
+}
+/**
+ * A message waiting for the lead (busy, or behind the owner's earlier messages): "Waiting for your earlier messages…"
+ * as a draft, refreshed only after the keep-alive interval, and never while this chat's running turn has its own
+ * draft. Carries no project data: the pairing and the claim fence it.
+ */
+export async function telegramWaitingDraft(args) {
+    const key = `${args.botId}:${args.draftId}`;
+    if (liveChats.has(`${args.botId}:${args.binding}`))
+        return;
+    const last = waitingDrafts.get(key);
+    if (last !== undefined && Date.now() - last < (args.timing?.keepAliveMs ?? DRAFT_KEEPALIVE_MS))
+        return;
+    if (!args.allowed())
+        return;
+    const payload = telegramDraftOf({ phase: "queued" });
+    if (await sendDraft(args.store, args.botId, args.transport, args.clock, args.chatId, args.draftId, payload) !== "sent")
+        return;
+    waitingDrafts.set(key, Date.now());
+    // Bounded: the oldest entries go first.
+    while (waitingDrafts.size > 500)
+        waitingDrafts.delete(waitingDrafts.keys().next().value);
+}
+/** The message is answered or failed: its waiting draft is forgotten. */
+export function forgetWaitingDraft(botId, draftId) {
+    waitingDrafts.delete(`${botId}:${draftId}`);
+}

package/dist/telegram.d.ts

@@ -258,3 +258,5 @@ export declare function digestText(rows: readonly Notification[], since: string
  */
 /** At most this many of a chat's messages wait for the lead at once (the personal lead queue's bound). */
 export declare const TELEGRAM_MAX_WAITING = 10;
+/** A pushed update was kept for this bot: wake its bridge if it runs in this process (docs/plans/responsive-chat.md §3.1). */
+export declare function wakeTelegramBridge(botId: string): void;

package/dist/telegram.js

@@ -47,6 +47,7 @@ import { phoneCommand, phoneStatus, phoneTaskView, PHONE_CONSOLE_FOOTER, PHONE_H
 import { LEAD_MESSAGE_MAX_CHARS } from "./lead.js";
 import { envValue } from "./names.js";
 import { applyProposalTap, processTelegramConversations, phoneLinkButton, replyContextFor, telegramConversationRepos, telegramRequestId, tooLongText, whichTaskText, } from "./telegram-lead.js";
+import { telegramAck } from "./telegram-live.js";
 import { askOf, parseTelegramUpdate, pickOf, readTelegramButtonData, readTelegramUpdate, telegramButton } from "./contracts/telegram-callback.js";
 /** Read the enrolled project list on demand. No callback means no task data,
  * never an implicit all-database ceiling. Shared by pass and embedded follower. */
@@ -119,7 +120,11 @@ export function keepPushedUpdate(store, botId, body, now) {
         console.warn(`Ignoring a pushed Telegram update: ${update.issues.map(issue => issue.line).join("; ")}`);
         return { ok: true, kept: false };
     }
-    return { ok: true, kept: store.queueTelegramUpdate(botId, update.value.update_id, JSON.stringify(raw), now) };
+    const kept = store.queueTelegramUpdate(botId, update.value.update_id, JSON.stringify(raw), now);
+    // The bridge in this process (if any) stops idling and drains it now; elsewhere it waits at most one cycle.
+    if (kept)
+        wakeTelegramBridge(botId);
+    return { ok: true, kept };
 }
 /**
  * Environment wins, the credential file beside the database otherwise.
@@ -387,6 +392,21 @@ export async function followBridge(store, options) {
             }
             signal.addEventListener("abort", finish, { once: true });
         }));
+    /** The push idle: the ordinary wait, ended early when this process keeps a push for this bot. */
+    const idle = (ms) => {
+        if (bridgeWokenEarly.delete(botId))
+            return Promise.resolve();
+        let wake = () => { };
+        const woken = new Promise(resolve => { wake = resolve; });
+        const wakers = bridgeWakers.get(botId) ?? new Set();
+        bridgeWakers.set(botId, wakers);
+        wakers.add(wake);
+        return Promise.race([wait(ms), woken]).finally(() => {
+            wakers.delete(wake);
+            if (wakers.size === 0 && bridgeWakers.get(botId) === wakers)
+                bridgeWakers.delete(botId);
+        });
+    };
     const total = { cycles: 0, sent: 0, answered: 0, paired: 0, ignored: 0, problems: [] };
     let commandsListed = false;
     let failures = 0;
@@ -568,7 +588,8 @@ export async function followBridge(store, options) {
             // While Telegram pushes (v98) there is no long poll to wait on: a pushed update waits at most this long.
             const floor = pushing() ? PUSH_IDLE_MS : FOLLOW_IDLE_FLOOR_MS;
             if (!signal.aborted && report.sent === 0 && report.answered === 0 && (report.chatAnswered ?? 0) === 0 && took < floor) {
-                await wait(floor - took);
+                // While Telegram pushes, a push kept by this process's hook ends the idle at once.
+                await (pushing() ? idle(floor - took) : wait(floor - took));
             }
         }
     }
@@ -1886,6 +1907,19 @@ function applyConversation(context, update, effects) {
         request: telegramRequestId(botId, binding.id, update.update_id), text, context: context_, taskId, sourceRun,
     }, clock());
     report.chatQueued = (report.chatQueued ?? 0) + 1;
+    // Saved: 👀 on the owner's message right away (docs/plans/responsive-chat.md §3.1), once this update's transaction
+    // has committed. It comes off when the answer or the failure notice is delivered. Never awaited: a burst of messages
+    // waits its turn on the chat's own lane, not the drain.
+    const gapMs = context.conversation?.liveTiming?.ackGapMs;
+    effects.push(async () => {
+        void telegramAck({
+            store, botId, transport, clock, chatId: binding.chatId, messageId: String(message.message_id), on: true, ...(gapMs === undefined ? {} : { gapMs }),
+            paired: () => {
+                const live = store.liveTelegramBindingById(binding.id);
+                return live !== null && live.approverGeneration === binding.approverGeneration && store.accountOf(live.approver)?.role === "approver";
+            },
+        });
+    });
 }
 /** The picker's buttons: one task per row (its title and where it stands),
  * carried by the task's numeric reference so the data fits Telegram's 64
@@ -2605,3 +2639,17 @@ function expiredDraftGuard(store, binding, decisionId, now) {
     store.setNoteDraftState(Number(expired["id"]), "discarded");
     return true;
 }
+/** Bridges in this process waiting out their push idle, by bot: a kept push ends the wait early. */
+const bridgeWakers = new Map();
+/** Bots with a push kept while no bridge idled (it was mid-cycle): the next idle doesn't wait. */
+const bridgeWokenEarly = new Set();
+/** A pushed update was kept for this bot: wake its bridge if it runs in this process (docs/plans/responsive-chat.md §3.1). */
+export function wakeTelegramBridge(botId) {
+    const wakers = bridgeWakers.get(botId);
+    if (wakers === undefined || wakers.size === 0) {
+        bridgeWokenEarly.add(botId);
+        return;
+    }
+    for (const wake of wakers)
+        wake();
+}

package/dist/toolroll-update.js

@@ -43,6 +43,7 @@ import { V151_ADDED_COLUMNS } from "./storage.js";
 import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS } from "./store.js";
 import { V152_ADDED_COLUMNS } from "./code-map-store.js";
 import { V153_ADDED_COLUMNS } from "./plain-schema.js";
+import { V158_ADDED_COLUMNS } from "./lead-latency-schema.js";
 import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
@@ -429,7 +430,9 @@ const HISTORY_RULES = {
     // v154 adds a table only (check_stamp): no saved row changes, so no rule is needed for it.
     // v155 adds tables only (fleet-schema.ts): no saved row changes, so no rule is needed for it.
     // v156 adds tables only (fallback chains): likewise.
-    ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS, V151_ADDED_COLUMNS, V152_ADDED_COLUMNS, V153_ADDED_COLUMNS))
+    // v158 (after v157's chat-app tables): a saved lead step reads no tool names and no failure detail, and a saved reply no route and no failure detail
+    // (NULL); the quick-answer switch is a new table.
+    ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS, V134_ADDED_COLUMNS, V135_ADDED_COLUMNS, V138_ADDED_COLUMNS, V143_ADDED_COLUMNS, V147_ADDED_COLUMNS, V148_ADDED_COLUMNS, V150_ADDED_COLUMNS, V151_ADDED_COLUMNS, V152_ADDED_COLUMNS, V153_ADDED_COLUMNS, V158_ADDED_COLUMNS))
         .map(([table, rule]) => [table, { ...EARLIER_RULES[table], ...rule }])),
 };
 /** The tables a migration may remove whole (v115's removed features). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.95",
+  "version": "0.9.97",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"