toolroll 0.9.9 → 0.9.11

package/dist/telegram.js

@@ -29,7 +29,8 @@ import { join } from "node:path";
 import { validateNote } from "./decision.js";
 import { isLifecycleNotification, isTelegramProgressNotification, TELEGRAM_HOLD_REASONS } from "./store.js";
 import { telegramProgressCard } from "./telegram-progress.js";
-import { enqueueEveningDigests, isTaskFact, needsPerson, quietCardView, readyPingView } from "./chat-quiet.js";
+import { enqueueEveningDigests, finishedView, isTaskFact, joinsBatch, needsPerson, quietCardView } from "./chat-quiet.js";
+import { BATCH_MS, chatText, chatTitle, factLinkLabel, mentions, nameTelegramBot } from "./chat-voice.js";
 import { applyTeamInbound, deliverTeamChats, teamCommand } from "./telegram-team.js";
 import { applyFlowReply, applyFlowTap, FLOW_DECIDE_KEY, flowButtons, flowDecisionAt } from "./telegram-flow.js";
 import { connectChannel, FLOW_WORDS, takeChannelMessage, watchedChannel } from "./chat-inbox.js";
@@ -193,7 +194,7 @@ export function createTransport(token, timeoutMs = 30_000) {
         catch (error) {
             return {
                 ok: false,
-                description: scrub(error instanceof Error ? error.message : String(error), token),
+                description: scrub(transportError(error), token),
                 uncertain: true,
             };
         }
@@ -203,6 +204,48 @@ export function createTransport(token, timeoutMs = 30_000) {
         }
     };
 }
