@stage-labs/metro 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/stations/telegram.js

@@ -0,0 +1,213 @@
+/** 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;
+    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() {
+        return tg('getMe', {});
+    }
+    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 text = [m.text ?? m.caption, ...attachmentTags(m)].filter(Boolean).join(' ');
+        if (!text)
+            return;
+        const topicId = m.is_topic_message ? m.message_thread_id : undefined;
+        const fromName = m.from?.username ? `@${m.from.username}` : m.from?.first_name;
+        log.info({ from: fromName, 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: Line.user('telegram', m.from?.id ?? 'unknown'), fromName, text, payload: m,
+        });
+    }
+}

package/dist/stations/webhook.js

@@ -0,0 +1,99 @@
+/** Receive-only HTTP station. Each registered endpoint = one path `/wh/<id>` → InboundMessage on stdout. */
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { errMsg, log } from '../log.js';
+import { mintId } from '../history.js';
+import { findEndpoint, listEndpoints, webhookPort } from '../webhooks.js';
+import { Line } from './index.js';
+/** Synthesize an `event` tag from common provider-specific headers (GitHub, Intercom). */
+function pickEvent(headers) {
+    return headers['x-github-event'] ?? headers['x-intercom-topic'] ?? 'event';
+}
+/** Constant-time signature check against `X-Hub-Signature-256: sha256=<hex>` (GitHub/Intercom style). */
+function verifySig(secret, raw, header) {
+    if (!header?.startsWith('sha256='))
+        return false;
+    const given = Buffer.from(header.slice(7), 'hex');
+    const want = createHmac('sha256', secret).update(raw).digest();
+    return given.length === want.length && timingSafeEqual(given, want);
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    return Buffer.concat(chunks);
+}
+export class WebhookStation {
+    name = 'webhook';
+    server = null;
+    handler = null;
+    onMessage(h) { this.handler = h; }
+    start() {
+        const port = webhookPort();
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => this.handle(req, res).catch(err => {
+                log.warn({ err: errMsg(err) }, 'webhook handler error');
+                if (!res.headersSent)
+                    res.writeHead(500).end();
+            }));
+            this.server.on('error', reject);
+            this.server.listen(port, '127.0.0.1', () => {
+                log.info({ port, endpoints: listEndpoints().length }, 'webhook station ready');
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        const srv = this.server;
+        if (!srv)
+            return;
+        await new Promise(resolve => srv.close(() => resolve()));
+        this.server = null;
+    }
+    async handle(req, res) {
+        const m = req.url?.match(/^\/wh\/([A-Za-z0-9_-]+)/);
+        if (!m) {
+            res.writeHead(404).end();
+            return;
+        }
+        const endpointId = m[1];
+        const endpoint = findEndpoint(endpointId);
+        if (!endpoint) {
+            res.writeHead(404).end();
+            return;
+        }
+        if (req.method === 'GET') {
+            res.writeHead(200).end(`metro webhook ${endpointId} ready\n`);
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(405).end();
+            return;
+        }
+        const raw = await readBody(req);
+        const headers = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(',') : v ?? '']));
+        if (endpoint.secret && !verifySig(endpoint.secret, raw, headers['x-hub-signature-256'])) {
+            log.warn({ endpoint: endpointId }, 'webhook signature mismatch — rejecting');
+            res.writeHead(401).end('signature mismatch');
+            return;
+        }
+        let body = raw.toString('utf8');
+        try {
+            body = JSON.parse(body);
+        }
+        catch { /* keep as string */ }
+        const line = Line.webhook(endpointId);
+        this.handler?.({
+            id: mintId(),
+            ts: new Date().toISOString(),
+            station: 'webhook',
+            line,
+            lineName: endpoint.label,
+            from: line,
+            messageId: headers['x-github-delivery'] || headers['x-request-id'] || randomUUID(),
+            text: `${pickEvent(headers)} ${req.method} ${req.url}`,
+            payload: { headers, body },
+        });
+        res.writeHead(200).end('ok');
+    }
+}

