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

package/dist/lib/codex-rc.js

@@ -0,0 +1,274 @@
+// JSON-RPC over WebSocket client for the Codex app-server. By default
+// connects over the Unix domain socket exposed by `codex remote-control`
+// (see paths.DEFAULT_CODEX_SOCKET). On every metro inbound it calls
+// `turn/start`, which lands the JSON line in the agent's history as a
+// user message and wakes the agent — the Codex equivalent of Claude
+// Code's `Monitor`.
+//
+// Wire format: standard JSON-RPC 2.0 over WebSocket. Methods we use:
+//   - initialize      → handshake, declares clientInfo.
+//   - thread/list     → discover existing threads on connect.
+//   - thread/started  → notification; track new threads as they appear.
+//   - turn/started    → notification; mark a turn in flight.
+//   - turn/completed  → notification; drain queued inbounds.
+//   - turn/start      → push a user message and wake the agent.
+//
+// If no thread exists yet, inbounds queue in memory; they fire as soon
+// as a thread is started or learned. If the connection drops, reconnect
+// with linear backoff and replay the queue. Connection failures don't
+// break metro — stdout emit always runs first, so Claude Code Monitor
+// users keep working regardless.
+import { createConnection } from 'node:net';
+import { WebSocket } from 'ws';
+import { errMsg, log } from '../log.js';
+const RECONNECT_DELAY_MS = 2_000;
+const MAX_QUEUE = 100;
+// Backstop: if `turn/completed` never arrives (the daemon doesn't broadcast
+// it to all clients, or we miss it for any reason), unstick after this long.
+// Generous enough that any normal turn finishes well within it.
+const TURN_TIMEOUT_MS = 120_000;
+/**
+ * Accept any of these forms for METRO_CODEX_RC:
+ *   ws://host:port/    TCP WebSocket.
+ *   wss://host/        TCP WebSocket over TLS.
+ *   unix:///abs/path   UDS WebSocket (the default for `codex remote-control`).
+ *   /abs/path          shorthand for unix:///abs/path.
+ */
+export function parseCodexUrl(input) {
+    if (input.startsWith('ws://') || input.startsWith('wss://')) {
+        return { kind: 'tcp', url: input };
+    }
+    if (input.startsWith('unix://')) {
+        return { kind: 'unix', path: input.replace(/^unix:\/+/, '/') };
+    }
+    if (input.startsWith('/')) {
+        return { kind: 'unix', path: input };
+    }
+    throw new Error(`unsupported METRO_CODEX_RC: ${input} (expected ws://…, wss://…, unix://…, or absolute path)`);
+}
+function openSocket(endpoint) {
+    if (endpoint.kind === 'tcp')
+        return new WebSocket(endpoint.url);
+    // UDS WebSocket: ws library upgrades any duplex stream, so we feed it a
+    // unix-socket Net connection via `createConnection`. The `ws://localhost/`
+    // URL is a placeholder — only the framing matters at this point; the
+    // bytes flow over the UDS we just opened.
+    return new WebSocket('ws://localhost/', {
+        createConnection: () => createConnection({ path: endpoint.path }),
+    });
+}
+export class CodexRC {
+    clientVersion;
+    ws = null;
+    nextId = 1;
+    pending = new Map();
+    threadId = null;
+    queue = [];
+    connected = false;
+    connecting = false;
+    turnInFlight = false;
+    turnTimeout = null;
+    closed = false;
+    endpoint;
+    displayUrl;
+    constructor(url, clientVersion) {
+        this.clientVersion = clientVersion;
+        this.endpoint = parseCodexUrl(url);
+        this.displayUrl = url;
+    }
+    start() {
+        void this.connect();
+    }
+    stop() {
+        this.closed = true;
+        this.ws?.close();
+        this.ws = null;
+    }
+    /**
+     * Push an inbound JSON line to the Codex agent. If not yet connected or
+     * no thread is active, queues until ready (FIFO, capped).
+     */
+    push(line) {
+        if (this.queue.length >= MAX_QUEUE) {
+            log.warn({ url: this.displayUrl }, 'codex-rc queue full, dropping oldest inbound');
+            this.queue.shift();
+        }
+        this.queue.push(line);
+        void this.drainQueue();
+    }
+    async connect() {
+        if (this.closed || this.connected || this.connecting)
+            return;
+        this.connecting = true;
+        try {
+            const ws = openSocket(this.endpoint);
+            this.ws = ws;
+            // Register the persistent error handler BEFORE awaiting open — without
+            // it, an error fired during the upgrade (UDS missing, daemon down,
+            // bad URL) is "unhandled" and crashes the process under Bun. The
+            // once('error') below covers the connect-time rejection; this on()
+            // covers later errors and the rare double-emit.
+            ws.on('error', err => log.warn({ err: errMsg(err) }, 'codex-rc websocket error'));
+            await new Promise((resolve, reject) => {
+                ws.once('open', resolve);
+                ws.once('error', err => reject(err));
+            });
+            ws.on('message', data => this.onMessage(data));
+            ws.on('close', () => this.onClose());
+            await this.call('initialize', {
+                clientInfo: { name: 'metro', version: this.clientVersion, title: null },
+            });
+            try {
+                const list = await this.call('thread/list', {});
+                const active = (list.data ?? []).find(t => t.status !== 'archived');
+                if (active)
+                    this.threadId = active.id;
+            }
+            catch (err) {
+                log.warn({ err: errMsg(err) }, 'codex-rc thread/list failed (non-fatal)');
+            }
+            this.connected = true;
+            log.info({ url: this.displayUrl, thread: this.threadId ?? '(none yet)' }, 'codex-rc connected');
+            void this.drainQueue();
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err), url: this.displayUrl }, 'codex-rc connect failed; retrying');
+            this.scheduleReconnect();
+        }
+        finally {
+            this.connecting = false;
+        }
+    }
+    onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err) }, 'codex-rc malformed message');
+            return;
+        }
+        log.debug({ id: msg.id, method: msg.method, hasError: !!msg.error }, 'codex-rc ← message');
+        if (msg.id !== undefined && this.pending.has(msg.id)) {
+            const p = this.pending.get(msg.id);
+            this.pending.delete(msg.id);
+            if (msg.error)
+                p.reject(new Error(msg.error.message ?? 'rpc error'));
+            else
+                p.resolve(msg.result);
+            return;
+        }
+        if (msg.method === 'thread/started') {
+            const params = msg.params;
+            if (params?.thread?.id) {
+                this.threadId = params.thread.id;
+                log.info({ thread: this.threadId }, 'codex-rc thread started');
+                void this.drainQueue();
+            }
+        }
+        else if (msg.method === 'thread/status/changed') {
+            // Codex 0.130 doesn't emit turn/started or turn/completed to a non-
+            // owner connection (the TUI gets them; metro doesn't). Instead the
+            // daemon broadcasts thread/status/changed transitions: status is
+            // either a string (`"idle"` / `"notLoaded"` / `"systemError"`) or an
+            // object (`{"active": {...}}`) per the v2 protocol enum. Treat
+            // anything other than `active` as ready-for-next-turn.
+            const params = msg.params;
+            if (params?.threadId === this.threadId) {
+                const isActive = typeof params.status === 'object' && params.status !== null && 'active' in params.status;
+                log.debug({ thread: this.threadId, isActive, status: params.status }, 'codex-rc thread status changed');
+                if (isActive) {
+                    this.turnInFlight = true;
+                }
+                else {
+                    this.clearTurnTimeout();
+                    this.turnInFlight = false;
+                    void this.drainQueue();
+                }
+            }
+        }
+        else if (msg.method === 'turn/completed') {
+            // Backstop in case some codex version does emit turn lifecycle
+            // notifications on the metro connection.
+            log.debug({ thread: this.threadId, queue: this.queue.length }, 'codex-rc turn/completed; draining');
+            this.clearTurnTimeout();
+            this.turnInFlight = false;
+            void this.drainQueue();
+        }
+        else if (msg.method === 'turn/started') {
+            log.debug({ thread: this.threadId }, 'codex-rc turn/started');
+            this.turnInFlight = true;
+        }
+        else if (msg.method === 'thread/closed' || msg.method === 'thread/archived') {
+            log.warn({ method: msg.method, params: msg.params }, 'codex-rc thread closed/archived; clearing thread reference');
+            this.threadId = null;
+        }
+    }
+    onClose() {
+        if (this.closed)
+            return;
+        this.connected = false;
+        this.ws = null;
+        for (const p of this.pending.values())
+            p.reject(new Error('websocket closed'));
+        this.pending.clear();
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        this.connected = false;
+        setTimeout(() => void this.connect(), RECONNECT_DELAY_MS);
+    }
+    async drainQueue() {
+        if (!this.connected || !this.threadId || this.turnInFlight)
+            return;
+        if (this.queue.length === 0)
+            return;
+        const line = this.queue[0];
+        this.turnInFlight = true;
+        this.armTurnTimeout();
+        log.debug({ thread: this.threadId, queue: this.queue.length }, 'codex-rc → turn/start');
+        try {
+            await this.call('turn/start', {
+                threadId: this.threadId,
+                input: [{ type: 'text', text: line, textElements: [] }],
+            });
+            this.queue.shift();
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err) }, 'codex-rc turn/start failed; will retry');
+            this.clearTurnTimeout();
+            this.turnInFlight = false;
+            setTimeout(() => void this.drainQueue(), 1_000);
+        }
+    }
+    // If `turn/completed` never arrives (the daemon doesn't broadcast it to
+    // metro's connection, or we miss it for any reason), unstick after the
+    // backstop so subsequent inbounds don't queue forever.
+    armTurnTimeout() {
+        this.clearTurnTimeout();
+        this.turnTimeout = setTimeout(() => {
+            log.warn({ thread: this.threadId, queue: this.queue.length }, `codex-rc turn/completed not received within ${TURN_TIMEOUT_MS}ms; force-clearing single-flight gate`);
+            this.turnInFlight = false;
+            this.turnTimeout = null;
+            void this.drainQueue();
+        }, TURN_TIMEOUT_MS);
+    }
+    clearTurnTimeout() {
+        if (this.turnTimeout) {
+            clearTimeout(this.turnTimeout);
+            this.turnTimeout = null;
+        }
+    }
+    call(method, params) {
+        if (!this.ws)
+            return Promise.reject(new Error('not connected'));
+        const id = this.nextId++;
+        const ws = this.ws;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+        });
+    }
+}

