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

package/docs/uri-scheme.md

@@ -0,0 +1,125 @@
+# Metro URI scheme
+
+Universal identifier for every conversational scope and notification sink in metro. Lines pass around as opaque strings; only the owning station parses its own paths.
+
+## Grammar
+
+```
+line       = "metro://" station "/" path
+station    = lowercase identifier (claude | codex | discord | telegram | webhook | …)
+path       = station-specific, "/"-separated segments
+```
+
+The URI parses cleanly with the WHATWG `URL` parser: `new URL(line)` gives `protocol="metro:"`, `host=<station>`, `pathname="/<path>"`.
+
+## Registered stations
+
+| Station    | Kind    | Pattern                                      | Example                                                                |
+|------------|---------|----------------------------------------------|------------------------------------------------------------------------|
+| `discord`  | chat    | `metro://discord/<channel-id>`               | `metro://discord/1234567890123456789`                                  |
+| `telegram` | chat    | `metro://telegram/<chat-id>[/<topic-id>]`    | `metro://telegram/-1001234567890/42`                                   |
+| `claude`   | agent   | `metro://claude/<agent-id>/<session-id>`     | `metro://claude/9bfc7af0-…/50b00d11-…`                                 |
+| `codex`    | agent   | `metro://codex/<agent-id>/<session-id>`      | `metro://codex/8119ecb1-…/01997d4b-…`                                  |
+| `webhook`  | service | `metro://webhook/<endpoint-id>`              | `metro://webhook/fwaCgTKJuLAjS2K0`                                     |
+
+Agent lines mirror the `<root>/<sub>` structure of `metro://telegram/<chat-id>/<topic-id>`: `<agent-id>` (the user's stable account id — same across devices) plays the role of `<chat-id>`, and `<session-id>` (one conversation) plays the role of `<topic-id>`. Both segments are derived per station (see [participants](#participants) below).
+
+## Participants
+
+Every chat station also exposes participant URIs — used as `from` on inbound/outbound events and history rows.
+
+| Kind   | Pattern                          | Example                                                       |
+|--------|----------------------------------|---------------------------------------------------------------|
+| user    | `metro://<station>/user/<id>`    | `metro://discord/user/87654321`                               |
+| claude  | `metro://claude/user/<orgId>`    | `metro://claude/user/9bfc7af0-2117-44c5-baf2-d22ba382d065`    |
+| codex   | `metro://codex/user/<accountId>` | `metro://codex/user/8119ecb1-b05e-48db-aa80-434584439df9`     |
+| webhook | `metro://webhook/<endpointId>`   | `metro://webhook/fwaCgTKJuLAjS2K0` (line + `from` are the same — no HTTP-side user identity) |
+
+`from` and `to` on history entries are always participant URIs. Discord/Telegram inbounds set `from` to the user URI; the daemon sets `to` to the agent identity:
+
+- **Claude Code** (`$CLAUDECODE` set) — `metro://claude/user/<orgId>`. `<orgId>` is the stable Anthropic-account UUID, resolved by shelling out to `claude auth status --json`.
+- **Codex** (`$METRO_CODEX_RC` or `$CODEX_HOME` set) — `metro://codex/user/<accountId>`. `<accountId>` is the ChatGPT-account UUID, read from `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`) at the `tokens.account_id` field. Requires `auth_mode=chatgpt`; API-key-only Codex sessions have no account id and metro will error.
+- **Neither** — `to` is the generic `metro://agent`.
+
+Same account on any machine yields the same URI. Switching accounts via `claude auth login` / `codex login` flips the URI within ~5 s for the long-lived daemon (5 s TTL cache); one-shot CLI invocations re-resolve every run. On outbound, `from` = the same agent identity; `to` = the original sender for replies/reacts (looked up from history), or the channel `line` for fresh group sends. A `fromName` field carries the display name (`@alice`, `bonustrack_`).
+
+Override with `--from=<uri>` on any write command, or set `$METRO_FROM` to pin a custom identity for the whole session.
+
+Chat lines identify a Discord channel / Telegram chat (with optional forum topic). Agent lines now identify a *specific session* of a specific agent (`<agent-id>/<session-id>`) — posting to one re-emits the message on the daemon's stdout stream and (if configured) pushes it to the Codex app-server. They have no inherent "messages"; only events.
+
+### Session derivation per station
+
+| Station  | `<agent-id>`               | `<session-id>`                                                  |
+|----------|----------------------------|-----------------------------------------------------------------|
+| `claude` | `orgId` from `claude auth status --json` | `$CLAUDE_CODE_SESSION_ID` (set by Claude Code; stable across `--resume`)|
+| `codex`  | `tokens.account_id` from `$CODEX_HOME/auth.json` | codex-rc thread id from the JSON-RPC handshake (`thread/loaded/list` → `thread/start`) |
+
+Override either segment with `METRO_AGENT_ID` / `METRO_AGENT_SESSION_ID` env vars.
+
+### Agent registry
+
+The daemon persists every `(station, agent-id, session)` tuple it sees to `$METRO_STATE_DIR/agent-registry.json`. `metro stations` prints the count of seen agents and sessions per station. Run it to discover what's reachable rather than guessing topic names.
+
+## Webhook station
+
+Receive-only HTTP endpoint for third-party services (GitHub, Intercom, Fireflies, …). Each registered endpoint is one `metro://webhook/<endpoint-id>` line.
+
+- **Register:** `metro webhook add <label> [--secret=<shared-secret>]` mints a 16-char endpoint id (96 bits of entropy, persisted to `$METRO_STATE_DIR/webhooks.json`) and prints the receiving URL. `metro webhook list` / `remove <id>` for the obvious.
+- **Listener:** the dispatcher binds `127.0.0.1:8420` (override with `METRO_WEBHOOK_PORT`) when ≥1 endpoint is registered. Routes `POST /wh/<endpoint-id>` to an inbound event with `payload: { headers, body }` — `body` is parsed JSON when the request `Content-Type` is JSON, raw string otherwise. `GET /wh/<endpoint-id>` returns 200 (for provider ping checks).
+- **Envelope:** `messageId` falls back to `X-GitHub-Delivery` / `X-Request-ID` / a generated UUID for idempotency tracking. `text` is synthesized from `X-GitHub-Event` / `X-Intercom-Topic` plus method + path for at-a-glance routing; agents narrow on `payload.body` for full event details.
+- **HMAC verification:** if `--secret` was set on `metro webhook add`, requests must include a matching `X-Hub-Signature-256: sha256=<hex>` (GitHub/Intercom format) — mismatches are rejected with 401 before reaching the stream.
+- **Public reachability:** provided by a Cloudflare named tunnel — see [Tunneling](#tunneling) below. Without one, the listener stays loopback-only (useful for `curl` testing).
+
+## Tunneling
+
+Webhook providers need a public URL. Metro integrates with **Cloudflare named tunnels** (free, stable, account-scoped):
+
+```bash
+cloudflared tunnel login                                   # one-time OAuth (browser)
+metro tunnel setup metro webhook.yourdomain.com            # creates the tunnel + DNS route
+metro                                                      # daemon spawns `cloudflared tunnel run`
+```
+
+After setup, `metro webhook list` prints `https://webhook.yourdomain.com/wh/<id>` for each endpoint. The URL is stable across restarts (bound to the tunnel UUID in `~/.cloudflared/<uuid>.json`, not the cloudflared process). Tunnel config persists at `$METRO_STATE_DIR/tunnel.json`. Without setup, endpoints fall back to `http://127.0.0.1:8420/wh/<id>` (local-only, useful for curl testing).
+
+## Message addressing
+
+Messages on chat lines are referenced by **line + message id** (two args), not as part of the URI. So:
+
+```bash
+metro reply  metro://discord/123…  4567  "ack"
+metro edit   metro://discord/123…  9876  "fixed typo"
+metro react  metro://telegram/-100…/42  4567  👍
+```
+
+## Properties
+
+- **Stable**: a Line is valid for the lifetime of the scope.
+- **Self-describing**: the station name is encoded; the dispatcher routes by station prefix.
+- **Persistable**: safe as a JSON key on disk (used by `lines.json`).
+- **Branded**: TypeScript type `Line` prevents mixing with arbitrary strings.
+
+## API
+
+```ts
+import { Line } from './stations/index.js';            // value namespace + type
+
+const l: Line = Line.discord('1234567890');     // typed Line
+Line.parse(l);                                   // { station: 'discord', path: ['1234567890'] } | null
+Line.station(l);                                 // 'discord'
+Line.claude(orgId, sessionId);                   // metro://claude/<orgId>/<sessionId>
+Line.codex(accountId, threadId);                 // metro://codex/<accountId>/<threadId>
+Line.parseClaude(l);                             // { agentId, sessionId } | null
+Line.parseCodex(l);                              // { agentId, sessionId } | null
+Line.webhook(endpointId);                        // metro://webhook/<endpointId>
+Line.parseWebhook(l);                            // string | null  (the endpoint id)
+Line.user(station, id);                          // metro://<station>/user/<id>
+Line.bot(station, id);                           // metro://<station>/bot/<id>
+Line.isAgent(l);                                 // true for any metro://{claude,codex}/...
+```
+
+## Adding a new station
+
+1. Pick a lowercase station name (`slack`, `matrix`, …).
+2. Add a `Line.<station>(...)` formatter and a parser that returns your typed payload.
+3. Document the path grammar in the table above.

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.10",
+  "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": {
     "type": "git",
@@ -14,10 +14,12 @@
     "node": ">=22"
   },
   "bin": {
-    "metro": "./dist/cli.js"
+    "metro": "./dist/cli/index.js"
   },
   "files": [
     "dist",
+    "docs",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -32,13 +34,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "discord.js": "^14.14.0",
     "pino": "^9.5.0",
-    "zod": "^3.23.0"
+    "pino-pretty": "^13.1.3",
+    "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,257 @@
+---
+name: metro
+description: Run the metro Telegram/Discord/webhook 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/webhook reply/edit/react/send/download/fetch/notify.
+---
+
+# Metro — running the Telegram / Discord / webhook bridge
+
+Metro is a CLI bridge between this agent session and external sources: Telegram, Discord, and HTTP webhooks from third parties (GitHub, Intercom, Fireflies, …). You launch `metro` once when the user asks, then act on each inbound JSON line via `metro <subcommand>`.
+
+## Starting the bridge
+
+When the user asks to run/start/launch metro:
+
+### Claude Code
+
+```
+Bash(command: "metro", run_in_background: true)
+```
+
+Then attach `Monitor` to its stdout. Each line is one JSON event. Stderr is pino logs — don't act on it.
+
+### Codex
+
+```
+shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)
+```
+
+Codex has no Monitor equivalent. Instead, metro pushes each event into your thread via JSON-RPC `turn/start`, so events arrive as user input on your next turn. The user must have a daemon + TUI running on the **same WebSocket URL**:
+
+```
+codex app-server --listen ws://127.0.0.1:8421     # daemon (terminal 1)
+codex --remote ws://127.0.0.1:8421                # TUI (terminal 2) — type "hi" once to create a live thread
+```
+
+Then metro starts third. If metro exits immediately or you see `thread not found` retries on its stderr, the TUI didn't create a thread yet — tell the user to type something in the TUI.
+
+### 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, or (Codex) no live thread on the daemon.
+
+## Event shape
+
+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
+- `station` — `"discord"`, `"telegram"`, `"claude"`, `"codex"`, `"webhook"`
+- `line` — conversation URI; `lineName?` is the channel/topic display name (for webhooks: the label you gave it)
+- `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
+{"kind":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","lineName":"infra","from":"metro://telegram/user/12345","fromName":"@alice","to":"metro://claude/user/9bfc7af0-…","messageId":"4567","text":"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
+{"kind":"notification","id":"msg_pQ4r5sT0","ts":"…","station":"claude","line":"metro://claude/9bfc7af0-…/50b00d11-…","from":"metro://codex/user/8119ecb1-…","to":"metro://claude/9bfc7af0-…/50b00d11-…","text":"deploy 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.
+- **`webhook`** — `{ headers, body }`. The provider lives in `headers['x-github-event']`, `headers['x-intercom-topic']`, etc. Full event payload is `body` (parsed JSON when possible). `text` is a short summary; always narrow on `body` for real routing.
+
+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>}}`.
+- **webhook** — every POST is "for you" by design (it's an endpoint you registered). Route on `payload.headers['x-github-event']` / `x-intercom-topic` etc. to decide which provider event you're handling.
+
+Default for chat: only reply on DM or ping; otherwise stay silent or `metro react` to ack. Webhooks have no "ack" mechanism — just consume the event.
+
+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/user/<orgId>` — a Claude Code agent (orgId = stable Anthropic-account UUID, same across devices for the same account)
+- `metro://codex/user/<accountId>` — a Codex agent (accountId = stable ChatGPT-account UUID, same across devices)
+- `metro://webhook/<endpoint-id>` — a webhook endpoint (line + `from` are the same — no HTTP-side user identity)
+- `metro://<station>/<channelId>` — a channel (used as `to` for fresh sends to a group, where no single recipient)
+
+When **you** send via `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from = metro://claude/user/<orgId>` (when `$CLAUDECODE` is set; resolved from `claude auth status --json`) or `metro://codex/user/<accountId>` (from `$METRO_CODEX_RC` / `$CODEX_HOME`; resolved from `$CODEX_HOME/auth.json`). Switching accounts via `claude auth login` / `codex login` flips the id on the next event (within ~5 s for the daemon). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is automatically the original sender (looked up via the universal id).
+
+The `id` is the **canonical handle** for that message across all stations — store it if you want to refer back to it later.
+
+- `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`.
+
+## Required flow on every event
+
+1. **Echo `event.display` verbatim as your first chat output.** Every event ships a pre-rendered chat-bubble in `event.display` — bold header (icon + station + sender) and a markdown blockquote body. Render this string as-is, before any commentary or tool calls. Monitor's notification chip is a CLI-only UI and won't surface visibly in VSCode/Cursor, so this echo is the only cross-surface signal the user has. Example:
+
+   ```
+   **📩 telegram · @bonustrack**
+   > Hey
+   ```
+
+   Don't compose your own bubble — the format is centralized in metro's dispatcher; just paste the string.
+
+2. **Decide and act** using the subcommands below.
+
+No server-side auto-reaction — don't expect 👀 to be on the user's message; add one yourself with `metro react` if you want to ack quickly.
+
+## Subcommands
+
+All take positional args (no `--to=`/`--text=` flags). Append `--json` to any for a parseable single-line result.
+
+| Action | Command |
+|---|---|
+| Quote-reply (threads under original) | `metro reply <line> <messageId> <text>` |
+| Send a fresh message (no reply context) | `metro send <line> <text>` |
+| Edit a message you previously sent | `metro edit <line> <messageId> <text>` |
+| Reaction (empty emoji clears) | `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/<agent-id>/<session-id> <text> [--from=<line>]` |
+| Register webhook endpoint | `metro webhook add <label> [--secret=<hmac-secret>]` |
+| List / remove webhook endpoints | `metro webhook list` · `metro webhook remove <id>` |
+| Configure Cloudflare named tunnel | `metro tunnel setup <tunnel-name> <hostname>` |
+
+`reply` / `send` / `edit` accept multi-line text via stdin (heredoc).
+
+### Rich content flags
+
+`send` and `reply` accept these extra flags; `edit` accepts `--buttons` only.
+
+- `--image=<path>` — upload a local image. **Repeatable** for albums: `--image=a.png --image=b.png`. Comma-separated also works: `--image='a.png,b.png'`. Up to 10 / message. Text becomes the caption (on the first image for albums).
+- `--document=<path>` — upload any local file (PDF, log, csv, …). Same repeat/comma syntax.
+- `--voice=<path>` — single voice message (`.ogg` Opus or `.mp3`). On Telegram renders as a voice bubble via `sendVoice`; on Discord uploaded as an audio attachment.
+- `--buttons='[[{"text":"…","url":"https://…"}]]'` — attach an inline URL-button keyboard. 2D array: outer = rows, inner = buttons on that row.
+
+```bash
+metro send <line> "screenshot"                     --image=/tmp/build.png
+metro send <line> "before/after"                   --image=/tmp/before.png --image=/tmp/after.png
+metro reply <line> <id> "log + transcript"          --document=/tmp/run.log --document=/tmp/transcript.txt
+metro send <line> "have a listen"                  --voice=/tmp/note.ogg
+metro send <line> "approve?" --buttons='[[{"text":"Open PR","url":"https://github.com/x/y/pull/1"}]]'
+metro edit <line> <id> "still working…" --buttons='[]'    # clears buttons
+```
+
+Limits / quirks:
+- 20 MB per file (both platforms).
+- Telegram albums are single-type (all photos OR all documents in one album). Mixing kinds in one send still works — metro splits into two album messages and returns the first id.
+- Telegram drops `--buttons` when multiple attachments are sent (the bot API doesn't allow `reply_markup` on media groups).
+- URL buttons only (no callback / interactive components yet).
+
+## When to use `reply` vs `send`
+
+- **`reply`** — responding to a specific inbound message. Threads under it. Default for handling an `inbound` event.
+- **`send`** — initiating without a triggering message: a long task finished, a follow-up the user asked you to deliver later, or posting to an agent line (`metro://claude/...`, `metro://codex/...`) to notify a peer.
+
+## Line URI scheme
+
+`metro://<station>/<path>` — see [docs/uri-scheme.md](https://github.com/bonustrack/metro/blob/main/docs/uri-scheme.md) for the full grammar.
+
+| Station    | Pattern                                   | Example                              |
+|------------|-------------------------------------------|--------------------------------------|
+| `discord`  | `metro://discord/<channel-id>`            | `metro://discord/1234567890`         |
+| `telegram` | `metro://telegram/<chat-id>[/<topic-id>]` | `metro://telegram/-1001234567890/42` |
+| `claude`   | `metro://claude/<agent-id>/<session-id>`  | `metro://claude/9bfc7af0-…/50b00d11-…` |
+| `codex`    | `metro://codex/<agent-id>/<session-id>`   | `metro://codex/8119ecb1-…/01997d4b-…`  |
+| `webhook`  | `metro://webhook/<endpoint-id>`           | `metro://webhook/fwaCgTKJuLAjS2K0`     |
+
+The `messageId` is **not** part of the URI — it's a separate positional arg for `reply` / `edit` / `react` / `download`.
+
+## Image attachments
+
+When an event's `text` contains `[image]`:
+
+1. `metro download <line> <messageId>` — writes images to disk and prints absolute paths.
+2. `Read` each path with your Read tool — the image enters your context as a vision input.
+3. Reply normally with `metro reply`.
+
+## Opaque attachment markers
+
+`[voice]`, `[audio]`, and `[file: <name>]` are opaque — `metro download` only handles images. Acknowledge in text or ask the user to resend as a regular file.
+
+## Cross-agent notification
+
+Both agents can post to each other's "agent line":
+
+```bash
+metro send metro://claude/9bfc7af0-…/50b00d11-… "build green, ready to ship"
+metro send metro://codex/8119ecb1-…/01997d4b-… "build green" --from=metro://claude/user/9bfc7af0-…   # 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 `{"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
+
+- `metro lines` — list recently-seen conversations (sorted by recency).
+- `metro stations` — list stations + capability matrix.
+- `metro history` — universal message log (every inbound + outbound + notification across all stations). Newest first. Filters:
+  - `--limit=N` (default 50)
+  - `--line=<metro://…>` — only this conversation
+  - `--station=<discord|telegram|claude|codex|webhook>`
+  - `--kind=<inbound|outbound|edit|react|notification>`
+  - `--from=<sender>`
+  - `--text=<substring>`
+  - `--since=<iso>` — e.g. `--since=2026-05-14T00:00:00Z`
+  - `--json` — machine-parseable
+
+Every action you take is logged automatically — `metro send`/`reply`/`edit`/`react` append outbound entries, daemon-side inbounds + notifications append on arrival. Stored at `$METRO_STATE_DIR/history.jsonl`.
+
+## Universal message IDs
+
+The `id` from `metro history` or an event JSON works **anywhere a `<message_id>` argument is expected**:
+
+```bash
+# Either form works for reply/edit/react/download:
+metro reply <line> 4567                "ack"     # platform messageId (Telegram int)
+metro reply <line> msg_aB3xY7zP        "ack"     # universal — resolves via history
+```
+
+Use universal IDs when chaining commands or referring back to a specific message across stations.
+
+## Exit codes
+
+- `0` success
+- `1` usage error (bad args, unknown subcommand)
+- `2` configuration error (no tokens — tell the user to run `metro setup`)
+- `3` upstream error (rate limit, auth, network) — retry once after a few seconds before surfacing
+
+`metro doctor` diagnoses tokens, gateways, dispatcher liveness, and codex-rc target.
+
+## --json output
+
+Every command supports `--json` for stable parseable output:
+
+```bash
+metro reply <line> <messageId> "ack" --json
+# {"ok":true,"line":"metro://discord/...","replyTo":"...","messageId":"..."}
+
+metro fetch metro://discord/1234 --limit=10 --json
+# {"ok":true,"line":"...","messages":[{"messageId":"...","author":"...","text":"...","timestamp":"..."},...]}
+
+metro download <line> <messageId> --json
+# {"ok":true,"line":"...","files":[{"path":"/abs/...png","mediaType":"image/png"}]}
+```
+
+Use `--json` when you need to chain calls or capture the new `messageId` for a later edit.
+
+## Don'ts
+
+- ❌ Spawning a second metro daemon — there's one per machine (lockfile-enforced).
+- ❌ Posting to a line that isn't in `metro lines` unless the user gave it to you explicitly.
+- ❌ Narrating the tool ("I'll now use metro reply to…"). The tool call is already visible to the user.

package/dist/channels/discord.js

@@ -1,117 +0,0 @@
-import { Client, Events, GatewayIntentBits, Partials } from 'discord.js';
-import { errMsg, log } from '../log.js';
-let client = null;
-function getClient() {
-    if (client)
-        return client;
-    if (!process.env.DISCORD_BOT_TOKEN)
-        throw new Error('DISCORD_BOT_TOKEN is not set');
-    client = new Client({
-        intents: [
-            GatewayIntentBits.DirectMessages,
-            GatewayIntentBits.Guilds,
-            GatewayIntentBits.GuildMessages,
-            GatewayIntentBits.MessageContent,
-        ],
-        // DM channels arrive partial; without this messageCreate never fires.
-        partials: [Partials.Channel],
-    });
-    return client;
-}
-async function getTextChannel(channelId) {
-    const channel = await getClient().channels.fetch(channelId);
-    if (!channel?.isTextBased() || !('messages' in channel)) {
-        throw new Error(`discord: channel ${channelId} is not text-capable`);
-    }
-    return channel;
-}
-async function fetchMessage(channelId, messageId) {
-    return (await getTextChannel(channelId)).messages.fetch(messageId);
-}
-let onInboundHandler = () => { };
-export function onInbound(handler) {
-    onInboundHandler = handler;
-}
-export async function startGateway() {
-    const c = getClient();
-    c.on(Events.MessageCreate, m => {
-        if (m.author.bot)
-            return;
-        // Guild messages: only forward when the bot is mentioned. DMs always pass.
-        if (m.guildId && c.user && !m.mentions.has(c.user.id))
-            return;
-        const tags = [...m.attachments.values()]
-            .map(a => {
-            if (a.contentType?.startsWith('image/'))
-                return '[image]';
-            if (a.contentType?.startsWith('audio/'))
-                return `[audio: ${a.name}]`;
-            return `[file: ${a.name}]`;
-        })
-            .join(' ');
-        const text = [m.content, tags].filter(Boolean).join(' ').trim();
-        if (!text)
-            return;
-        onInboundHandler({ channel_id: m.channelId, message_id: m.id, text });
-    });
-    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()));
-}
-export async function getMe() {
-    const c = getClient();
-    if (!c.user)
-        throw new Error('discord: gateway not ready');
-    return { username: c.user.username };
-}
-export async function replyToMessage(channelId, messageId, text) {
-    await (await fetchMessage(channelId, messageId)).reply(text);
-}
-export async function editMessage(channelId, messageId, text) {
-    await (await fetchMessage(channelId, messageId)).edit(text);
-}
-export async function sendTyping(channelId) {
-    const channel = await getClient().channels.fetch(channelId);
-    if (!channel?.isTextBased() || !('sendTyping' in channel))
-        return;
-    await channel.sendTyping();
-}
-export async function setReaction(channelId, messageId, emoji) {
-    const target = await fetchMessage(channelId, messageId);
-    if (emoji) {
-        await target.react(emoji);
-        return;
-    }
-    // Clear only the bot's own reactions (matches Telegram's clear semantics).
-    const me = getClient().user;
-    if (!me)
-        return;
-    for (const r of target.reactions.cache.values()) {
-        if (r.users.cache.has(me.id))
-            await r.users.remove(me.id);
-    }
-}
-export async function fetchAttachments(channelId, messageId) {
-    const target = await fetchMessage(channelId, messageId);
-    const out = [];
-    for (const a of target.attachments.values()) {
-        if (!a.contentType?.startsWith('image/'))
-            continue;
-        const res = await fetch(a.url);
-        if (!res.ok)
-            throw new Error(`discord: download ${a.url}: ${res.status}`);
-        out.push({ data: Buffer.from(await res.arrayBuffer()).toString('base64'), mime: a.contentType });
-    }
-    return out;
-}
-export async function fetchRecentMessages(channelId, limit) {
-    const channel = await getTextChannel(channelId);
-    const msgs = await channel.messages.fetch({ limit: Math.min(Math.max(limit, 1), 100) });
-    // Discord returns newest-first; reverse for chronological.
-    return [...msgs.values()].reverse().map(m => ({
-        message_id: m.id,
-        author: m.author.username,
-        text: m.content,
-        timestamp: m.createdAt.toISOString(),
-    }));
-}