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

package/README.md

@@ -1,15 +1,25 @@
 # Metro
 
-Run a long-lived daemon that bridges Discord and Telegram to your Codex + Claude Code agents. Each chat thread/topic gets its own agent session with streaming responses and inline, persistent tool-call traces. Both agents run side-by-side — pick per-message with a `with claude` / `with codex` suffix.
+> **A live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session.**
 
-## Prereqs
+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.
 
-- **Node ≥ 22** (or Bun ≥ 1.3).
-- **One or both agent CLIs** installed and authenticated:
-  - **Claude Code** — run `claude` once interactively to log in. Metro shells out per turn and inherits your auth, plugins, settings.
-  - **Codex** — run `codex` once interactively to log in. Metro spawns `codex app-server` and inherits your auth, MCPs, sandboxing.
-- **Discord bot** (optional) with **Message Content Intent** enabled (Developer Portal → Bot → Privileged Gateway Intents).
-- **Telegram bot** (optional). In supergroup forums, the bot also needs the **Manage Topics** admin permission so it can auto-create topics on @-mention.
+```
+[Claude Code session]
+
+$ 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,…}
+
+  [I'd run git log + read services/sync.ts, then…]
+  Bash: metro reply metro://discord/123… 9876 "three deploys in the last 24h…"
+```
+
+The agent owns its own streaming, tool calls, and reply timing. Metro is the wire.
+
+---
 
 ## Quickstart
 
@@ -18,100 +28,165 @@ npm install -g @stage-labs/metro@beta    # or: bun add -g @stage-labs/metro@beta
 
 metro setup discord <token>              # https://discord.com/developers/applications
 metro setup telegram <token>             # https://t.me/BotFather
-
 metro doctor                             # verify
-metro                                    # run the orchestrator
+metro                                    # run the daemon
 ```
 
-Metro starts both agents at boot and listens on whichever platforms are configured. Each scope defaults to **Claude** for the first turn; once you've used an agent there, follow-up messages stick with it. Switch per-message by suffixing `with claude` or `with codex` (any casing):
+Requires **Node ≥ 22 or Bun ≥ 1.3**. Metro doesn't launch Claude or Codex — you do, and the agent launches metro. See [`docs/agents.md`](docs/agents.md).
 
-```
-@Metro draft a release note
-   → uses Claude (default for a new scope)
+In **Discord**: DM the bot, or `@<bot>` in any channel. In **Telegram**: DM, or `@<bot>` in a forum supergroup. Every inbound becomes one JSON line on `metro`'s stdout.
+
+---
+
+## Architecture
 
-How would Codex have done this? with codex
-   → routes this turn to Codex; stays Codex on subsequent turns
 ```
+Discord gateway ──┐
+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)
+                  │
+agent CLI calls ──┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
+```
+
+- **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.
+
+---
+
+## Stations
+
+Each endpoint is a **station** with declared capabilities:
+
+| Station    | Kind  | Modalities    | Features                                              | Config                                                      |
+|------------|-------|---------------|-------------------------------------------------------|-------------------------------------------------------------|
+| `discord`  | chat  | text + image  | reply, send, edit, react, download, fetch             | `DISCORD_BOT_TOKEN` + Message Content Intent                |
+| `telegram` | chat  | text + image  | reply, send, edit, react, download                    | `TELEGRAM_BOT_TOKEN`                                        |
+| `claude`   | agent | text          | notify                                                | watches metro stdout via Claude Code's `Monitor`            |
+| `codex`    | agent | text          | notify                                                | set `METRO_CODEX_RC=ws://…` to push                         |
 
-### Discord
+Run `metro stations` to see live config status (`✓` configured, `✗` not, `·` informational).
 