package/dist/tunnel.js

@@ -0,0 +1,64 @@
+/** Cloudflared tunnel manager. Prefers token-from-env so a missing local credentials JSON does not block startup. */
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATE_DIR } from './paths.js';
+import { errMsg, log } from './log.js';
+const FILE = join(STATE_DIR, 'tunnel.json');
+const RESTART_DELAY_MS = 2_000;
+export const loadTunnelConfig = () => existsSync(FILE)
+    ? JSON.parse(readFileSync(FILE, 'utf8'))
+    : null;
+export function saveTunnelConfig(c) { writeFileSync(FILE, JSON.stringify(c, null, 2)); }
+/** Fetch the tunnel's auth token. Null when CLI is unavailable, not logged in, or no such tunnel. */
+function fetchTunnelToken(name) {
+    const r = spawnSync('cloudflared', ['tunnel', 'token', name], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    const token = r.stdout.trim();
+    return token.length > 0 ? token : null;
+}
+export class Tunnel {
+    cfg;
+    port;
+    child = null;
+    closed = false;
+    /** `undefined` = unresolved; `null` = resolved but unavailable (CLI missing / not logged in / no tunnel). */
+    token = undefined;
+    constructor(cfg, port) {
+        this.cfg = cfg;
+        this.port = port;
+    }
+    get hostname() { return this.cfg.hostname; }
+    start() {
+        if (this.closed)
+            return;
+        if (this.token === undefined)
+            this.token = fetchTunnelToken(this.cfg.name);
+        const mode = this.token ? 'token' : 'named';
+        log.info({ name: this.cfg.name, hostname: this.cfg.hostname, port: this.port, mode }, 'cloudflared tunnel starting');
+        /** `--no-autoupdate` is a global cloudflared flag — must come before the `tunnel` subcommand. */
+        const args = ['--no-autoupdate', 'tunnel', 'run', '--url', `http://127.0.0.1:${this.port}`];
+        /** Token form resolves the tunnel from TUNNEL_TOKEN so the trailing name arg must be omitted. */
+        if (!this.token)
+            args.push(this.cfg.name);
+        const env = this.token
+            ? { ...process.env, TUNNEL_TOKEN: this.token }
+            : process.env;
+        this.child = spawn('cloudflared', args, { stdio: ['ignore', 'pipe', 'pipe'], env });
+        this.child.stderr?.on('data', d => log.debug({ cloudflared: d.toString().trim() }, 'cloudflared'));
+        this.child.on('exit', code => {
+            this.child = null;
+            if (this.closed)
+                return;
+            log.warn({ code }, 'cloudflared exited; restarting');
+            setTimeout(() => this.start(), RESTART_DELAY_MS);
+        });
+        this.child.on('error', err => log.warn({ err: errMsg(err) }, 'cloudflared spawn error'));
+    }
+    stop() {
+        this.closed = true;
+        this.child?.kill();
+        this.child = null;
+    }
+}

package/dist/webhooks.js

@@ -0,0 +1,41 @@
+/** Webhook endpoint registry: persists `(id, label, secret?)` for each receive endpoint. */
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATE_DIR } from './paths.js';
+const FILE = join(STATE_DIR, 'webhooks.json');
+/** Local listener port — `127.0.0.1` only; expose publicly via Cloudflare tunnel. */
+export const webhookPort = () => Number(process.env.METRO_WEBHOOK_PORT) || 8420;
+function read() {
+    if (!existsSync(FILE))
+        return { endpoints: [] };
+    try {
+        return JSON.parse(readFileSync(FILE, 'utf8'));
+    }
+    catch {
+        return { endpoints: [] };
+    }
+}
+function write(s) { writeFileSync(FILE, JSON.stringify(s, null, 2)); }
+export const listEndpoints = () => read().endpoints;
+export const findEndpoint = (id) => read().endpoints.find(e => e.id === id);
+export function addEndpoint(label, secret) {
+    const s = read();
+    /** 16-char URL-safe id (~96 bits — collision-proof for any reasonable count). */
+    const ep = {
+        id: randomBytes(12).toString('base64url'), label, createdAt: new Date().toISOString(),
+        ...(secret ? { secret } : {}),
+    };
+    s.endpoints.push(ep);
+    write(s);
+    return ep;
+}
+export function removeEndpoint(id) {
+    const s = read();
+    const before = s.endpoints.length;
+    s.endpoints = s.endpoints.filter(e => e.id !== id);
+    if (s.endpoints.length === before)
+        return false;
+    write(s);
+    return true;
+}