+/**
+ * Why this process can't reach Telegram the way the service does, or null.
+ * A coding agent's sandbox fences the network: Codex says so in its own
+ * variables, and Claude Code's sandbox routes traffic through a proxy on
+ * this computer, which curl uses and Node's fetch does not — so sends fail
+ * "fetch failed" while curl works (Oct 2). Builds, checks and agents also
+ * get a database of their own, so none of them can hold the live bridge;
+ * this keeps an agent-launched `watch` or `bridge` from holding it either.
+ */
+export function networkFence(env) {
+    const set = (name) => (env[name] ?? "") !== "";
+    if (set("CODEX_SANDBOX_NETWORK_DISABLED") || set("CODEX_SANDBOX"))
+        return "a Codex sandbox";
+    const agent = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT"].some(set);
+    const loopbackProxy = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"].some(name => {
+        const value = env[name] ?? "";
+        if (value === "")
+            return false;
+        try {
+            return /^(?:localhost|127\.\d+\.\d+\.\d+|\[::1\])$/i.test(new URL(value.includes("://") ? value : `http://${value}`).hostname);
+        }
+        catch {
+            return false;
+        }
+    });
+    return agent && loopbackProxy ? "a Claude Code sandbox" : null;
+}
+/** The plain line a fenced process says instead of polling or sending. */
+export function networkFenceLine(reason) {
+    return `Telegram: not connecting from here — this process runs inside ${reason}, which blocks its network. Replies and notifications go out from the Toolroll service.`;
+}
+/** fetch's own message ("fetch failed") with the reason under it, e.g. "fetch failed (EMFILE: too many open files)". */
+export function transportError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = error instanceof Error ? error.cause : undefined;
+    if (cause === undefined || cause === null)
+        return message;
+    const code = typeof cause.code === "string" ? cause.code : null;
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    const why = code !== null && !detail.includes(code) ? `${code}: ${detail}` : detail;
+    return why === "" || why === message ? message : `${message} (${why.slice(0, 160)})`;
+}
 /** The multipart body: every param a field (objects as JSON), the file last. Exported for the adapter's own test only. */
 export function multipartOf(params, upload) {
     const form = new FormData();
@@ -331,12 +374,16 @@ export async function followBridge(store, options) {
     // turn must not stall the long poll, and each cycle's lease re-acquire is
     // the renewal that keeps this the only live poller meanwhile. One
     // processor at a time; its counts land on the totals when it finishes.
+    // It only persists the reply: the cycle sends it, in the same slot as
+    // notifications, so a reply never needs a connection of its own beside
+    // the long poll (Oct 2: replies failed "fetch failed" for minutes while
+    // notifications from the same process went out).
     let inFlight = null;
     const kick = () => {
         if (inFlight !== null || options.conversation === undefined || options.readProjects === undefined)
             return;
         const report = { sent: 0, answered: 0, paired: 0, ignored: 0, backlog: false, problems: [] };
-        inFlight = processConversations(store, botId, transport, owner, clock, report, options.readProjects, options.conversation, signal)
+        inFlight = processConversations(store, botId, transport, owner, clock, report, options.readProjects, options.conversation, signal, "turns")
             .catch(error => { report.problems.push(`telegram chat: ${error instanceof Error ? error.message : String(error)}`); })
             .finally(() => {
             inFlight = null;
@@ -438,6 +485,8 @@ export async function followBridge(store, options) {
                     await transport("setMyCommands", { commands: TELEGRAM_COMMANDS });
                 }
                 catch { /* typed commands still work */ }
+                // After an upgrade, a bot still called StandingOrders becomes Toolroll, once per start; any other name is kept.
+                await nameTelegramBot(transport, "upgrade");
             }
             const startedAt = Date.now();
             const report = { sent: 0, answered: 0, paired: 0, ignored: 0, backlog: false, problems: [] };
@@ -446,13 +495,18 @@ export async function followBridge(store, options) {
                 await deliverOutbox(store, botId, transport, owner, clock, report, options.readProjects, options.canDeliver, options.conversation?.phoneOrigin, options.conversation?.evidenceRoot);
                 await deliverTeam(store, botId, transport, clock, report, options.readProjects, options.canDeliver, options.conversation?.phoneOrigin);
             }
+            // Replies the turn worker has planned go out here, like notifications.
+            if (options.conversation !== undefined && options.readProjects !== undefined) {
+                await processConversations(store, botId, transport, owner, clock, report, options.readProjects, options.conversation, signal, "replies");
+            }
             // Pushed updates first (some may wait from before a fall back), then — only while
             // Telegram isn't pushing — ask for more.
             const pushed = await drainInbox({ store, botId, transport, clock, report, readProjects: options.readProjects, conversation: options.conversation, projects: null }, owner, lease.generation);
             if (pushed > 0)
                 report.pushed = pushed;
             if (!pushing()) {
-                await drainUpdates(store, botId, transport, owner, lease.generation, lease.cursor, clock, report, pollSeconds, signal, options.readProjects, options.conversation);
+                // While a turn is running, poll briefly so its reply is sent within a second or two of being written.
+                await drainUpdates(store, botId, transport, owner, lease.generation, lease.cursor, clock, report, inFlight === null ? pollSeconds : 1, signal, options.readProjects, options.conversation);
                 // A push address nobody here wants any more (the public address was removed): take it down, so asking works again.
                 if (report.webhookActive === true && push === null)
                     await transport("deleteWebhook", { drop_pending_updates: false }, signal);
@@ -471,11 +525,13 @@ export async function followBridge(store, options) {
                 total.chatRefused = (total.chatRefused ?? 0) + report.chatRefused;
             if (report.chatConfirmed !== undefined)
                 total.chatConfirmed = (total.chatConfirmed ?? 0) + report.chatConfirmed;
+            if (report.chatAnswered !== undefined)
+                total.chatAnswered = (total.chatAnswered ?? 0) + report.chatAnswered;
             total.problems.push(...report.problems);
-            if (report.sent > 0 || report.answered > 0 || report.paired > 0 || (report.statusReplies ?? 0) > 0 || (report.chatQueued ?? 0) > 0 || (report.chatRefused ?? 0) > 0 || (report.chatConfirmed ?? 0) > 0 || report.problems.length > 0) {
+            if (report.sent > 0 || report.answered > 0 || report.paired > 0 || (report.statusReplies ?? 0) > 0 || (report.chatQueued ?? 0) > 0 || (report.chatAnswered ?? 0) > 0 || (report.chatRefused ?? 0) > 0 || (report.chatConfirmed ?? 0) > 0 || report.problems.length > 0) {
                 options.onCycle?.(report);
             }
-            if (report.problems.length > 0 && report.sent === 0 && report.answered === 0) {
+            if (report.problems.length > 0 && report.sent === 0 && report.answered === 0 && (report.chatAnswered ?? 0) === 0) {
                 // The wire is down. Back off; the counter resets on the first clean cycle.
                 if (!signal.aborted) {
                     await wait(FOLLOW_BACKOFF_MS[Math.min(failures, FOLLOW_BACKOFF_MS.length - 1)]);
@@ -490,7 +546,7 @@ export async function followBridge(store, options) {
             const took = Date.now() - startedAt;
             // 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 && took < floor) {
+            if (!signal.aborted && report.sent === 0 && report.answered === 0 && (report.chatAnswered ?? 0) === 0 && took < floor) {
                 await wait(floor - took);
             }
         }
@@ -498,37 +554,50 @@ export async function followBridge(store, options) {
     finally {
         // A turn in flight finishes on its own bounds (the engine's wall clock);
         // its reply is fenced on the claim and the channel like every other part.
-        if (inFlight !== null)
+        if (inFlight !== null) {
             await inFlight;
+            // Its reply was written for the cycle that will not come: send it now, while the lease is still ours.
+            if (options.conversation !== undefined && options.readProjects !== undefined) {
+                const report = { sent: 0, answered: 0, paired: 0, ignored: 0, backlog: false, problems: [] };
+                await processConversations(store, botId, transport, owner, clock, report, options.readProjects, options.conversation, undefined, "replies").catch(() => { });
+                if (report.chatAnswered !== undefined)
+                    total.chatAnswered = (total.chatAnswered ?? 0) + report.chatAnswered;
+                total.problems.push(...report.problems);
+            }
+        }
         store.releaseBridgeLease(botId, owner, clock());
     }
     return total;
 }
 /** The queued turns for one bot, counted onto the pass's report. */
-async function processConversations(store, botId, transport, owner, clock, report, readProjects, conversation, signal) {
+async function processConversations(store, botId, transport, owner, clock, report, readProjects, conversation, signal, only) {
     const chat = { answered: 0, refused: 0, problems: [] };
-    await processTelegramConversations({ store, botId, transport, owner, clock, readProjects, options: conversation, report: chat, ...(signal === undefined ? {} : { signal }) });
+    await processTelegramConversations({ store, botId, transport, owner, clock, readProjects, options: conversation, report: chat, ...(signal === undefined ? {} : { signal }), ...(only === undefined ? {} : { only }) });
     if (chat.answered > 0)
         report.chatAnswered = (report.chatAnswered ?? 0) + chat.answered;
     if (chat.refused > 0)
         report.chatRefused = (report.chatRefused ?? 0) + chat.refused;
     report.problems.push(...chat.problems);
 }
-/** The one button a plain fact may carry: its machine-minted console path
- * under the trusted origin read now — the same road `/task` uses. The label
- * names where the path goes; nothing in it comes from the fact's text. */
-function factLinkLabel(path) {
-    if (/^\/review\?result=[^&]+&run=\d+&tab=checks$/.test(path))
-        return "Inspect result";
-    if (/^\/t\/[^?#]+#merge$/.test(path))
-        return "Merge";
-    if (/^\/chat\?task=[^&]+&result=/.test(path))
-        return "Open result";
-    if (/^\/(?:chat\?task=|t\/)/.test(path))
-        return "Open task";
-    if (/^\/d\//.test(path))
-        return "Open decision";
-    return "Open console";
+/** A fact's own next-action button row under the trusted origin read now; none without one. */
+function factButton(phoneOrigin, link) {
+    try {
+        return phoneLinkButton(phoneOrigin?.() ?? null, { label: factLinkLabel(link), path: link });
+    }
+    catch {
+        return null;
+    }
+}
+/** A view's buttons on one row: its link, then any others ([Merge] [Look first]); none without a trusted origin. */
+function viewKeyboard(phoneOrigin, view) {
+    try {
+        const origin = phoneOrigin?.() ?? null;
+        const row = [view.link, ...(view.also ?? [])].flatMap(link => phoneLinkButton(origin, link) ?? []);
+        return row.length === 0 ? [] : [row];
+    }
+    catch {
+        return [];
+    }
 }
 /** Team-conversation traffic to the chats that follow one — after the outbox, under the same delivery switch, never a problem to raise when nothing follows anything. */
 async function deliverTeam(store, botId, transport, clock, report, readProjects, canDeliver, phoneOrigin) {
@@ -720,7 +789,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             const messageId = store.telegramProgressMessage(binding, progressRun);
             if (messageId === null && onlyExisting)
                 return null;
-            const card = telegramProgressCard(store, store.getRun(progressRun.id), row.taskId, row.project, clock(), evidenceRoot);
+            const card = telegramProgressCard(store, store.getRun(progressRun.id), row.taskId, row.project, clock(), evidenceRoot, binding.approver);
             let button = null;
             try {
                 button = phoneLinkButton(phoneOrigin?.() ?? null, card.link);
@@ -750,7 +819,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             if (problem !== null)
                 return { ok: false, error: problem };
             const card = store.chatCardFor(fact.destination, fact.taskRef, store.getTask(fact.taskId)?.createdAt ?? fact.createdAt, clock());
-            const view = quietCardView(store, card.tasks, clock(), evidenceRoot);
+            const view = quietCardView(store, card.tasks, clock(), evidenceRoot, binding.approver);
             if (view === null)
                 return { ok: true, messageId: card.message };
             let button = null;
@@ -792,14 +861,55 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             if (!needsPerson(fact))
                 return { ok: true, receipt: receiptFor(botId, binding.chatId, card.messageId) };
             const readyRun = fact.kind === "run-finished" ? store.telegramProgressRun(fact) : null;
-            if (readyRun !== null) {
-                const ping = readyPingView(store, store.getRun(readyRun.id), fact.taskId, fact.project, clock(), evidenceRoot);
-                let button = null;
-                try {
-                    button = phoneLinkButton(phoneOrigin?.() ?? null, ping.link);
+            if (readyRun !== null || (fact.kind !== "run-finished" && joinsBatch(fact))) {
+                // Any update for this person joins their open batch: one message, edited in place while it grows.
+                const batch = store.chatBatchFor(fact.destination, fact.taskRef, readyRun?.id ?? store.telegramProgressRun(fact)?.id ?? null, clock(), BATCH_MS, readyRun !== null ? null : fact.id);
+                // A lone update that is not finished work goes out exactly as it always has; a later one edits it in place.
+                const lone = batch.items.length === 1 && batch.items[0].notification !== null;
+                if (batch.message === null && lone) {
+                    const sent = await deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects);
+                    const placed = store.telegramMessageOf(fact.id, fact.destination);
+                    if (placed !== null)
+                        store.setChatBatchMessage(batch.id, placed, "");
+                    return sent;
+                }
+                const view = finishedView(store, batch, clock(), evidenceRoot, binding.approver);
+                // Nothing in the batch reads as a line. Finished work left out on purpose (a release check, a replaced task,
+                // the reader's own completion) stays quiet; any other update that needs this person still reaches them alone.
+                if (view === null) {
+                    if (readyRun !== null)
+                        return { ok: true, receipt: receiptFor(botId, binding.chatId, card.messageId) };
+                    return deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects);
                 }
-                catch { /* No trusted origin. */ }
-                const sent = await sender(ping.text, button === null ? undefined : [button], [fact], ping.entities);
+                // While a lone update is still the only item, its edit keeps that update's own action button.
+                const own = lone && fact.link !== null ? factButton(phoneOrigin, fact.link) : null;
+                const keyboard = own !== null ? [own] : viewKeyboard(phoneOrigin, view);
+                const shown = createHash("sha256").update(JSON.stringify([view.text, keyboard])).digest("hex");
+                if (batch.message !== null) {
+                    if (batch.digest === shown) {
+                        store.recordTelegramMessage(fact, binding, batch.message, clock());
+                        return { ok: true, receipt: receiptFor(botId, binding.chatId, batch.message) };
+                    }
+                    const problem = (await readAccess()) ?? fence();
+                    if (problem !== null)
+                        return { ok: false, error: problem };
+                    const edited = await editProgress(transport, binding.chatId, batch.message, view.text, keyboard);
+                    if (edited.ok) {
+                        store.setChatBatchMessage(batch.id, batch.message, shown);
+                        store.recordTelegramMessage(fact, binding, batch.message, clock());
+                        const after = (await readAccess()) ?? fence();
+                        return after === null ? { ok: true, receipt: receiptFor(botId, binding.chatId, batch.message) } : { ok: false, error: after };
+                    }
+                    if (edited.retryAfter !== undefined)
+                        store.deferTelegram(botId, new Date(clock().getTime() + edited.retryAfter * 1000).toISOString());
+                    // Only Telegram's definitive missing/uneditable answer permits a new message.
+                    if (!edited.replace)
+                        return edited;
+                }
+                const sent = await sender(view.text, keyboard.length === 0 ? undefined : keyboard, [fact]);
+                const placed = sent.ok ? sent.messageId : store.telegramMessageOf(fact.id, fact.destination);
+                if (placed !== null)
+                    store.setChatBatchMessage(batch.id, placed, shown);
                 return sent.ok ? { ok: true, receipt: receiptFor(botId, binding.chatId, sent.messageId) } : sent;
             }
             return fact.kind === "acceptance-evidence" ? imageSender(fact) : deliverOne(store, botId, binding, sender, fact, clock, phoneOrigin, evidenceRoot, projects);
@@ -815,7 +925,7 @@ async function deliverOutboxTo(store, botId, binding, transport, owner, clock, r
             const updated = progress ? await updateProgress(false) : null;
             outcome = updated !== null ? updated.ok ? { ok: true, receipt: receiptFor(botId, binding.chatId, updated.messageId) } : updated
                 : rows[0].kind === "acceptance-evidence" ? await imageSender(rows[0]) : batched
-                    ? await deliverDigest(botId, binding, sender, rows, digest.lastSentAt, clock)
+                    ? await deliverDigest(botId, binding, sender, rows, digest.lastSentAt, clock, taskId => chatTitle(store, taskId))
                     : await deliverOne(store, botId, binding, sender, rows[0], clock, phoneOrigin, evidenceRoot, projects);
         }
         const finalProblem = outcome.ok ? (await readAccess()) ?? fence() : null;
@@ -850,26 +960,29 @@ function isUrgent(notification) {
 /** The digest text: a header with the count and the window, then one
  * fact per entry — its subject, then its body's first line, indented.
  * Plain text, no buttons: nothing in a digest is tappable. */
-export function digestText(rows, since, now) {
+export function digestText(rows, since, now, titleOf) {
     const window = since === null ? "" : ` since ${since.slice(0, 16).replace("T", " ")}`;
     const lines = [`digest — ${rows.length} routine fact(s)${window} (as of ${now.toISOString().slice(0, 16).replace("T", " ")})`, ""];
     for (const row of rows) {
-        lines.push(digestEntry(row));
+        lines.push(digestEntry(row, titleOf));
     }
     return lines.join("\n");
 }
-function digestEntry(row) {
+function digestEntry(row, titleOf) {
+    const title = row.taskId === null ? undefined : titleOf?.(row.taskId);
+    const task = row.taskId === null ? [] : [{ id: row.taskId, ...(title === undefined ? {} : { title }) }];
+    const subject = chatText(row.subject, task);
     const first = row.body.split("\n").map(one => one.trim()).find(one => one !== "");
     const body = first === undefined ? "" : `\n    ${first.length > 200 ? `${first.slice(0, 200).replace(/[\uD800-\uDBFF]$/, "")}…` : first}`;
-    return `• ${notificationIdentity(row)}${row.subject}${body}`;
+    return `• ${notificationIdentity(row, title !== undefined && mentions(subject, title) ? undefined : title)}${subject}${chatText(body, task)}`;
 }
-async function deliverDigest(botId, binding, sender, rows, since, clock) {
-    const text = digestText(rows, since, clock());
+async function deliverDigest(botId, binding, sender, rows, since, clock, titleOf) {
+    const text = digestText(rows, since, clock(), titleOf);
     // Track the exact rows represented by each text part. A split row may bind
     // several messages; a digest message may bind several rows.
     let offset = text.indexOf("\n\n") + 2;
     const spans = rows.map(row => {
-        const length = digestEntry(row).length;
+        const length = digestEntry(row, titleOf).length;
         const span = { row, start: offset, end: offset + length };
         offset += length + 1;
         return span;
@@ -917,16 +1030,13 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
             else
                 body = `${packet.text}\n\n${notification.body}`;
         }
-        const parts = split(`${notificationIdentity(notification)}${alreadyAccepted ? "Acceptance recorded" : notification.subject}\n\n${body}`);
-        let button = null;
-        if (notification.link !== null && !alreadyAccepted && current) {
-            try {
-                button = phoneLinkButton(phoneOrigin?.() ?? null, { label: factLinkLabel(notification.link), path: notification.link });
-            }
-            catch {
-                button = null;
-            }
-        }
+        // A short title, never the task's id or a "— revision" suffix (chat-voice.ts).
+        const title = notification.taskId === null ? undefined : chatTitle(store, notification.taskId);
+        const task = notification.taskId === null ? [] : [{ id: notification.taskId, ...(title === undefined ? {} : { title }) }];
+        const words = chatText(`${alreadyAccepted ? "Acceptance recorded" : notification.subject}${body === "" ? "" : `\n\n${body}`}`, task);
+        // The task's title once: in front, unless the words already name it.
+        const parts = split(`${notificationIdentity(notification, title !== undefined && mentions(words, title) ? undefined : title)}${words}`);
+        const button = notification.link !== null && !alreadyAccepted && current ? factButton(phoneOrigin, notification.link) : null;
         // A flow card waiting on a decision (v86): Approve, Edit, Send back on the last part, for this visit only.
         const visit = FLOW_DECIDE_KEY.exec(notification.dedupeKey);
         const waiting = visit === null ? null : flowDecisionAt(store, Number(visit[1]), Number(visit[2]));
@@ -1403,6 +1513,8 @@ function applyMessage(context, update, effects) {
             text: `paired: this chat now answers as ${approver}\n\nSend /status to check recent work, /task <id> for one task, or /help for your options.`,
             link_preview_options: { is_disabled: true },
         });
+        // The bot is Toolroll in every chat list from here on (best effort; pairing never waits on it).
+        await nameTelegramBot(transport, "pairing");
     });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "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"