package/dist/lib/dotenv.js

@@ -0,0 +1,31 @@
+// Tiny .env reader/writer. Used by `metro setup` (read/write the global
+// config file) and by paths.ts (load env vars into process.env at startup).
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const LINE_RE = /^\s*([A-Za-z_]\w*)\s*=\s*(.*?)\s*$/;
+const QUOTED_RE = /^(['"])(.*)\1$/;
+export function readDotenv(path) {
+    if (!existsSync(path))
+        return {};
+    const out = {};
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        const m = line.match(LINE_RE);
+        if (m)
+            out[m[1]] = m[2].replace(QUOTED_RE, '$2');
+    }
+    return out;
+}
+export function writeDotenv(path, env) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, Object.entries(env).map(([k, v]) => `${k}=${v}`).join('\n') + '\n');
+    chmodSync(path, 0o600);
+}
+// Load .env at `path` into process.env, but only for keys that aren't already
+// set — first definer wins, so callers control precedence by the order they
+// invoke this.
+export function loadDotenvIntoProcess(path) {
+    for (const [k, v] of Object.entries(readDotenv(path))) {
+        if (process.env[k] === undefined)
+            process.env[k] = v;
+    }
+}

package/dist/log.js

@@ -1,5 +1,12 @@
-// Pino → stderr. Stdout is reserved for MCP JSON-RPC; any stray write there
-// breaks the protocol. Override level with METRO_LOG_LEVEL.
+// Pino → stderr. Stdout is reserved for command output (`metro`'s inbound
+// JSON lines, subcommand results, --json) — any stray write there breaks
+// parsing. 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));
+export const errMsg = (err) => {
+    if (err instanceof Error)
+        return err.message;
+    if (err && typeof err === 'object' && 'message' in err)
+        return String(err.message);
+    return String(err);
+};

