@stage-labs/metro 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/stations/discord.js

@@ -0,0 +1,198 @@
+/** Discord station: receive via discord.js gateway; send/edit/react/download/fetch via REST. */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Client, Events, GatewayIntentBits, Partials } from 'discord.js';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { errMsg, log } from '../log.js';
+import { mintId } from '../history.js';
+import { Line, } from './index.js';
+const API_BASE = 'https://discord.com/api/v10';
+const SUPPRESS_EMBEDS = 1 << 2;
+const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+const token = () => {
+    const t = process.env.DISCORD_BOT_TOKEN;
+    if (!t)
+        throw new Error('DISCORD_BOT_TOKEN is not set');
+    return t;
+};
+async function rest(method, path, body, timeoutMs = 30_000, retriesLeft = 2) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: {
+            'Authorization': `Bot ${token()}`,
+            'User-Agent': 'metro (https://github.com/bonustrack/metro, dev)',
+            ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res.status === 429 && retriesLeft > 0) {
+        const retryAfter = Number(res.headers.get('retry-after')) || 1;
+        log.debug({ path, retryAfter }, 'discord 429; backing off');
+        await new Promise(r => setTimeout(r, Math.max(retryAfter * 1000, 250)));
+        return rest(method, path, body, timeoutMs, retriesLeft - 1);
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`discord ${method} ${path}: ${res.status} ${text}`);
+    }
+    return res.status === 204 ? undefined : (await res.json());
+}
+/** Multipart upload (payload_json + files[N]). Same retry semantics as `rest`. */
+async function restMultipart(method, path, payload, files) {
+    const form = new FormData();
+    form.append('payload_json', JSON.stringify(payload));
+    for (const [i, f] of files.entries()) {
+        form.append(`files[${i}]`, new Blob([new Uint8Array(f.data)]), basename(f.path));
+    }
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: {
+            'Authorization': `Bot ${token()}`,
+            'User-Agent': 'metro (https://github.com/bonustrack/metro, dev)',
+        },
+        body: form, signal: AbortSignal.timeout(60_000),
+    });
+    if (!res.ok) {
+        const t = await res.text().catch(() => '');
+        throw new Error(`discord ${method} ${path}: ${res.status} ${t}`);
+    }
+    return (await res.json());
+}
+const collectFiles = async (opts) => {
+    const paths = [...(opts?.images ?? []), ...(opts?.documents ?? []), ...(opts?.voice ? [opts.voice] : [])];
+    return Promise.all(paths.map(async (p) => ({ path: p, data: await readFile(p) })));
+};
+/** Convert button rows to Discord component arrays (URL buttons only — style=5). */
+const discordButtons = (rows) => rows.map(row => ({
+    type: 1, components: row.map(b => ({ type: 2, style: 5, label: b.text, url: b.url })),
+}));
+const channelOf = (line) => {
+    const id = Line.parseDiscord(line);
+    if (!id)
+        throw new Error(`not a discord line: ${line}`);
+    return id;
+};
+const CAPS = {
+    in: ['text', 'image'], out: ['text'],
+    features: ['reply', 'send', 'edit', 'react', 'download', 'fetch'],
+};
+export class DiscordStation {
+    name = 'discord';
+    capabilities = CAPS;
+    client = null;
+    messageHandler = () => { };
+    onMessage(handler) {
+        this.messageHandler = handler;
+    }
+    getClient() {
+        return this.client ??= new Client({
+            intents: [
+                GatewayIntentBits.DirectMessages, GatewayIntentBits.Guilds,
+                GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent,
+            ],
+            partials: [Partials.Channel],
+        });
+    }
+    async start() {
+        const c = this.getClient();
+        c.on(Events.MessageCreate, m => { void this.handleMessage(m, c); });
+        c.on(Events.Error, err => log.error({ err: errMsg(err) }, 'discord error'));
+        await c.login(process.env.DISCORD_BOT_TOKEN);
+        await new Promise(r => c.once(Events.ClientReady, () => r()));
+    }
+    async stop() {
+        if (!this.client)
+            return;
+        await this.client.destroy();
+        this.client = null;
+    }
+    async getMe() {
+        return rest('GET', '/users/@me');
+    }
+    async send(line, text, opts) {
+        const payload = { content: text, flags: SUPPRESS_EMBEDS };
+        if (opts?.replyTo)
+            payload.message_reference = { message_id: opts.replyTo };
+        if (opts?.buttons?.length)
+            payload.components = discordButtons(opts.buttons);
+        const path = `/channels/${channelOf(line)}/messages`;
+        const files = await collectFiles(opts);
+        const sent = files.length
+            ? await restMultipart('POST', path, payload, files)
+            : await rest('POST', path, payload);
+        return sent.id;
+    }
+    async edit(line, messageId, text, opts) {
+        const payload = { content: text, flags: SUPPRESS_EMBEDS };
+        payload.components = opts?.buttons?.length ? discordButtons(opts.buttons) : [];
+        await rest('PATCH', `/channels/${channelOf(line)}/messages/${messageId}`, payload);
+    }
+    async react(line, messageId, emoji) {
+        const ch = channelOf(line);
+        if (!emoji) {
+            await rest('DELETE', `/channels/${ch}/messages/${messageId}/reactions/@me`);
+            return;
+        }
+        await rest('PUT', `/channels/${ch}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}/@me`);
+    }
+    async download(line, messageId, outDir) {
+        const ch = channelOf(line);
+        const msg = await rest('GET', `/channels/${ch}/messages/${messageId}`);
+        const out = [];
+        for (const [i, a] of (msg.attachments ?? []).entries()) {
+            if (!a.content_type?.startsWith('image/'))
+                continue;
+            if (a.size > MAX_ATTACHMENT_BYTES) {
+                log.warn({ size: a.size, name: a.filename }, 'discord: attachment too large; skipped');
+                continue;
+            }
+            try {
+                const res = await fetch(a.url, { signal: AbortSignal.timeout(30_000) });
+                if (!res.ok)
+                    throw new Error(`status ${res.status}`);
+                const buf = Buffer.from(await res.arrayBuffer());
+                const path = join(outDir, `${messageId}-${i}-${a.filename}`);
+                await writeFile(path, buf);
+                out.push({ path, mediaType: a.content_type });
+            }
+            catch (err) {
+                log.warn({ err: errMsg(err), url: a.url }, 'discord: attachment fetch failed');
+            }
+        }
+        return out;
+    }
+    async fetch(line, limit) {
+        const capped = Math.max(1, Math.min(100, limit | 0));
+        const msgs = await rest('GET', `/channels/${channelOf(line)}/messages?limit=${capped}`);
+        return [...msgs].reverse().map(m => ({
+            messageId: m.id, author: m.author.username, text: m.content, timestamp: m.timestamp,
+        }));
+    }
+    async handleMessage(m, c) {
+        if (m.author.bot)
+            return;
+        const attachmentNames = [];
+        for (const a of m.attachments.values()) {
+            if (a.contentType?.startsWith('image/'))
+                attachmentNames.push('[image]');
+            else
+                attachmentNames.push(a.contentType?.startsWith('audio/') ? `[audio: ${a.name}]` : `[file: ${a.name}]`);
+        }
+        const text = m.content.trim();
+        if (!text && !attachmentNames.length)
+            return;
+        log.info({ from: m.author.username, bot: c.user?.username, channel: m.channelId, text: text.slice(0, 80) }, 'discord: inbound');
+        const lineName = m.channel && 'name' in m.channel
+            ? m.channel.name ?? undefined : undefined;
+        this.messageHandler({
+            id: mintId(), ts: new Date(m.createdTimestamp).toISOString(),
+            station: 'discord', line: Line.discord(m.channelId), lineName,
+            from: Line.user('discord', m.author.id), fromName: m.author.username,
+            messageId: m.id, text, attachmentNames,
+            mentionsBot: !m.guildId || (c.user ? m.mentions.has(c.user.id) : false),
+            meta: { inGuild: !!m.guildId },
+        });
+    }
+}

