@stage-labs/metro 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -1,55 +1,252 @@
 # Metro
 
-Chat with your Claude Code or Codex agent over Telegram and Discord.
+[![npm](https://img.shields.io/npm/v/@stage-labs/metro/beta?label=npm&color=cb3837)](https://www.npmjs.com/package/@stage-labs/metro)
+[![lines of code](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.codetabs.com%2Fv1%2Floc%2F%3Fgithub%3Dbonustrack%2Fmetro&query=%24%5B0%5D.linesOfCode&label=lines%20of%20TypeScript&color=blue)](https://github.com/bonustrack/metro)
 
-## Quickstart
+> **A live JSON stream of Telegram, Discord, webhooks, and cross-user messages for your local Claude Code / Codex session.**
+
+Metro is a small daemon you launch from inside your session. It connects to Discord, Telegram, and any third-party service that can POST a webhook (GitHub, Intercom, Fireflies, …), 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-user: any user can ping any other via `metro send metro://claude/<user-id>/<session-id>` and the daemon re-emits it on the stream.
+
+```
+[Claude Code session]
+
+$ metro &                              # backgrounded
+$ Monitor( … metro's stdout … )
+
+>>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
+     "text":"@metro 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…"
+```
 
-In your shell:
+You own your own streaming, tool calls, and reply timing. Metro is the wire.
+
+---
+
+## Quickstart
 
 ```bash
 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 setup discord  <token>             # https://discord.com/developers/applications
-
-metro setup skill                        # writes SKILL.md so Claude Code + Codex auto-onboard
 metro doctor                             # verify
+metro                                    # run the daemon
+```
+
+Requires **Node ≥ 22 or Bun ≥ 1.3**. Metro doesn't launch Claude or Codex — you do, and the user launches metro. See [`docs/users.md`](docs/users.md).
+
+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
+
 ```
+Discord gateway     ──┐
+Telegram poller     ──┤
+Cloudflare tunnel   ──┤ ── HTTP webhooks (GitHub, Intercom, …)
+                      │
+                      ├─▶ metro daemon ───▶ stdout (JSON events; Claude Code's Monitor reads here)
+                      │                ───▶ codex-rc WebSocket (Codex turn/start; opt-in)
+                      │                ◀── IPC Unix socket  (metro send to Claude / Codex lines)
+                      │
+local CLI calls   ────┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
+```
+
+- **Inversion of control.** Claude Code / Codex launches `metro`, not the other way around. Metro never spawns a Claude / Codex process.
+- **Single daemon per machine.** Lockfile at `$METRO_STATE_DIR/.tail-lock` enforces singleton.
+- **Account-tied identity.** `to` on inbound and `from` on outbound resolve to a stable account-scoped URI per runtime: `metro://claude/user/<orgId>` (from `claude auth status --json`) or `metro://codex/user/<accountId>` (from `$CODEX_HOME/auth.json`). Same on any device for the same logged-in account.
+- **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-user notification.** `metro send metro://claude/<user-id>/<session-id>` (or `metro://codex/<user-id>/<session-id>`) routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer sees it. Discover reachable users/sessions via `metro stations` or `$METRO_STATE_DIR/user-registry.json`.
+- **Webhooks (opt-in).** `metro webhook add <label>` registers an HTTP receive endpoint; the daemon binds `127.0.0.1:8420` (override with `$METRO_WEBHOOK_PORT`). If you've run `metro tunnel setup`, a Cloudflare named tunnel exposes it publicly. Each POST is re-emitted on stdout as an inbound event.
+
+---
+
+## Stations
+
+Each endpoint is a **station** with declared capabilities:
+
+| Station    | Modalities    | Features                                              | Config                                                                                  |
+|------------|---------------|-------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| `discord`  | text + image  | reply, send, edit, react, download, fetch             | `DISCORD_BOT_TOKEN` + Message Content Intent                                            |
+| `telegram` | text + image  | reply, send, edit, react, download                    | `TELEGRAM_BOT_TOKEN`                                                                    |
+| `claude`   | text          | send                                                  | auto-detected from `$CLAUDECODE`; identity via `claude auth status --json`              |
+| `codex`    | text          | send                                                  | auto-detected from `$METRO_CODEX_RC` / `$CODEX_HOME`; identity via `$CODEX_HOME/auth.json` |
+| `webhook`  | text          | (receive-only; optional HMAC verify)                  | `metro webhook add <label>` + `metro tunnel setup` (Cloudflare named tunnel)            |
 
-> **Discord setup:** toggle **Message Content Intent** in Developer Portal → Bot → Privileged Gateway Intents.
+Run `metro stations` to see live config status (`✓` configured, `✗` not, `·` informational).
 
-Open Claude Code (`claude`) or Codex (`codex`), and tell it:
+Behaviors worth knowing:
+- **No streaming / no edit machinery in metro.** The local CLI 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 user 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.
+- **Webhook signature verification.** Pass `--secret=<shared-secret>` to `metro webhook add` and the daemon verifies `X-Hub-Signature-256` (GitHub/Intercom format) on every POST. Mismatches return 401 and never reach the stream.
+
+---
+
+## Webhooks
+
+Receive HTTP events from third parties (GitHub, Intercom, Fireflies, anything that POSTs) as standard metro inbound events. Each registered endpoint is one Line.
+
+```bash
+# One-time per machine — bring your own Cloudflare domain (free Registrar at-cost):
+brew install cloudflared
+cloudflared tunnel login                       # browser OAuth, pick your domain
+metro tunnel setup metro webhook.example.com   # creates tunnel + DNS CNAME
+
+# Per endpoint — repeat for each provider:
+metro webhook add github --secret=$(openssl rand -hex 32)
+# → https://webhook.example.com/wh/<id>
+# (without `metro tunnel setup`, falls back to http://127.0.0.1:8420/wh/<id> — local-only)
+
+metro                                          # daemon binds 8420 + spawns cloudflared automatically
+```
 
-> Run `metro` in the background.
+Paste the URL into the provider's webhook settings (for GitHub: **Content type must be `application/json`** — form-encoded won't parse). Every POST becomes an inbound event with `station: "webhook"`, `line: metro://webhook/<id>`, `payload: { headers, body }`. If you set `--secret`, metro verifies the `X-Hub-Signature-256` header (GitHub/Intercom format) and rejects mismatches with 401.
 
-DM your bot. The agent picks up the next inbound and replies — the bundled skill handles launching, stdout watching, reactions, and replies.
+| Action | Command |
+|---|---|
+| Register an endpoint | `metro webhook add <label> [--secret=<shared-secret>]` |
+| List endpoints + URLs | `metro webhook list` |
+| Remove an endpoint | `metro webhook remove <id>` |
+| One-time tunnel setup | `metro tunnel setup <tunnel-name> <hostname>` |
+| Tunnel status | `metro tunnel status` |
 
-## Config
+The tunnel is optional — without it the listener binds `127.0.0.1:8420` only (good for local testing or your own loopback tools). With Cloudflare named tunnels, the URL stays stable across daemon restarts and machines. See [docs/uri-scheme.md](docs/uri-scheme.md) and [docs/users.md](docs/users.md) for the full event shape.
+
+---
+
+## Lines
+
+Every conversational scope is identified by a **Line** — a URI in the form `metro://<station>/<path>`:
+
+```
+metro://discord/1234567890123456789
+metro://telegram/-1001234567890                 # main chat / DM
+metro://telegram/-1001234567890/42              # forum topic 42
+metro://claude/9bfc7af0-…/50b00d11-…            # claude user session
+metro://codex/8119ecb1-…/01997d4b-…             # codex user session
+metro://webhook/fwaCgTKJuLAjS2K0                # HTTP webhook endpoint
+```
+
+Anyone can post to a line via [`metro send`](#cli) — daemon required only for Claude / Codex lines. Full grammar in [`docs/uri-scheme.md`](docs/uri-scheme.md).
+
+---
+
+## CLI
+
+```
+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 history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
+                                            Universal message log (every inbound + outbound), newest first.
+metro webhook add <label> [--secret=…]      Register an HTTP receive endpoint (GitHub, Intercom, …).
+metro webhook list | remove <id>            List or remove webhook endpoints.
+metro tunnel setup <name> <hostname>        Configure a Cloudflare named tunnel for public webhook URLs.
+metro tunnel status                         Show current tunnel config.
+metro update                                Upgrade in place.
+```
+
+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`):
+- `USERS.md` — user 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/user/<orgId>`, `metro://codex/user/<accountId>`) plus a `fromName` display field. The dispatcher auto-detects the local user for `to` on inbound (`$CLAUDECODE` → `metro://claude/user/<orgId>` from `claude auth status --json`; `$METRO_CODEX_RC`/`$CODEX_HOME` → `metro://codex/user/<accountId>` from `$CODEX_HOME/auth.json`).
+- `bot-ids.json` — `{discord: "<botUserId>", telegram: "<botUserId>"}` written by the daemon on startup (cached for the few historical lookups that still need a platform-side bot identity).
+- `lines.json` — line → last-seen / name cache (read by `metro lines`)
+- `user-registry.json` — every `(station, user-id, sessions[])` tuple metro has seen; surfaced under each Claude / Codex row in `metro stations`
+- `stations/codex/session-id` — current codex-rc thread id (daemon writes on handshake; CLI processes read for `metro://codex/<user-id>/<session>`)
+- `webhooks.json` — registered HTTP receive endpoints (id, label, optional shared secret)
+- `tunnel.json` — Cloudflare named-tunnel config (`{name, hostname}`); when present, the daemon spawns `cloudflared tunnel run`. The token is resolved via `cloudflared tunnel token <name>` and passed through as `TUNNEL_TOKEN`, so the per-tunnel credentials JSON at `~/.cloudflared/<id>.json` is not required (the named-form spawn is the fallback when the token call fails)
+- `.tail-lock` — dispatcher pid
+- `metro.sock` — daemon IPC socket
+- `telegram-offset.json` — last processed update id
+
+---
+
+## 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_WEBHOOK_PORT` | `8420` | Local port the HTTP webhook listener binds to (always `127.0.0.1`; expose publicly via Cloudflare tunnel). |
+| `METRO_USER_ID` | — | Override the resolved user id (orgId / accountId) used in `metro://<station>/user/<id>` and `metro://<station>/<id>/<session>`. Useful for testing. |
+| `METRO_USER_SESSION_ID` | — | Override the resolved session id (Claude session / Codex thread). |
+| `METRO_FROM` | — | Pin a custom `from` URI for all writes (overrides runtime detection). |
 | `METRO_CONFIG_DIR` | `~/.config/metro` | Where the global `.env` lives. |
-| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, attachment cache, default download dir. |
+| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, IPC socket, telegram offset, registries, tunnel config. |
 | `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.
 
-## Reference
+---
 
-- `metro --help` — command surface
-- `metro doctor` — health check
-- [SKILL.md](skills/metro/SKILL.md) — agent-facing flow
-
-## Uninstall
+## Develop
 
 ```bash
-metro setup clear; metro setup skill --clear
-rm -rf ~/.cache/metro/
-npm uninstall -g @stage-labs/metro
+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
 ```
 
+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), action handlers ([`actions.ts`](src/cli/actions.ts): send/reply/edit/react/download/fetch), webhook + tunnel commands ([`webhook.ts`](src/cli/webhook.ts)), and shared CLI primitives ([`util.ts`](src/cli/util.ts)).
+- [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: starts each station, emits events on stdout, listens on the IPC socket, optionally pushes to codex-rc, supervises the Cloudflare tunnel.
+- [`src/stations/`](src/stations/) — Line URI scheme + ChatStation interface + listing ([`index.ts`](src/stations/index.ts)). Chat impls: [`discord.ts`](src/stations/discord.ts), [`telegram.ts`](src/stations/telegram.ts) (+ [`telegram-md.ts`](src/stations/telegram-md.ts) markdown helper). User identity resolvers: [`claude.ts`](src/stations/claude.ts) (orgId via `claude auth status --json`), [`codex.ts`](src/stations/codex.ts) (account_id via `auth.json`). HTTP receive: [`webhook.ts`](src/stations/webhook.ts).
+- [`src/codex-rc.ts`](src/codex-rc.ts) — Codex app-server WebSocket push client (also exposes the rc thread id used as Codex session-id).
+- [`src/tunnel.ts`](src/tunnel.ts) — Cloudflared named-tunnel supervisor.
+- [`src/webhooks.ts`](src/webhooks.ts) — webhook endpoint store (`webhooks.json` CRUD).
+- [`src/registry.ts`](src/registry.ts) — user registry: `(station, user-id, sessions[])` tracking.
+- [`src/history.ts`](src/history.ts) — universal message log + `userSelf()` / `selfLine()` identity helpers.
+- [`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`, plus bot-id cache.
+- [`docs/uri-scheme.md`](docs/uri-scheme.md) specs the Line format; [`docs/users.md`](docs/users.md) is the in-context skill for users.
+
+CI runs typecheck + lint + build on every PR via [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
+---
+
 ## Caveats
 
-- **No allowlist.** Anyone who can DM your bot or @-mention it can talk to your session. Run against bots you own.
-- **Latency.** Inbounds surface at the next agent decision boundary — sub-second on Claude Code, longer on Codex turns.
+- **No allowlist on chat stations.** Anyone who can DM/`@`-mention your bot can produce events. Run against bots you own.
+- **Webhook secrets are optional but recommended.** Without `--secret`, anyone who learns the endpoint URL can POST events. With it, metro verifies `X-Hub-Signature-256` and rejects mismatches.
+- **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.
+- **Cloudflared is your responsibility.** `metro tunnel setup` records the named tunnel; you still install `cloudflared` (`brew install cloudflared`) and run `cloudflared tunnel login` once.
+
+---
+
+## Uninstall
+
+```bash
+metro setup clear
+rm -rf ~/.cache/metro
+npm uninstall -g @stage-labs/metro
+```

package/dist/cache.js

@@ -0,0 +1,69 @@
+/** 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';
+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');
+const readBotIds = () => {
+    try {
+        return existsSync(botIdsFile) ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
+    }
+    catch {
+        return {};
+    }
+};
+export function saveBotId(station, id) {
+    const cur = readBotIds();
+    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');
+    }
+}

package/dist/cli/actions.js

@@ -0,0 +1,147 @@
+/** 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';
+import { errMsg } from '../log.js';
+import { DiscordStation } from '../stations/discord.js';
+import { TelegramStation } from '../stations/telegram.js';
+import { ipcCall } from '../ipc.js';
+import { userSelf, appendHistory, lookupEntry, mintId, readHistory, 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;
+}
+/** Mirror the original entry's destination: group → `line`; DM → the other-party user URI. */
+function destinationFor(orig, line) {
+    if (!orig || !orig.to || orig.to === orig.line)
+        return line;
+    return orig.from;
+}
+/** Append an outbound action to history.jsonl; `to` mirrors the destination per `destinationFor`. */
+function logOutbound(f, e) {
+    const id = mintId();
+    const fromOverride = flagOne(f, 'from');
+    appendHistory({
+        id, ts: new Date().toISOString(), station: Line.station(e.line) ?? '?',
+        from: fromOverride ? asLine(fromOverride) : userSelf(), to: e.to ?? e.line, ...e,
+    });
+    return id;
+}
+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.isLocal(line)) {
+        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 messageId = await chatStationOf(line).send(line, text, richOpts(f));
+    /** Inherit destination from the most recent inbound on this line so DM sends address the user. */
+    const to = destinationFor(readHistory({ line, kind: 'inbound', limit: 1 })[0], line);
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, to });
+    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 messageId = await chatStationOf(line).send(line, text, { ...richOpts(f), replyTo });
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, replyTo: replyToArg, to: destinationFor(lookupEntry(replyToArg), line) });
+    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 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) {
+    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, { kind: 'react', line, messageId: platformId, emoji, to: destinationFor(lookupEntry(msgArg), line) });
+    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`);
+}