@stage-labs/metro 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stage Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# Metro
+
+Chat with your Claude Code or Codex agent over Telegram and Discord. Messages land in the session live, the agent reacts, types while it works, and replies — ~700 lines of TypeScript, one stdio MCP, no hosted infra.
+
+## Quickstart
+
+```bash
+npm install -g @stage-labs/metro@beta    # or: bun add -g @stage-labs/metro@beta
+```
+
+> The `@beta` tag is required while Metro is in prerelease.
+
+Register Metro with your agent (use `claude` or `codex` interchangeably):
+
+```bash
+claude mcp add metro \
+  --env TELEGRAM_BOT_TOKEN=123:ABC… \
+  --env DISCORD_BOT_TOKEN=MTIz… \
+  -- metro mcp
+```
+
+Both `--env` flags are optional — configure at least one of Telegram or Discord.
+
+In your agent session, ask it to start the inbound stream:
+
+> Run `metro tail` in the background and Monitor its stdout for inbound Telegram/Discord messages.
+
+DM your bot. The agent reacts on its next decision boundary (see Caveats for latency notes).
+
+## Bot tokens
+
+- **Telegram**: DM [@BotFather](https://t.me/BotFather), `/newbot`, copy the token.
+- **Discord**: [discord.com/developers/applications](https://discord.com/developers/applications) → New Application → Bot → Reset Token. **Toggle Message Content Intent** in the same Bot tab (Privileged Gateway Intents) — without it, message bodies arrive empty. Generate an OAuth invite with the `bot` scope, or DM the bot directly.
+
+## How it works
+
+Metro ships two commands:
+
+- **`metro mcp`** — a stdio MCP server. Registers the tools below so the agent can reply, react, edit, and download attachments. Started once when the agent boots (via `claude mcp add` / `codex mcp add` above).
+- **`metro tail`** — the inbound runtime. Polls Telegram and connects to Discord's WebSocket gateway, then prints one JSON line per inbound message to stdout. The agent watches that stdout (Bash+Monitor in Claude Code, unified_exec in Codex) and acts on each line at its next decision boundary. Started on demand from inside an agent session.
+
+While the agent works on a reply, both platforms show a typing indicator; when it replies, the indicator stops and the auto-ack reaction (👀) is cleared on the exact message replied to.
+
+## MCP tools
+
+Registered by `metro mcp` — the agent calls these to act on the messages it sees from `metro tail`:
+
+| Tool | Telegram | Discord | Purpose |
+|---|---|---|---|
+| Reply | `telegram-reply` | `discord-reply` | Quote-reply, threading under the original message. Clears the 👀 auto-ack. |
+| React | `telegram-react` | `discord-react` | Set or clear an emoji reaction. |
+| Edit | `telegram-edit-message` | `discord-edit-message` | Edit a message the bot previously sent. |
+| Download attachment | `telegram-download-attachment` | `discord-download-attachment` | Pull image attachments back as `image` content blocks. |
+| Fetch recent messages | — | `discord-fetch-messages` | Lookback for context. (Discord exposes no search API for bots; Telegram has none either.) |
+
+The agent reads `chat_id` / `channel_id` and `message_id` from the inbound JSON and threads them through. Voice / audio surface as `[voice]` / `[audio]` text placeholders — the agent sees them but can't download.
+
+## Config
+
+All settings come from environment variables passed via the MCP server's `--env` block:
+
+| Variable | Default | Description |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | — | Telegram bot token. Required for the Telegram channel. |
+| `DISCORD_BOT_TOKEN` | — | Discord bot token. Required for the Discord channel. |
+| `METRO_LOG_LEVEL` | `info` | `trace`/`debug`/`info`/`warn`/`error`/`fatal`. |
+| `METRO_STATE_DIR` | `~/.cache/metro` | Where the lockfile, typing-stop signals, and the Telegram attachment cache live. |
+
+Logs go to stderr. Claude Code captures them at `~/Library/Caches/claude-cli-nodejs/…/mcp-logs-plugin-metro-metro/*.jsonl`.
+
+For local dev (cloned repo, no host agent): `cp .env.example .env && chmod 600 .env`, then run `metro tail` / `metro mcp` from the repo dir — `.env` is read as a fallback when env vars aren't set.
+
+## Troubleshooting
+
+```bash
+which metro                                # → e.g. ~/.bun/bin/metro
+metro                                      # prints usage
+
+ps aux | grep metro | grep -v grep         # one `metro mcp`, optionally one `metro tail`
+
+rm -rf ~/.cache/metro/                     # clean stuck state — or whatever METRO_STATE_DIR points at
+
+# Latest agent-side log (Claude Code):
+ls -t ~/Library/Caches/claude-cli-nodejs/-Users-*-metro/mcp-logs-plugin-metro-metro/*.jsonl | head -1 | xargs cat
+```
+
+## Caveats
+
+- **Discord Message Content Intent** is privileged — toggle it in the Developer Portal. See above.
+- **Telegram single-poller.** Telegram allows one `getUpdates` consumer per bot token. If two `metro tail` instances start, the second-comer detects the lockfile (`$METRO_STATE_DIR/.tail-lock`) and exits cleanly. Re-run after the first exits to take over.
+- **No allowlist.** Anyone who can DM your bot or @-mention it can talk to your session. Run against bots you own.
+- **Mid-task latency.** New messages surface at the next agent decision boundary — sub-second on Claude Code (lots of small tool calls), longer on Codex turns. Neither runtime can interrupt an in-progress LLM generation.
+- **UI visibility.** Claude Code's `Monitor` collapses stdout into a card; Codex dims MCP tool args. Metro's MCP `instructions` direct the agent to echo each inbound in its visible reply so you see what arrived without expanding cards.

package/dist/channels/discord.js

@@ -0,0 +1,117 @@
+import { Client, Events, GatewayIntentBits, Partials } from 'discord.js';
+import { errMsg, log } from '../log.js';
+let client = null;
+function getClient() {
+    if (client)
+        return client;
+    if (!process.env.DISCORD_BOT_TOKEN)
+        throw new Error('DISCORD_BOT_TOKEN is not set');
+    client = new Client({
+        intents: [
+            GatewayIntentBits.DirectMessages,
+            GatewayIntentBits.Guilds,
+            GatewayIntentBits.GuildMessages,
+            GatewayIntentBits.MessageContent,
+        ],
+        // DM channels arrive partial; without this messageCreate never fires.
+        partials: [Partials.Channel],
+    });
+    return client;
+}
+async function getTextChannel(channelId) {
+    const channel = await getClient().channels.fetch(channelId);
+    if (!channel?.isTextBased() || !('messages' in channel)) {
+        throw new Error(`discord: channel ${channelId} is not text-capable`);
+    }
+    return channel;
+}
+async function fetchMessage(channelId, messageId) {
+    return (await getTextChannel(channelId)).messages.fetch(messageId);
+}
+let onInboundHandler = () => { };
+export function onInbound(handler) {
+    onInboundHandler = handler;
+}
+export async function startGateway() {
+    const c = getClient();
+    c.on(Events.MessageCreate, m => {
+        if (m.author.bot)
+            return;
+        // Guild messages: only forward when the bot is mentioned. DMs always pass.
+        if (m.guildId && c.user && !m.mentions.has(c.user.id))
+            return;
+        const tags = [...m.attachments.values()]
+            .map(a => {
+            if (a.contentType?.startsWith('image/'))
+                return '[image]';
+            if (a.contentType?.startsWith('audio/'))
+                return `[audio: ${a.name}]`;
+            return `[file: ${a.name}]`;
+        })
+            .join(' ');
+        const text = [m.content, tags].filter(Boolean).join(' ').trim();
+        if (!text)
+            return;
+        onInboundHandler({ channel_id: m.channelId, message_id: m.id, text });
+    });
+    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()));
+}
+export async function getMe() {
+    const c = getClient();
+    if (!c.user)
+        throw new Error('discord: gateway not ready');
+    return { username: c.user.username };
+}
+export async function replyToMessage(channelId, messageId, text) {
+    await (await fetchMessage(channelId, messageId)).reply(text);
+}
+export async function editMessage(channelId, messageId, text) {
+    await (await fetchMessage(channelId, messageId)).edit(text);
+}
+export async function sendTyping(channelId) {
+    const channel = await getClient().channels.fetch(channelId);
+    if (!channel?.isTextBased() || !('sendTyping' in channel))
+        return;
+    await channel.sendTyping();
+}
+export async function setReaction(channelId, messageId, emoji) {
+    const target = await fetchMessage(channelId, messageId);
+    if (emoji) {
+        await target.react(emoji);
+        return;
+    }
+    // Clear only the bot's own reactions (matches Telegram's clear semantics).
+    const me = getClient().user;
+    if (!me)
+        return;
+    for (const r of target.reactions.cache.values()) {
+        if (r.users.cache.has(me.id))
+            await r.users.remove(me.id);
+    }
+}
+export async function fetchAttachments(channelId, messageId) {
+    const target = await fetchMessage(channelId, messageId);
+    const out = [];
+    for (const a of target.attachments.values()) {
+        if (!a.contentType?.startsWith('image/'))
+            continue;
+        const res = await fetch(a.url);
+        if (!res.ok)
+            throw new Error(`discord: download ${a.url}: ${res.status}`);
+        out.push({ data: Buffer.from(await res.arrayBuffer()).toString('base64'), mime: a.contentType });
+    }
+    return out;
+}
+export async function fetchRecentMessages(channelId, limit) {
+    const channel = await getTextChannel(channelId);
+    const msgs = await channel.messages.fetch({ limit: Math.min(Math.max(limit, 1), 100) });
+    // Discord returns newest-first; reverse for chronological.
+    return [...msgs.values()].reverse().map(m => ({
+        message_id: m.id,
+        author: m.author.username,
+        text: m.content,
+        timestamp: m.createdAt.toISOString(),
+    }));
+}