package/dist/stations/index.js

@@ -0,0 +1,73 @@
+/** Line URI scheme + ChatStation interface + station listing. The whole station surface. */
+export const asLine = (s) => s;
+const PREFIX = 'metro://';
+const build = (station, ...seg) => asLine(`${PREFIX}${station}/${seg.map(String).join('/')}`);
+/** URI helpers. Lives on a const that doubles as the `Line` type's value-side namespace. */
+export const Line = {
+    discord: (channelId) => build('discord', channelId),
+    telegram: (chatId, topicId) => topicId !== undefined ? build('telegram', chatId, topicId) : build('telegram', chatId),
+    claude: (topic) => build('claude', topic),
+    codex: (topic) => build('codex', topic),
+    /** Participant URIs — `metro://<station>/user/<id>` and `metro://<station>/bot/<id>`. */
+    user: (station, id) => build(station, 'user', id),
+    bot: (station, id) => build(station, 'bot', id),
+    parse(line) {
+        if (!line.startsWith(PREFIX))
+            return null;
+        const rest = line.slice(PREFIX.length);
+        const slash = rest.indexOf('/');
+        if (slash <= 0)
+            return null;
+        const path = rest.slice(slash + 1).split('/').filter(Boolean);
+        return path.length ? { station: rest.slice(0, slash), path } : null;
+    },
+    station: (line) => Line.parse(line)?.station ?? null,
+    parseDiscord(line) {
+        const p = Line.parse(line);
+        return p?.station === 'discord' && p.path.length === 1 ? p.path[0] : null;
+    },
+    parseTelegram(line) {
+        const p = Line.parse(line);
+        if (p?.station !== 'telegram')
+            return null;
+        const chatId = Number(p.path[0]);
+        if (!Number.isFinite(chatId))
+            return null;
+        if (p.path.length === 1)
+            return { chatId };
+        const topicId = Number(p.path[1]);
+        return Number.isFinite(topicId) ? { chatId, topicId } : null;
+    },
+    isAgent: (line) => {
+        const s = Line.station(line);
+        return s === 'claude' || s === 'codex';
+    },
+};
+const AGENT_CAPS = { in: ['text'], out: [], features: ['notify'] };
+const CHAT_CAPS = {
+    in: ['text', 'image'],
+    out: ['text'],
+    features: ['reply', 'send', 'edit', 'react', 'download', 'fetch'],
+};
+export const listStations = () => [
+    {
+        name: 'discord', kind: 'chat', capabilities: CHAT_CAPS,
+        configured: !!process.env.DISCORD_BOT_TOKEN, detail: 'DISCORD_BOT_TOKEN',
+    },
+    {
+        name: 'telegram', kind: 'chat', capabilities: CHAT_CAPS,
+        configured: !!process.env.TELEGRAM_BOT_TOKEN, detail: 'TELEGRAM_BOT_TOKEN',
+    },
+    {
+        name: 'claude', kind: 'agent', capabilities: AGENT_CAPS,
+        configured: null, detail: 'stdout stream (watch via Claude Code Monitor)',
+    },
+    {
+        name: 'codex', kind: 'agent', capabilities: AGENT_CAPS,
+        configured: process.env.METRO_CODEX_RC ? true : null,
+        detail: process.env.METRO_CODEX_RC
+            ? `push → ${process.env.METRO_CODEX_RC}`
+            : 'set METRO_CODEX_RC=ws://… to push',
+    },
+];
+export const fmtCapabilities = (c) => `in: ${c.in.join('+') || '–'} · out: ${c.out.join('+') || '–'} · features: ${c.features.join(', ') || '–'}`;

