@timqi/pier 0.0.1

package/dist/channels/telegram-panel.js

@@ -0,0 +1,113 @@
+// Telegram's half of the settings panel: HTML markup, an inline keyboard, and
+// a forced reply for the one typed answer. The panel itself lives in
+// `panel.ts`.
+//
+// Asking for a working directory costs a Map here: a forced reply arrives as
+// an ordinary message, so the prompt's message id has to be remembered to
+// recognize the answer. Slack's modal carries that context itself.
+import { ChatPanel, PANEL_PREFIX, } from "./panel.js";
+import { escapeHtml as esc } from "./telegram-render.js";
+const button = (b) => ({ text: b.label, callback_data: `${PANEL_PREFIX}${b.action}` });
+export class TelegramPanel extends ChatPanel {
+    deps;
+    platform = "telegram";
+    fence = ["<code>", "</code>"];
+    /** Conversations waiting for a typed working directory (ForceReply). */
+    cwdPrompts = new Map();
+    constructor(deps) {
+        super(deps);
+        this.deps = deps;
+    }
+    esc(text) {
+        return esc(text);
+    }
+    /** Topics are a Telegram-only gate, and only on a forum. */
+    gateExtras(chat, policy) {
+        return chat.kind === "forum" ? ` · topics ${policy.topicMode ? "on" : "off"}` : "";
+    }
+    // --- rendering ---------------------------------------------------------------
+    text(view, note) {
+        const body = view.groups
+            .map((g) => [`<b>${g.title}</b>${g.suffix ?? ""}`, ...g.lines].join("\n"))
+            .join("\n\n");
+        return note ? `${body}\n\n<i>${esc(note)}</i>` : body;
+    }
+    /** A long model id does not share a row with anything. */
+    keyboard(view) {
+        return {
+            inline_keyboard: [
+                ...(view.picks ?? []).map((pick) => [button(pick)]),
+                ...view.rows.map((row) => row.map(button)),
+            ],
+        };
+    }
+    /** Open a fresh panel, replacing whichever one this conversation had. */
+    async open(key, chatId, topicId) {
+        const view = await this.view(key, chatId);
+        const sent = await this.deps.api.sendMessage({
+            chat_id: chatId,
+            message_thread_id: topicId,
+            text: this.text(view),
+            parse_mode: "HTML",
+            reply_markup: this.keyboard(view),
+        });
+        this.remember(key, { chatId, topicId, messageId: sent.message_id, models: [] });
+    }
+    async draw(state, view, note) {
+        await this.deps.api.editMessage({
+            chat_id: state.chatId,
+            message_id: state.messageId,
+            text: this.text(view, note),
+            parse_mode: "HTML",
+            reply_markup: this.keyboard(view),
+        }).catch((err) => this.deps.log(`panel edit failed: ${String(err)}`));
+    }
+    async erase(state) {
+        await this.deps.api.deleteMessage(state.chatId, state.messageId)
+            .catch((err) => this.deps.log(`panel close failed: ${String(err)}`));
+    }
+    // --- actions -----------------------------------------------------------------
+    /**
+     * Handle a `cfg:` button. Returns false when the payload is not ours, so the
+     * caller can treat it as one of the agent's next-step labels instead.
+     */
+    async onCallback(query, key) {
+        return this.dispatch(key, query.data ?? "", undefined, async () => {
+            const message = query.message;
+            if (message)
+                await this.open(key, String(message.chat.id), message.message_thread_id);
+        });
+    }
+    // --- working directory (one typed answer) ------------------------------------
+    async promptCwd(key, state) {
+        const sent = await this.deps.api.sendMessage({
+            chat_id: state.chatId,
+            message_thread_id: state.topicId,
+            // Said plainly: this is not an edit, it is a new session.
+            text: "Reply with an absolute path. A new session starts there; the current one stays in its own directory.",
+            reply_markup: { force_reply: true, input_field_placeholder: "/path/to/project" },
+        });
+        this.cwdPrompts.set(key.conversationId, sent.message_id);
+    }
+    /**
+     * Consume a reply to the working-directory prompt. Returns true when this
+     * message was that answer and must not reach the agent.
+     */
+    async consumeCwdReply(msg, key) {
+        const pending = this.cwdPrompts.get(key.conversationId);
+        if (!pending || msg.reply_to_message?.message_id !== pending)
+            return false;
+        this.cwdPrompts.delete(key.conversationId);
+        const path = (msg.text ?? "").trim();
+        const started = await this.startSessionIn(key, path);
+        // The answer was typed in the chat, so the outcome is said in the chat:
+        // a panel note alone would be easy to miss under one's own message.
+        await this.deps.api.sendMessage({
+            chat_id: msg.chat.id,
+            message_thread_id: msg.message_thread_id,
+            text: "error" in started ? started.error : `New session in <code>${esc(path)}</code>.`,
+            parse_mode: "HTML",
+        });
+        return true;
+    }
+}