package/dist/channels/telegram.js

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATE_DIR } from '../config.js';
+import { errMsg, log } from '../log.js';
+const API_BASE = 'https://api.telegram.org';
+function token() {
+    const t = process.env.TELEGRAM_BOT_TOKEN;
+    if (!t)
+        throw new Error('TELEGRAM_BOT_TOKEN is not set');
+    return t;
+}
+export async function tg(method, body, timeoutMs = 30_000) {
+    const res = await fetch(`${API_BASE}/bot${token()}/${method}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const json = (await res.json());
+    if (!json.ok)
+        throw new Error(`telegram ${method}: ${json.description ?? 'unknown error'}`);
+    return json.result;
+}
+export function buildSendBody(chatId, text, opts) {
+    const body = { chat_id: chatId, text };
+    if (opts.parseMode)
+        body.parse_mode = opts.parseMode;
+    if (opts.disableLinkPreview)
+        body.link_preview_options = { is_disabled: true };
+    if (opts.buttons?.length)
+        body.reply_markup = { inline_keyboard: opts.buttons };
+    return body;
+}
+export async function getMe() {
+    return tg('getMe', {});
+}
+const CACHE_MAX = 200;
+const cacheFile = join(STATE_DIR, 'telegram-attachments.json');
+function readCache() {
+    try {
+        return existsSync(cacheFile) ? JSON.parse(readFileSync(cacheFile, 'utf8')) : {};
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'telegram attachment cache read failed');
+        return {};
+    }
+}
+function cacheAttachment(chatId, messageId, att) {
+    try {
+        const data = readCache();
+        const key = `${chatId}:${messageId}`;
+        data[key] = [...(data[key] ?? []), att];
+        const keys = Object.keys(data);
+        for (const stale of keys.slice(0, Math.max(0, keys.length - CACHE_MAX)))
+            delete data[stale];
+        writeFileSync(cacheFile, JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'telegram attachment cache write failed');
+    }
+}
+export function getCachedAttachments(chatId, messageId) {
+    return readCache()[`${chatId}:${messageId}`] ?? [];
+}
+export async function downloadAttachment(fileId, mime) {
+    const file = await tg('getFile', { file_id: fileId });
+    const res = await fetch(`${API_BASE}/file/bot${token()}/${file.file_path}`, {
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok)
+        throw new Error(`download failed: ${res.status}`);
+    const blob = await res.blob();
+    return { data: Buffer.from(await blob.arrayBuffer()).toString('base64'), mime: blob.type || mime };
+}
+async function messageToText(m, chatId) {
+    if (m.text)
+        return m.text;
+    const caption = m.caption ?? '';
+    if (m.photo?.length) {
+        const photo = m.photo[m.photo.length - 1];
+        cacheAttachment(chatId, m.message_id, { file_id: photo.file_id, mime: 'image/jpeg' });
+        return [caption, '[image]'].filter(Boolean).join(' ');
+    }
+    if (m.document?.mime_type?.startsWith('image/')) {
+        cacheAttachment(chatId, m.message_id, { file_id: m.document.file_id, mime: m.document.mime_type });
+        return [caption, '[image]'].filter(Boolean).join(' ');
+    }
+    if (m.voice)
+        return [caption, '[voice]'].filter(Boolean).join(' ');
+    if (m.audio)
+        return [caption, '[audio]'].filter(Boolean).join(' ');
+    return caption || null;
+}
+let onInboundHandler = () => { };
+export function onInbound(handler) {
+    onInboundHandler = handler;
+}
+export async function startPolling() {
+    // A registered webhook short-circuits getUpdates — clear it defensively.
+    await tg('deleteWebhook', { drop_pending_updates: false }).catch(() => { });
+    let offset = 0;
+    const initial = await tg('getUpdates', { timeout: 0 });
+    if (initial.length)
+        offset = initial[initial.length - 1].update_id + 1;
+    while (true) {
+        try {
+            const updates = await tg('getUpdates', { offset, timeout: 50 }, 60_000);
+            for (const u of updates) {
+                offset = u.update_id + 1;
+                void dispatchUpdate(u);
+            }
+        }
+        catch (err) {
+            log.error({ err: errMsg(err) }, 'telegram poll error');
+            await new Promise(r => setTimeout(r, 1000));
+        }
+    }
+}
+async function dispatchUpdate(u) {
+    const m = u.message;
+    if (!m?.chat?.id || typeof m.message_id !== 'number')
+        return;
+    const base = { chat_id: m.chat.id, message_id: m.message_id };
+    try {
+        const text = await messageToText(m, m.chat.id);
+        if (text === null)
+            return;
+        onInboundHandler({ ...base, text });
+    }
+    catch (err) {
+        onInboundHandler({ ...base, text: `[message processing failed: ${errMsg(err)}]` });
+    }
+}

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+const cmd = process.argv[2];
+if (cmd === 'tail') {
+    await import('./tail.js');
+}
+else if (cmd === 'mcp') {
+    await import('./server.js');
+}
+else {
+    process.stderr.write('usage: metro <tail|mcp>\n');
+    process.exit(cmd ? 1 : 0);
+}
+export {};

package/dist/config.js

@@ -0,0 +1,33 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { log } from './log.js';
+// Lockfiles, typing-stop signals, and the attachment cache live here.
+// Override with METRO_STATE_DIR.
+export const STATE_DIR = process.env.METRO_STATE_DIR ?? join(homedir(), '.cache', 'metro');
+mkdirSync(STATE_DIR, { recursive: true });
+// Optional .env in cwd — convenience for local development. In production,
+// env vars come from the MCP server's `env` block.
+export function loadMetroEnv() {
+    const envFile = join(process.cwd(), '.env');
+    if (!existsSync(envFile))
+        return;
+    for (const line of readFileSync(envFile, 'utf8').split('\n')) {
+        const m = line.match(/^\s*([A-Za-z_]\w*)\s*=\s*(.*?)\s*$/);
+        if (m && process.env[m[1]] === undefined) {
+            process.env[m[1]] = m[2].replace(/^(['"])(.*)\1$/, '$2');
+        }
+    }
+}
+export function configuredPlatforms() {
+    return {
+        telegram: !!process.env.TELEGRAM_BOT_TOKEN,
+        discord: !!process.env.DISCORD_BOT_TOKEN,
+    };
+}
+export function requireConfiguredPlatform(p) {
+    if (p.telegram || p.discord)
+        return;
+    log.fatal('set TELEGRAM_BOT_TOKEN and/or DISCORD_BOT_TOKEN — pass via the MCP server `env` block, or in ./.env for local dev');
+    process.exit(1);
+}

package/dist/log.js

@@ -0,0 +1,5 @@
+// Pino → stderr. Stdout is reserved for MCP JSON-RPC; any stray write there
+// breaks the protocol. Override level with METRO_LOG_LEVEL.
+import pino from 'pino';
+export const log = pino({ name: 'metro', level: process.env.METRO_LOG_LEVEL || 'info' }, pino.destination(2));
+export const errMsg = (err) => (err instanceof Error ? err.message : String(err));

package/dist/server.js

@@ -0,0 +1,158 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import pkg from '../package.json' with { type: 'json' };
+import * as discord from './channels/discord.js';
+import * as telegram from './channels/telegram.js';
+import { buildSendBody, tg } from './channels/telegram.js';
+import { configuredPlatforms, loadMetroEnv, STATE_DIR, requireConfiguredPlatform } from './config.js';
+import { errMsg, log } from './log.js';
+loadMetroEnv();
+const platforms = configuredPlatforms();
+requireConfiguredPlatform(platforms);
+// Tell tail.ts to stop refreshing typing for this chat (the agent has replied).
+const TYPING_DIR = join(STATE_DIR, '.typing-stop');
+function signalReplyComplete(platform, chat) {
+    try {
+        mkdirSync(TYPING_DIR, { recursive: true });
+        writeFileSync(join(TYPING_DIR, `${platform}_${chat}`), '');
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'typing stop-signal write failed');
+    }
+}
+// Discord tools need a logged-in client for REST calls; warm the gateway in
+// the background so MCP stdio binds before discord.js's slow handshake. Tool
+// handlers below await `discordReady` before touching the client.
+const discordReady = platforms.discord
+    ? discord.startGateway().catch(err => log.warn({ err: errMsg(err) }, 'discord gateway warmup failed'))
+    : Promise.resolve();
+const ok = (text) => ({ content: [{ type: 'text', text }] });
+const enabled = [platforms.telegram && 'Telegram', platforms.discord && 'Discord']
+    .filter(Boolean)
+    .join(' + ');
+const server = new McpServer({ name: 'metro', version: pkg.version }, {
+    capabilities: { tools: {} },
+    instructions: `Metro: ${enabled} channel.\n\n` +
+        'Inbound messages arrive as JSON lines on stdout of `metro tail` running in ' +
+        'the background (Bash+Monitor on Claude Code, unified_exec on Codex). Each line: ' +
+        '`{"platform":"telegram"|"discord","chat_id"|"channel_id":"…","message_id":…,"text":"…"}`.\n\n' +
+        'VISIBILITY: when handling an inbound message, your FIRST visible line MUST echo ' +
+        'the content so the user sees what arrived:\n' +
+        '  [telegram chat_id=<id>] <content>\n' +
+        '  [discord channel_id=<id>] <content>\n\n' +
+        'Then call the matching tool — `telegram-*` or `discord-*` — passing `chat_id`, ' +
+        '`channel_id`, and `message_id` verbatim from the inbound. Defaults: `reply` for ' +
+        'questions, `react` 👍 for quick acks, `edit-message` to update, ' +
+        '`*-download-attachment` for `[image]` markers (voice/audio are opaque), ' +
+        '`discord-fetch-messages` for prior context.',
+});
+const parseMode = z.enum(['HTML', 'MarkdownV2']).optional();
+const disableLinkPreview = z.boolean().optional();
+const buttons = z
+    .array(z.array(z.object({ text: z.string(), url: z.string() })))
+    .optional()
+    .describe('Inline URL buttons. Outer = rows, inner = buttons in row.');
+if (platforms.telegram) {
+    const chatId = z.union([z.string(), z.number()]).describe('Telegram chat_id from the inbound tag.');
+    const messageId = z.number().int().describe('Telegram message_id from the inbound tag.');
+    const sendInputs = { chatId, messageId, text: z.string(), parseMode, disableLinkPreview, buttons };
+    server.registerTool('telegram-reply', { description: "Quote-reply to a Telegram message. Threads under the user's original.", inputSchema: sendInputs }, async ({ chatId, messageId, text, parseMode, disableLinkPreview, buttons }) => {
+        const body = buildSendBody(chatId, text, { parseMode, disableLinkPreview, buttons });
+        body.reply_parameters = { message_id: messageId, allow_sending_without_reply: true };
+        await tg('sendMessage', body);
+        signalReplyComplete('telegram', String(chatId));
+        // Clear the auto-acknowledgement emoji on the specific message we replied to.
+        await tg('setMessageReaction', { chat_id: chatId, message_id: messageId, reaction: [] }).catch(err => log.warn({ err: errMsg(err) }, 'telegram clear-reaction failed'));
+        return ok('sent');
+    });
+    server.registerTool('telegram-react', {
+        description: "Set or clear an emoji reaction. Pass '' to clear. Telegram's bot whitelist: " +
+            '👍 ❤️ 🔥 🥰 👏 😁 🤔 🎉 🙏 👌 💯 🤣 …',
+        inputSchema: { chatId, messageId, emoji: z.string() },
+    }, async ({ chatId, messageId, emoji }) => {
+        const reaction = emoji ? [{ type: 'emoji', emoji }] : [];
+        await tg('setMessageReaction', { chat_id: chatId, message_id: messageId, reaction });
+        return ok(emoji ? 'reacted' : 'cleared');
+    });
+    server.registerTool('telegram-edit-message', { description: 'Edit a Telegram message the bot previously sent.', inputSchema: sendInputs }, async ({ chatId, messageId, text, parseMode, disableLinkPreview, buttons }) => {
+        const body = buildSendBody(chatId, text, { parseMode, disableLinkPreview, buttons });
+        body.message_id = messageId;
+        await tg('editMessageText', body);
+        return ok('edited');
+    });
+    server.registerTool('telegram-download-attachment', {
+        description: 'Download image attachments as image content blocks.',
+        inputSchema: { chatId, messageId },
+    }, async ({ chatId, messageId }) => {
+        const atts = telegram.getCachedAttachments(chatId, messageId);
+        if (atts.length === 0)
+            return ok('no cached attachments — message may pre-date this session');
+        const blocks = await Promise.all(atts.map(async (a) => {
+            const { data, mime } = await telegram.downloadAttachment(a.file_id, a.mime);
+            return { type: 'image', data, mimeType: mime };
+        }));
+        return { content: blocks };
+    });
+}
+if (platforms.discord) {
+    const channelId = z.string().describe('Discord channel snowflake from the inbound tag.');
+    const messageId = z.string().describe('Discord message snowflake from the inbound tag.');
+    server.registerTool('discord-reply', {
+        description: 'Reply to a Discord message. Threads under the original.',
+        inputSchema: { channelId, messageId, text: z.string() },
+    }, async ({ channelId, messageId, text }) => {
+        await discordReady;
+        await discord.replyToMessage(channelId, messageId, text);
+        signalReplyComplete('discord', channelId);
+        // Clear the auto-acknowledgement emoji on the specific message we replied to.
+        await discord
+            .setReaction(channelId, messageId, '')
+            .catch(err => log.warn({ err: errMsg(err) }, 'discord clear-reaction failed'));
+        return ok('sent');
+    });
+    server.registerTool('discord-react', {
+        description: "Set or clear an emoji reaction on a Discord message. Pass '' to clear.",
+        inputSchema: { channelId, messageId, emoji: z.string() },
+    }, async ({ channelId, messageId, emoji }) => {
+        await discordReady;
+        await discord.setReaction(channelId, messageId, emoji);
+        return ok(emoji ? 'reacted' : 'cleared');
+    });
+    server.registerTool('discord-edit-message', {
+        description: 'Edit a Discord message the bot previously sent.',
+        inputSchema: { channelId, messageId, text: z.string() },
+    }, async ({ channelId, messageId, text }) => {
+        await discordReady;
+        await discord.editMessage(channelId, messageId, text);
+        return ok('edited');
+    });
+    server.registerTool('discord-download-attachment', {
+        description: 'Download image attachments as image content blocks. Non-images are skipped.',
+        inputSchema: { channelId, messageId },
+    }, async ({ channelId, messageId }) => {
+        await discordReady;
+        const atts = await discord.fetchAttachments(channelId, messageId);
+        if (atts.length === 0)
+            return ok('no image attachments on this message');
+        return { content: atts.map(a => ({ type: 'image', data: a.data, mimeType: a.mime })) };
+    });
+    server.registerTool('discord-fetch-messages', {
+        description: 'Fetch recent messages for context — Discord has no search API for bots.',
+        inputSchema: {
+            channelId,
+            limit: z.number().int().min(1).max(100).optional().describe('1–100, default 10.'),
+        },
+    }, async ({ channelId, limit }) => {
+        await discordReady;
+        const msgs = await discord.fetchRecentMessages(channelId, limit ?? 10);
+        const text = msgs
+            .map(m => `[message_id=${m.message_id} ${m.timestamp}] ${m.author}: ${m.text}`)
+            .join('\n');
+        return ok(text || '(channel is empty)');
+    });
+}
+await server.server.connect(new StdioServerTransport());
+process.stdin.on('end', () => process.exit(0)).on('close', () => process.exit(0));

package/dist/tail.js

@@ -0,0 +1,131 @@
+// Standalone inbound stream. Polls Telegram + connects to Discord, prints
+// one JSON line per inbound message on stdout. Designed to be launched by
+// an agent and observed via Bash+Monitor (Claude Code) or unified_exec
+// polling (Codex).
+//
+// On every inbound: fires a 👀 reaction and starts a typing indicator that
+// refreshes until the agent replies (signaled by server.ts touching
+// .typing-stop/<key>) or the 60s safety cap is hit.
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as discord from './channels/discord.js';
+import * as telegram from './channels/telegram.js';
+import { tg } from './channels/telegram.js';
+import { configuredPlatforms, loadMetroEnv, STATE_DIR, requireConfiguredPlatform } from './config.js';
+import { errMsg, log } from './log.js';
+loadMetroEnv();
+const platforms = configuredPlatforms();
+requireConfiguredPlatform(platforms);
+// Telegram allows only one getUpdates poller per bot token. If another
+// tail.ts is already running, exit cleanly instead of fighting (409 spam).
+// Stale lockfiles (PID dead) are reclaimed.
+const LOCK_FILE = join(STATE_DIR, '.tail-lock');
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+if (existsSync(LOCK_FILE)) {
+    const pid = Number(readFileSync(LOCK_FILE, 'utf8').trim());
+    if (Number.isInteger(pid) && pid > 0 && processIsAlive(pid)) {
+        log.info({ pid }, 'another tail.ts is already polling; exiting');
+        process.exit(0);
+    }
+    try {
+        unlinkSync(LOCK_FILE);
+    }
+    catch { }
+}
+writeFileSync(LOCK_FILE, String(process.pid));
+function releaseLock() {
+    try {
+        if (existsSync(LOCK_FILE) && readFileSync(LOCK_FILE, 'utf8').trim() === String(process.pid)) {
+            unlinkSync(LOCK_FILE);
+        }
+    }
+    catch { }
+}
+process.on('exit', releaseLock);
+const TYPING_DIR = join(STATE_DIR, '.typing-stop');
+const TYPING_REFRESH_MS = 4_000;
+const TYPING_MAX_MS = 60_000;
+mkdirSync(TYPING_DIR, { recursive: true });
+const emit = (line) => process.stdout.write(`${JSON.stringify(line)}\n`);
+const typingActive = new Map();
+const typingKey = (platform, chat) => `${platform}_${chat}`;
+function fireTyping(platform, chat) {
+    if (platform === 'telegram') {
+        void tg('sendChatAction', { chat_id: chat, action: 'typing' }).catch(err => log.warn({ err: errMsg(err) }, 'telegram typing failed'));
+    }
+    else {
+        void discord.sendTyping(chat).catch(err => log.warn({ err: errMsg(err) }, 'discord typing failed'));
+    }
+}
+function startTyping(platform, chat) {
+    const k = typingKey(platform, chat);
+    typingActive.set(k, { platform, chat, started: Date.now() });
+    // Clear any stale stop signal so the new typing actually fires.
+    const stopFile = join(TYPING_DIR, k);
+    if (existsSync(stopFile)) {
+        try {
+            unlinkSync(stopFile);
+        }
+        catch { }
+    }
+    fireTyping(platform, chat);
+}
+setInterval(() => {
+    const now = Date.now();
+    for (const [k, e] of typingActive) {
+        const stopFile = join(TYPING_DIR, k);
+        if (existsSync(stopFile)) {
+            try {
+                unlinkSync(stopFile);
+            }
+            catch { }
+            typingActive.delete(k);
+            continue;
+        }
+        if (now - e.started > TYPING_MAX_MS) {
+            typingActive.delete(k);
+            continue;
+        }
+        fireTyping(e.platform, e.chat);
+    }
+}, TYPING_REFRESH_MS);
+if (platforms.telegram) {
+    const me = await telegram.getMe();
+    log.info({ bot: `@${me.username}` }, 'telegram ready');
+    telegram.onInbound(m => {
+        void tg('setMessageReaction', {
+            chat_id: m.chat_id,
+            message_id: m.message_id,
+            reaction: [{ type: 'emoji', emoji: '👀' }],
+        }).catch(err => log.warn({ err: errMsg(err) }, 'telegram auto-react failed'));
+        startTyping('telegram', String(m.chat_id));
+        emit({ platform: 'telegram', chat_id: String(m.chat_id), message_id: m.message_id, text: m.text });
+    });
+    void telegram.startPolling();
+}
+if (platforms.discord) {
+    await discord.startGateway();
+    const me = await discord.getMe();
+    log.info({ bot: me.username }, 'discord ready');
+    discord.onInbound(m => {
+        void discord
+            .setReaction(m.channel_id, m.message_id, '👀')
+            .catch(err => log.warn({ err: errMsg(err) }, 'discord auto-react failed'));
+        startTyping('discord', m.channel_id);
+        emit({ platform: 'discord', channel_id: m.channel_id, message_id: m.message_id, text: m.text });
+    });
+}
+// process.on('exit', releaseLock) above runs whenever process.exit is called.
+const exit = () => process.exit(0);
+process.stdin.on('end', exit);
+process.stdin.on('close', exit);
+process.on('SIGINT', exit);
+process.on('SIGTERM', exit);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@stage-labs/metro",
+  "version": "0.1.0-beta.0",
+  "description": "Chat with your Claude Code or Codex agent over Telegram and Discord. Ultra-lightweight: ~700 lines of TypeScript, one stdio MCP, no hosted infra.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bonustrack/metro.git"
+  },
+  "homepage": "https://github.com/bonustrack/metro#readme",
+  "bugs": "https://github.com/bonustrack/metro/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "metro": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "discord.js": "^14.14.0",
+    "pino": "^9.5.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "eslint": "^10.3.0",
+    "typescript": "^5",
+    "typescript-eslint": "^8.59.2"
+  },
+  "packageManager": "bun@1.3.9"
+}