package/dist/{helpers/telegram-format.js → stations/telegram-md.js}

@@ -5,32 +5,27 @@ const esc = (s) => s.replace(/[&<>]/g, c => ENTITY_MAP[c]);
 const SENT = '\x01';
 export function mdToTelegramHtml(md) {
     const slots = [];
-    const stash = (html) => {
-        slots.push(html);
-        return `${SENT}${slots.length - 1}${SENT}`;
-    };
-    /** Fenced code first so its contents aren't touched by other rules. */
+    const stash = (html) => { slots.push(html); return `${SENT}${slots.length - 1}${SENT}`; };
+    /* Fenced code first so its contents aren't touched by other rules. */
     let work = md.replace(/```([A-Za-z0-9_+\-.]*)\n?([\s\S]*?)```/g, (_m, lang, code) => {
-        const inner = lang
+        return stash(lang
             ? `<pre><code class="language-${esc(lang)}">${esc(code)}</code></pre>`
-            : `<pre>${esc(code)}</pre>`;
-        return stash(inner);
+            : `<pre>${esc(code)}</pre>`);
     });
-    /** Inline code; skip multi-line spans (likely an unclosed mid-stream fence). */
+    /* Inline code (single-line only — multi-line spans look like unclosed mid-stream fences). */
     work = work.replace(/`([^`\n]+)`/g, (_m, code) => stash(`<code>${esc(code)}</code>`));
-    /** Escape outside stashes before running tag-emitting rules. */
     work = esc(work);
     work = work.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/g, (_m, text, url) => stash(`<a href="${url.replace(/"/g, '%22')}">${text}</a>`));