-@-mention the bot in any channel:
-1. Metro creates a thread anchored on your message (named after the message).
-2. Spins up an agent session for that thread.
-3. Streams the agent's reply with each tool call as its own block: plain header `🛠 **Read**` followed by two fenced code blocks — input (`src/foo.ts`) above, output (file contents) below. Outputs are capped at 50 lines / 1500 chars per tool with a `_(N more lines)_` note if truncated. `Thinking…` shows as a transient status that vanishes once real content arrives.
+Behaviors worth knowing:
+- **No streaming / no edit machinery in metro.** The agent runs the show; metro is one-shot REST.
+- **No link previews.** Outgoing messages set `link_preview_options.is_disabled` on Telegram and `SUPPRESS_EMBEDS` on Discord.
+- **Image attachments inbound** — `[image]` placeholders surface inline in `text`; the agent calls `metro download` to materialize them. 20 MB cap.
+- **Rich content outbound.** `metro send` / `reply` accept `--image=<path>` (repeatable: albums of up to 10), `--document=<path>` (repeatable), `--voice=<path>` (single voice message — Telegram renders the voice bubble), and `--buttons='[[{"text":"…","url":"…"}]]'` for inline URL-button keyboards. `metro edit` accepts `--buttons` (pass `'[]'` to clear). 20 MB / file. URL buttons only for now — no callback/interactive components.
+- **Telegram non-forum groups are skipped.** No thread boundary to scope on.
 
-Follow-ups in the thread route automatically — no @-mention needed.
+---
 
-### Telegram
+## Lines
 
-- **DM the bot** — every message is implicitly addressed to it; one scope per chat.
-- **@-mention the bot in a forum supergroup's General topic** — metro auto-creates a new topic for the conversation (Discord-style "thread from message") and posts a deep link back in General so the new topic is one tap away. Subsequent messages in that topic route automatically.
-- **Inside an existing custom topic** — routes to that topic's scope on every message.
+Every conversational scope is identified by a **Line** — a URI in the form `metro://<station>/<path>`:
 