package/dist/channels/telegram-render.js

@@ -0,0 +1,96 @@
+import { chunkText } from "./chunk.js";
+// How a reply looks on Telegram: text and buttons.
+//
+// Markdown → Telegram Bot API HTML. Telegram's parser accepts a tiny tag set
+// and rejects the whole message on anything else, so we escape first and
+// reintroduce exactly the tags it documents: b, i, s, code, pre, a.
+// Unsupported markdown (tables, images, nested lists) degrades to plain text
+// rather than losing the message.
+const MAX_CHARS = 3800; // Telegram's hard limit is 4096; leave room for tags.
+/** Shared: the adapter and the panel escape plain text with this too. */
+export const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** Inline emphasis, applied after escaping so `<b>` can only come from us. */
+function inline(text) {
+    return text
+        // Links first: their label may itself carry emphasis.
+        .replace(/\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)/g, (_m, label, url) => `<a href="${url.replace(/"/g, "&quot;")}">${label}</a>`)
+        .replace(/\*\*([^\n*]+)\*\*/g, "<b>$1</b>")
+        .replace(/~~([^\n~]+)~~/g, "<s>$1</s>")
+        .replace(/(^|[\s(])[*_]([^\n*_]+)[*_](?=[\s).,!?:;]|$)/g, "$1<i>$2</i>")
+        // Headings carry no size in Telegram; bold is the closest honest render.
+        .replace(/^#{1,6}[ \t]+(.+)$/gm, "<b>$1</b>");
+}
+/**
+ * Render one assistant turn. Code spans and fences are extracted before
+ * escaping so emphasis inside them stays literal.
+ */
+export function toTelegramHtml(markdown) {
+    const stash = [];
+    // Private-use sentinels: markdown can't contain them, so a stashed block
+    // can't be re-matched by the escaping and emphasis passes that follow.
+    const keep = (html) => `\uE000${stash.push(html) - 1}\uE001`;
+    let out = markdown.replace(/```([\w.+-]*)\n?([\s\S]*?)```/g, (_m, lang, code) => keep(lang
+        ? `<pre><code class="language-${escapeHtml(lang)}">${escapeHtml(code.replace(/\n+$/, ""))}</code></pre>`
+        : `<pre>${escapeHtml(code.replace(/\n+$/, ""))}</pre>`));
+    out = out.replace(/`([^`\n]+)`/g, (_m, code) => keep(`<code>${escapeHtml(code)}</code>`));
+    out = inline(escapeHtml(out));
+    return out.replace(/\uE000(\d+)\uE001/g, (_m, i) => stash[Number(i)] ?? "");
+}
+/**
+ * Split rendered HTML into sendable chunks. A turn long enough to need this can
+ * still be cut inside a <pre> block; Telegram closes the tag on its own and the
+ * text survives, which beats dropping the turn. (Slack cannot do that, which is
+ * why its renderer re-balances fences after the cut.)
+ */
+export const chunk = (html) => chunkText(html, MAX_CHARS);
+// --- next-step buttons -------------------------------------------------------
+/**
+ * Telegram caps `callback_data` at 64 *bytes* — about 21 CJK characters, far
+ * too little to carry a label. Buttons send an index instead, and the label is
+ * read back off the message's own keyboard.
+ */
+export const OFFER_PREFIX = "sg:";
+// Buttons in one row share the row's width, so packing is budgeted by display
+// width rather than count: a CJK glyph takes about twice an ASCII one.
+const ROW_WIDTH = 26;
+const ROW_BUTTONS = 3;
+/** Rough rendered width: CJK, fullwidth punctuation and emoji take two cells. */
+const displayWidth = (label) => [...label].reduce((n, ch) => n + ((ch.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1), 0);
+/**
+ * Pack short labels onto shared rows, keeping the offered order. A row that is
+ * already wide stops accepting: buttons in one Telegram row split the width
+ * evenly, so squeezing a long label in truncates everything beside it.
+ */
+export function keyboard(labels) {
+    if (!labels.length)
+        return undefined;
+    const rows = [];
+    let used = 0;
+    labels.forEach((label, index) => {
+        const width = displayWidth(label);
+        const row = rows.at(-1);
+        const button = { text: label, callback_data: `${OFFER_PREFIX}${index}` };
+        if (!row || row.length >= ROW_BUTTONS || used + width > ROW_WIDTH) {
+            rows.push([button]);
+            used = width;
+            return;
+        }
+        row.push(button);
+        used += width;
+    });
+    return { inline_keyboard: rows };
+}
+/**
+ * The label a next-step payload stands for. Read off the tapped message's own
+ * keyboard, which Telegram echoes back — so a button keeps working across a
+ * restart or a config reload, where an in-memory offer list would not.
+ * A payload we never wrote (an older label-as-payload button) passes through.
+ */
+export function offeredLabel(msg, data) {
+    if (!data.startsWith(OFFER_PREFIX))
+        return data;
+    return msg.reply_markup?.inline_keyboard
+        .flat()
+        .find((button) => button.callback_data === data)
+        ?.text;
+}

package/dist/channels/telegram.js

@@ -0,0 +1,473 @@
+// Telegram adapter: normalize inbound updates, render outbound turns.
+//
+// Three behaviours are Telegram-specific and live only here:
+//  - Topic mode. A message that lands in a forum group's General opens a fresh
+//    topic named after its first line, and the conversation (hence the Pi
+//    session) is that topic. One group therefore hosts many parallel sessions.
+//  - Reaction receipts. Intermediate reasoning is never posted to IM; instead
+//    every message that entered a turn wears 👀 until the turn settles, so a
+//    steered message gets feedback without a line in the chat.
+//  - Bind. `/bind <code>` in a DM redeems a Console-issued code.
+//
+// Everything policy-shaped (mention/bind gates, per-chat overrides) is in
+// config.ts, platform-blind and shared with the adapters still to come.
+import { formatTurnMeta, originLabel } from "../core/reply.js";
+import { logger } from "../log.js";
+import { Chains } from "./chains.js";
+import { parseCommand } from "./commands.js";
+import { Gatekeeper } from "./gatekeeper.js";
+import { ReceiptLedger, Receipts } from "./receipts.js";
+import { TelegramPanel } from "./telegram-panel.js";
+import { chunk, escapeHtml, keyboard, offeredLabel, toTelegramHtml } from "./telegram-render.js";
+import { TelegramApi, } from "./telegram-api.js";
+const WORKING = "👀";
+const POLL_SECONDS = 30;
+// Backpressure: how many chats may be mid-handling before the poll loop waits.
+// Bounds memory without ever advancing the offset past what we accepted.
+const MAX_ACTIVE_CHATS = 16;
+// Longest a 👀 may sit before we assume its turn will never settle (a dispatch
+// that failed, a session that died). Generous: a real coding turn can be long.
+const RECEIPT_STALE_MS = 30 * 60_000;
+// Longest stop() waits for in-flight handlers before letting reload() proceed.
+const DRAIN_TIMEOUT_MS = 5000;
+const TOPIC_TITLE_MAX = 60;
+/**
+ * A forum conversation is `<chatId>/<topicId>`; anything else is `<chatId>`.
+ * This pair is the only definition of the format — control.ts and the panel
+ * decode with it rather than splitting on "/" themselves.
+ */
+const conversationId = (chatId, topicId) => topicId ? `${chatId}/${topicId}` : String(chatId);
+export const parseConversation = (id) => {
+    const [chatId = "", topic] = id.split("/");
+    const topicId = topic ? Number(topic) : undefined;
+    return { chatId, topicId: Number.isSafeInteger(topicId) ? topicId : undefined };
+};
+/** Telegram numbers General as topic 1 and omits the id on plain groups. */
+const inGeneral = (msg) => !msg.message_thread_id || msg.message_thread_id === 1;
+function topicTitle(text) {
+    const line = (text.split("\n").find((l) => l.trim()) ?? "").trim();
+    if (!line)
+        return `Session ${new Date().toISOString().slice(5, 16).replace("T", " ")}`;
+    return line.length > TOPIC_TITLE_MAX ? `${line.slice(0, TOPIC_TITLE_MAX - 3).trimEnd()}...` : line;
+}
+export class TelegramChannel {
+    deps;
+    id = "telegram";
+    api;
+    log;
+    /** 👀 lifecycle, durable; see receipts.ts for why it is not just a Map. */
+    receipts;
+    /** Ordering per chat, concurrency across them; see chains.ts. */
+    chains;
+    /** The inbound gate and the bind-hint throttle; see gatekeeper.ts. */
+    gate;
+    /** The in-chat settings panel; absent when no control was wired (tests). */
+    panel;
+    me;
+    offset;
+    running = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.api = deps.client ?? new TelegramApi(deps.store.get("telegram").token);
+        this.log = deps.log ?? ((m) => logger("telegram").warn(m));
+        // No cap here: the poll loop applies backpressure itself, before advancing
+        // the ack cursor past an update it has not accepted.
+        this.chains = new Chains(this.log);
+        this.gate = new Gatekeeper(deps.store, "telegram", this.log);
+        this.receipts = new Receipts(
+        // The ledger keeps message ids as opaque strings (a Slack ts is not a
+        // number); Telegram's own are numeric, so the cast happens right here at
+        // the API boundary rather than leaking a platform's id type into shared code.
+        { setReaction: (chatId, messageId, emoji) => this.api.setReaction(chatId, Number(messageId), emoji) }, deps.receipts ?? new ReceiptLedger("telegram"), this.log, WORKING, RECEIPT_STALE_MS);
+        if (deps.control) {
+            this.panel = new TelegramPanel({
+                api: this.api,
+                control: deps.control,
+                store: deps.store,
+                log: this.log,
+            });
+        }
+    }
+    async start(onMessage) {
+        const me = await this.api.getMe();
+        this.me = { id: me.id, username: me.username ?? "" };
+        if (!this.me.username) {
+            // Without a handle, "was I mentioned?" can only ever answer no, so every
+            // group with require-mention on goes silent. Loud, not a debug line.
+            this.log("bot has no username: mention detection is disabled");
+        }
+        this.running = true;
+        // Best-effort and off the critical path.
+        void this.receipts.sweep(true);
+        void this.poll(onMessage);
+    }
+    async stop() {
+        this.running = false;
+        // Let in-flight updates finish: reload() starts a replacement right after,
+        // and two adapters handling one message would prompt the session twice.
+        // Bounded, because reload() runs on the Console's save request — a stuck
+        // handler must not hold that open.
+        await this.chains.drain(DRAIN_TIMEOUT_MS);
+    }
+    // --- inbound ---------------------------------------------------------------
+    async poll(onMessage) {
+        while (this.running) {
+            try {
+                // Floor on an empty round trip: getUpdates is supposed to block for
+                // POLL_SECONDS, and a proxy that answers instantly would otherwise
+                // turn this into a hot loop.
+                const startedAt = Date.now();
+                const updates = await this.api.getUpdates(this.offset, POLL_SECONDS);
+                if (!this.running)
+                    return;
+                void this.receipts.sweep();
+                if (!updates.length && Date.now() - startedAt < 1000) {
+                    await new Promise((r) => setTimeout(r, 1000));
+                }
+                for (const update of updates) {
+                    if (!this.running)
+                        return;
+                    while (this.chains.size >= MAX_ACTIVE_CHATS)
+                        await this.chains.oldest();
+                    this.offset = update.update_id + 1;
+                    const chat = update.message?.chat.id ?? update.callback_query?.message?.chat.id;
+                    if (chat === undefined)
+                        continue; // malformed: no chat to answer in
+                    this.chains.run(String(chat), async () => {
+                        try {
+                            if (update.callback_query)
+                                await this.onCallback(update.callback_query, onMessage);
+                            else if (update.message)
+                                await this.onMessage(update.message, onMessage);
+                        }
+                        catch (err) {
+                            this.log(`update ${update.update_id} dropped: ${String(err)}`);
+                        }
+                    });
+                }
+            }
+            catch (err) {
+                if (!this.running)
+                    return;
+                this.log(`poll failed, retrying: ${String(err)}`);
+                await new Promise((r) => setTimeout(r, 3000));
+            }
+        }
+    }
+    async onMessage(msg, onMessage) {
+        if (!msg.from || msg.from.id === this.me?.id)
+            return; // own echo, or malformed
+        const raw = (msg.text ?? msg.caption ?? "").trim();
+        if (!raw && !msg.photo?.length)
+            return;
+        const chatId = String(msg.chat.id);
+        const isDm = msg.chat.type === "private";
+        const kind = isDm ? "dm" : msg.chat.is_forum ? "forum" : "group";
+        const name = msg.chat.title ?? [msg.from.first_name, msg.from.last_name].filter(Boolean).join(" ");
+        this.deps.store.discoverChat("telegram", { id: chatId, name: name || chatId, kind });
+        const text = this.stripMention(raw, msg);
+        const command = parseCommand(text);
+        // A command aimed at another bot in the same group is not ours to answer.
+        const mine = !command?.target || command.target.toLowerCase() === this.me?.username.toLowerCase();
+        const bindRequest = mine && command?.name === "bind" && isDm;
+        const admitted = this.gate.admit("message", chatId, {
+            isDm,
+            addressed: this.addressed(raw, msg),
+            userId: String(msg.from.id),
+            bindRequest,
+        });
+        if (!admitted) {
+            if (isDm)
+                await this.hintBind(msg);
+            return;
+        }
+        if (bindRequest)
+            return this.bind(msg, command?.args ?? "");
+        if (mine && command?.name === "stop")
+            return this.abortTurn(msg);
+        const here = {
+            channelId: this.id,
+            conversationId: conversationId(chatId, msg.message_thread_id),
+        };
+        // A typed answer to the panel's directory prompt, not a prompt for the agent.
+        if (await this.panel?.consumeCwdReply(msg, here))
+            return;
+        // `@bot` on its own (text is empty once the mention is stripped) and
+        // `/settings` are the same request: show me this conversation's settings.
+        if (this.panel && mine && (command?.name === "settings" || (!text && !msg.photo?.length))) {
+            return this.panel.open(here, chatId, msg.message_thread_id);
+        }
+        // Downloading only past the gate: an unauthorized sender must not be able
+        // to make the bot pull bytes on their behalf.
+        const images = await this.photos(msg);
+        const topicId = await this.routeTopic(msg, text);
+        const key = { channelId: this.id, conversationId: conversationId(chatId, topicId) };
+        this.receipts.mark(key.conversationId, chatId, String(msg.message_id));
+        // IM messages steer by default: a follow-up that waits for the turn to end
+        // is the wrong default when the human is watching a 👀 in a chat window.
+        onMessage({
+            key,
+            senderId: String(msg.from.id),
+            // A group is many people talking into one session; the update already
+            // carries the name, so no lookup is needed here.
+            sender: { id: String(msg.from.id), name: senderName(msg.from) },
+            text,
+            images,
+            mode: "steer",
+        });
+    }
+    /** Quick-reply buttons send their own label back as an ordinary message. */
+    async onCallback(query, onMessage) {
+        await this.api.answerCallbackQuery(query.id).catch(() => { });
+        const msg = query.message;
+        if (!msg || !query.data)
+            return;
+        const chatId = String(msg.chat.id);
+        const admitted = this.gate.admit("callback", chatId, {
+            isDm: msg.chat.type === "private",
+            addressed: true, // pressing the bot's own button is addressing it
+            userId: String(query.from.id),
+        });
+        if (!admitted)
+            return;
+        const key = {
+            channelId: this.id,
+            conversationId: conversationId(chatId, msg.message_thread_id),
+        };
+        // Panel taps are namespaced `cfg:` and never reach the agent.
+        if (await this.panel?.onCallback(query, key))
+            return;
+        const text = offeredLabel(msg, query.data);
+        if (text === undefined) {
+            await this.api.answerCallbackQuery(query.id, "That option is no longer on this message.")
+                .catch(() => { });
+            return;
+        }
+        // The options belonged to the turn that just ended; once one is taken the
+        // rest answer a question the conversation has moved past (the web drops
+        // them for the same reason).
+        await this.api.clearKeyboard(chatId, msg.message_id).catch(() => { });
+        // A bot cannot post as the user, so the pick is echoed and marked as one.
+        // Without it the chat shows an answer to a request nobody can see being
+        // made, and there is no message of the user's to carry the eyes.
+        //
+        // No reply quote: the marker already says what this is, and quoting a long
+        // answer to show which of its buttons was tapped costs more space than it
+        // explains.
+        const echo = await this.api.sendMessage({
+            chat_id: chatId,
+            message_thread_id: msg.message_thread_id,
+            text: `\u25b8 ${escapeHtml(text)}`,
+            parse_mode: "HTML",
+        }).catch((err) => {
+            this.log(`option echo failed: ${String(err)}`);
+            return undefined;
+        });
+        // The receipt goes on the echo, not on the bot message that held the
+        // buttons: the eyes mean "this input is being worked on".
+        if (echo)
+            this.receipts.mark(key.conversationId, chatId, String(echo.message_id));
+        onMessage({ key, senderId: String(query.from.id), text, mode: "steer" });
+    }
+    /**
+     * Stop the turn this conversation is running. The abort makes Pi end the
+     * turn, which reaches send() through the normal turn-end path and clears the
+     * 👀 receipts — so nothing here touches them.
+     */
+    async abortTurn(msg) {
+        const key = {
+            channelId: this.id,
+            conversationId: conversationId(msg.chat.id, msg.message_thread_id),
+        };
+        await this.deps.control?.abort(key);
+        await this.api.sendMessage({
+            chat_id: msg.chat.id,
+            message_thread_id: msg.message_thread_id,
+            text: "⏹ Stopped.",
+        });
+    }
+    /**
+     * Tell an unbound DM sender what to do. Groups stay silent (see gate()), but
+     * a DM that swallows every message looks broken rather than locked.
+     */
+    async hintBind(msg) {
+        if (!this.gate.mayHint(String(msg.from?.id ?? "")))
+            return;
+        await this.api.sendMessage({
+            chat_id: msg.chat.id,
+            text: "You are not bound yet. Ask the operator for a bind code, then send /bind <code>.",
+        }).catch((err) => this.log(`bind hint failed: ${String(err)}`));
+    }
+    async bind(msg, code) {
+        const user = msg.from;
+        const name = senderName(user);
+        const ok = this.deps.store.redeemBindCode("telegram", code, { id: String(user.id), name });
+        await this.api.sendMessage({
+            chat_id: msg.chat.id,
+            text: ok ? `Bound as ${name}.` : "That bind code is invalid or expired.",
+        });
+    }
+    /**
+     * Topic mode: a message arriving in a forum group's General starts a new
+     * topic, so every request gets its own thread and its own Pi session. A
+     * reply or a slash command stays put — it is continuing something, not
+     * starting it. Failure falls back to the current thread rather than losing
+     * the message.
+     */
+    async routeTopic(msg, text) {
+        // Every reason to decline is named and logged: "why did it not open a
+        // topic" is the question this feature will be asked forever, and silence
+        // makes six invisible conditions indistinguishable from a bug.
+        const decline = !this.deps.store.policy("telegram", String(msg.chat.id)).topicMode
+            ? "topic mode off for this chat"
+            : msg.chat.type !== "supergroup"
+                ? `chat is a ${msg.chat.type}, not a supergroup`
+                : !msg.chat.is_forum
+                    ? "group has Topics disabled in Telegram"
+                    : !inGeneral(msg)
+                        ? `already inside topic ${msg.message_thread_id}`
+                        : msg.reply_to_message
+                            ? "message is a reply, so it continues an existing thread"
+                            : text.startsWith("/")
+                                ? "message is a command"
+                                : "";
+        if (decline) {
+            this.log(`no new topic in chat ${msg.chat.id}: ${decline}`);
+            return msg.message_thread_id;
+        }
+        const title = topicTitle(text);
+        try {
+            const topic = await this.api.createForumTopic(msg.chat.id, title);
+            // The whole point of the notice is to get out of General, so the title is
+            // the link into the new topic rather than decoration.
+            await this.api.sendMessage({
+                chat_id: msg.chat.id,
+                text: `→ <a href="${topicLink(msg.chat, topic.message_thread_id)}">${escapeHtml(title)}</a>`,
+                parse_mode: "HTML",
+                message_thread_id: msg.message_thread_id,
+                reply_to_message_id: msg.message_id,
+            }).catch(() => { });
+            return topic.message_thread_id;
+        }
+        catch (err) {
+            this.log(`topic creation failed, staying in General: ${String(err)}`);
+            return msg.message_thread_id;
+        }
+    }
+    async photos(msg) {
+        const largest = msg.photo?.at(-1);
+        if (!largest)
+            return [];
+        try {
+            return [await this.api.downloadPhoto(largest.file_id)];
+        }
+        catch (err) {
+            this.log(`photo download failed: ${String(err)}`);
+            return [];
+        }
+    }
+    // --- addressing ------------------------------------------------------------
+    /** Mentioned, replying to the bot, or a slash command aimed at this bot. */
+    addressed(text, msg) {
+        if (msg.reply_to_message?.from?.id === this.me?.id)
+            return true;
+        if (text.startsWith("/")) {
+            const target = /^\/\S+?@(\S+)/.exec(text)?.[1];
+            return !target || target.toLowerCase() === this.me?.username.toLowerCase();
+        }
+        const handle = `@${this.me?.username.toLowerCase()}`;
+        return !!this.me?.username && text.toLowerCase().includes(handle);
+    }
+    /** A leading @bot is addressing, not content — the agent should not see it. */
+    stripMention(text, msg) {
+        const handle = `@${this.me?.username ?? ""}`;
+        if (!this.me?.username)
+            return text;
+        const mention = msg.entities?.find((e) => e.type === "mention" && e.offset === 0);
+        if (mention && text.slice(0, mention.length).toLowerCase() === handle.toLowerCase()) {
+            return text.slice(mention.length).replace(/^[\s,:-]+/, "");
+        }
+        return text.toLowerCase().startsWith(handle.toLowerCase())
+            ? text.slice(handle.length).replace(/^[\s,:-]+/, "")
+            : text;
+    }
+    // --- outbound --------------------------------------------------------------
+    /**
+     * Called on every turn-end, empty text included: the turn settled with
+     * nothing to say, and the 👀 receipts still have to come off.
+     */
+    async send(conversation, reply) {
+        const { chatId, topicId } = parseConversation(conversation);
+        const text = reply.text.trim();
+        // A turn that produced no text still posts its footer, and says which kind
+        // of nothing it was: total silence is indistinguishable from a crash, and
+        // the person waiting cannot tell. See AGENTS.md — an empty turn is still an
+        // event, and an event nobody can see is not observable.
+        const buttons = keyboard(reply.suggestions);
+        // Options count as a reply: the buttons are the answer.
+        const quiet = text || buttons
+            ? ""
+            : reply.silence
+                ? `<i>stayed silent \u2014 ${escapeHtml(reply.silence)}</i>`
+                : "<i>no reply</i>";
+        const body = (text ? toTelegramHtml(text) : quiet) + turnFooter(reply.meta);
+        try {
+            if (body.trim()) {
+                const parts = chunk(body);
+                for (const [i, part] of parts.entries()) {
+                    await this.api.sendMessage({
+                        chat_id: chatId,
+                        message_thread_id: topicId,
+                        text: part,
+                        parse_mode: "HTML",
+                        // Next-step buttons ride the last chunk; a click sends the label.
+                        reply_markup: i === parts.length - 1 ? buttons : undefined,
+                    });
+                }
+            }
+        }
+        finally {
+            // Always: a 👀 left up because the reply failed would sit there until the
+            // stale sweep, looking like the agent is still working.
+            await this.receipts.settle(conversation);
+        }
+    }
+    /**
+     * A system note: quoted, labelled with where it came from, and deliberately
+     * plain — no buttons, no turn footer, and the 👀 receipts stay up, because
+     * the turn this input triggers has not ended yet.
+     */
+    async notify(conversation, note) {
+        const { chatId, topicId } = parseConversation(conversation);
+        const label = originLabel(note.origin);
+        for (const part of chunk(`<i>${label}</i>\n<blockquote>${toTelegramHtml(note.text)}</blockquote>`)) {
+            await this.api.sendMessage({
+                chat_id: chatId,
+                message_thread_id: topicId,
+                text: part,
+                parse_mode: "HTML",
+            });
+        }
+    }
+}
+/** Display name from an update, which always carries enough to build one. */
+const senderName = (user) => [user.first_name, user.last_name].filter(Boolean).join(" ") || user.username || String(user.id);
+/**
+ * Deep link to a forum topic. A public supergroup links by username; a private
+ * one uses the `/c/<internal id>` form, which is the chat id with its `-100`
+ * supergroup prefix removed. Both only resolve for members — exactly the
+ * audience standing in General.
+ */
+function topicLink(chat, topicId) {
+    if (chat.username)
+        return `https://t.me/${chat.username}/${topicId}`;
+    const internal = String(chat.id).replace(/^-100(?=\d)/, "").replace(/^-/, "");
+    return `https://t.me/c/${internal}/${topicId}`;
+}
+/**
+ * The web shows a turn's cost on hover; IM has none, so it becomes a footer.
+ * One newline, not a blank line: Telegram has no small or muted text, so the
+ * only way to make it read as a footnote instead of its own paragraph is to
+ * keep it tucked against the reply.
+ */
+const turnFooter = (meta) => meta ? `\n<i>${formatTurnMeta(meta)}</i>` : "";