package/docs/agents.md

@@ -0,0 +1,224 @@
+# Metro: a guide for coding agents
+
+You are running inside a session that has **launched `metro`** in the background. Metro emits a live stream of JSON events from Discord, Telegram, third-party webhooks (GitHub, Intercom, …), and other agents on its stdout. Your job is to consume that stream and post replies back via subcommands.
+
+## Starting the bridge
+
+The launch mechanics differ by runtime — pick the one that matches yours.
+
+### Claude Code
+
+```
+Bash(command: "metro", run_in_background: true)
+```
+
+Then attach `Monitor` to its stdout. Each line is one JSON event you act on.
+
+### Codex
+
+```
+shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)
+```
+
+Don't watch its stdout — Codex has no Monitor equivalent. Metro pushes each event into your thread via JSON-RPC `turn/start`, so events arrive as user input on your next turn. The user must have a daemon and TUI running for this to work:
+
+```
+codex app-server --listen ws://127.0.0.1:8421       # daemon (terminal 1)
+codex --remote ws://127.0.0.1:8421                  # TUI (this session — terminal 2)
+```
+
+Run `metro doctor` if anything seems off.
+
+## Event shape
+
+Every event is a **history entry** — the same record that's appended to `history.jsonl`. Fields: `kind` (`inbound`/`notification`/`outbound`/`edit`/`react`), `id` (`msg_…`), `ts`, `station`, `line` (conversation), `lineName?`, `from` (participant URI), `fromName?`, `to`, `text`, `messageId?` (platform-side id; inbound/outbound only), `payload?` (raw platform message; inbound only).
+
+```json
+{"kind":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","lineName":"infra","from":"metro://telegram/user/12345","fromName":"@alice","to":"metro://claude/user/9bfc7af0-…","messageId":"4567","text":"hello [image]","payload":{"message_id":4567,"chat":{"id":-100,"type":"supergroup","is_forum":true},"from":{"id":12345,"username":"alice"},"text":"hello","entities":[{"type":"mention","offset":0,"length":6}],"photo":[{"file_id":"…"}],"reply_to_message":{"message_id":4500,"text":"earlier","from":{"id":99,"username":"bob"}}}}
+```
+
+```json
+{"kind":"notification","id":"msg_pQ4r5sT0","ts":"…","station":"claude","line":"metro://claude/9bfc7af0-…/50b00d11-…","from":"metro://codex/user/8119ecb1-…","to":"metro://claude/9bfc7af0-…/50b00d11-…","text":"deploy succeeded"}
+```
+
+### `payload` by station
+
+`payload` is the platform's native message shape. Narrow on `event.station`:
+
+- **`discord`** — discord.js `Message.toJSON()`: camelCase fields (`channelId`, `guildId`, `content`, `author`, `mentions: { users[], roles[], everyone }`, `attachments[]`, `reference`, …). Collections come back as **arrays of IDs**. `referencedMessage` (also `toJSON()`-shaped) is added inline on replies (auto-fetched).
+- **`telegram`** — raw Bot API `Message` (snake_case): `{ message_id, chat, from, text, caption, entities[], photo[], document, voice, audio, reply_to_message, … }`. `reply_to_message` is inline on replies.
+- **`webhook`** — `{ headers: Record<string,string>, body: <parsed JSON | raw string> }`. Narrow further on the provider — GitHub sets `headers['x-github-event']` (`push`, `pull_request`, `issues`, …) and includes a `repository`/`sender` in body; Intercom sets `x-intercom-topic` etc. `text` is a short summary; full event is always in `payload.body`.
+
+Use `payload` for anything the envelope doesn't surface — mentions, reply chains, embeds, stickers, entities.
+
+Both `from` and `to` are **participant URIs** (the conversation lives in `line`): `metro://<station>/user/<id>` for a person, `metro://claude/user/<orgId>` for a Claude Code agent (orgId = stable Anthropic-account UUID), `metro://codex/user/<accountId>` for a Codex agent (accountId = stable ChatGPT-account UUID), `metro://<station>/<channelId>` as a fallback `to` when sending to a group with no single recipient.
+
+When **you** call `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from` to your runtime — `metro://claude/user/<orgId>` (when `$CLAUDECODE` is set; orgId comes from `claude auth status --json`) or `metro://codex/user/<accountId>` (when `$METRO_CODEX_RC`/`$CODEX_HOME` is set; accountId comes from `$CODEX_HOME/auth.json`, `tokens.account_id`). Both identities are account-scoped, not install-scoped: switch accounts with `claude auth login` / `codex login` and the next event uses the new id (within ~5 s for the daemon, immediately for one-shot CLI calls). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is auto-set to the original sender (history lookup).
+
+- `kind: "inbound"` — a human (or another bot) posted on a chat platform **or a third-party service POSTed to a registered webhook endpoint** (`station: "webhook"`, `payload: { headers, body }`).
+- `kind: "notification"` — another agent called `metro send` against your agent line. This is how Codex pings Claude Code and vice versa.
+
+`text` may include `[image]` / `[voice]` / `[audio]` / `[file: <name>]` placeholders alongside the real text — non-image attachments are opaque markers, images can be materialized via `metro download`.
+
+## Required flow on every event
+
+1. **Echo `event.display` verbatim as your first chat output.** Every event ships a pre-rendered chat-bubble in `event.display` — bold header (icon + station + sender) and a markdown blockquote body. Paste it as-is before any commentary or tool calls. Monitor's notification chip is a CLI-only UI and won't surface visibly in VSCode/Cursor, so the agent's own echo is the only cross-surface signal:
+
+   ```
+   **📩 telegram · @bonustrack**
+   > Hey
+   ```
+
+   The format is centralized in metro's dispatcher (`formatDisplay()` in `src/history.ts`) — don't compose your own.
+
+2. **Decide and act** using the subcommands below.
+
+## Detecting "is this for me?"
+
+Derive from `payload`. Bot id per station is in `$METRO_STATE_DIR/bot-ids.json` (`{discord:"<userId>", telegram:"<userId>"}`).
+
+- **`discord`** — DM if `payload.guildId == null`; otherwise pinged if `payload.mentions.users.includes(<bot-id>)`.
+- **`telegram`** — DM if `payload.chat.type === 'private'`; otherwise pinged if any entity in `payload.entities` (or `caption_entities`) is `{type:"mention"}` matching `@<bot-username>`, or `{type:"text_mention", user:{id:<bot-id>}}`.
+- **`webhook`** — every POST is for you (you registered the endpoint). Route on `payload.headers['x-github-event']` / `x-intercom-topic` etc. to know which provider event it is.
+
+Default for chat: only reply on DM or ping; otherwise stay silent or `metro react` to ack. Webhooks just consume — no ack mechanism.
+
+## Subcommands
+
+| Action | Command |
+|---|---|
+| Quote-reply (threads under original) | `metro reply <line> <messageId> <text>` |
+| Send a fresh message (no reply context) | `metro send <line> <text>` |
+| Edit a message you previously sent | `metro edit <line> <messageId> <text>` |
+| Reaction (empty emoji clears it) | `metro react <line> <messageId> <emoji>` |
+| Download `[image]` attachments | `metro download <line> <messageId> [--out=<dir>]` |
+| Recent-message lookback (Discord only) | `metro fetch <line> [--limit=20]` |
+| Cross-agent ping | `metro send <agent-line> <text> [--from=<line>]` |
+| Register webhook endpoint | `metro webhook add <label> [--secret=<hmac-secret>]` |
+| List / remove webhook endpoints | `metro webhook list` · `metro webhook remove <id>` |
+| Configure Cloudflare named tunnel | `metro tunnel setup <tunnel-name> <hostname>` |
+
+`reply` / `send` / `edit` accept multi-line text via stdin (heredoc). Webhooks are receive-only — there's no `reply` for them, just consume the event.
+
+### Rich content flags
+
+`send` and `reply` accept these flags; `edit` accepts `--buttons` only.
+
+- `--image=<path>` — local image. **Repeatable** for albums: `--image=a.png --image=b.png` (or comma-separated). Up to 10 / message. Text becomes the caption (on the first image for albums).
+- `--document=<path>` — local file (PDF, log, csv, …). Same repeat/comma syntax.
+- `--voice=<path>` — single voice message (`.ogg` Opus or `.mp3`). On Telegram renders as a voice bubble; on Discord uploaded as audio attachment.
+- `--buttons='[[{"text":"…","url":"…"}]]'` — inline URL-button keyboard (2D rows × buttons). Pass `'[]'` to `edit` to clear.
+
+```bash
+metro send <line> "screenshot" --image=/tmp/build.png
+metro send <line> "before/after" --image=/tmp/before.png --image=/tmp/after.png
+metro reply <line> <id> "voice note" --voice=/tmp/note.ogg
+metro send <line> "approve?" --buttons='[[{"text":"Open PR","url":"https://github.com/x/y/pull/1"}]]'
+```
+
+Limits: 20 MB / file. Telegram albums are single-type (photos OR documents per album); mixing kinds still works — metro splits into two messages. Buttons are dropped on multi-attachment Telegram sends. URL buttons only for now.
+
+Append `--json` to any command for a single JSON line you can parse.
+
+## When to use `reply` vs `send`
+
+- **`reply`** — responding to a specific inbound message. Threads under it. Default when handling an `inbound` event.
+- **`send`** — initiating without a triggering message: a long task you kicked off finished, a follow-up the user asked you to deliver later, or posting to an agent line (`metro://claude/...`, `metro://codex/...`) to notify a peer.
+
+## Universal message IDs
+
+The `id` field on every event and `metro history` row is metro's **universal ID** (`msg_<8 chars>`). It works anywhere a `<message_id>` is expected — `metro reply`, `edit`, `react`, `download` — and resolves to the platform's own id via the history file. Use it for chaining commands or referring back across stations.
+
+## `metro history` — read the universal message log
+
+Every inbound, outbound, edit, react, and notification is appended to `$METRO_STATE_DIR/history.jsonl` automatically.
+
+```bash
+metro history --limit=20                              # recent 20, newest first
+metro history --line=metro://discord/123              # only this conversation
+metro history --kind=inbound --since=2026-05-14       # inbounds since that day
+metro history --station=telegram --text=deploy        # all Telegram entries containing "deploy"
+metro history --from='@alice' --json                  # everything from alice, JSON
+```
+
+Filters: `--limit` (default 50), `--line`, `--station`, `--kind` (`inbound`/`outbound`/`edit`/`react`/`notification`), `--from`, `--text`, `--since` (ISO), `--json`.
+
+## Discovery
+
+### `metro lines`
+
+```
+$ metro lines
+2m ago    metro://discord/1234567890           infra
+5m ago    metro://telegram/-100123/42          design-review
+```
+
+Lines sorted by recency. Use when the user says "the Telegram channel" or "that PR thread."
+
+### `metro stations`
+
+```
+$ metro stations
+  ✓ discord    chat     in: text+image · out: text · features: reply, send, edit, react, download, fetch
+        DISCORD_BOT_TOKEN
+  ✓ telegram   chat     in: text+image · out: text · features: reply, send, edit, react, download, fetch
+        TELEGRAM_BOT_TOKEN
+  ✓ claude     agent    in: text · out: text · features: send, notify
+        account: 9bfc7af0-… · seen 1 agent, 2 sessions
+          seen: 9bfc7af0-… · sessions: 2
+  ✗ codex      agent    in: text · out: text · features: send, notify
+        set METRO_CODEX_RC=ws://… to push
+  ✓ webhook    service  in: text · out: – · features: –
+        2 endpoints · base https://webhook.example.com
+```
+
+`✓` = ready (env/runtime detected), `✗` = configured-but-broken or runtime not detected, `·` = informational. The detail line under each agent row shows the resolved account id plus the per-agent count of sessions metro has observed — pull addressable agent lines from those.
+
+## Webhooks (receiving HTTP events)
+
+When the user wants metro to receive events from a third-party service (GitHub PRs, Intercom conversations, Fireflies meetings, …):
+
+1. **One-time tunnel setup** (only needed once per machine): `metro tunnel setup <tunnel-name> <hostname>`. Requires `cloudflared` on PATH (`brew install cloudflared`) and a Cloudflare account + domain on Cloudflare DNS. Run `cloudflared tunnel login` first if you haven't.
+2. **Register an endpoint**: `metro webhook add <label> [--secret=<shared-secret>]`. Prints the public URL — paste it into the provider's webhook settings. For GitHub specifically, set **Content type: `application/json`** (form-encoded won't parse into `payload.body`).
+3. **Run the daemon**: `metro`. With at least one endpoint registered, metro auto-binds the HTTP listener (port 8420, override `METRO_WEBHOOK_PORT`) and spawns `cloudflared tunnel run` if `tunnel.json` exists.
+
+Each POST becomes an inbound event:
+
+```json
+{"kind":"inbound","station":"webhook","line":"metro://webhook/<id>","lineName":"github",
+ "from":"metro://webhook/<id>","to":"metro://claude/user/<orgId>",
+ "messageId":"<x-github-delivery>","text":"push POST /wh/<id>",
+ "payload":{"headers":{"x-github-event":"push",…},"body":{"ref":"refs/heads/main",…}}}
+```
+
+`text` is a short summary; the real event lives in `payload.body`. Use `payload.headers['x-github-event']` (or `x-intercom-topic` etc.) to narrow on provider event type. If you set `--secret`, metro verifies `X-Hub-Signature-256` and rejects bad signatures with 401 — agents see only authenticated events.
+
+## Image attachments
+
+When an inbound has an `[image]` tag in `text`:
+
+1. `metro download <line> <messageId>` → prints absolute paths.
+2. `Read` each path with your `Read` tool — the image enters your context as a vision input.
+3. Reply normally via `metro reply`.
+
+## Cross-agent notification
+
+Both agents can post to each other's **agent line** — `metro://claude/<agent-id>/<session-id>` or `metro://codex/<agent-id>/<session-id>`. `<agent-id>` is the peer's stable account id (cross-device); `<session-id>` is one conversation. Discover both by running `metro stations` (which lists every agent + session metro has seen), or by reading `$METRO_STATE_DIR/agent-registry.json` directly. The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer agent sees it as a notification:
+
+```bash
+metro send metro://claude/9bfc7af0-…/50b00d11-… "build green, ready to ship"
+metro send metro://claude/9bfc7af0-…/50b00d11-… "build green" --from=metro://codex/user/8119ecb1-…   # override sender
+```
+
+This requires the metro daemon to be running on the machine. Without a daemon, agent-line sends error with a clear message.
+
+## Don'ts
+
+- ❌ Spawning a second metro daemon — there's one per machine (lockfile-enforced).
+- ❌ `metro send` to a line that isn't in `metro lines` unless the user gave it to you explicitly.
+- ❌ Narrating the tool ("I'll now use metro reply to…"). The tool call is already visible.
+
+## Further reading
+
+- URI scheme: [`uri-scheme.md`](uri-scheme.md)
+- Source: https://github.com/bonustrack/metro