package/dist/paths.js

@@ -0,0 +1,45 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadDotenvIntoProcess } from './lib/dotenv.js';
+import { log } from './log.js';
+// Lockfile, typing-stop signals, attachment cache. Override with METRO_STATE_DIR.
+export const STATE_DIR = process.env.METRO_STATE_DIR ?? join(homedir(), '.cache', 'metro');
+mkdirSync(STATE_DIR, { recursive: true });
+// Where `metro setup` writes the global .env. Override with METRO_CONFIG_DIR
+// or the standard $XDG_CONFIG_HOME.
+const CONFIG_DIR = process.env.METRO_CONFIG_DIR ??
+    join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'metro');
+export const CONFIG_ENV_FILE = join(CONFIG_DIR, '.env');
+// Default codex app-server WebSocket. The TUI's `--remote <ADDR>` flag
+// only accepts ws:// (no UDS), so this is the canonical URL we recommend
+// users align on across the daemon, the TUI, and metro:
+//   codex app-server --listen ws://127.0.0.1:8421
+//   codex --remote ws://127.0.0.1:8421
+//   METRO_CODEX_RC=ws://127.0.0.1:8421 metro
+// Override via METRO_CODEX_RC if a different port/host is needed.
+export const DEFAULT_CODEX_RC_URL = 'ws://127.0.0.1:8421';
+export function skillDir(runtime, scope) {
+    const base = scope === 'user' ? homedir() : process.cwd();
+    const root = runtime === 'claude-code' ? '.claude' : '.agents';
+    return join(base, root, 'skills', 'metro');
+}
+// Precedence: process.env (already set) > cwd/.env > <CONFIG_DIR>/.env.
+// loadDotenvIntoProcess only fills vars that aren't already populated, so the
+// first call that defines a key wins.
+export function loadMetroEnv() {
+    loadDotenvIntoProcess(join(process.cwd(), '.env'));
+    loadDotenvIntoProcess(CONFIG_ENV_FILE);
+}
+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('no platforms configured — run `metro setup telegram <token>` or `metro setup discord <token>`');
+    process.exit(2);
+}

