@stage-labs/metro 0.1.0-beta.13 → 0.1.0-beta.15

package/examples/telegram.ts

@@ -0,0 +1,121 @@
+/**
+ * Reference train — Telegram (long-polling, no npm deps). Pattern is identical for any platform.
+ *
+ * Setup:
+ *   cp <this-file> ~/.metro/trains/telegram.ts
+ *   echo 'TELEGRAM_BOT_TOKEN=…' >> ~/.metro/.env
+ *
+ * Discord-flavoured port: swap the API base + `tg()` helper for `https://discord.com/api/v10`
+ * with `Authorization: Bot $TOKEN`, install `discord.js` for the gateway, and emit the same
+ * envelope shape. The stdin/stdout protocol is platform-independent. Discord adds `sticker_ids`
+ * support on `sendMessage` payloads — preserve those in `payload` so downstream tooling sees them.
+ */
+
+const TOKEN = process.env.TELEGRAM_BOT_TOKEN;
+if (!TOKEN) { process.stderr.write('TELEGRAM_BOT_TOKEN unset\n'); process.exit(2); }
+const API = `https://api.telegram.org/bot${TOKEN}`;
+
+const emit = (e: unknown): void => void process.stdout.write(JSON.stringify(e) + '\n');
+const respond = (id: string, body: { result?: unknown; error?: string }): void =>
+  void process.stdout.write(JSON.stringify({ op: 'response', id, ...body }) + '\n');
+const mintId = (): string => `msg_${Math.random().toString(36).slice(2, 10)}`;
+/** Self URI for outbound emissions. Set by the supervisor; trains echo their own sends so mobile + tail see them. */
+const SELF_URI = process.env.METRO_SELF_URI ?? '';
+const emitOutbound = (line: string, messageId: string, text: string, replyTo?: string): void => emit({
+  kind: 'outbound', id: mintId(), ts: new Date().toISOString(),
+  station: 'telegram', line, from: SELF_URI, to: line, message_id: messageId, text, reply_to: replyTo,
+});
+
+async function tg<T>(method: string, body: unknown, timeoutMs = 30_000): Promise<T> {
+  const res = await fetch(`${API}/${method}`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs),
+  });
+  const json = (await res.json()) as { ok: boolean; description?: string; result?: T };
+  if (!json.ok) throw new Error(`telegram ${method}: ${json.description ?? 'unknown'}`);
+  return json.result as T;
+}
+
+type TgMsg = {
+  message_id: number; date: number;
+  chat: { id: number; type: string; title?: string; first_name?: string };
+  from?: { id: number; username?: string; first_name?: string; is_bot?: boolean };
+  text?: string; caption?: string;
+  message_thread_id?: number; is_topic_message?: boolean;
+  photo?: unknown[]; document?: { file_name?: string };
+};
+
+function envelope(m: TgMsg): Record<string, unknown> {
+  const tags = [...(m.photo?.length ? ['[image]'] : []), ...(m.document ? [`[file: ${m.document.file_name ?? 'doc'}]`] : [])];
+  const text = [m.text ?? m.caption, ...tags].filter(Boolean).join(' ');
+  const topicId = m.is_topic_message ? m.message_thread_id : undefined;
+  const line = topicId !== undefined ? `metro://telegram/${m.chat.id}/${topicId}` : `metro://telegram/${m.chat.id}`;
+  return {
+    kind: 'inbound', id: mintId(), ts: new Date(m.date * 1000).toISOString(),
+    station: 'telegram', line,
+    line_name: topicId === undefined ? (m.chat.title ?? m.chat.first_name ?? undefined) : undefined,
+    from: `metro://telegram/user/${m.from?.id ?? 'unknown'}`,
+    from_name: m.from?.username ? `@${m.from.username}` : m.from?.first_name,
+    message_id: String(m.message_id), text, payload: m, is_private: m.chat.type === 'private',
+  };
+}
+
+const targetOf = (line: string): { chatId: number; topicId?: number } => {
+  const m = line.match(/^metro:\/\/telegram\/(-?\d+)(?:\/(\d+))?/);
+  if (!m) throw new Error(`bad telegram line: ${line}`);
+  return { chatId: Number(m[1]), topicId: m[2] ? Number(m[2]) : undefined };
+};
+
+type CallMsg = { op: 'call'; id: string; action: string; args: Record<string, unknown> };
+async function handleCall({ id, action, args }: CallMsg): Promise<void> {
+  try {
+    if (action === 'send') {
+      const { line, text, replyTo } = args as { line: string; text: string; replyTo?: string };
+      const { chatId, topicId } = targetOf(line);
+      const body: Record<string, unknown> = { chat_id: chatId, text };
+      if (topicId !== undefined) body.message_thread_id = topicId;
+      if (replyTo) body.reply_parameters = { message_id: Number(replyTo) };
+      const sent = await tg<{ message_id: number }>('sendMessage', body);
+      const sentId = String(sent.message_id);
+      emitOutbound(line, sentId, text, replyTo);
+      respond(id, { result: { messageId: sentId } });
+    } else if (action === 'react') {
+      const { line, messageId, emoji } = args as { line: string; messageId: string; emoji: string };
+      await tg('setMessageReaction', {
+        chat_id: targetOf(line).chatId, message_id: Number(messageId),
+        reaction: emoji ? [{ type: 'emoji', emoji }] : [],
+      });
+      respond(id, { result: { ok: true } });
+    } else respond(id, { error: `unknown action '${action}' (have: send, react)` });
+  } catch (err) { respond(id, { error: (err as Error).message }); }
+}
+
+let buf = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf('\n')) !== -1) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    try { const msg = JSON.parse(line); if (msg.op === 'call') void handleCall(msg); }
+    catch (err) { process.stderr.write(`bad stdin line: ${(err as Error).message}\n`); }
+  }
+});
+
+let offset = 0;
+process.stderr.write('telegram train ready\n');
+while (true) {
+  try {
+    const updates = await tg<{ update_id: number; message?: TgMsg }[]>('getUpdates',
+      { offset, timeout: 25, allowed_updates: ['message'] }, 60_000);
+    for (const u of updates) {
+      offset = u.update_id + 1;
+      if (u.message && !u.message.from?.is_bot) emit(envelope(u.message));
+    }
+  } catch (err) {
+    process.stderr.write(`telegram poll error: ${(err as Error).message}\n`);
+    await new Promise(r => setTimeout(r, 2_000));
+  }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.15",
   "private": false,
-  "description": "Live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session. The user launches metro; metro emits inbounds on stdout and accepts replies via CLI subcommands.",
+  "description": "Event-interception wire. Supervises train subprocesses in ~/.metro/trains/, multiplexes their JSON event stream onto stdout, and routes outbound action calls back via stdin. Per-platform code is written by the agent (or user) as train scripts — metro core is pure transport.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "skills",
     "README.md",
     "LICENSE"
@@ -30,18 +31,18 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "tsc",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
+    "lint": "eslint src/ examples/",
+    "lint:fix": "eslint src/ examples/ --fix",
     "typecheck": "tsc --noEmit",
     "test": "METRO_STATE_DIR=\"$(mktemp -d /tmp/metro-test.XXXXXX)\" bun test test/"
   },
   "dependencies": {
-    "discord.js": "^14.14.0",
     "pino": "^9.5.0",
     "pino-pretty": "^13.1.3",
     "ws": "^8.20.0"
   },
   "devDependencies": {
+    "@types/bun": "^1.2.0",
     "@types/node": "^22.10.0",
     "@types/ws": "^8.18.1",
     "eslint": "^10.3.0",

package/skills/metro/SKILL.md

@@ -1,256 +1,110 @@
 ---
 name: metro
-description: Run the metro Telegram/Discord/webhook relay 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.
+description: Run the metro train-supervisor 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 `{"station":"…","line":"metro://…","from":"…","to":"…","text":"…"}`, or when handling a chat/webhook reply/edit/react/send via `metro call`.
 ---
 
-# Metro — running the Telegram / Discord / webhook relay
+# Metro — event-interception wire
 
-Metro is a CLI that relays between this 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>`.
+Metro is the wire between this session and any number of platforms. Platform code lives in
+**trains** under `~/.metro/trains/` — single TS files that you (the agent) write, edit, or
+replace on demand.
 
-## Starting metro
+## What metro does
 
-When the user asks to run/start/launch metro:
+1. Spawns each file in `~/.metro/trains/*.{ts,js,mjs}` as a long-running Bun subprocess.
+2. Multiplexes their stdout (JSON lines) into one unified event stream on metro's stdout.
+3. Routes `metro call <train> <action> <args>` requests back to the matching train's stdin.
+4. Two builtin event sources stay in core: **webhooks** (HTTP receiver) and **messenger** (in-daemon chat).
 
-### Claude Code
+## Starting metro
 
-```
-Bash(command: "metro", run_in_background: true)
-```
+**Claude Code:** `Bash(command: "metro", run_in_background: true)`, then attach `Monitor` to its stdout.
 
-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)` — metro pushes each event via JSON-RPC `turn/start`. The user must run a Codex daemon + TUI on the same WebSocket URL (`codex app-server --listen ws://127.0.0.1:8421` + `codex --remote ws://127.0.0.1:8421`, type "hi" once to seed a thread).
 
-### Codex
+`metro doctor` reports trains found, deps installed, dispatcher running, codex-rc, skill install.
 
-```
-shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)
-```
+## Envelope
 
-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**:
+Every event on stdout is a single JSON line:
 
-```
-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
+```json
+{"id":"msg_…","ts":"2026-05-17T18:00:00Z","station":"discord","line":"metro://discord/123","line_name":"infra","from":"metro://discord/user/456","from_name":"alice","to":"metro://claude/user/9bfc…","text":"hi","message_id":"789","reply_to":"…","payload":{…}}
 ```
 
-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.
+Wire fields are `snake_case` on the train protocol; the dispatcher translates to camelCase for `history.jsonl`. Trains supply `line`, `from`, `to`, `text`, plus `payload` (the platform's native message). Metro mints `id` + `display` if missing.
 
-### Diagnostics
+**No `kind` field.** Direction is derived: `Line.isLocal(from)` → outbound (📤), else inbound (📩). Reactions and edits are train-specific — encode them in `text` (e.g. `[react 👀]`) plus whatever you need in `payload`.
 
-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.
+## Outbound: `metro call <train> <action> <args>`
 
-## Event shape
-
-Every line on stdout is one **history entry** — the same record appended to `history.jsonl`. Fields:
-- `kind` — `"inbound"`, `"outbound"`, `"edit"`, or `"react"`. Inbound `react` events fire when a human adds an emoji reaction in Discord/Telegram — `emoji` is set, `text` is omitted, `messageId` is the message that got reacted to.
-- `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 (local user for DMs, conversation `line` for groups, 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":"inbound","id":"msg_pQ4r5sT0","ts":"…","station":"claude","line":"metro://claude/9bfc7af0-…/50b00d11-…","from":"metro://codex/user/8119ecb1-…","to":"metro://claude/9bfc7af0-…/50b00d11-…","text":"deploy green"}
+metro call discord send '{"line":"metro://discord/123","text":"hi","replyTo":"789"}'
+metro call telegram react '{"line":"metro://telegram/-100/1","messageId":"42","emoji":"👀"}'
+metro call discord edit  '{"line":"metro://discord/123","messageId":"999","text":"new"}'
 ```
 
-### `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 user (orgId = stable Anthropic-account UUID, same across devices for the same account)
-- `metro://codex/user/<accountId>` — a Codex user (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 message arrived. Source can be a human on Discord/Telegram, a webhook POST, or another Claude / Codex user posting to your line via `metro send` (cross-process).
-
-`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.
+`[args]` can be JSON, `@path/to/args.json`, `-` (stdin), or a bare string. Action names are whatever the train exposes — metro core knows nothing about them.
 
-2. **Decide and act** using the subcommands below.
+## Writing a new train
 
-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.
+1. Start from `node_modules/@stage-labs/metro/examples/telegram.ts`.
+2. Copy → `~/.metro/trains/<name>.ts` and edit. Keep the inbound envelope shape and the `op:"call"` → `op:"response"` protocol.
+3. Deps (if needed): `cd ~/.metro && bun add <pkg>`. Credentials: `echo 'FOO_TOKEN=…' >> ~/.metro/.env`.
+4. Restart the metro daemon (or just `metro trains restart <name>`) to pick up the new train.
 
-## Subcommands
+Trains are throwaway — if the user asks for new functionality, rewrite the train rather than adding glue in core.
 
-All take positional args (no `--to=`/`--text=` flags). Append `--json` to any for a parseable single-line result.
+## First-run setup (once per machine)
 
-| 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 user (cross-user line) | `metro send metro://claude/<user-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 a Claude / Codex 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/<user-id>/<session-id>`   | `metro://claude/9bfc7af0-…/50b00d11-…` |
-| `codex`    | `metro://codex/<user-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-user notification
-
-Both Claude Code and Codex can post to each other's 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
+mkdir -p ~/.metro && cd ~/.metro && bun init -y
+cp node_modules/@stage-labs/metro/examples/telegram.ts ~/.metro/trains/
+echo 'TELEGRAM_BOT_TOKEN=…' >> ~/.metro/.env
+metro setup skill    # optional — installs this SKILL.md into ~/.claude / ~/.codex
+metro
 ```
 
-The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer sees an `{"kind":"inbound",...}` event. Requires the metro daemon to be running on the machine — Claude / Codex 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 + edit + react 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>`
-  - `--from=<sender>`
-  - `--text=<substring>`
-  - `--since=<iso>` — e.g. `--since=2026-05-14T00:00:00Z`
-  - `--json` — machine-parseable
+## Detecting "is this for me?"
 
-Every action you take is logged automatically — `metro send`/`reply`/`edit`/`react` append outbound entries, daemon-side inbounds append on arrival. Stored at `$METRO_STATE_DIR/history.jsonl`.
+Trains should set `is_private: true` for DMs. For groups, narrow on `payload`:
 
-## Universal message IDs
+- **discord** — DM when `payload.guildId == null`; otherwise look at `payload.mentions.users`.
+- **telegram** — DM when `payload.chat.type === 'private'`; otherwise look at `payload.entities` mentions.
+- **webhook** — every POST is for you by design. Route on `payload.headers['x-github-event']` / `x-intercom-topic`.
+- **messenger** — every event on the messenger line is between the user and the agent. No filtering needed.
 
-The `id` from `metro history` or an event JSON works **anywhere a `<message_id>` argument is expected**:
+## CLI cheat sheet
 
-```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
+```
+metro                                       # start the daemon
+metro trains [list]                         # list trains + state
+metro trains new <name>                     # scaffold ~/.metro/trains/<name>.ts
+metro trains restart <name>                 # kill + respawn a train (resets backoff)
+metro call <train> <action> <args>          # forward an action call
+metro tail [--as=<user-uri>] [--follow]     # subscribe to the event log
+metro history [--limit=N] [--line=…] [--from=…] [--text=…] [--since=…]
+metro webhook add <label>                   # register an HTTP receive endpoint
+metro tunnel setup <name> <hostname>        # configure a Cloudflare named tunnel
+metro doctor                                # health check
 ```
 
-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
+## Webhooks (builtin source)
 
-Every command supports `--json` for stable parseable output:
+Webhooks stay in core because they're shared HTTP infra (one Cloudflare tunnel routes many endpoints). `metro webhook add <label>` issues an endpoint id; the full URL is `https://<tunnel-host>/wh/<id>` (or `http://127.0.0.1:8420/wh/<id>` locally). Events arrive on `metro://webhook/<id>`.
 
-```bash
-metro reply <line> <messageId> "ack" --json
-# {"ok":true,"line":"metro://discord/...","replyTo":"...","messageId":"..."}
+## Messenger (builtin source)
 
-metro fetch metro://discord/1234 --limit=10 --json
-# {"ok":true,"line":"...","messages":[{"messageId":"...","author":"...","text":"...","timestamp":"..."},...]}
+Direct chat between the agent and the device. Five endpoints — all under the same bearer-token guard as `/api/state`:
 
-metro download <line> <messageId> --json
-# {"ok":true,"line":"...","files":[{"path":"/abs/...png","mediaType":"image/png"}]}
-```
+- `POST /api/messenger/send {text?, attachments?, as?}` — emit an envelope on `metro://messenger/owner`. Either text or attachments required.
+- `POST /api/messenger/react {messageId, emoji, as?}` — emit a slim `payload.reactTo` envelope. If the sender already has an active reaction with this emoji on this target, emits `{removed: true}` instead — reactions are toggleable.
+- `POST /api/messenger/upload` — raw binary upload (≤ 25 MiB, body = file bytes, `Content-Type` + optional `X-Filename` headers). Returns `{id, url, kind, mime, size, name?}`; files land in `$METRO_STATE_DIR/messenger-uploads/`.
+- `GET /api/messenger/files/<name>` — stream a stored upload. Accepts `Authorization: Bearer …` header *or* `?token=…` query (for `<img>` / `<audio>` tags). Content-Type derived from extension.
+- `POST /api/messenger/register {pushToken}` — store an Expo push token so agent replies push to the device.
 
-Use `--json` when you need to chain calls or capture the new `messageId` for a later edit.
+The mobile + web companion apps use these for chat with the agent. The envelope is the standard slim shape — no `kind` / `emoji` fields, direction derived from `Line.isLocal(from)`.
 
-## Don'ts
+## Crashes
 
-- ❌ 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.
+If a train crashes, metro restarts it with backoff (1s → 5s → 30s, then gives up after 5 consecutive failures). Use `metro trains` to check state.

package/dist/cache.js

@@ -1,69 +0,0 @@
-/** 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');
-export 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');
-    }
-}