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

package/README.md

@@ -2,7 +2,7 @@
 
 > **A live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session.**
 
-Metro is a small daemon you launch from inside your agent. It connects to Discord and Telegram, emits each inbound as one JSON line on stdout (which Claude Code's `Monitor` consumes natively, and Codex picks up via an app-server WebSocket push), and exposes a tiny CLI — `metro reply`, `metro send`, `metro edit`, `metro react`, `metro download`, `metro fetch`, `metro notify` — for posting back. Cross-agent: any agent can ping any other via `metro send metro://claude/<topic>` and the daemon re-emits it on the stream.
+Metro is a small daemon you launch from inside your agent. It connects to Discord and Telegram, emits each inbound as one JSON line on stdout (which Claude Code's `Monitor` consumes natively, and Codex picks up via an app-server WebSocket push), and exposes a tiny CLI — `metro reply`, `metro send`, `metro edit`, `metro react`, `metro download`, `metro fetch` — for posting back. Cross-agent: any agent can ping any other via `metro send metro://claude/<topic>` and the daemon re-emits it on the stream.
 
 ```
 [Claude Code session]
@@ -10,8 +10,10 @@ Metro is a small daemon you launch from inside your agent. It connects to Discor
 $ metro &                              # backgrounded
 $ Monitor( … metro's stdout … )
 
->>> {"type":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
-     "text":"@bot we got a 5xx spike from /v1/sync. Look?","mentionsBot":true,…}
+>>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
+     "text":"@bot we got a 5xx spike from /v1/sync. Look?",
+     "payload":{"channelId":"123…","guildId":"456…","content":"<@…> we got a 5xx spike…",
+                "mentions":{"users":["<bot-id>"],"roles":[],"everyone":false},…}}
 
   [I'd run git log + read services/sync.ts, then…]
   Bash: metro reply metro://discord/123… 9876 "three deploys in the last 24h…"
@@ -46,7 +48,7 @@ Telegram poller ──┤
                   │
                   ├─▶ metro daemon ───▶ stdout (JSON events; Claude Code's Monitor reads here)
                   │                ───▶ codex-rc WebSocket (Codex turn/start; opt-in)
-                  │                ◀── IPC Unix socket  (metro notify / metro send to agent lines)
+                  │                ◀── IPC Unix socket  (metro send to agent lines)
                   │
 agent CLI calls ──┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
 ```
@@ -54,7 +56,7 @@ agent CLI calls ──┴── REST → Discord / Telegram   (metro reply / sen
 - **Inversion of control.** The agent (Claude Code, Codex) launches `metro`, not the other way around. Metro never spawns an agent process.
 - **Single daemon per machine.** Lockfile at `$METRO_STATE_DIR/.tail-lock` enforces singleton.
 - **Codex push (opt-in).** Set `METRO_CODEX_RC=ws://127.0.0.1:8421` and metro pushes each event via JSON-RPC `turn/start` to the Codex app-server. Codex's TUI must be attached with `--remote` to the same URL.
-- **Cross-agent notification.** `metro send metro://claude/<topic>` or `metro notify metro://codex/<topic>` routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer agent sees it.
+- **Cross-agent notification.** `metro send metro://claude/<topic>` (or `metro://codex/<topic>`) routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer agent sees it.
 
 ---
 
@@ -115,7 +117,6 @@ metro react <line> <message_id> <emoji>     Set or clear ('') a reaction.
 metro download <line> <message_id> [--out=<dir>]
                                             Download image attachments to disk.
 metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
-metro notify <line> <text> [--from=<line>]  Emit a notification on the daemon's stream.
 metro history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
                                             Universal message log (every inbound + outbound), newest first.
 metro update                                Upgrade in place.

package/dist/cache.js

@@ -48,9 +48,16 @@ export function noteSeen(line, name) {
 export const listLines = () => Object.entries(read()).map(([line, entry]) => ({ line: line, entry }));
 /** Bot identity cache: `{discord: "<userId>", telegram: "<userId>"}`. Daemon writes after getMe(). */
 const botIdsFile = join(STATE_DIR, 'bot-ids.json');
+const readBotIds = () => {
+    try {
+        return existsSync(botIdsFile) ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
+    }
+    catch {
+        return {};
+    }
+};
 export function saveBotId(station, id) {
-    const cur = existsSync(botIdsFile)
-        ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
+    const cur = readBotIds();
     if (cur[station] === id)
         return;
     cur[station] = id;
@@ -63,12 +70,6 @@ export function saveBotId(station, id) {
 }
 /** Resolve the bot's URI for a station. Returns `metro://<station>/bot/<id>` or the placeholder. */
 export function botLine(station) {
-    try {
-        const ids = existsSync(botIdsFile)
-            ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
-        return ids[station] ? Line.bot(station, ids[station]) : `metro://${station}/bot`;
-    }
-    catch {
-        return `metro://${station}/bot`;
-    }
+    const id = readBotIds()[station];
+    return id ? Line.bot(station, id) : `metro://${station}/bot`;
 }

package/dist/cli/actions.js

@@ -1,4 +1,4 @@
-/** CLI action handlers: send/reply/edit/react/download/fetch/notify + helpers. */
+/** CLI action handlers: send/reply/edit/react/download/fetch + helpers. */
 import { mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -45,34 +45,29 @@ function richOpts(f) {
         opts.buttons = buttons;
     return opts;
 }
-/** Append an outbound action to history.jsonl; pass `to` = the original sender when replying/reacting. */
-function logOutbound(f, kind, line, text, platformMessageId, replyTo, opts, emoji, to) {
+/** Append an outbound action to history.jsonl; `to` = the original sender when replying/reacting. */
+function logOutbound(f, e) {
     const id = mintId();
-    const station = Line.station(line) ?? '?';
     const fromOverride = flagOne(f, 'from');
-    const from = fromOverride ? asLine(fromOverride) : agentSelf();
     appendHistory({
-        id, ts: new Date().toISOString(), kind, station, line, from, to: to ?? line,
-        text, platformMessageId, replyTo, emoji,
-        attachments: [...(opts?.images ?? []), ...(opts?.documents ?? []), ...(opts?.voice ? [opts.voice] : [])],
+        id, ts: new Date().toISOString(), station: Line.station(e.line) ?? '?',
+        from: fromOverride ? asLine(fromOverride) : agentSelf(), to: e.to ?? e.line, ...e,
     });
     return id;
 }
-/** When replying/reacting/editing, the recipient is the original message's sender (if we have it). */
-const recipientFor = (idOrPlatform) => lookupEntry(idOrPlatform)?.from;
 export async function cmdSend(p, f) {
     need(p, 1, 'metro send <line> <text> [--image=<path>]… [--document=<path>]… [--voice=<path>] [--buttons=<json>]');
     loadMetroEnv();
     const text = await resolveText(p, 1), line = asLine(p[0]);
     if (Line.isAgent(line)) {
-        const resp = await ipcCall({ op: 'notify', line, text });
+        const from = flagOne(f, 'from');
+        const resp = await ipcCall({ op: 'notify', line, from, text });
         if (!resp.ok)
             throw new Error(resp.error);
         return emit(f, `notified ${line}`, { ok: true, line, id: null, messageId: null });
     }
-    const opts = richOpts(f);
-    const messageId = await chatStationOf(line).send(line, text, opts);
-    const id = logOutbound(f, 'outbound', line, text, messageId, undefined, opts);
+    const messageId = await chatStationOf(line).send(line, text, richOpts(f));
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId });
     emit(f, `sent ${id} (${messageId}) to ${line}`, { ok: true, line, id, messageId });
 }
 export async function cmdReply(p, f) {
@@ -80,9 +75,8 @@ export async function cmdReply(p, f) {
     loadMetroEnv();
     const [to, replyToArg] = p, text = await resolveText(p, 2), line = asLine(to);
     const replyTo = resolvePlatformId(replyToArg);
-    const opts = richOpts(f);
-    const messageId = await chatStationOf(line).send(line, text, { ...opts, replyTo });
-    const id = logOutbound(f, 'outbound', line, text, messageId, replyToArg, opts, undefined, recipientFor(replyToArg));
+    const messageId = await chatStationOf(line).send(line, text, { ...richOpts(f), replyTo });
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, replyTo: replyToArg, to: lookupEntry(replyToArg)?.from });
     emit(f, `replied ${id} (${messageId}) to ${line}#${replyTo}`, { ok: true, line, id, replyTo: replyToArg, messageId });
 }
 export async function cmdEdit(p, f) {
@@ -93,8 +87,7 @@ export async function cmdEdit(p, f) {
     const buttons = parseButtons(f);
     await chatStationOf(line).edit(line, platformId, text, buttons ? { buttons } : undefined);
     /** Carry forward the original recipient if we have a row for this message. */
-    const original = lookupEntry(msgArg);
-    const id = logOutbound(f, 'edit', line, text, platformId, msgArg, undefined, undefined, original?.to);
+    const id = logOutbound(f, { kind: 'edit', line, text, messageId: platformId, replyTo: msgArg, to: lookupEntry(msgArg)?.to });
     emit(f, `edited ${line}#${platformId} (${id})`, { ok: true, line, id, messageId: platformId });
 }
 export async function cmdReact(p, f) {
@@ -103,7 +96,7 @@ export async function cmdReact(p, f) {
     const [to, msgArg, emoji = ''] = p, line = asLine(to);
     const platformId = resolvePlatformId(msgArg);
     await chatStationOf(line).react(line, platformId, emoji);
-    const id = logOutbound(f, 'react', line, undefined, platformId, undefined, undefined, emoji, recipientFor(msgArg));
+    const id = logOutbound(f, { kind: 'react', line, messageId: platformId, emoji, to: lookupEntry(msgArg)?.from });
     const human = emoji ? `reacted ${emoji} on ${line}#${platformId}` : `cleared reaction on ${line}#${platformId}`;
     emit(f, human, { ok: true, line, id, messageId: platformId, emoji });
 }
@@ -144,13 +137,3 @@ export async function cmdFetch(p, f) {
     for (const m of messages)
         process.stdout.write(`${m.timestamp}  ${m.author}: ${m.text}\n`);
 }
-export async function cmdNotify(p, f) {
-    need(p, 1, 'metro notify <line> <text> [--from=<line>]');
-    loadMetroEnv();
-    const text = await resolveText(p, 1), line = asLine(p[0]);
-    const from = flagOne(f, 'from');
-    const resp = await ipcCall({ op: 'notify', line, from, text });
-    if (!resp.ok)
-        throw new Error(resp.error);
-    emit(f, `notified ${line}`, { ok: true, line });
-}

package/dist/cli/config.js

@@ -10,6 +10,7 @@ import { CONFIG_ENV_FILE, configuredPlatforms, loadMetroEnv, readDotenv, STATE_D
 import { emit, exitErr, isJson, writeJson } from './util.js';
 import { cmdSetupSkill, skillStatus } from './skill.js';
 const TOKEN_KEYS = { telegram: 'TELEGRAM_BOT_TOKEN', discord: 'DISCORD_BOT_TOKEN' };
+const stationFor = (p) => p === 'telegram' ? new TelegramStation() : new DiscordStation();
 const maskToken = (t) => !t ? '' : t.length <= 8 ? '••••' : `${t.slice(0, 6)}…${t.slice(-2)}`;
 /** Apply token across CONFIG_ENV_FILE (always set/cleared) AND cwd/.env (only if it exists). */
 function applyToken(key, value) {
@@ -62,7 +63,7 @@ export async function cmdSetup(p, f) {
         if (!f['no-validate']) {
             process.env[TOKEN_KEYS[sub]] = trimmed;
             try {
-                const me = await (sub === 'telegram' ? new TelegramStation() : new DiscordStation()).getMe();
+                const me = await stationFor(sub).getMe();
                 identity = sub === 'telegram' ? `@${me.username}` : me.username;
             }
             catch (err) {
@@ -103,26 +104,26 @@ function tokenSource(key) {
 export async function cmdDoctor(_, f) {
     loadMetroEnv();
     const cfg = configuredPlatforms();
-    const sources = [['telegram', 'TELEGRAM_BOT_TOKEN'], ['discord', 'DISCORD_BOT_TOKEN']]
-        .filter(([p]) => cfg[p]).map(([p, k]) => `${p}←${tokenSource(k)}`).join(', ');
-    const checks = [{
-            name: 'tokens', ok: cfg.telegram || cfg.discord,
-            detail: cfg.telegram || cfg.discord ? sources
-                : 'no platform configured — run `metro setup telegram|discord <token>`',
-        }];
+    const checks = [];
+    const sources = [];
     for (const p of ['telegram', 'discord']) {
         if (!cfg[p]) {
             checks.push({ name: p, ok: null, detail: 'not configured' });
             continue;
         }
+        sources.push(`${p}←${tokenSource(TOKEN_KEYS[p])}`);
         try {
-            const me = await (p === 'telegram' ? new TelegramStation() : new DiscordStation()).getMe();
+            const me = await stationFor(p).getMe();
             checks.push({ name: p, ok: true, detail: `getMe → ${p === 'telegram' ? '@' : ''}${me.username}` });
         }
         catch (err) {
             checks.push({ name: p, ok: false, detail: errMsg(err) });
         }
     }
+    checks.unshift({
+        name: 'tokens', ok: cfg.telegram || cfg.discord,
+        detail: sources.length ? sources.join(', ') : 'no platform configured — run `metro setup telegram|discord <token>`',
+    });
     const lockFile = join(STATE_DIR, '.tail-lock');
     if (!existsSync(lockFile))
         checks.push({ name: 'dispatcher', ok: null, detail: 'not running' });

package/dist/cli/index.js

@@ -7,7 +7,7 @@ import { fmtCapabilities, listStations } from '../stations/index.js';
 import { loadMetroEnv } from '../paths.js';
 import { readHistory } from '../history.js';
 import { cmdDoctor, cmdSetup, cmdUpdate } from './config.js';
-import { cmdDownload, cmdEdit, cmdFetch, cmdNotify, cmdReact, cmdReply, cmdSend, } from './actions.js';
+import { cmdDownload, cmdEdit, cmdFetch, cmdReact, cmdReply, cmdSend, } from './actions.js';
 import { flagOne, isJson, parseArgs, writeJson, } from './util.js';
 const USAGE = `metro — Telegram + Discord stream for your Claude Code / Codex agent
 
@@ -29,7 +29,6 @@ Usage:
   metro download <line> <message_id> [--out=<dir>]
                                               Download image attachments to disk.
   metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
-  metro notify <line> <text> [--from=<line>]  Emit a notification on the daemon's stream.
   metro history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
                                               Read the universal message log (newest first).
   metro update                                Upgrade in place.
@@ -58,10 +57,8 @@ async function cmdLines(_, f) {
         .sort((a, b) => (b.lastSeenAt ?? '').localeCompare(a.lastSeenAt ?? ''));
     if (isJson(f))
         return writeJson({ lines: rows });
-    if (!rows.length) {
-        process.stdout.write('metro lines\n\n  (none yet — start the dispatcher and send a message)\n\n');
-        return;
-    }
+    if (!rows.length)
+        return void process.stdout.write('metro lines\n\n  (none yet — start the dispatcher and send a message)\n\n');
     const widest = Math.max(...rows.map(r => r.line.length));
     process.stdout.write('metro lines\n\n');
     for (const r of rows) {
@@ -128,7 +125,7 @@ const pad = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s.padEnd(n));
 const COMMANDS = {
     setup: cmdSetup, doctor: cmdDoctor, stations: cmdStations, lines: cmdLines,
     send: cmdSend, reply: cmdReply, edit: cmdEdit, react: cmdReact,
-    download: cmdDownload, fetch: cmdFetch, notify: cmdNotify,
+    download: cmdDownload, fetch: cmdFetch,
     history: cmdHistory, update: cmdUpdate,
 };
 async function main() {

package/dist/dispatcher.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 import pkg from '../package.json' with { type: 'json' };
 import { DiscordStation } from './stations/discord.js';
 import { TelegramStation } from './stations/telegram.js';
-import { asLine } from './stations/index.js';
+import { asLine, Line } from './stations/index.js';
 import { CodexRC } from './codex-rc.js';
 import { startIpcServer, stopIpcServer } from './ipc.js';
 import { agentSelf, appendHistory, mintId } from './history.js';
@@ -34,37 +34,21 @@ const codexRc = process.env.METRO_CODEX_RC ? new CodexRC(process.env.METRO_CODEX
 codexRc?.start();
 const discord = new DiscordStation();
 const telegram = new TelegramStation();
-function emit(event) {
-    const json = JSON.stringify(event);
+function emit(entry) {
+    const json = JSON.stringify(entry);
     process.stdout.write(json + '\n');
     codexRc?.push(json);
-    if ('lineName' in event)
-        noteSeen(event.line, event.lineName);
-    else
-        noteSeen(event.line);
-    if (event.type === 'inbound') {
-        appendHistory({
-            id: event.id, ts: event.ts, kind: 'inbound', station: event.station, line: event.line,
-            from: event.from, fromName: event.fromName, to: agentSelf(), text: event.text,
-            platformMessageId: event.messageId, attachments: event.attachmentNames,
-        });
-    }
-    else if (event.type === 'notification') {
-        appendHistory({
-            id: event.id, ts: event.ts, kind: 'notification',
-            station: event.line.replace(/^metro:\/\/([^/]+)\/.*$/, '$1'),
-            line: event.line, from: event.from ?? agentSelf(),
-            to: event.line, text: event.text,
-        });
-    }
+    noteSeen(entry.line, entry.lineName);
+    appendHistory(entry);
 }
-const onInbound = (m) => emit({ type: 'inbound', ...m, to: agentSelf() });
+const onInbound = (m) => emit({ ...m, kind: 'inbound', to: agentSelf() });
 const ipc = startIpcServer(async (req) => {
     if (req.op === 'notify') {
+        const line = asLine(req.line);
         emit({
-            type: 'notification', id: mintId(), ts: new Date().toISOString(),
-            line: asLine(req.line),
-            from: req.from ? asLine(req.from) : agentSelf(), text: req.text,
+            id: mintId(), ts: new Date().toISOString(), kind: 'notification',
+            station: Line.station(line) ?? '?', line,
+            from: req.from ? asLine(req.from) : agentSelf(), to: line, text: req.text,
         });
         return { ok: true };
     }
@@ -105,8 +89,7 @@ async function shutdown() {
         await telegram.stop().catch(() => { });
     process.exit(0);
 }
-process.stdin.on('end', shutdown);
-process.stdin.on('close', shutdown);
-process.on('SIGINT', shutdown);
-process.on('SIGTERM', shutdown);
+process.stdin.on('end', shutdown).on('close', shutdown);
+for (const sig of ['SIGINT', 'SIGTERM'])
+    process.on(sig, shutdown);
 await main();

package/dist/history.js

@@ -60,15 +60,15 @@ function matches(e, f) {
 /** Find an entry by universal id OR platform message id. */
 export function lookupEntry(id) {
     const entries = readHistory({ limit: 5_000 });
-    return entries.find(e => e.id === id || e.platformMessageId === id);
+    return entries.find(e => e.id === id || e.messageId === id);
 }
 /** Look up the platform messageId for a universal `msg_*` id; returns the input unchanged otherwise. */
 export function resolvePlatformId(id) {
     if (!id.startsWith('msg_'))
         return id;
     const hit = lookupEntry(id);
-    if (hit?.platformMessageId)
-        return hit.platformMessageId;
+    if (hit?.messageId)
+        return hit.messageId;
     throw new Error(`unknown universal id: ${id} (run \`metro history --limit=50\` to see recent ids)`);
 }
 /** Resolve the current agent's identity URI. Precedence: METRO_FROM > runtime env > generic. */

package/dist/ipc.js

@@ -12,7 +12,8 @@ export function startIpcServer(handler) {
         }
         catch { /* ignore */ }
     }
-    const server = createServer(socket => handleConnection(socket, handler));
+    /** allowHalfOpen: any `await` in the handler races Node's auto-end-on-client-FIN, dropping the response. */
+    const server = createServer({ allowHalfOpen: true }, s => handleConnection(s, handler));
     server.on('error', err => log.warn({ err: errMsg(err) }, 'ipc server error'));
     server.listen(SOCKET_PATH, () => log.debug({ path: SOCKET_PATH }, 'ipc socket listening'));
     return server;

package/dist/stations/discord.js

@@ -97,7 +97,7 @@ export class DiscordStation {
     }
     async start() {
         const c = this.getClient();
-        c.on(Events.MessageCreate, m => { void this.handleMessage(m, c); });
+        c.on(Events.MessageCreate, m => { void this.handleMessage(m); });
         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()));
@@ -170,29 +170,31 @@ export class DiscordStation {
             messageId: m.id, author: m.author.username, text: m.content, timestamp: m.timestamp,
         }));
     }
-    async handleMessage(m, c) {
+    async handleMessage(m) {
         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)
+        const tags = [...m.attachments.values()].map(a => a.contentType?.startsWith('image/') ? '[image]'
+            : a.contentType?.startsWith('audio/') ? `[audio: ${a.name}]` : `[file: ${a.name}]`);
+        const text = [m.content.trim(), ...tags].filter(Boolean).join(' ');
+        if (!text)
             return;
-        log.info({ from: m.author.username, bot: c.user?.username, channel: m.channelId, text: text.slice(0, 80) }, 'discord: inbound');
+        log.info({ from: m.author.username, channel: m.channelId, text: text.slice(0, 80) }, 'discord: inbound');
         const lineName = m.channel && 'name' in m.channel
             ? m.channel.name ?? undefined : undefined;
+        const payload = m.toJSON();
+        if (m.reference?.messageId) {
+            try {
+                payload.referencedMessage = (await m.fetchReference()).toJSON();
+            }
+            catch (err) {
+                log.debug({ err: errMsg(err) }, 'discord: fetchReference failed');
+            }
+        }
         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 },
+            messageId: m.id, text, payload,
         });
     }
 }

package/dist/stations/telegram.js

@@ -59,8 +59,6 @@ const CAPS = {
 export class TelegramStation {
     name = 'telegram';
     capabilities = CAPS;
-    botUsername = null;
-    botUserId = null;
     pollOffset = 0;
     pollAbort = null;
     messageHandler = () => { };
@@ -85,10 +83,7 @@ export class TelegramStation {
     }
     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;
+        return tg('getMe', {});
     }
     async send(line, text, opts) {
         const { chatId, topicId } = targetOf(line);
@@ -196,15 +191,12 @@ export class TelegramStation {
         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)
+        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;
-        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');
+        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)
@@ -215,21 +207,7 @@ export class TelegramStation {
             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 },
+            from: Line.user('telegram', m.from?.id ?? 'unknown'), fromName, text, payload: m,
         });
     }
-    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;
-    }
 }