package/dist/tail.js

@@ -4,21 +4,23 @@
 // polling (Codex).
 //
 // On every inbound: fires a 👀 reaction and starts a typing indicator that
-// refreshes until the agent replies (signaled by server.ts touching
+// refreshes until the agent replies (signaled by `metro reply` 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 pkg from '../package.json' with { type: 'json' };
 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 { CodexRC } from './lib/codex-rc.js';
+import { configuredPlatforms, loadMetroEnv, STATE_DIR, requireConfiguredPlatform } from './paths.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.
+// `metro` instance 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 {
@@ -32,7 +34,7 @@ function processIsAlive(pid) {
 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');
+        log.info({ pid }, 'another `metro` instance is already polling; exiting');
         process.exit(0);
     }
     try {
@@ -54,7 +56,20 @@ 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`);
+// Codex push channel. Set METRO_CODEX_RC to the codex app-server URL
+// (typically `ws://127.0.0.1:8421` matching `codex app-server --listen
+// ws://127.0.0.1:8421`) to inject each inbound into the agent's history
+// via JSON-RPC `turn/start`. Codex's TUI `--remote` flag only accepts
+// ws://, so the daemon, the TUI, and metro must all share the same URL.
+// Unset → metro behaves exactly as before; stdout emit always runs first
+// so Claude Code Monitor users are unaffected.
+const codexRC = process.env.METRO_CODEX_RC ? new CodexRC(process.env.METRO_CODEX_RC, pkg.version) : null;
+codexRC?.start();
+const emit = (line) => {
+    const json = JSON.stringify(line);
+    process.stdout.write(`${json}\n`);
+    codexRC?.push(json);
+};
 const typingActive = new Map();
 const typingKey = (platform, chat) => `${platform}_${chat}`;
 function fireTyping(platform, chat) {
@@ -106,8 +121,9 @@ if (platforms.telegram) {
             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 });
+        const chat = String(m.chat_id);
+        startTyping('telegram', chat);
+        emit({ platform: 'telegram', to: `telegram:${chat}/${m.message_id}`, text: m.text });
     });
     void telegram.startPolling();
 }
