toolroll 0.5.0

package/dist/telegram-team.js

@@ -0,0 +1,359 @@
+import { TeamLeads } from "./team-leads.js";
+import { proposalPreview, tooLongText } from "./chat-channel.js";
+import { mintCardTokens, phoneLinkButton, splitParts } from "./telegram-mate.js";
+import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
+import { phoneText } from "./telegram-status.js";
+/** `/team` lists, `/team <n>` chooses, `/team off` (or `private`) leaves. Any other slash text is not ours. */
+export function teamCommand(text) {
+    const trimmed = text.trim();
+    if (/^\/team(?:@\w+)?\s*$/.test(trimmed))
+        return { kind: "list" };
+    const pick = /^\/team(?:@\w+)?\s+([1-9][0-9]{0,2})\s*$/.exec(trimmed);
+    if (pick !== null)
+        return { kind: "select", index: Number(pick[1]) };
+    if (/^\/team(?:@\w+)?\s+(?:off|private)\s*$/i.test(trimmed))
+        return { kind: "off" };
+    return /^\/team(?:@\w+)?(?:\s|$)/.test(trimmed) ? { kind: "list" } : null;
+}
+export const PAIR_FIRST = "Pair your phone first: open Settings → Telegram in Toolroll, then send the code here in a private chat.";
+function domainFor(store, projects) {
+    return new TeamLeads(store, () => projects ?? []);
+}
+function actorOf(binding) {
+    return { name: binding.approver, generation: binding.approverGeneration };
+}
+function conversationRow(store, id) {
+    const row = store.handle.prepare("SELECT c.id, c.title, c.thread, c.lead, c.visibility, l.name FROM team_conversation c JOIN team_lead l ON l.id = c.lead WHERE c.id = ?").get(id);
+    return row === undefined ? null : { conversation: String(row["id"]), title: String(row["title"]), thread: Number(row["thread"]), lead: String(row["lead"]), leadName: String(row["name"]), visibility: String(row["visibility"]) };
+}
+/** The conversations a person may talk in, with their lead's name, as the console lists them. */
+function conversationsFor(store, domain, actor) {
+    try {
+        const snapshot = domain.snapshot(actor);
+        return snapshot.conversations.map(conversation => ({ conversation, leadName: snapshot.leads.find(lead => lead.id === conversation.leadId)?.name ?? "lead" }));
+    }
+    catch {
+        return [];
+    }
+}
+function managerOf(domain, actor, conversationId) {
+    try {
+        return domain.access(actor, conversationId, "manager").role === "manager";
+    }
+    catch {
+        return false;
+    }
+}
+function audience(conversation) {
+    return conversation.visibility === "team" ? "Team" : "Private";
+}
+/** The `/team` listing for a private chat: everything the person can talk in, the current choice marked. */
+function privateListing(rows, current) {
+    if (rows.length === 0)
+        return "You are not in any team conversation yet. Join one in Toolroll under Chat → Team chat, then send /team again.";
+    const lines = ["Your conversations", ""];
+    rows.forEach((row, index) => {
+        lines.push(`${index + 1}. ${phoneText(row.conversation.title, 80)} — ${audience(row.conversation)} · lead ${phoneText(row.leadName, 40)}${row.conversation.id === current ? " (current)" : ""}`);
+    });
+    lines.push("", current === null ? "This chat talks to your private assistant. Send /team <number> to talk in a conversation instead." : "Send /team <number> to switch, or /team off for your private assistant.");
+    return lines.join("\n");
+}
+function groupListing(rows, current) {
+    if (rows.length === 0)
+        return "No team conversation you manage is available to this group. Create one in Toolroll under Chat → Team chat, then send /team again.";
+    const lines = [current === null ? "Choose the conversation this group follows" : "This group follows a conversation", ""];
+    rows.forEach((row, index) => {
+        lines.push(`${index + 1}. ${phoneText(row.conversation.title, 80)} — lead ${phoneText(row.leadName, 40)}${row.conversation.id === current ? " (current)" : ""}`);
+    });
+    lines.push("", "Send /team <number> to follow it (managers only), or /team off to stop. Everyone in this group will read its replies.");
+    return lines.join("\n");
+}
+/**
+ * Handle one inbound message that belongs to the team layer. Returns true
+ * when it was consumed here (a `/team` command in any chat, any message in
+ * a group, or a private message while a conversation is selected); false
+ * hands the update to the older personal paths untouched.
+ */
+export function applyTeamInbound(input) {
+    const { store, botId, now, report, message, say } = input;
+    const chat = message.chat;
+    const from = message.from;
+    if (chat === undefined || from === undefined)
+        return false;
+    const isGroup = chat.type === "group" || chat.type === "supergroup";
+    const isPrivate = chat.type === "private";
+    if (!isGroup && !isPrivate)
+        return false;
+    const chatId = String(chat.id);
+    const suspicious = message.text === undefined || message.forward_origin !== undefined || message.forward_date !== undefined ||
+        message.via_bot !== undefined || message.sender_chat !== undefined || message.caption !== undefined;
+    if (suspicious) {
+        if (isGroup) {
+            report.ignored++;
+            return true;
+        }
+        return false;
+    }
+    const text = message.text;
+    const command = teamCommand(text);
+    const binding = store.liveTelegramBindingFor(botId, String(from.id));
+    const paired = binding !== null && store.accountOf(binding.approver)?.role === "approver";
+    const teamChat = store.telegramTeamChat(botId, chatId);
+    const domain = domainFor(store, input.projects);
+    if (command !== null) {
+        report.statusReplies = (report.statusReplies ?? 0) + 1;
+        if (!paired || binding === null) {
+            say(chatId, PAIR_FIRST);
+            return true;
+        }
+        const actor = actorOf(binding);
+        const rows = conversationsFor(store, domain, actor).filter(row => !isGroup || (row.conversation.visibility === "team" && managerOf(domain, actor, row.conversation.id)));
+        const current = teamChat?.conversation ?? null;
+        if (command.kind === "list") {
+            say(chatId, isGroup ? groupListing(rows, current) : privateListing(rows, current));
+            return true;
+        }
+        if (command.kind === "off") {
+            const ended = teamChat !== null && (!isGroup || managerOf(domain, actor, teamChat.conversation) || teamChat.boundBy === actor.name) && store.unbindTelegramTeamChat(botId, chatId, actor.name, now);
+            say(chatId, ended ? (isGroup ? "This group no longer follows a conversation." : "Back to your private assistant.") : isGroup ? "This group follows nothing you can change." : "This chat already talks to your private assistant.");
+            return true;
+        }
+        const chosen = rows[command.index - 1];
+        if (chosen === undefined) {
+            say(chatId, `Choose a number from the list: send /team to see it.`);
+            return true;
+        }
+        const bound = store.bindTelegramTeamChat({ botId, chatId, kind: isGroup ? "group" : "private", conversation: chosen.conversation.id, by: actor.name, binding: binding.id }, now);
+        if (!bound.ok) {
+            say(chatId, "Another group already follows that conversation. Stop it there first, or choose a different conversation.");
+            return true;
+        }
+        say(chatId, isGroup
+            ? `This group now follows ${phoneText(chosen.conversation.title, 80)} (lead ${phoneText(chosen.leadName, 40)}). Paired members' messages go there; everyone here reads its replies. Send /team off to stop.`
+            : `This chat now talks in ${phoneText(chosen.conversation.title, 80)} (lead ${phoneText(chosen.leadName, 40)}). Send /team off for your private assistant.`);
+        return true;
+    }
+    if (teamChat === null) {
+        // A group the bot merely sits in stays silent; a private chat falls through to the personal assistant.
+        if (isGroup)
+            report.ignored++;
+        return isGroup;
+    }
+    if (!paired || binding === null) {
+        // Unpaired members' chatter is nobody's message. A slash attempt gets the one hint.
+        if (text.trimStart().startsWith("/")) {
+            say(chatId, PAIR_FIRST);
+            report.statusReplies = (report.statusReplies ?? 0) + 1;
+        }
+        else
+            report.ignored++;
+        return true;
+    }
+    // A current sender must not queue into a destination whose sharing grant
+    // ended: it could run successfully while every reply is withheld.
+    const grant = store.liveTelegramBindingById(teamChat.binding);
+    let connected = false;
+    try {
+        if (grant !== null && grant.botId === botId && grant.approver === teamChat.boundBy &&
+            (isGroup || grant.id === binding.id)) {
+            const access = domain.access(actorOf(grant), teamChat.conversation, isGroup ? "manager" : "viewer");
+            connected = !isGroup || access.conversation.visibility === "team";
+        }
+    }
+    catch { /* Give a reconnect instruction without disclosing conversation content. */ }
+    if (!connected) {
+        say(chatId, isGroup ? "This group's connection ended. Ask a conversation manager to send /team and connect it again." : "This chat's connection ended. Send /team and choose the conversation again.");
+        report.chatRefused = (report.chatRefused ?? 0) + 1;
+        return true;
+    }
+    const trimmed = text.trim();
+    if (trimmed === "") {
+        report.ignored++;
+        return true;
+    }
+    if (trimmed.length > MATE_MESSAGE_MAX_CHARS) {
+        say(chatId, tooLongText(trimmed.length));
+        report.chatRefused = (report.chatRefused ?? 0) + 1;
+        return true;
+    }
+    const actor = actorOf(binding);
+    const row = conversationRow(store, teamChat.conversation);
+    if (row === null) {
+        store.unbindTelegramTeamChat(botId, chatId, "system", now);
+        report.ignored++;
+        return true;
+    }
+    // Membership first, in the domain's own words: a removed person is told so.
+    try {
+        domain.access(actor, row.conversation, "contributor");
+    }
+    catch (error) {
+        say(chatId, phoneText(error instanceof Error ? error.message : "You cannot talk in this conversation.", 300));
+        report.chatRefused = (report.chatRefused ?? 0) + 1;
+        return true;
+    }
+    // Consent is the person's own, per conversation, and is checked before the
+    // message is saved: an unconsented message must not sit in the shared queue.
+    const session = store.teamMateSession(actor.name, row.thread);
+    if (session === null || session.approverGeneration !== actor.generation || session.endedAt !== null) {
+        const origin = input.phoneOrigin?.() ?? null;
+        const link = phoneLinkButton(origin, { label: "Enable chat", path: `/chat?conversation=${encodeURIComponent(row.conversation)}` });
+        say(chatId, `${phoneText(row.title, 80)}: enable chat for yourself in Toolroll first (it shows the provider and limits), then send again.`, link === null ? undefined : [link]);
+        report.chatRefused = (report.chatRefused ?? 0) + 1;
+        return true;
+    }
+    const answer = domain.execute(actor, { operation: "send", args: { conversationId: row.conversation, requestId: teamRequestId(chatId, input.updateId), text: trimmed } }, now);
+    if (!answer.ok) {
+        say(chatId, phoneText(answer.message, 300));
+        report.chatRefused = (report.chatRefused ?? 0) + 1;
+        return true;
+    }
+    report.chatQueued = (report.chatQueued ?? 0) + 1;
+    return true;
+}
+/** The request identity a Telegram message carries into the team queue: the chat and the update, so the same update never saves twice and delivery can tell its own messages apart. */
+export function teamRequestId(chatId, updateId) {
+    return `telegram:${chatId}:${updateId}`;
+}
+/**
+ * Carry new conversation messages to every chat that follows one: the
+ * lead's replies, teammates' messages (never this chat's own), and each
+ * reply's pending cards. Read from the cursor on every cycle; a failed send
+ * leaves the cursor where it was, so the next cycle retries the same
+ * message rather than skipping it.
+ */
+export async function deliverTeamChats(store, botId, transport, clock, report, projects, phoneOrigin, options = {}) {
+    for (const chat of store.listTelegramTeamChats(botId)) {
+        // Selection is a grant from an exact pairing. Current membership, scope,
+        // and the selection itself are rechecked after each await and before each
+        // send; another person's new pairing cannot inherit this destination.
+        const access = async () => {
+            try {
+                if (options.canDeliver !== undefined && !options.canDeliver())
+                    return null;
+                const enrolled = options.readProjects === undefined ? projects : await options.readProjects();
+                if (options.canDeliver !== undefined && !options.canDeliver())
+                    return null;
+                if (store.telegramTeamChat(botId, chat.chatId)?.id !== chat.id)
+                    return null;
+                const binding = store.liveTelegramBindingById(chat.binding);
+                if (binding === null || binding.botId !== botId || binding.approver !== chat.boundBy ||
+                    (chat.kind === "private" && binding.chatId !== chat.chatId))
+                    return null;
+                const allowed = domainFor(store, enrolled).access(actorOf(binding), chat.conversation, chat.kind === "group" ? "manager" : "viewer");
+                if (chat.kind === "group" && allowed.conversation.visibility !== "team")
+                    return null;
+                return allowed.conversation.projects;
+            }
+            catch {
+                return null;
+            }
+        };
+        if (await access() === null)
+            continue;
+        const row = conversationRow(store, chat.conversation);
+        if (row === null)
+            continue;
+        const pending = store.handle.prepare(`SELECT m.id, m.role, m.text, m.turn, q.author, q.request_id, q.status FROM mate_message m
+      LEFT JOIN team_message q ON q.message = m.id WHERE m.thread = ? AND m.id > ? ORDER BY m.id LIMIT 20`).all(row.thread, chat.cursor);
+        for (const message of pending) {
+            const id = Number(message["id"]);
+            const role = String(message["role"]);
+            const requestId = message["request_id"] === null || message["request_id"] === undefined ? null : String(message["request_id"]);
+            const ownMessage = requestId !== null && requestId.startsWith(`telegram:${chat.chatId}:`);
+            const status = message["status"] === null || message["status"] === undefined ? null : String(message["status"]);
+            const skip = role === "operator" && (ownMessage || status === "cancelled" || String(message["author"] ?? "").length === 0);
+            const prefix = `telegram-team:${chat.id}:`;
+            if (!skip) {
+                const text = role === "assistant" ? String(message["text"]) : `${phoneText(String(message["author"]), 40)}: ${String(message["text"])}`;
+                const sent = await sendParts(store, transport, chat.chatId, text, `${prefix}message:${id}`, clock, access, report);
+                if (sent !== null) {
+                    report.problems.push(`team chat ${chat.chatId}: ${sent}`);
+                    break;
+                }
+            }
+            let complete = true;
+            if (role === "assistant" && message["turn"] !== null) {
+                const turn = Number(message["turn"]);
+                const cardBinding = cardBindingFor(store, botId, chat, turn);
+                for (const proposal of store.listMateProposals(row.thread, ["pending"]).filter(one => one.turn === turn)) {
+                    const enrolled = await access();
+                    if (enrolled === null) {
+                        complete = false;
+                        break;
+                    }
+                    const preview = proposalPreview(store, proposal, enrolled, "telegram");
+                    if (store.serviceCursor(`${prefix}proposal:${proposal.id}`) >= splitParts(preview.text).length)
+                        continue;
+                    const keyboard = [];
+                    let tokens = [];
+                    if (preview.buttons && cardBinding !== null) {
+                        const minted = mintCardTokens(store, cardBinding, proposal.id, clock(), undefined, chat.chatId);
+                        keyboard.push(...minted.keyboard);
+                        tokens = minted.tokens;
+                    }
+                    const link = preview.buttons ? null : phoneLinkButton(phoneOrigin?.() ?? null, { label: "Open in Toolroll", path: `/chat?conversation=${encodeURIComponent(row.conversation)}&proposal=${proposal.id}` });
+                    if (link !== null)
+                        keyboard.push(link);
+                    const problem = await sendParts(store, transport, chat.chatId, preview.text, `${prefix}proposal:${proposal.id}`, clock, access, report, keyboard.length === 0 ? undefined : keyboard, tokens);
+                    if (problem !== null) {
+                        for (const token of tokens)
+                            store.consumeTelegramProposalAction(token, clock());
+                        report.problems.push(`team card ${proposal.id}: ${problem}`);
+                        complete = false;
+                        break;
+                    }
+                }
+            }
+            if (!complete || await access() === null)
+                break;
+            // Commit only after the body and every card are delivered. Confirmed
+            // parts survive a retry, so a failed card does not repeat the body.
+            store.transact(() => {
+                if (store.advanceTelegramTeamCursor(chat.id, id))
+                    store.handle.prepare("DELETE FROM service_cursor WHERE key LIKE ?").run(`${prefix}%`);
+            });
+        }
+    }
+}
+/** Whose binding a group card's tokens ride: the person the lead was answering, else any paired member of the conversation. */
+function cardBindingFor(store, botId, chat, turn) {
+    const author = store.handle.prepare("SELECT author FROM team_message WHERE turn_id = ?").get(turn);
+    const bindings = store.liveTelegramBindings(botId);
+    if (chat.kind === "private")
+        return bindings.find(one => one.chatId === chat.chatId) ?? null;
+    const own = author === undefined ? undefined : bindings.find(one => one.approver === String(author["author"]));
+    if (own !== undefined)
+        return own;
+    const members = new Set(store.handle.prepare("SELECT account FROM team_participant WHERE conversation = ? AND active = 1").all(chat.conversation).map(one => String(one["account"])));
+    return bindings.find(one => members.has(one.approver)) ?? null;
+}
+async function sendParts(store, transport, chatId, text, receipt, clock, access, report, keyboard, tokens = []) {
+    const parts = splitParts(text);
+    const delivered = store.serviceCursor(receipt);
+    for (const [index, part] of parts.entries()) {
+        if (index < delivered)
+            continue;
+        if (await access() === null)
+            return "conversation access changed; delivery stopped";
+        const last = index === parts.length - 1;
+        try {
+            const answer = await transport("sendMessage", { chat_id: chatId, text: part, link_preview_options: { is_disabled: true }, ...(last && keyboard !== undefined ? { reply_markup: { inline_keyboard: keyboard } } : {}) });
+            if (!answer.ok)
+                return answer.description ?? "Telegram did not accept the message";
+            const messageId = typeof answer.result === "object" && answer.result !== null ? answer.result.message_id : undefined;
+            if (typeof messageId !== "number")
+                return "Telegram did not confirm a message id";
+            store.transact(() => {
+                if (last && tokens.length > 0)
+                    store.placeTelegramProposalActions(tokens, String(messageId));
+                store.setServiceCursor(receipt, index + 1, clock());
+            });
+            report.sent++;
+        }
+        catch (error) {
+            return `Telegram transport failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    return null;
+}

package/dist/telegram.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The Telegram bridge: decisions out, answers back, zero tokens spent.
+ *
+ * This is channel plumbing — no LLM is anywhere in this path, and everything
+ * it renders is deterministic. The security model, in one breath: a chat is
+ * not a person, so pairing is a local authenticated act that binds one
+ * private chat AND one immutable user id to one approver generation; a
+ * button is not a command, so callback_data carries only an opaque one-time
+ * token whose meaning lives in this database where a stolen bot token
+ * cannot read it; and an answer lands in the same transaction that proves
+ * the binding is still live and consumes the token — or it does not land.
+ *
+ * What a stolen bot token CAN do is stated rather than wished away: read
+ * the decision text this installation chose to send through Telegram,
+ * repaint the bot's keyboards with deceptive labels, and race our poll for
+ * updates. It cannot mint an action token, answer as the operator, or make
+ * `answered_by` say anything the pairing did not authorize. Rotating the
+ * BotFather token plus `bridge telegram unpair` is the recovery, and both
+ * are one command.
+ */
+import { type Store, type Notification } from "./store.js";
+import { type TelegramConversationOptions } from "./telegram-mate.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. */
+export type TelegramReadProjects = () => Promise<readonly string[]>;
+/** The environment name — and therefore the name the builder strips from agents (both names; see names.ts). */
+export { TELEGRAM_TOKEN_ENV as TOKEN_ENV, TELEGRAM_TOKEN_ENVS as TOKEN_ENVS } from "./names.js";
+export declare const PAIRING_TTL_MS: number;
+export declare const CONFIRM_TTL_MS: number;
+export declare const BRIDGE_LEASE_MS: number;
+export declare const DELIVERY_CLAIM_MS: number;
+/** Where Telegram pushes this bot's updates: under the public hooks address (Tailscale Funnel covers /hooks). */
+export declare const TELEGRAM_HOOK_PATH = "/hooks/telegram";
+/** The secret Telegram sends with every push (its header), kept beside the database; made once when asked to. */
+export declare function telegramHookSecret(dir: string, make?: boolean): string | null;
+/** The address Telegram pushes to: the public hooks address (https only) and /hooks/telegram; null without one. */
+export declare function telegramPushUrl(hooksBase: string | null): string | null;
+/** A push is Telegram's when its secret header matches ours (compared in constant time). */
+export declare function pushedByTelegram(header: unknown, secret: string | null): boolean;
+/** Keep one pushed update for the bridge: a JSON object with a positive integer update_id. */
+export declare function keepPushedUpdate(store: Store, botId: string, body: Buffer, now: Date): {
+    ok: true;
+    kept: boolean;
+} | {
+    ok: false;
+};
+export type TokenSource = {
+    token: string;
+    botId: string;
+    source: "env" | "file";
+};
+/**
+ * Environment wins, the credential file beside the database otherwise.
+ * The file is how the CLI and the web settings card set it (0600, owner
+ * only); the env var is how people who already run keychain tooling keep
+ * it out of files entirely.
+ */
+export declare function loadBotToken(env: Record<string, string | undefined>, file: string): TokenSource | null;
+/** Write the credential file, owner-only. Refuses a string that is not a bot token. */
+export declare function saveBotToken(file: string, token: string): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function clearBotToken(file: string): boolean;
+/** The last four characters are enough to recognize a token without holding it. */
+export declare function redactToken(token: string): string;
+/** Scrub a token out of any text on its way to a log, an error, or a row. */
+export declare function scrub(text: string, token: string): string;
+/**
+ * One Bot API call. Injectable, so the suite scripts Telegram instead of
+ * dialing it. The optional signal lets a follower cancel a long poll the
+ * moment it is told to stop, instead of waiting the poll window out.
+ */
+export type TelegramTransport = (method: string, params: Record<string, unknown>, signal?: AbortSignal, 
+/** v64: one verified file to send as multipart — the ONLY way bytes leave. Absent, the call is JSON exactly as before. */
+upload?: TelegramUpload) => Promise<{
+    ok: boolean;
+    result?: unknown;
+    description?: string;
+    parameters?: {
+        retry_after?: number;
+    };
+    uncertain?: boolean;
+}>;
+/**
+ * The one typed shape a file takes onto the wire: bytes the caller already
+ * verified, under a name and type the caller chose from the verified
+ * kind. There is no path, no URL and no `file_id` form here on purpose —
+ * Telegram never fetches anything for us, and nothing on this machine is
+ * uploaded by name.
+ */
+export type TelegramUpload = {
+    field: "document";
+    fileName: string;
+    contentType: "image/png" | "image/jpeg";
+    bytes: Buffer;
+};
+export declare function createTransport(token: string, timeoutMs?: number): TelegramTransport;
+/** The multipart body: every param a field (objects as JSON), the file last. Exported for the adapter's own test only. */
+export declare function multipartOf(params: Record<string, unknown>, upload: TelegramUpload): FormData;
+export declare function hashPairingCode(code: string): string;
+/** 128 bits, hex — pasteable, and not guessable inside any code's lifetime. */
+export declare function mintPairingCode(): string;
+export type BridgeReport = {
+    sent: number;
+    answered: number;
+    paired: number;
+    ignored: number;
+    /** Updates Telegram still holds beyond this pass's page budget. */
+    backlog: boolean;
+    problems: string[];
+    /** Free-text notes captured as drafts. */
+    noted?: number;
+    /** Digests sent this pass (away mode). */
+    digests?: number;
+    /** Successful replies to read-only phone commands, separate from outbox sends. */
+    statusReplies?: number;
+    /** Ordinary messages persisted for the shared assistant this pass. */
+    chatQueued?: number;
+    /** Assistant replies delivered (including a recovered earlier reply). */
+    chatAnswered?: number;
+    /** Messages settled without a reply from the assistant: refused, failed, unpaired, or answered deterministically. */
+    chatRefused?: number;
+    /** Proposal cards confirmed by a tap this pass. */
+    chatConfirmed?: number;
+    /** v98: another program asked Telegram for this bot's updates (harmless: nothing is lost). */
+    contention?: number;
+    /** v98: Telegram answered that it pushes this bot's updates to a webhook. */
+    webhookActive?: boolean;
+    /** v98: pushed updates applied this pass. */
+    pushed?: number;
+};
+/**
+ * One bridge pass: claim and send what the outbox holds, then read one
+ * budgeted window of updates and apply each in its own transaction. Cron
+ * calls this; running it twice concurrently loses the lease race and does
+ * nothing, which is the design working.
+ */
+export declare function bridgePass(store: Store, options: {
+    botId: string;
+    transport: TelegramTransport;
+    clock?: () => Date;
+    owner?: string;
+    /** false: inbound only — another channel is primary and carries the
+     * pages; taps and replies still land here. */
+    deliver?: boolean;
+    readProjects?: TelegramReadProjects;
+    /** Reload channel configuration before every outbound part. */
+    canDeliver?: () => boolean;
+    /** Ordinary text talks to the shared assistant. Absent: text that is not a command or a decision note is ignored, as before. */
+    conversation?: TelegramConversationOptions;
+}): Promise<{
+    ok: true;
+    report: BridgeReport;
+} | {
+    ok: false;
+    reason: "bridge-busy";
+    message: string;
+}>;
+/**
+ * The longest long poll the follower may ask for. `createTransport`'s HTTP
+ * timeout is 30s and must outlive the poll window, or the client would abort
+ * a poll Telegram is still honestly holding open.
+ */
+export declare const MAX_POLL_SECONDS = 25;
+export type FollowReport = {
+    cycles: number;
+    sent: number;
+    answered: number;
+    paired: number;
+    ignored: number;
+    problems: string[];
+    statusReplies?: number;
+    chatQueued?: number;
+    chatAnswered?: number;
+    chatRefused?: number;
+    chatConfirmed?: number;
+};
+/**
+ * The follower (§M4): one actor that holds the poll lease and stays on the
+ * wire, so an answer tapped on a phone reaches the store in seconds, not at
+ * the next cron firing. `bridge telegram --follow` runs it standalone;
+ * watch embeds the same actor — the poll lease guarantees only one is
+ * live, and a cron pass overlapping it simply loses the lease race.
+ *
+ * Each cycle re-acquires the lease under the same owner — that is the
+ * fenced renewal: same generation while held, and if the lease lapsed
+ * mid-poll (a stall longer than the TTL), the re-acquire takes the next
+ * generation and the cursor rides it, so nothing this follower stamped
+ * with the old generation can move state afterwards. Transport failures
+ * back off exponentially and are counted, not hidden; cancellation aborts
+ * the in-flight long poll instead of waiting it out.
+ */
+/** What Telegram lists when the person taps "/". */
+export declare const TELEGRAM_COMMANDS: {
+    command: string;
+    description: string;
+}[];
+export declare function followBridge(store: Store, options: {
+    botId: string;
+    transport: TelegramTransport;
+    signal: AbortSignal;
+    clock?: () => Date;
+    owner?: string;
+    /** false: inbound only; another channel is primary. */
+    deliver?: boolean;
+    readProjects?: TelegramReadProjects;
+    /** Reload channel configuration before every outbound part. */
+    canDeliver?: () => boolean;
+    /** Ordinary text talks to the shared assistant. */
+    conversation?: TelegramConversationOptions;
+    pollSeconds?: number;
+    /** One line per cycle that did something — the follower's narration hook. */
+    onCycle?: (report: BridgeReport) => void;
+    /** Injectable for tests; the default resolves early on abort. */
+    sleep?: (ms: number) => Promise<void>;
+    /** v98: have Telegram push updates to this public address (with this secret) instead of asking for them. */
+    push?: {
+        url: string;
+        secret: string;
+    } | null;
+    /** v98: how often to check Telegram still pushes to us (tests shorten it). */
+    pushCheckMs?: number;
+}): Promise<FollowReport>;
+/** 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 declare function digestText(rows: readonly Notification[], since: string | null, now: Date): string;