-    /** Bold before italic so single-`*` rule doesn't eat half of `**bold**`. */
+    /* Bold before italic so `*`-rule doesn't eat half of `**bold**`. */
     work = work.replace(/\*\*([^*\n]+?)\*\*/g, '<b>$1</b>').replace(/__([^_\n]+?)__/g, '<b>$1</b>');
-    /** Italic: \S guards prevent matching `2 * 3` arithmetic or `foo_bar` identifiers. */
+    /* \S guards keep `2 * 3` arithmetic and `foo_bar` identifiers intact. */
     work = work
         .replace(/(^|[^*\w])\*(\S[^*\n]*?\S|\S)\*(?!\w)/g, '$1<i>$2</i>')
         .replace(/(^|[^_\w])_(\S[^_\n]*?\S|\S)_(?!\w)/g, '$1<i>$2</i>');
     work = work.replace(/~~([^~\n]+?)~~/g, '<s>$1</s>');
-    /** Headings → bold (Telegram has no heading element). */
+    /* Headings → bold (Telegram has no heading element). */
     work = work.replace(/^#{1,6}\s+(.+?)\s*$/gm, '<b>$1</b>');
-    /** Collapse consecutive `> ` lines into one <blockquote> for prose-level quotes. */
+    /* Collapse consecutive `> ` lines into one <blockquote>. */
     work = work.replace(/(^|\n)((?:&gt;\s?[^\n]*\n?)+)/g, (_m, lead, block) => {
         const inner = block.replace(/^&gt;\s?/gm, '').replace(/\n+$/, '');
         return `${lead}<blockquote>${inner}</blockquote>${block.endsWith('\n') ? '\n' : ''}`;

package/dist/stations/telegram-upload.js

@@ -0,0 +1,113 @@
+/** Telegram outgoing sends — single multipart, media groups, and the rich-content dispatch. */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { log } from '../log.js';
+import { mdToTelegramHtml } from './telegram-md.js';
+const API_BASE = 'https://api.telegram.org';
+const NO_PREVIEW = { link_preview_options: { is_disabled: true } };
+export const inlineKeyboard = (rows) => ({ inline_keyboard: rows });
+async function post(token, method, form) {
+    const res = await fetch(`${API_BASE}/bot${token}/${method}`, {
+        method: 'POST', body: form, signal: AbortSignal.timeout(60_000),
+    });
+    const json = (await res.json());
+    if (!json.ok)
+        throw new Error(`telegram ${method}: ${json.description ?? 'unknown error'}`);
+    return json.result;
+}
+function appendFields(form, fields) {
+    for (const [k, v] of Object.entries(fields)) {
+        if (v === undefined || v === null)
+            continue;
+        form.append(k, typeof v === 'string' ? v : JSON.stringify(v));
+    }
+}
+async function appendFile(form, field, filePath) {
+    form.append(field, new Blob([new Uint8Array(await readFile(filePath))]), basename(filePath));
+}
+const isParseError = (err) => err instanceof Error && err.message.includes("can't parse entities");
+/** sendPhoto / sendDocument / sendVoice with HTML-caption + plain fallback. */
+async function sendOne(token, base, method, fileField, filePath, caption) {
+    const attempt = async (html) => {
+        const form = new FormData();
+        appendFields(form, {
+            ...base,
+            caption: html ? mdToTelegramHtml(caption) : caption,
+            ...(html ? { parse_mode: 'HTML' } : {}),
+        });
+        await appendFile(form, fileField, filePath);
+        return post(token, method, form);
+    };
+    try {
+        return String((await attempt(true)).message_id);
+    }
+    catch (err) {
+        if (!isParseError(err))
+            throw err;
+        log.warn('telegram: HTML rejected, retrying plain');
+        return String((await attempt(false)).message_id);
+    }
+}
+/** sendMediaGroup — 2-10 same-kind files. Caption goes on the first item only. */
+async function sendGroup(token, base, kind, paths, caption) {
+    const form = new FormData();
+    appendFields(form, base);
+    const media = await Promise.all(paths.map(async (p, i) => {
+        const field = `m${i}`;
+        await appendFile(form, field, p);
+        return {
+            type: kind, media: `attach://${field}`,
+            ...(i === 0 && caption ? { caption: mdToTelegramHtml(caption), parse_mode: 'HTML' } : {}),
+        };
+    }));
+    form.append('media', JSON.stringify(media));
+    const sent = await post(token, 'sendMediaGroup', form);
+    return String(sent[0].message_id);
+}
+/** Plain text via sendMessage with HTML + plain fallback. */
+async function sendText(send, base, text) {
+    const attempt = (html) => send('sendMessage', html ? { ...base, ...NO_PREVIEW, text: mdToTelegramHtml(text), parse_mode: 'HTML' }
+        : { ...base, ...NO_PREVIEW, text });
+    try {
+        return String((await attempt(true)).message_id);
+    }
+    catch (err) {
+        if (!isParseError(err))
+            throw err;
+        log.warn('telegram: HTML rejected, sending plain');
+        return String((await attempt(false)).message_id);
+    }
+}
+/** Dispatch for text + images + documents + voice + buttons. Returns the first message id. */
+export async function tgSendRich(token, send, base, text, opts) {
+    const images = opts?.images ?? [], docs = opts?.documents ?? [], voice = opts?.voice;
+    const total = images.length + docs.length + (voice ? 1 : 0);
+    const baseWithButtons = opts?.buttons?.length
+        ? { ...base, reply_markup: inlineKeyboard(opts.buttons) } : base;
+    if (total === 0)
+        return sendText(send, baseWithButtons, text);
+    if (total === 1) {
+        if (voice)
+            return sendOne(token, baseWithButtons, 'sendVoice', 'voice', voice, text);
+        if (images.length)
+            return sendOne(token, baseWithButtons, 'sendPhoto', 'photo', images[0], text);
+        return sendOne(token, baseWithButtons, 'sendDocument', 'document', docs[0], text);
+    }
+    /* Multi-attachment: media groups don't support reply_markup — buttons are dropped. */
+    if (opts?.buttons?.length)
+        log.warn('telegram: buttons dropped on multi-attachment send');
+    let first;
+    let caption = text;
+    const claim = async (id) => { first ??= id; caption = ''; };
+    if (voice)
+        await claim(await sendOne(token, base, 'sendVoice', 'voice', voice, caption));
+    if (images.length === 1)
+        await claim(await sendOne(token, base, 'sendPhoto', 'photo', images[0], caption));
+    else if (images.length)
+        await claim(await sendGroup(token, base, 'photo', images, caption));
+    if (docs.length === 1)
+        await claim(await sendOne(token, base, 'sendDocument', 'document', docs[0], caption));
+    else if (docs.length)
+        await claim(await sendGroup(token, base, 'document', docs, caption));
+    return first;
+}

package/dist/stations/telegram.js

@@ -0,0 +1,235 @@
+/** Telegram station: long-poll bot API; sends agent-style markdown as HTML with plain-text fallback. */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { errMsg, log } from '../log.js';
+import { mintId } from '../history.js';
+import { mdToTelegramHtml } from './telegram-md.js';
+import { inlineKeyboard, tgSendRich } from './telegram-upload.js';
+import { Line, } from './index.js';
+import { STATE_DIR } from '../paths.js';
+const API_BASE = 'https://api.telegram.org';
+const NO_PREVIEW = { link_preview_options: { is_disabled: true } };
+const MAX_BYTES = 20 * 1024 * 1024;
+const token = () => {
+    const t = process.env.TELEGRAM_BOT_TOKEN;
+    if (!t)
+        throw new Error('TELEGRAM_BOT_TOKEN is not set');
+    return t;
+};
+async function tg(method, body, opts = {}) {
+    const signals = [AbortSignal.timeout(opts.timeoutMs ?? 30_000)];
+    if (opts.signal)
+        signals.push(opts.signal);
+    const res = await fetch(`${API_BASE}/bot${token()}/${method}`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body), signal: AbortSignal.any(signals),
+    });
+    const json = (await res.json());
+    if (!json.ok)
+        throw new Error(`telegram ${method}: ${json.description ?? 'unknown error'}`);
+    return json.result;
+}
+const isParseError = (err) => errMsg(err).includes("can't parse entities");
+const isNoopEdit = (err) => errMsg(err).includes('message is not modified');
+const targetOf = (line) => {
+    const t = Line.parseTelegram(line);
+    if (!t)
+        throw new Error(`not a telegram line: ${line}`);
+    return t;
+};
+function attachmentTags(m) {
+    const out = [];
+    if (m.photo?.length)
+        out.push('[image]');
+    if (m.document?.mime_type?.startsWith('image/'))
+        out.push('[image]');
+    else if (m.document)
+        out.push(`[file: ${m.document.file_name ?? m.document.file_id}]`);
+    if (m.voice)
+        out.push('[voice]');
+    if (m.audio)
+        out.push('[audio]');
+    return out;
+}
+const CAPS = {
+    in: ['text', 'image'], out: ['text'],
+    features: ['reply', 'send', 'edit', 'react', 'download', 'fetch'],
+};
+export class TelegramStation {
+    name = 'telegram';
+    capabilities = CAPS;
+    botUsername = null;
+    botUserId = null;
+    pollOffset = 0;
+    pollAbort = null;
+    messageHandler = () => { };
+    offsetFile = join(STATE_DIR, 'telegram-offset.json');
+    /** Snapshot recent inbounds in memory so `metro download <line> <id>` can resolve them. */
+    recent = new Map();
+    onMessage(handler) { this.messageHandler = handler; }
+    async start() {
+        await tg('deleteWebhook', { drop_pending_updates: false }).catch(() => { });
+        const persisted = Number(existsSync(this.offsetFile) ? readFileSync(this.offsetFile, 'utf8').trim() : 0) || 0;
+        if (persisted > 0)
+            this.pollOffset = persisted;
+        else {
+            /* First run: anchor on latest update id (-1 returns most recent without consuming). */
+            const initial = await tg('getUpdates', { offset: -1, timeout: 0 });
+            this.pollOffset = initial.length ? initial[0].update_id + 1 : 0;
+            this.saveOffset();
+        }
+        log.info({ offset: this.pollOffset }, 'telegram station: polling started');
+        this.pollAbort = new AbortController();
+        void this.pollLoop();
+    }
+    async stop() { this.pollAbort?.abort(); this.pollAbort = null; }
+    async getMe() {
+        const me = await tg('getMe', {});
+        this.botUsername = me.username;
+        this.botUserId = me.id;
+        return me;
+    }
+    async send(line, text, opts) {
+        const { chatId, topicId } = targetOf(line);
+        const base = { chat_id: chatId };
+        if (topicId !== undefined)
+            base.message_thread_id = topicId;
+        if (opts?.replyTo)
+            base.reply_parameters = { message_id: Number(opts.replyTo) };
+        return tgSendRich(token(), tg, base, text, opts);
+    }
+    async edit(line, messageId, text, opts) {
+        const { chatId } = targetOf(line);
+        const base = { chat_id: chatId, message_id: Number(messageId), ...NO_PREVIEW };
+        if (opts?.buttons)
+            base.reply_markup = opts.buttons.length ? inlineKeyboard(opts.buttons) : { inline_keyboard: [] };
+        try {
+            await tg('editMessageText', { ...base, text: mdToTelegramHtml(text), parse_mode: 'HTML' });
+        }
+        catch (err) {
+            if (isNoopEdit(err))
+                return;
+            if (!isParseError(err))
+                throw err;
+            log.warn({ err: errMsg(err) }, 'telegram: HTML edit rejected, retrying plain');
+            try {
+                await tg('editMessageText', { ...base, text });
+            }
+            catch (e) {
+                if (!isNoopEdit(e))
+                    throw e;
+            }
+        }
+    }
+    async react(line, messageId, emoji) {
+        await tg('setMessageReaction', {
+            chat_id: targetOf(line).chatId, message_id: Number(messageId),
+            reaction: emoji ? [{ type: 'emoji', emoji }] : [],
+        });
+    }
+    async download(line, messageId, outDir) {
+        /* Telegram has no "get message by id" — resolve from the in-memory snapshot. */
+        const { chatId } = targetOf(line);
+        const m = this.recent.get(`${chatId}:${messageId}`);
+        if (!m)
+            return [];
+        const refs = [];
+        if (m.photo?.length)
+            refs.push({ id: m.photo[m.photo.length - 1].file_id, mime: 'image/jpeg' });
+        if (m.document?.mime_type?.startsWith('image/'))
+            refs.push({ id: m.document.file_id, mime: m.document.mime_type });
+        const out = [];
+        for (const [i, { id, mime }] of refs.entries()) {
+            try {
+                const file = await tg('getFile', { file_id: id });
+                const res = await fetch(`${API_BASE}/file/bot${token()}/${file.file_path}`, { signal: AbortSignal.timeout(30_000) });
+                if (!res.ok)
+                    throw new Error(`status ${res.status}`);
+                const buf = Buffer.from(await res.arrayBuffer());
+                if (buf.byteLength > MAX_BYTES) {
+                    log.warn({ id, size: buf.byteLength }, 'telegram: attachment too large');
+                    continue;
+                }
+                const path = join(outDir, `${chatId}-${messageId}-${i}.${mime.split('/')[1] ?? 'bin'}`);
+                await writeFile(path, buf);
+                out.push({ path, mediaType: mime });
+            }
+            catch (err) {
+                log.warn({ err: errMsg(err), id }, 'telegram: attachment fetch failed');
+            }
+        }
+        return out;
+    }
+    /** Bot API has no history endpoint — only the in-memory snapshot is reachable. */
+    async fetch() { return []; }
+    saveOffset() {
+        try {
+            writeFileSync(this.offsetFile, String(this.pollOffset));
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err) }, 'telegram offset save failed');
+        }
+    }
+    async pollLoop() {
+        const signal = this.pollAbort?.signal;
+        const body = { timeout: 25, allowed_updates: ['message'] };
+        while (this.pollAbort && !this.pollAbort.signal.aborted) {
+            try {
+                const updates = await tg('getUpdates', { offset: this.pollOffset, ...body }, { timeoutMs: 60_000, signal });
+                for (const u of updates) {
+                    this.pollOffset = u.update_id + 1;
+                    this.dispatchUpdate(u);
+                }
+                if (updates.length)
+                    this.saveOffset();
+            }
+            catch (err) {
+                if (this.pollAbort?.signal.aborted)
+                    break;
+                log.warn({ err: errMsg(err) }, 'telegram poll error; backing off');
+                await new Promise(r => setTimeout(r, 2000));
+            }
+        }
+    }
+    dispatchUpdate(u) {
+        const m = u.message;
+        if (!m?.chat?.id || typeof m.message_id !== 'number' || m.from?.is_bot)
+            return;
+        const attachmentNames = attachmentTags(m);
+        const text = m.text ?? m.caption ?? '';
+        if (!text && !attachmentNames.length)
+            return;
+        const topicId = m.is_topic_message ? m.message_thread_id : undefined;
+        const fromName = m.from?.username ? `@${m.from.username}` : m.from?.first_name;
+        const fromUri = Line.user('telegram', m.from?.id ?? 'unknown');
+        const bot = this.botUsername ? `@${this.botUsername}` : undefined;
+        log.info({ from: fromName, bot, chat: m.chat.id, topic: topicId, text: text.slice(0, 80) }, 'telegram: inbound');
+        if (this.recent.size >= 50) {
+            const first = this.recent.keys().next().value;
+            if (first)
+                this.recent.delete(first);
+        }
+        this.recent.set(`${m.chat.id}:${m.message_id}`, m);
+        this.messageHandler({
+            id: mintId(), ts: new Date((m.date ?? Math.floor(Date.now() / 1000)) * 1000).toISOString(),
+            station: 'telegram', line: Line.telegram(m.chat.id, topicId), messageId: String(m.message_id),
+            lineName: topicId === undefined ? (m.chat.title ?? m.chat.first_name ?? undefined) : undefined,
+            from: fromUri, fromName, text, attachmentNames, mentionsBot: this.detectMentionsBot(m),
+            meta: { isPrivate: m.chat.type === 'private', inForum: !!m.chat.is_forum, isForumTopic: !!m.is_topic_message },
+        });
+    }
+    detectMentionsBot(m) {
+        if (m.chat?.type === 'private')
+            return true;
+        const text = m.text ?? m.caption ?? '';
+        for (const e of m.entities ?? m.caption_entities ?? []) {
+            if (e.type === 'mention' && this.botUsername
+                && text.substring(e.offset, e.offset + e.length).toLowerCase() === `@${this.botUsername.toLowerCase()}`)
+                return true;
+            if (e.type === 'text_mention' && e.user?.id === this.botUserId)
+                return true;
+        }
+        return false;
+    }
+}