@@ -120,12 +136,26 @@ if (platforms.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 });
+        emit({ platform: 'discord', to: `discord:${m.channel_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);
+// `process.on('exit', releaseLock)` above runs whenever process.exit is
+// called. We also `await discord.shutdownGateway()` here so the bot flips
+// offline immediately on SIGTERM / SIGINT instead of waiting ~45s for the
+// gateway's missed-heartbeat timeout. SIGKILL bypasses this (nothing we can
+// do); the lockfile auto-reclaims on the next start either way.
+let shuttingDown = false;
+async function shutdown() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    codexRC?.stop();
+    if (platforms.discord) {
+        await discord.shutdownGateway().catch(err => log.warn({ err: errMsg(err) }, 'discord shutdown failed'));
+    }
+    process.exit(0);
+}
+process.stdin.on('end', shutdown);
+process.stdin.on('close', shutdown);
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.1.0-beta.2",
+  "description": "Chat with your Claude Code or Codex agent over Telegram and Discord. Ultra-lightweight: ~1.2K lines of TypeScript, pure CLI, no hosted infra.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -32,13 +33,13 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "discord.js": "^14.14.0",
     "pino": "^9.5.0",
-    "zod": "^3.23.0"
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
     "eslint": "^10.3.0",
     "typescript": "^5",
     "typescript-eslint": "^8.59.2"

package/skills/metro/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: metro
+description: Handle Telegram/Discord messages from `metro` for this agent session. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout or as user input shaped `{"platform":..., "to":..., "text":...}`, or when handling chat reply/react/edit/send/download/fetch.
+---
+
+# Metro — handling the Telegram & Discord bridge
+
+Metro is a CLI bridge between this agent session and Telegram/Discord. Each inbound message arrives as a JSON line; you act on it via `metro <subcommand>`. The launch mechanics differ between Claude Code (you launch metro via shell) and Codex (the user launches metro outside the agent and the daemon pushes turns to you).
+
+## Starting the bridge
+
+When the user asks to run/start/launch metro, you launch it as a backgrounded shell command. The exact invocation depends on the runtime:
+
+### Claude Code
+
+```
+Bash(command: "metro", run_in_background: true)
+```
+
+Then attach `Monitor` to its stdout. Each stdout line is one inbound JSON event you act on directly.
+
+### 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. Instead, metro pushes each inbound 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 the TUI running for this to work — refer them to:
+
+```
+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)
+```
+
+If `metro` exits immediately or the daemon isn't on 8421, ask the user. (`codex remote-control` is stdio-only and doesn't work for this flow.)
+
+### Diagnostics
+
+If something seems off, run `metro doctor`. Common causes: missing tokens (`metro setup telegram <token>` / `metro setup discord <token>`), Discord Message Content Intent not toggled, stale lockfile. On Codex, also: app-server not listening on the expected URL, or the TUI not attached via `--remote`.
+
+## Inbound shape
+
+Each `metro` line on stdout:
+
+```json
+{"platform":"telegram"|"discord","to":"<platform>:<chat>/<message_id>","text":"…"}
+```
+
+`text` may include placeholders for non-text content: `[image]`, `[voice]`, `[audio]`, `[file: <name>]`. Voice/audio are opaque markers — you can't download them.
+
+Discord guild messages preserve the user's raw mention markup, including the bot's own `<@bot_id>` (the gate that made the message visible). Treat the bot's own mention as metadata; other users' mentions (`<@some_other_id>`) can be addressee context. Reply normally — the message is addressed to you regardless of where the mention sits.
+
+## Required flow on every inbound
+
+1. **Echo to the visible reply.** Write `[<to>] <text>` on its own line in your visible output. Both Claude Code's Monitor and Codex dim/collapse tool output, so this echo is the only way the user sees what arrived without expanding cards.
+2. **Decide and act.** Pick the matching subcommand below.
+
+> 👀 is already on the message — `metro` auto-reacts server-side on every inbound and clears the reaction when you reply. Don't call `metro react --emoji=👀` yourself; you'd just flicker it on/off and waste a tool call.
+
+## Subcommands
+
+`reply` / `react` / `edit` / `download` take `--to=<platform>:<chat>/<message_id>` copied verbatim from the inbound `to` field. `send` and `fetch` take a channel-only `--to=<platform>:<chat>` (no message id). Append `--json` to any of them for a single JSON result line you can parse.
+
+| Action | Command |
+|---|---|
+| Quote-reply (threads under original; clears 👀) | `metro reply --to=<to> --text=<reply>` |
+| Quick ack reaction | `metro react --to=<to> --emoji=👍` |
+| Edit your previous bot message | `metro edit --to=<to> --text=<new text>` |
+| Send a proactive message (no reply context) | `metro send --to=<platform>:<chat_id> --text=<msg>` |
+| Download `[image]` attachments → file paths | `metro download --to=<to>` |
+| Fetch recent channel history (Discord only) | `metro fetch --to=discord:<channel_id> --limit=20` |
+
+`reply` / `edit` / `send` accept multi-line `--text` via stdin (heredoc).
+
+## When to use `send` vs `reply`
+
+- **`reply`** — responding to a specific inbound message. Threads under it. This is the default when handling a `metro` inbound line.
+- **`send`** — initiating without a triggering message: a long task you kicked off finished, a scheduled job fired, a follow-up the user asked you to deliver later. The chat/channel id you target must be one the bot can reach (existing DM, joined guild channel).
+
+## Address format
+
+- `telegram:<chat_id>/<message_id>` — copied straight from inbound `to`
+- `discord:<channel_id>/<message_id>` — same
+- `discord:<channel_id>` — channel-only, used for `metro fetch`
+
+## Image attachments
+
+When `text` contains `[image]`:
+
+1. Run `metro download --to=<to>` — writes images to disk and prints absolute paths (one per line).
+2. `Read` each path with the Read tool — the image enters your context as a vision input.
+3. Reply normally with `metro reply`.
+
+## Opaque attachment markers
+
+`[voice]`, `[audio: <name>]`, and `[file: <name>]` are opaque — `metro download` only handles images. Acknowledge in text (e.g., "got your voice note — could you type it out?") or, if your runtime accepts audio/file input directly, ask the user to resend as a regular file.
+
+## Exit codes
+
+- `0` success
+- `1` usage error (bad flags, unknown subcommand)
+- `2` configuration error (no tokens; tell the user to run `metro setup`)
+- `3` upstream error (rate limit, auth, network) — wait a few seconds and retry once before surfacing to the user
+
+If anything's misbehaving, run `metro doctor` to see which check fails.
+
+## --json output
+
+Every action command supports `--json` for stable, parseable output:
+
+```bash
+metro reply --to=… --text=… --json
+# {"ok":true,"platform":"discord","to":"discord:123/456","sent_message_id":"…"}
+
+metro fetch --to=discord:1234 --limit=10 --json
+# [{"message_id":"…","author":"…","text":"…","timestamp":"…"}, …]
+
+metro download --to=… --json
+# {"images":[{"path":"/abs/…png","mime":"image/png"}]}
+```
+
+Use `--json` when you need to chain calls or capture the new message_id for a later edit.

package/dist/config.js

@@ -1,33 +0,0 @@
-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);
-}