-Regular (non-forum) groups are not routed — they have no thread boundary.
+```
+metro://discord/1234567890123456789
+metro://telegram/-1001234567890                 # main chat / DM
+metro://telegram/-1001234567890/42              # forum topic 42
+metro://claude/deploys                          # agent notification sink
+metro://codex/ci
+```
+
+Anyone can post to a line via [`metro send`](#cli) — daemon required only for agent lines. Full grammar in [`docs/uri-scheme.md`](docs/uri-scheme.md).
 
-## How it works
+---
+
+## CLI
 
 ```
-Discord gateway ──┐                       ┌─▶ codex app-server   (long-lived subprocess, UDS JSON-RPC)
-                  ├─▶ metro orchestrator ─┤
-Telegram poller ──┘                       └─▶ claude -p ...      (per-turn subprocess, stream-json)
-                            │
-                            └──── scope map (scopes.json)
+metro                                       Run the daemon (emits JSON events on stdout).
+metro setup [telegram|discord <token>]      Save token, or show status.
+metro setup clear [telegram|discord|all]    Remove tokens.
+metro doctor                                Health check.
+metro stations                              List stations + capabilities.
+metro lines                                 List recently-seen conversations.
+metro send <line> <text> [--image=…]… [--document=…]… [--voice=…] [--buttons=…]
+                                            Post a fresh message; --image/--document repeat for albums.
+metro reply <line> <message_id> <text> [--image|--document|--voice|--buttons]
+                                            Threaded reply (same flags as send).
+metro edit <line> <message_id> <text> [--buttons=<json>]
+                                            Edit a previously-sent message (text + URL-button keyboard).
+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.
 ```
 
-- **One metro = one daemon.** Lockfile at `$METRO_STATE_DIR/.tail-lock` keeps things singleton.
-- **Both agents side-by-side.** A scope can have up to one session per agent — independent histories. Routing is per-message: explicit `with claude` / `with codex` suffix, otherwise the scope's last-used agent, otherwise Claude.
-- **Streaming.** Replies edit one message every ~1500 ms while deltas stream in (leading-edge first flush for fast initial feedback). Long replies split past ~1900 chars onto a follow-up message.
-- **Tool-call visibility.** Each tool call is rendered as a plain `🛠 **<tool>**` header plus two fenced code blocks — input then output — paired by tool id so parallel calls don't collide. Both blocks are fully visible (no collapse). Outputs are capped at 50 lines / 1500 chars per tool.
-- **Telegram formatting.** Agent markdown (`**bold**`, `*italic*`, `` `code` ``, fenced blocks, `[link](url)`, blockquotes) is converted to Telegram's HTML parse mode on the way out, so it renders as formatted text instead of literal characters.
-- **No link previews.** Outgoing messages set `link_preview_options.is_disabled` on Telegram and the `SUPPRESS_EMBEDS` flag on Discord, so URLs in agent replies don't unfurl into giant auto-embeds.
-- **Queueing.** Messages that arrive while a turn is running are buffered per-scope and answered together in the next reply.
-- **Catchup-on-restart.** Discord uses a per-scope `lastSeenMessageId` watermark and REST-fetches anything newer when metro comes back up. Telegram leans on its own update-id queue (persisted offset in `telegram-offset.json`).
+All commands accept `--json`. `reply` / `send` / `edit` read multi-line `<text>` from stdin if no positional is given.
+
+**State files** in `$METRO_STATE_DIR` (default `~/.cache/metro`):
+- `AGENTS.md` — agent skill copied from the package on every start (so the path is stable across upgrades)
+- `history.jsonl` — universal message log (one JSON object per line; append-only). Read with `metro history`. Each entry carries `from` and `to` as universal participant URIs (`metro://<station>/user/<id>`, `metro://claude/<topic>`, `metro://codex/<topic>`) plus a `fromName` display field. The dispatcher auto-detects the consuming agent for `to` on inbound (`$CLAUDECODE` → `metro://claude/agent`; `$METRO_CODEX_RC`/`$CODEX_HOME` → `metro://codex/agent`).
+- `bot-ids.json` — `{discord: "<botUserId>", telegram: "<botUserId>"}` written by the daemon on startup (cached for the few historical lookups that still need a bot identity).
+- `lines.json` — line → last-seen / name cache (read by `metro lines`)
+- `.tail-lock` — dispatcher pid
+- `metro.sock` — daemon IPC socket
+- `telegram-offset.json` — last processed update id
 
-## Config
+---
+
+## Configuration
 
 | Variable | Default | Description |
 |---|---|---|
 | `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN` | — | Bot tokens. `metro setup` writes them here. |
+| `METRO_CODEX_RC` | — | Codex app-server URL (`ws://…`, `wss://…`, `unix:///…`). When set, the daemon pushes each event via JSON-RPC `turn/start`. |
 | `METRO_CONFIG_DIR` | `~/.config/metro` | Where the global `.env` lives. |
-| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, scope cache, codex socket, telegram offset, claude session set. |
+| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, IPC socket, telegram offset. |
 | `METRO_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
 
-Token precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs to stderr.
+Precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs go to stderr.
+
+---
 
-## Develop locally
+## Develop
 
 ```bash
 git clone https://github.com/bonustrack/metro && cd metro
 bun install && bun run build
 bun link                                 # makes `metro` resolve to this checkout
 METRO_LOG_LEVEL=debug metro
+
+bun run typecheck                        # ts
+bun run lint                             # eslint
 ```
 
-## Reference
+Source map:
+
+- [`src/cli/`](src/cli/) — `metro` binary entry ([`index.ts`](src/cli/index.ts)) + admin commands ([`config.ts`](src/cli/config.ts): setup/doctor/update) + shared CLI primitives ([`util.ts`](src/cli/util.ts)).
+- [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: starts each chat station, emits events on stdout, listens on the IPC socket, optionally pushes to codex-rc.
+- [`src/stations/`](src/stations/) — Line URI scheme + ChatStation interface + listing ([`index.ts`](src/stations/index.ts)), the two chat-station impls (`discord.ts`, `telegram.ts`), plus the Telegram markdown→HTML helper ([`telegram-md.ts`](src/stations/telegram-md.ts)). Agent stations have no impl — they're notification sinks expressed only as URI prefixes.
+- [`src/codex-rc.ts`](src/codex-rc.ts) — Codex app-server WebSocket push client.
+- [`src/ipc.ts`](src/ipc.ts) — Unix-socket IPC between the daemon and one-shot CLI commands.
+- [`src/cache.ts`](src/cache.ts) — in-memory line cache with debounced flush to `lines.json`.
+- [`docs/uri-scheme.md`](docs/uri-scheme.md) specs the Line format; [`docs/agents.md`](docs/agents.md) is the in-context skill for agents.
 
-- `metro --help` — command surface
-- `metro doctor` — health check (tokens + gateway/poller reachability + orchestrator status)
-- State files (`$METRO_STATE_DIR`, defaults to `~/.cache/metro/`):
-  - `scopes.json` — Discord-thread / Telegram-topic ↔ agent-session map
-  - `.tail-lock` — orchestrator pid
-  - `codex-app-server.sock` — codex's UDS
-  - `telegram-offset.json` — last processed update id (used for catchup on restart)
-  - `claude-sessions.json` — set of started Claude session uuids (so restarts use `--resume` instead of `--session-id`)
+CI runs typecheck + lint + build on every PR via [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+---
+
+## Caveats
+
+- **No allowlist.** Anyone who can DM/`@`-mention your bot can produce events. Run against bots you own.
+- **Telegram bot privacy is on by default**, which can block `@`-mentions in groups. Disable via [@BotFather](https://t.me/BotFather) → Bot Settings → Group Privacy, then kick + re-invite.
+- **Telegram non-forum groups are skipped.** No thread boundary to scope on. DMs and forum topics work normally.
+- **Telegram fetch isn't supported** (bot API doesn't expose history); `metro fetch` returns `[]` on Telegram lines.
+
+---
 
 ## Uninstall
 
 ```bash
 metro setup clear
-rm -rf ~/.cache/metro/
+rm -rf ~/.cache/metro
 npm uninstall -g @stage-labs/metro
 ```
-
-## Caveats
-
-- **No allowlist.** Anyone who can DM/@-mention your bot can spawn an agent session. Run against bots you own.
-- **Per-agent histories are separate.** Switching with `with codex` mid-scope spins up a fresh Codex session — it has no idea what you discussed with Claude in the same scope. Each agent only sees what was sent to it.
-- **One agent missing is OK.** If only `claude` or only `codex` is installed/authenticated, metro still starts; messages asking for the missing one surface an error in chat.
-- **Telegram non-forum groups are skipped.** Without a per-topic thread boundary the routing model breaks down. DMs and forum topics (incl. auto-created ones from General) work normally.
-- **Telegram bot privacy.** Default Telegram bot privacy is *enabled*, which can block group messages even with @-mentions. Disable in [@BotFather](https://t.me/BotFather) → Bot Settings → Group Privacy → Turn off, then kick + re-invite the bot.

package/dist/cache.js

@@ -0,0 +1,74 @@
+/** Per-machine caches: seen lines (lines.json) + bot ids (bot-ids.json). */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from './log.js';
+import { STATE_DIR } from './paths.js';
+import { Line } from './stations/index.js';
+const cacheFile = join(STATE_DIR, 'lines.json');
+const FLUSH_DELAY_MS = 5_000;
+let cache = null;
+let dirty = false;
+let flushTimer = null;
+function read() {
+    if (cache)
+        return cache;
+    if (!existsSync(cacheFile))
+        return cache = {};
+    try {
+        cache = JSON.parse(readFileSync(cacheFile, 'utf8'));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err), path: cacheFile }, 'lines cache read failed; treating as empty');
+        cache = {};
+    }
+    return cache;
+}
+function flush() {
+    if (!dirty || !cache)
+        return;
+    try {
+        writeFileSync(cacheFile, JSON.stringify(cache, null, 2));
+        dirty = false;
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err), path: cacheFile }, 'lines cache write failed');
+    }
+}
+process.on('exit', flush);
+export function noteSeen(line, name) {
+    const c = read();
+    const entry = c[line] ??= { createdAt: new Date().toISOString() };
+    entry.lastSeenAt = new Date().toISOString();
+    if (name && entry.name !== name)
+        entry.name = name;
+    dirty = true;
+    if (!flushTimer)
+        flushTimer = setTimeout(() => { flushTimer = null; flush(); }, FLUSH_DELAY_MS);
+}
+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');
+export function saveBotId(station, id) {
+    const cur = existsSync(botIdsFile)
+        ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
+    if (cur[station] === id)
+        return;
+    cur[station] = id;
+    try {
+        writeFileSync(botIdsFile, JSON.stringify(cur, null, 2));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'bot-ids cache write failed');
+    }
+}
+/** 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`;
+    }
+}

