@stage-labs/metro 0.1.0-beta.8 → 0.1.0-beta.80

package/docs/agents.md

@@ -1,216 +0,0 @@
-# Metro: a guide for coding agents
-
-You are running inside a session that has **launched `metro`** in the background. Metro emits a live stream of JSON events from Discord, Telegram, third-party webhooks (GitHub, Intercom, …), and other agents on its stdout. Your job is to consume that stream and post replies back via subcommands.
-
-## Starting the bridge
-
-The launch mechanics differ by runtime — pick the one that matches yours.
-
-### Claude Code
-
-```
-Bash(command: "metro", run_in_background: true)
-```
-
-Then attach `Monitor` to its stdout. Each line is one JSON event you act on.
-
-### Codex
-
-```
-shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)
-```
-
-Don't watch its stdout — Codex has no Monitor equivalent. 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 and TUI running for this to work:
-
-```
-codex app-server --listen ws://127.0.0.1:8421       # daemon (terminal 1)
-codex --remote ws://127.0.0.1:8421                  # TUI (this session — terminal 2)
-```
-
-Run `metro doctor` if anything seems off.
-
-## Event shape
-
-Every event is a **history entry** — the same record that's appended to `history.jsonl`. Fields: `kind` (`inbound`/`notification`/`outbound`/`edit`/`react`), `id` (`msg_…`), `ts`, `station`, `line` (conversation), `lineName?`, `from` (participant URI), `fromName?`, `to`, `text`, `messageId?` (platform-side id; inbound/outbound only), `payload?` (raw platform message; inbound only).
-
-```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":"hello [image]","payload":{"message_id":4567,"chat":{"id":-100,"type":"supergroup","is_forum":true},"from":{"id":12345,"username":"alice"},"text":"hello","entities":[{"type":"mention","offset":0,"length":6}],"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 succeeded"}
-```
-
-### `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` (also `toJSON()`-shaped) 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: Record<string,string>, body: <parsed JSON | raw string> }`. Narrow further on the provider — GitHub sets `headers['x-github-event']` (`push`, `pull_request`, `issues`, …) and includes a `repository`/`sender` in body; Intercom sets `x-intercom-topic` etc. `text` is a short summary; full event is always in `payload.body`.
-
-Use `payload` for anything the envelope doesn't surface — mentions, reply chains, embeds, stickers, entities.
-
-Both `from` and `to` are **participant URIs** (the conversation lives in `line`): `metro://<station>/user/<id>` for a person, `metro://claude/user/<orgId>` for a Claude Code agent (orgId = stable Anthropic-account UUID), `metro://codex/user/<accountId>` for a Codex agent (accountId = stable ChatGPT-account UUID), `metro://<station>/<channelId>` as a fallback `to` when sending to a group with no single recipient.
-
-When **you** call `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from` to your runtime — `metro://claude/user/<orgId>` (when `$CLAUDECODE` is set; orgId comes from `claude auth status --json`) or `metro://codex/user/<accountId>` (when `$METRO_CODEX_RC`/`$CODEX_HOME` is set; accountId comes from `$CODEX_HOME/auth.json`, `tokens.account_id`). Both identities are account-scoped, not install-scoped: switch accounts with `claude auth login` / `codex login` and the next event uses the new id (within ~5 s for the daemon, immediately for one-shot CLI calls). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is auto-set to the original sender (history lookup).
-
-- `kind: "inbound"` — a human (or another bot) posted on a chat platform **or a third-party service POSTed to a registered webhook endpoint** (`station: "webhook"`, `payload: { headers, body }`).
-- `kind: "notification"` — another agent called `metro send` against your agent line. This is how Codex pings Claude Code and vice versa.
-
-`text` may include `[image]` / `[voice]` / `[audio]` / `[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 the event** to your visible output: `[<line>#<messageId>] <text>`. Both Monitor and Codex collapse tool output, so this echo is the only thing the user sees without expanding cards.
-2. **Decide and act** using the subcommands below.
-
-## Detecting "is this for me?"
-
-Derive from `payload`. Bot id per station is in `$METRO_STATE_DIR/bot-ids.json` (`{discord:"<userId>", telegram:"<userId>"}`).
-
-- **`discord`** — DM if `payload.guildId == null`; otherwise pinged if `payload.mentions.users.includes(<bot-id>)`.
-- **`telegram`** — DM if `payload.chat.type === 'private'`; otherwise pinged if 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 (you registered the endpoint). Route on `payload.headers['x-github-event']` / `x-intercom-topic` etc. to know which provider event it is.
-
-Default for chat: only reply on DM or ping; otherwise stay silent or `metro react` to ack. Webhooks just consume — no ack mechanism.
-
-## Subcommands
-
-| 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 it) | `metro react <line> <messageId> <emoji>` |
-| Download `[image]` attachments | `metro download <line> <messageId> [--out=<dir>]` |
-| Recent-message lookback (Discord only) | `metro fetch <line> [--limit=20]` |
-| Cross-agent ping | `metro send <agent-line> <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). Webhooks are receive-only — there's no `reply` for them, just consume the event.
-
-### Rich content flags
-
-`send` and `reply` accept these flags; `edit` accepts `--buttons` only.
-
-- `--image=<path>` — local image. **Repeatable** for albums: `--image=a.png --image=b.png` (or comma-separated). Up to 10 / message. Text becomes the caption (on the first image for albums).
-- `--document=<path>` — 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; on Discord uploaded as audio attachment.
-- `--buttons='[[{"text":"…","url":"…"}]]'` — inline URL-button keyboard (2D rows × buttons). Pass `'[]'` to `edit` to clear.
-
-```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> "voice note" --voice=/tmp/note.ogg
-metro send <line> "approve?" --buttons='[[{"text":"Open PR","url":"https://github.com/x/y/pull/1"}]]'
-```
-
-Limits: 20 MB / file. Telegram albums are single-type (photos OR documents per album); mixing kinds still works — metro splits into two messages. Buttons are dropped on multi-attachment Telegram sends. URL buttons only for now.
-
-Append `--json` to any command for a single JSON line you can parse.
-
-## When to use `reply` vs `send`
-
-- **`reply`** — responding to a specific inbound message. Threads under it. Default when handling an `inbound` event.
-- **`send`** — initiating without a triggering message: a long task you kicked off 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.
-
-## Universal message IDs
-
-The `id` field on every event and `metro history` row is metro's **universal ID** (`msg_<8 chars>`). It works anywhere a `<message_id>` is expected — `metro reply`, `edit`, `react`, `download` — and resolves to the platform's own id via the history file. Use it for chaining commands or referring back across stations.
-
-## `metro history` — read the universal message log
-
-Every inbound, outbound, edit, react, and notification is appended to `$METRO_STATE_DIR/history.jsonl` automatically.
-
-```bash
-metro history --limit=20                              # recent 20, newest first
-metro history --line=metro://discord/123              # only this conversation
-metro history --kind=inbound --since=2026-05-14       # inbounds since that day
-metro history --station=telegram --text=deploy        # all Telegram entries containing "deploy"
-metro history --from='@alice' --json                  # everything from alice, JSON
-```
-
-Filters: `--limit` (default 50), `--line`, `--station`, `--kind` (`inbound`/`outbound`/`edit`/`react`/`notification`), `--from`, `--text`, `--since` (ISO), `--json`.
-
-## Discovery
-
-### `metro lines`
-
-```
-$ metro lines
-2m ago    metro://discord/1234567890           infra
-5m ago    metro://telegram/-100123/42          design-review
-```
-
-Lines sorted by recency. Use when the user says "the Telegram channel" or "that PR thread."
-
-### `metro stations`
-
-```
-$ metro stations
-  ✓ discord    chat     in: text+image · out: text · features: reply, send, edit, react, download, fetch
-        DISCORD_BOT_TOKEN
-  ✓ telegram   chat     in: text+image · out: text · features: reply, send, edit, react, download, fetch
-        TELEGRAM_BOT_TOKEN
-  ✓ claude     agent    in: text · out: text · features: send, notify
-        account: 9bfc7af0-… · seen 1 agent, 2 sessions
-          seen: 9bfc7af0-… · sessions: 2
-  ✗ codex      agent    in: text · out: text · features: send, notify
-        set METRO_CODEX_RC=ws://… to push
-  ✓ webhook    service  in: text · out: – · features: –
-        2 endpoints · base https://webhook.example.com
-```
-
-`✓` = ready (env/runtime detected), `✗` = configured-but-broken or runtime not detected, `·` = informational. The detail line under each agent row shows the resolved account id plus the per-agent count of sessions metro has observed — pull addressable agent lines from those.
-
-## Webhooks (receiving HTTP events)
-
-When the user wants metro to receive events from a third-party service (GitHub PRs, Intercom conversations, Fireflies meetings, …):
-
-1. **One-time tunnel setup** (only needed once per machine): `metro tunnel setup <tunnel-name> <hostname>`. Requires `cloudflared` on PATH (`brew install cloudflared`) and a Cloudflare account + domain on Cloudflare DNS. Run `cloudflared tunnel login` first if you haven't.
-2. **Register an endpoint**: `metro webhook add <label> [--secret=<shared-secret>]`. Prints the public URL — paste it into the provider's webhook settings. For GitHub specifically, set **Content type: `application/json`** (form-encoded won't parse into `payload.body`).
-3. **Run the daemon**: `metro`. With at least one endpoint registered, metro auto-binds the HTTP listener (port 8420, override `METRO_WEBHOOK_PORT`) and spawns `cloudflared tunnel run` if `tunnel.json` exists.
-
-Each POST becomes an inbound event:
-
-```json
-{"kind":"inbound","station":"webhook","line":"metro://webhook/<id>","lineName":"github",
- "from":"metro://webhook/<id>","to":"metro://claude/user/<orgId>",
- "messageId":"<x-github-delivery>","text":"push POST /wh/<id>",
- "payload":{"headers":{"x-github-event":"push",…},"body":{"ref":"refs/heads/main",…}}}
-```
-
-`text` is a short summary; the real event lives in `payload.body`. Use `payload.headers['x-github-event']` (or `x-intercom-topic` etc.) to narrow on provider event type. If you set `--secret`, metro verifies `X-Hub-Signature-256` and rejects bad signatures with 401 — agents see only authenticated events.
-
-## Image attachments
-
-When an inbound has an `[image]` tag in `text`:
-
-1. `metro download <line> <messageId>` → prints absolute paths.
-2. `Read` each path with your `Read` tool — the image enters your context as a vision input.
-3. Reply normally via `metro reply`.
-
-## Cross-agent notification
-
-Both agents can post to each other's **agent line** — `metro://claude/<agent-id>/<session-id>` or `metro://codex/<agent-id>/<session-id>`. `<agent-id>` is the peer's stable account id (cross-device); `<session-id>` is one conversation. Discover both by running `metro stations` (which lists every agent + session metro has seen), or by reading `$METRO_STATE_DIR/agent-registry.json` directly. The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer agent sees it as a notification:
-
-```bash
-metro send metro://claude/9bfc7af0-…/50b00d11-… "build green, ready to ship"
-metro send metro://claude/9bfc7af0-…/50b00d11-… "build green" --from=metro://codex/user/8119ecb1-…   # override sender
-```
-
-This requires the metro daemon to be running on the machine. Without a daemon, agent-line sends error with a clear message.
-
-## Don'ts
-
-- ❌ Spawning a second metro daemon — there's one per machine (lockfile-enforced).
-- ❌ `metro send` 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.
-
-## Further reading
-
-- URI scheme: [`uri-scheme.md`](uri-scheme.md)
-- Source: https://github.com/bonustrack/metro

package/docs/uri-scheme.md

@@ -1,125 +0,0 @@
-# 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/skills/metro/SKILL.md

@@ -1,249 +0,0 @@
----
-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 to your visible output**: `[<line>#<messageId>] <text>` on its own line. Both Claude Code's Monitor and Codex collapse tool output, so this echo is the only way the user sees what arrived without expanding cards.
-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.