package/docs/agents.md

@@ -31,22 +31,31 @@ Run `metro doctor` if anything seems off.
 
 ## Event shape
 
-Every event carries `id` (`msg_…`), `ts`, `from` (a universal participant URI), `fromName` (display name), `line` (conversation = `to`), and `messageId` (the platform-side id).
+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
-{"type":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","from":"metro://telegram/user/12345","fromName":"@alice","messageId":"4567","text":"hello","attachmentNames":["[image]"],"mentionsBot":true,"meta":{"isPrivate":false,"inForum":true,"isForumTopic":true},"lineName":"infra"}
+{"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/agent","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
-{"type":"notification","id":"msg_pQ4r5sT0","ts":"…","line":"metro://claude/deploys","from":"metro://codex/ci","text":"deploy succeeded"}
+{"kind":"notification","id":"msg_pQ4r5sT0","ts":"…","station":"claude","line":"metro://claude/deploys","from":"metro://codex/ci","to":"metro://claude/deploys","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.
+
+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/<topic>` / `metro://codex/<topic>` for an agent, `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/agent` (from `$CLAUDECODE`) or `metro://codex/agent` (from `$METRO_CODEX_RC`/`$CODEX_HOME`). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is auto-set to the original sender (history lookup).
 
-- `type: "inbound"` — a human (or another bot) posted on a chat platform.
-- `type: "notification"` — another agent called `metro notify`/`metro send` against your agent line. This is how Codex pings Claude Code and vice versa.
+- `kind: "inbound"` — a human (or another bot) posted on a chat platform.
+- `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`.
 
@@ -55,6 +64,15 @@ When **you** call `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from`
 1. **Echo the event** to your visible output: `[<line>#<messageId>] <text>`. Both Monitor and Codex collapse tool output, so this echo is the only thing the user sees without expanding cards.
 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>}}`.
+
+Default: only reply on DM or ping; otherwise stay silent or `metro react` to ack.
+
 ## Subcommands
 
 | Action | Command |
@@ -65,7 +83,7 @@ When **you** call `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from`
 | 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 notify <line> <text> [--from=<line>]` |
+| Cross-agent ping | `metro send <agent-line> <text> [--from=<line>]` |
 
 `reply` / `send` / `edit` accept multi-line text via stdin (heredoc).
 
@@ -150,8 +168,7 @@ Both agents can post to each other's "agent line" — a logical channel under `m
 
 ```bash
 metro send metro://claude/deploys "build green, ready to ship"
-# or equivalently:
-metro notify metro://claude/deploys "build green, ready to ship" --from=metro://codex/ci
+metro send metro://claude/deploys "build green" --from=metro://codex/ci   # override sender
 ```
 
 This requires the metro daemon to be running on the machine. Without a daemon, agent-line sends error with a clear message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.7",
   "description": "Live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session. The agent launches metro; metro emits inbounds on stdout and accepts replies via CLI subcommands.",
   "license": "MIT",
   "repository": {

package/skills/metro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metro
-description: Run the metro Telegram/Discord bridge in this session — launch `metro` in the background, watch its stdout for inbound JSON events, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"type":"inbound","station":...,"line":"metro://...","messageId":...,"text":...}`, or when handling a chat reply/edit/react/send/download/fetch/notify.
+description: Run the metro Telegram/Discord bridge in this session — launch `metro` in the background, watch its stdout for inbound JSON events, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"kind":"inbound","station":...,"line":"metro://...","messageId":...,"text":...}`, or when handling a chat reply/edit/react/send/download/fetch/notify.
 ---
 
 # Metro — running the Telegram & Discord bridge
@@ -40,22 +40,44 @@ If something seems off, run `metro doctor`. Common causes: missing tokens (`metr
 
 ## Event shape
 
-Every line on stdout is one JSON object. Each event carries:
+Every line on stdout is one **history entry** — the same record appended to `history.jsonl`. Fields:
+- `kind` — `"inbound"`, `"notification"`, `"outbound"`, `"edit"`, or `"react"`
 - `id` (`msg_…`) — universal message ID minted by metro
 - `ts` — ISO timestamp
-- `from` — universal **participant URI** of the sender (a Line)
-- `fromName` — optional human-readable display name (`@alice`, `bonustrack_`)
-- `line` — the conversation URI (also the implicit `to`)
-- `messageId` — the platform-side id (Discord snowflake, Telegram int, …)
+- `station` — `"discord"`, `"telegram"`, `"claude"`, `"codex"`
+- `line` — conversation URI; `lineName?` is the channel/topic display name
+- `from` / `fromName?` — sender participant URI + optional display name
+- `to` — recipient participant URI (agent for inbound, line for notification, original sender for replies/reacts)
+- `text` — universal display projection. Includes `[image]`/`[file: …]`/`[voice]`/`[audio]` tags inline.
+- `messageId?` — platform-side id (Discord snowflake, Telegram int). Set on inbound/outbound.
+- `payload?` — raw platform-native message object. Set on inbound only. Shape varies per `station`.
 
 ```json
-{"type":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","from":"metro://telegram/user/12345","fromName":"@alice","messageId":"4567","text":"hi","attachmentNames":["[image]"],"mentionsBot":true,"meta":{"isPrivate":false,"inForum":true,"isForumTopic":true},"lineName":"infra"}
+{"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/agent","messageId":"4567","text":"hi [image]","payload":{"message_id":4567,"chat":{"id":-100,"type":"supergroup","is_forum":true},"from":{"id":12345,"username":"alice"},"text":"hi","photo":[{"file_id":"…"}],"reply_to_message":{"message_id":4500,"text":"earlier","from":{"id":99,"username":"bob"}}}}
 ```
 
 ```json
-{"type":"notification","id":"msg_pQ4r5sT0","ts":"…","line":"metro://claude/deploys","from":"metro://codex/ci","text":"deploy green"}
+{"kind":"notification","id":"msg_pQ4r5sT0","ts":"…","station":"claude","line":"metro://claude/deploys","from":"metro://codex/ci","to":"metro://claude/deploys","text":"deploy green"}
 ```
 
+### `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` 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.
+
+Use `payload` for anything the envelope doesn't surface — mentions, reply chains, embeds, entities.
+
+## Detecting "is this for me?"
+
+Derive from `payload`. Bot id per station is cached in `$METRO_STATE_DIR/bot-ids.json` (`{discord:"<userId>", telegram:"<userId>"}`, written by the daemon on start).
+
+- **discord** — DM when `payload.guildId == null`; otherwise pinged when `payload.mentions.users.includes(<bot-id>)`.
+- **telegram** — DM when `payload.chat.type === 'private'`; otherwise pinged when any entity in `payload.entities` (or `caption_entities`) is `{type:"mention"}` matching `@<bot-username>` or `{type:"text_mention", user:{id:<bot-id>}}`.
+
+Default: only reply on DM or ping; otherwise stay silent or `metro react` to ack.
+
 Both `from` and `to` are **participant URIs** (the conversation context lives in `line`):
 - `metro://<station>/user/<id>` — a person on a chat platform
 - `metro://claude/<topic>` / `metro://codex/<topic>` — an agent
@@ -65,8 +87,8 @@ When **you** send via `metro send`/`reply`/`edit`/`react`, metro auto-stamps `fr
 
 The `id` is the **canonical handle** for that message across all stations — store it if you want to refer back to it later.
 
-- `type: "inbound"` — a human (or another bot) posted on a chat platform.
-- `type: "notification"` — another agent called `metro notify` / `metro send` against your agent line. This is how Codex pings Claude Code and vice versa.
+- `kind: "inbound"` — a human (or another bot) posted on a chat platform.
+- `kind: "notification"` — another agent called `metro send` against your agent line. This is how Codex pings Claude Code and vice versa.
 
 `text` may contain `[image]`, `[voice]`, `[audio]`, or `[file: <name>]` placeholders alongside the real text — non-image attachments are opaque markers; images can be materialized via `metro download`.
 
@@ -89,7 +111,7 @@ All take positional args (no `--to=`/`--text=` flags). Append `--json` to any fo
 | Reaction (empty emoji clears) | `metro react <line> <messageId> <emoji>` |
 | Download `[image]` attachments → paths | `metro download <line> <messageId> [--out=<dir>]` |
 | Recent channel history (Discord only) | `metro fetch <line> [--limit=20]` |
-| Ping another agent (cross-agent line) | `metro send metro://claude/<topic> <text>` or `metro notify <line> <text> [--from=<line>]` |
+| Ping another agent (cross-agent line) | `metro send metro://claude/<topic> <text> [--from=<line>]` |
 
 `reply` / `send` / `edit` accept multi-line text via stdin (heredoc).
 
@@ -153,11 +175,10 @@ Both agents can post to each other's "agent line":
 
 ```bash
 metro send metro://claude/deploys "build green, ready to ship"
-# or
-metro notify metro://codex/ci "build green" --from=metro://claude/deploys
+metro send metro://codex/ci "build green" --from=metro://claude/deploys   # override sender
 ```
 
-The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer agent sees a `{"type":"notification",...}` event. Requires the metro daemon to be running on the machine — agent-line sends error with `metro daemon is not running` otherwise.
+The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer agent sees a `{"kind":"notification",...}` event. Requires the metro daemon to be running on the machine — agent-line sends error with `metro daemon is not running` otherwise.
 
 ## Discoverability