package/dist/cli/actions.js

@@ -0,0 +1,156 @@
+/** CLI action handlers: send/reply/edit/react/download/fetch/notify + helpers. */
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg } from '../log.js';
+import { DiscordStation } from '../stations/discord.js';
+import { TelegramStation } from '../stations/telegram.js';
+import { ipcCall } from '../ipc.js';
+import { agentSelf, appendHistory, lookupEntry, mintId, resolvePlatformId, } from '../history.js';
+import { asLine, Line } from '../stations/index.js';
+import { loadMetroEnv } from '../paths.js';
+import { emit, flagList, flagOne, isJson, need, resolveText, writeJson, } from './util.js';
+export function chatStationOf(line) {
+    const s = Line.station(line);
+    if (s === 'discord')
+        return new DiscordStation();
+    if (s === 'telegram')
+        return new TelegramStation();
+    throw new Error(`no chat station for line "${line}" (try metro://{discord|telegram}/...)`);
+}
+function parseButtons(f) {
+    const raw = flagOne(f, 'buttons');
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--buttons must be JSON like '[[{"text":"…","url":"…"}]]': ${errMsg(err)}`);
+    }
+}
+function richOpts(f) {
+    const opts = {};
+    const images = flagList(f, 'image');
+    if (images.length)
+        opts.images = images;
+    const documents = flagList(f, 'document');
+    if (documents.length)
+        opts.documents = documents;
+    const voice = flagOne(f, 'voice');
+    if (voice)
+        opts.voice = voice;
+    const buttons = parseButtons(f);
+    if (buttons)
+        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) {
+    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] : [])],
+    });
+    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 });
+        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);
+    emit(f, `sent ${id} (${messageId}) to ${line}`, { ok: true, line, id, messageId });
+}
+export async function cmdReply(p, f) {
+    need(p, 2, 'metro reply <line> <message_id> <text> [--image=… --document=… --voice=… --buttons=…]');
+    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));
+    emit(f, `replied ${id} (${messageId}) to ${line}#${replyTo}`, { ok: true, line, id, replyTo: replyToArg, messageId });
+}
+export async function cmdEdit(p, f) {
+    need(p, 2, 'metro edit <line> <message_id> <text> [--buttons=<json>]');
+    loadMetroEnv();
+    const [to, msgArg] = p, text = await resolveText(p, 2), line = asLine(to);
+    const platformId = resolvePlatformId(msgArg);
+    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);
+    emit(f, `edited ${line}#${platformId} (${id})`, { ok: true, line, id, messageId: platformId });
+}
+export async function cmdReact(p, f) {
+    need(p, 2, 'metro react <line> <message_id> <emoji>   (empty emoji clears)');
+    loadMetroEnv();
+    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 human = emoji ? `reacted ${emoji} on ${line}#${platformId}` : `cleared reaction on ${line}#${platformId}`;
+    emit(f, human, { ok: true, line, id, messageId: platformId, emoji });
+}
+export async function cmdDownload(p, f) {
+    need(p, 2, 'metro download <line> <message_id> [--out=<dir>]');
+    loadMetroEnv();
+    const [to, msgArg] = p, line = asLine(to);
+    const messageId = resolvePlatformId(msgArg);
+    const outDir = typeof f.out === 'string' ? f.out : join(tmpdir(), 'metro-downloads');
+    mkdirSync(outDir, { recursive: true });
+    /** Telegram has no get-message-by-id REST endpoint — daemon holds the in-memory snapshot. */
+    let files;
+    if (Line.station(line) === 'telegram') {
+        const resp = await ipcCall({ op: 'download', line, messageId, outDir });
+        if (!resp.ok)
+            throw new Error(resp.error);
+        files = 'files' in resp ? resp.files : [];
+    }
+    else {
+        files = await chatStationOf(line).download(line, messageId, outDir);
+    }
+    if (isJson(f))
+        return writeJson({ ok: true, line, files });
+    if (!files.length)
+        process.stdout.write(`(no image attachments on ${line}#${messageId})\n`);
+    for (const file of files)
+        process.stdout.write(file.path + '\n');
+}
+export async function cmdFetch(p, f) {
+    need(p, 1, 'metro fetch <line> [--limit=N]');
+    loadMetroEnv();
+    const line = asLine(p[0]);
+    const messages = await chatStationOf(line).fetch(line, Number(flagOne(f, 'limit')) || 20);
+    if (isJson(f))
+        return writeJson({ ok: true, line, messages });
+    if (!messages.length)
+        process.stdout.write(`(no messages on ${line})\n`);
+    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 });
+}