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

package/README.md

@@ -1,8 +1,8 @@
 # Metro
 
-> **A live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session.**
+> **A live JSON stream of Telegram, Discord, webhooks, and cross-agent messages for your local Claude Code / Codex session.**
 
-Metro is a small daemon you launch from inside your agent. It connects to Discord and Telegram, emits each inbound as one JSON line on stdout (which Claude Code's `Monitor` consumes natively, and Codex picks up via an app-server WebSocket push), and exposes a tiny CLI — `metro reply`, `metro send`, `metro edit`, `metro react`, `metro download`, `metro fetch`, `metro notify` — for posting back. Cross-agent: any agent can ping any other via `metro send metro://claude/<topic>` and the daemon re-emits it on the stream.
+Metro is a small daemon you launch from inside your agent. It connects to Discord, Telegram, and any third-party service that can POST a webhook (GitHub, Intercom, Fireflies, …), emits each inbound as one JSON line on stdout (which Claude Code's `Monitor` consumes natively, and Codex picks up via an app-server WebSocket push), and exposes a tiny CLI — `metro reply`, `metro send`, `metro edit`, `metro react`, `metro download`, `metro fetch` — for posting back. Cross-agent: any agent can ping any other via `metro send metro://claude/<agent-id>/<session-id>` and the daemon re-emits it on the stream.
 
 ```
 [Claude Code session]
@@ -10,8 +10,10 @@ Metro is a small daemon you launch from inside your agent. It connects to Discor
 $ metro &                              # backgrounded
 $ Monitor( … metro's stdout … )
 
->>> {"type":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
-     "text":"@bot we got a 5xx spike from /v1/sync. Look?","mentionsBot":true,…}
+>>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
+     "text":"@bot we got a 5xx spike from /v1/sync. Look?",
+     "payload":{"channelId":"123…","guildId":"456…","content":"<@…> we got a 5xx spike…",
+                "mentions":{"users":["<bot-id>"],"roles":[],"everyone":false},…}}
 
   [I'd run git log + read services/sync.ts, then…]
   Bash: metro reply metro://discord/123… 9876 "three deploys in the last 24h…"
@@ -41,20 +43,23 @@ In **Discord**: DM the bot, or `@<bot>` in any channel. In **Telegram**: DM, or
 ## Architecture
 
 ```
-Discord gateway ──┐
-Telegram poller ──┤
-                  │
-                  ├─▶ metro daemon ───▶ stdout (JSON events; Claude Code's Monitor reads here)
-                  │                ───▶ codex-rc WebSocket (Codex turn/start; opt-in)
-                  │                ◀── IPC Unix socket  (metro notify / metro send to agent lines)
-                  │
-agent CLI calls ──┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
+Discord gateway     ──┐
+Telegram poller     ──┤
+Cloudflare tunnel   ──┤ ── HTTP webhooks (GitHub, Intercom, …)
+                      │
+                      ├─▶ metro daemon ───▶ stdout (JSON events; Claude Code's Monitor reads here)
+                      │                ───▶ codex-rc WebSocket (Codex turn/start; opt-in)
+                      │                ◀── IPC Unix socket  (metro send to agent lines)
+                      │
+agent CLI calls   ────┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
 ```
 
 - **Inversion of control.** The agent (Claude Code, Codex) launches `metro`, not the other way around. Metro never spawns an agent process.
 - **Single daemon per machine.** Lockfile at `$METRO_STATE_DIR/.tail-lock` enforces singleton.
+- **Account-tied identity.** `to` on inbound and `from` on outbound resolve to a stable account-scoped URI per runtime: `metro://claude/user/<orgId>` (from `claude auth status --json`) or `metro://codex/user/<accountId>` (from `$CODEX_HOME/auth.json`). Same on any device for the same logged-in account.
 - **Codex push (opt-in).** Set `METRO_CODEX_RC=ws://127.0.0.1:8421` and metro pushes each event via JSON-RPC `turn/start` to the Codex app-server. Codex's TUI must be attached with `--remote` to the same URL.
-- **Cross-agent notification.** `metro send metro://claude/<topic>` or `metro notify metro://codex/<topic>` routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer agent sees it.
+- **Cross-agent notification.** `metro send metro://claude/<agent-id>/<session-id>` (or `metro://codex/<agent-id>/<session-id>`) routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer agent sees it. Discover reachable agents/sessions via `metro stations` or `$METRO_STATE_DIR/agent-registry.json`.
+- **Webhooks (opt-in).** `metro webhook add <label>` registers an HTTP receive endpoint; the daemon binds `127.0.0.1:8420` (override with `$METRO_WEBHOOK_PORT`). If you've run `metro tunnel setup`, a Cloudflare named tunnel exposes it publicly. Each POST is re-emitted on stdout as an inbound event.
 
 ---
 
@@ -62,12 +67,13 @@ agent CLI calls ──┴── REST → Discord / Telegram   (metro reply / sen
 
 Each endpoint is a **station** with declared capabilities:
 
-| Station    | Kind  | Modalities    | Features                                              | Config                                                      |
-|------------|-------|---------------|-------------------------------------------------------|-------------------------------------------------------------|
-| `discord`  | chat  | text + image  | reply, send, edit, react, download, fetch             | `DISCORD_BOT_TOKEN` + Message Content Intent                |
-| `telegram` | chat  | text + image  | reply, send, edit, react, download                    | `TELEGRAM_BOT_TOKEN`                                        |
-| `claude`   | agent | text          | notify                                                | watches metro stdout via Claude Code's `Monitor`            |
-| `codex`    | agent | text          | notify                                                | set `METRO_CODEX_RC=ws://…` to push                         |
+| Station    | Kind    | Modalities    | Features                                              | Config                                                                                  |
+|------------|---------|---------------|-------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| `discord`  | chat    | text + image  | reply, send, edit, react, download, fetch             | `DISCORD_BOT_TOKEN` + Message Content Intent                                            |
+| `telegram` | chat    | text + image  | reply, send, edit, react, download                    | `TELEGRAM_BOT_TOKEN`                                                                    |
+| `claude`   | agent   | text          | send, notify                                          | auto-detected from `$CLAUDECODE`; identity via `claude auth status --json`              |
+| `codex`    | agent   | text          | send, notify                                          | auto-detected from `$METRO_CODEX_RC` / `$CODEX_HOME`; identity via `$CODEX_HOME/auth.json` |
+| `webhook`  | service | text          | (receive-only; optional HMAC verify)                  | `metro webhook add <label>` + `metro tunnel setup` (Cloudflare named tunnel)            |
 
 Run `metro stations` to see live config status (`✓` configured, `✗` not, `·` informational).
 
@@ -77,6 +83,39 @@ Behaviors worth knowing:
 - **Image attachments inbound** — `[image]` placeholders surface inline in `text`; the agent calls `metro download` to materialize them. 20 MB cap.
 - **Rich content outbound.** `metro send` / `reply` accept `--image=<path>` (repeatable: albums of up to 10), `--document=<path>` (repeatable), `--voice=<path>` (single voice message — Telegram renders the voice bubble), and `--buttons='[[{"text":"…","url":"…"}]]'` for inline URL-button keyboards. `metro edit` accepts `--buttons` (pass `'[]'` to clear). 20 MB / file. URL buttons only for now — no callback/interactive components.
 - **Telegram non-forum groups are skipped.** No thread boundary to scope on.
+- **Webhook signature verification.** Pass `--secret=<shared-secret>` to `metro webhook add` and the daemon verifies `X-Hub-Signature-256` (GitHub/Intercom format) on every POST. Mismatches return 401 and never reach the stream.
+
+---
+
+## Webhooks
+
+Receive HTTP events from third parties (GitHub, Intercom, Fireflies, anything that POSTs) as standard metro inbound events. Each registered endpoint is one Line.
+
+```bash
+# One-time per machine — bring your own Cloudflare domain (free Registrar at-cost):
+brew install cloudflared
+cloudflared tunnel login                       # browser OAuth, pick your domain
+metro tunnel setup metro webhook.example.com   # creates tunnel + DNS CNAME
+
+# Per endpoint — repeat for each provider:
+metro webhook add github --secret=$(openssl rand -hex 32)
+# → https://webhook.example.com/wh/<id>
+# (without `metro tunnel setup`, falls back to http://127.0.0.1:8420/wh/<id> — local-only)
+
+metro                                          # daemon binds 8420 + spawns cloudflared automatically
+```
+
+Paste the URL into the provider's webhook settings (for GitHub: **Content type must be `application/json`** — form-encoded won't parse). Every POST becomes an inbound event with `station: "webhook"`, `line: metro://webhook/<id>`, `payload: { headers, body }`. If you set `--secret`, metro verifies the `X-Hub-Signature-256` header (GitHub/Intercom format) and rejects mismatches with 401.
+
+| Action | Command |
+|---|---|
+| Register an endpoint | `metro webhook add <label> [--secret=<shared-secret>]` |
+| List endpoints + URLs | `metro webhook list` |
+| Remove an endpoint | `metro webhook remove <id>` |
+| One-time tunnel setup | `metro tunnel setup <tunnel-name> <hostname>` |
+| Tunnel status | `metro tunnel status` |
+
+The tunnel is optional — without it the listener binds `127.0.0.1:8420` only (good for local testing or your own loopback tools). With Cloudflare named tunnels, the URL stays stable across daemon restarts and machines. See [docs/uri-scheme.md](docs/uri-scheme.md) and [docs/agents.md](docs/agents.md) for the full event shape.
 
 ---
 
@@ -88,8 +127,9 @@ Every conversational scope is identified by a **Line** — a URI in the form `me
 metro://discord/1234567890123456789
 metro://telegram/-1001234567890                 # main chat / DM
 metro://telegram/-1001234567890/42              # forum topic 42
-metro://claude/deploys                          # agent notification sink
-metro://codex/ci
+metro://claude/9bfc7af0-…/50b00d11-…            # claude agent session
+metro://codex/8119ecb1-…/01997d4b-…             # codex agent session
+metro://webhook/fwaCgTKJuLAjS2K0                # HTTP webhook endpoint
 ```
 
 Anyone can post to a line via [`metro send`](#cli) — daemon required only for agent lines. Full grammar in [`docs/uri-scheme.md`](docs/uri-scheme.md).
@@ -115,9 +155,12 @@ metro react <line> <message_id> <emoji>     Set or clear ('') a reaction.
 metro download <line> <message_id> [--out=<dir>]
                                             Download image attachments to disk.
 metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
-metro notify <line> <text> [--from=<line>]  Emit a notification on the daemon's stream.
 metro history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
                                             Universal message log (every inbound + outbound), newest first.
+metro webhook add <label> [--secret=…]      Register an HTTP receive endpoint (GitHub, Intercom, …).
+metro webhook list | remove <id>            List or remove webhook endpoints.
+metro tunnel setup <name> <hostname>        Configure a Cloudflare named tunnel for public webhook URLs.
+metro tunnel status                         Show current tunnel config.
 metro update                                Upgrade in place.
 ```
 
@@ -125,9 +168,13 @@ All commands accept `--json`. `reply` / `send` / `edit` read multi-line `<text>`
 
 **State files** in `$METRO_STATE_DIR` (default `~/.cache/metro`):
 - `AGENTS.md` — agent skill copied from the package on every start (so the path is stable across upgrades)
-- `history.jsonl` — universal message log (one JSON object per line; append-only). Read with `metro history`. Each entry carries `from` and `to` as universal participant URIs (`metro://<station>/user/<id>`, `metro://claude/<topic>`, `metro://codex/<topic>`) plus a `fromName` display field. The dispatcher auto-detects the consuming agent for `to` on inbound (`$CLAUDECODE` → `metro://claude/agent`; `$METRO_CODEX_RC`/`$CODEX_HOME` → `metro://codex/agent`).
+- `history.jsonl` — universal message log (one JSON object per line; append-only). Read with `metro history`. Each entry carries `from` and `to` as universal participant URIs (`metro://<station>/user/<id>`, `metro://claude/user/<orgId>`, `metro://codex/user/<accountId>`) plus a `fromName` display field. The dispatcher auto-detects the consuming agent for `to` on inbound (`$CLAUDECODE` → `metro://claude/user/<orgId>` from `claude auth status --json`; `$METRO_CODEX_RC`/`$CODEX_HOME` → `metro://codex/user/<accountId>` from `$CODEX_HOME/auth.json`).
 - `bot-ids.json` — `{discord: "<botUserId>", telegram: "<botUserId>"}` written by the daemon on startup (cached for the few historical lookups that still need a bot identity).
 - `lines.json` — line → last-seen / name cache (read by `metro lines`)
+- `agent-registry.json` — every `(station, agent-id, sessions[])` tuple metro has seen; surfaced under each agent row in `metro stations`
+- `stations/codex/session-id` — current codex-rc thread id (daemon writes on handshake; CLI processes read for `metro://codex/<agent-id>/<session>`)
+- `webhooks.json` — registered HTTP receive endpoints (id, label, optional shared secret)
+- `tunnel.json` — Cloudflare named-tunnel config (`{name, hostname}`); when present, the daemon spawns `cloudflared tunnel run`
 - `.tail-lock` — dispatcher pid
 - `metro.sock` — daemon IPC socket
 - `telegram-offset.json` — last processed update id
@@ -140,8 +187,12 @@ All commands accept `--json`. `reply` / `send` / `edit` read multi-line `<text>`
 |---|---|---|
 | `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN` | — | Bot tokens. `metro setup` writes them here. |
 | `METRO_CODEX_RC` | — | Codex app-server URL (`ws://…`, `wss://…`, `unix:///…`). When set, the daemon pushes each event via JSON-RPC `turn/start`. |
+| `METRO_WEBHOOK_PORT` | `8420` | Local port the HTTP webhook listener binds to (always `127.0.0.1`; expose publicly via Cloudflare tunnel). |
+| `METRO_AGENT_ID` | — | Override the resolved agent id (orgId / accountId) used in `metro://<station>/user/<id>` and `metro://<station>/<id>/<session>`. Useful for testing. |
+| `METRO_AGENT_SESSION_ID` | — | Override the resolved session id (Claude session / Codex thread). |
+| `METRO_FROM` | — | Pin a custom `from` URI for all writes (overrides runtime detection). |
 | `METRO_CONFIG_DIR` | `~/.config/metro` | Where the global `.env` lives. |
-| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, IPC socket, telegram offset. |
+| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, IPC socket, telegram offset, registries, tunnel config. |
 | `METRO_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
 
 Precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs go to stderr.
@@ -162,12 +213,16 @@ bun run lint                             # eslint
 
 Source map:
 
-- [`src/cli/`](src/cli/) — `metro` binary entry ([`index.ts`](src/cli/index.ts)) + admin commands ([`config.ts`](src/cli/config.ts): setup/doctor/update) + shared CLI primitives ([`util.ts`](src/cli/util.ts)).
-- [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: starts each chat station, emits events on stdout, listens on the IPC socket, optionally pushes to codex-rc.
-- [`src/stations/`](src/stations/) — Line URI scheme + ChatStation interface + listing ([`index.ts`](src/stations/index.ts)), the two chat-station impls (`discord.ts`, `telegram.ts`), plus the Telegram markdown→HTML helper ([`telegram-md.ts`](src/stations/telegram-md.ts)). Agent stations have no impl — they're notification sinks expressed only as URI prefixes.
-- [`src/codex-rc.ts`](src/codex-rc.ts) — Codex app-server WebSocket push client.
+- [`src/cli/`](src/cli/) — `metro` binary entry ([`index.ts`](src/cli/index.ts)) + admin commands ([`config.ts`](src/cli/config.ts): setup/doctor/update), action handlers ([`actions.ts`](src/cli/actions.ts): send/reply/edit/react/download/fetch), webhook + tunnel commands ([`webhook.ts`](src/cli/webhook.ts)), and shared CLI primitives ([`util.ts`](src/cli/util.ts)).
+- [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: starts each station, emits events on stdout, listens on the IPC socket, optionally pushes to codex-rc, supervises the Cloudflare tunnel.
+- [`src/stations/`](src/stations/) — Line URI scheme + ChatStation interface + listing ([`index.ts`](src/stations/index.ts)). Chat impls: [`discord.ts`](src/stations/discord.ts), [`telegram.ts`](src/stations/telegram.ts) (+ [`telegram-md.ts`](src/stations/telegram-md.ts) markdown helper). Agent identity resolvers: [`claude.ts`](src/stations/claude.ts) (orgId via `claude auth status --json`), [`codex.ts`](src/stations/codex.ts) (account_id via `auth.json`). HTTP receive: [`webhook.ts`](src/stations/webhook.ts).
+- [`src/codex-rc.ts`](src/codex-rc.ts) — Codex app-server WebSocket push client (also exposes the rc thread id used as Codex session-id).
+- [`src/tunnel.ts`](src/tunnel.ts) — Cloudflared named-tunnel supervisor.
+- [`src/webhooks.ts`](src/webhooks.ts) — webhook endpoint store (`webhooks.json` CRUD).
+- [`src/registry.ts`](src/registry.ts) — agent registry: `(station, agent-id, sessions[])` tracking.
+- [`src/history.ts`](src/history.ts) — universal message log + `agentSelf()` / `selfLine()` identity helpers.
 - [`src/ipc.ts`](src/ipc.ts) — Unix-socket IPC between the daemon and one-shot CLI commands.
-- [`src/cache.ts`](src/cache.ts) — in-memory line cache with debounced flush to `lines.json`.
+- [`src/cache.ts`](src/cache.ts) — in-memory line cache with debounced flush to `lines.json`, plus bot-id cache.
 - [`docs/uri-scheme.md`](docs/uri-scheme.md) specs the Line format; [`docs/agents.md`](docs/agents.md) is the in-context skill for agents.
 
 CI runs typecheck + lint + build on every PR via [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
@@ -176,10 +231,12 @@ CI runs typecheck + lint + build on every PR via [`.github/workflows/ci.yml`](.g
 
 ## Caveats
 
-- **No allowlist.** Anyone who can DM/`@`-mention your bot can produce events. Run against bots you own.
+- **No allowlist on chat stations.** Anyone who can DM/`@`-mention your bot can produce events. Run against bots you own.
+- **Webhook secrets are optional but recommended.** Without `--secret`, anyone who learns the endpoint URL can POST events. With it, metro verifies `X-Hub-Signature-256` and rejects mismatches.
 - **Telegram bot privacy is on by default**, which can block `@`-mentions in groups. Disable via [@BotFather](https://t.me/BotFather) → Bot Settings → Group Privacy, then kick + re-invite.
 - **Telegram non-forum groups are skipped.** No thread boundary to scope on. DMs and forum topics work normally.
 - **Telegram fetch isn't supported** (bot API doesn't expose history); `metro fetch` returns `[]` on Telegram lines.
+- **Cloudflared is your responsibility.** `metro tunnel setup` records the named tunnel; you still install `cloudflared` (`brew install cloudflared`) and run `cloudflared tunnel login` once.
 
 ---
 

package/dist/cache.js

@@ -48,9 +48,16 @@ export function noteSeen(line, name) {
 export const listLines = () => Object.entries(read()).map(([line, entry]) => ({ line: line, entry }));
 /** Bot identity cache: `{discord: "<userId>", telegram: "<userId>"}`. Daemon writes after getMe(). */
 const botIdsFile = join(STATE_DIR, 'bot-ids.json');
+const readBotIds = () => {
+    try {
+        return existsSync(botIdsFile) ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
+    }
+    catch {
+        return {};
+    }
+};
 export function saveBotId(station, id) {
-    const cur = existsSync(botIdsFile)
-        ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
+    const cur = readBotIds();
     if (cur[station] === id)
         return;
     cur[station] = id;
@@ -63,12 +70,6 @@ export function saveBotId(station, id) {
 }
 /** Resolve the bot's URI for a station. Returns `metro://<station>/bot/<id>` or the placeholder. */
 export function botLine(station) {
-    try {
-        const ids = existsSync(botIdsFile)
-            ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
-        return ids[station] ? Line.bot(station, ids[station]) : `metro://${station}/bot`;
-    }
-    catch {
-        return `metro://${station}/bot`;
-    }
+    const id = readBotIds()[station];
+    return id ? Line.bot(station, id) : `metro://${station}/bot`;
 }

package/dist/cli/actions.js

@@ -1,4 +1,4 @@
-/** CLI action handlers: send/reply/edit/react/download/fetch/notify + helpers. */
+/** CLI action handlers: send/reply/edit/react/download/fetch + helpers. */
 import { mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -45,34 +45,29 @@ function richOpts(f) {
         opts.buttons = buttons;
     return opts;
 }
-/** Append an outbound action to history.jsonl; pass `to` = the original sender when replying/reacting. */
-function logOutbound(f, kind, line, text, platformMessageId, replyTo, opts, emoji, to) {
+/** Append an outbound action to history.jsonl; `to` = the original sender when replying/reacting. */
+function logOutbound(f, e) {
     const id = mintId();
-    const station = Line.station(line) ?? '?';
     const fromOverride = flagOne(f, 'from');
-    const from = fromOverride ? asLine(fromOverride) : agentSelf();
     appendHistory({
-        id, ts: new Date().toISOString(), kind, station, line, from, to: to ?? line,
-        text, platformMessageId, replyTo, emoji,
-        attachments: [...(opts?.images ?? []), ...(opts?.documents ?? []), ...(opts?.voice ? [opts.voice] : [])],
+        id, ts: new Date().toISOString(), station: Line.station(e.line) ?? '?',
+        from: fromOverride ? asLine(fromOverride) : agentSelf(), to: e.to ?? e.line, ...e,
     });
     return id;
 }
-/** When replying/reacting/editing, the recipient is the original message's sender (if we have it). */
-const recipientFor = (idOrPlatform) => lookupEntry(idOrPlatform)?.from;
 export async function cmdSend(p, f) {
     need(p, 1, 'metro send <line> <text> [--image=<path>]… [--document=<path>]… [--voice=<path>] [--buttons=<json>]');
     loadMetroEnv();
     const text = await resolveText(p, 1), line = asLine(p[0]);
     if (Line.isAgent(line)) {
-        const resp = await ipcCall({ op: 'notify', line, text });
+        const from = flagOne(f, 'from');
+        const resp = await ipcCall({ op: 'notify', line, from, text });
         if (!resp.ok)
             throw new Error(resp.error);
         return emit(f, `notified ${line}`, { ok: true, line, id: null, messageId: null });
     }
-    const opts = richOpts(f);
-    const messageId = await chatStationOf(line).send(line, text, opts);
-    const id = logOutbound(f, 'outbound', line, text, messageId, undefined, opts);
+    const messageId = await chatStationOf(line).send(line, text, richOpts(f));
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId });
     emit(f, `sent ${id} (${messageId}) to ${line}`, { ok: true, line, id, messageId });
 }
 export async function cmdReply(p, f) {
@@ -80,9 +75,8 @@ export async function cmdReply(p, f) {
     loadMetroEnv();
     const [to, replyToArg] = p, text = await resolveText(p, 2), line = asLine(to);
     const replyTo = resolvePlatformId(replyToArg);
-    const opts = richOpts(f);
-    const messageId = await chatStationOf(line).send(line, text, { ...opts, replyTo });
-    const id = logOutbound(f, 'outbound', line, text, messageId, replyToArg, opts, undefined, recipientFor(replyToArg));
+    const messageId = await chatStationOf(line).send(line, text, { ...richOpts(f), replyTo });
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, replyTo: replyToArg, to: lookupEntry(replyToArg)?.from });
     emit(f, `replied ${id} (${messageId}) to ${line}#${replyTo}`, { ok: true, line, id, replyTo: replyToArg, messageId });
 }
 export async function cmdEdit(p, f) {
@@ -93,8 +87,7 @@ export async function cmdEdit(p, f) {
     const buttons = parseButtons(f);
     await chatStationOf(line).edit(line, platformId, text, buttons ? { buttons } : undefined);
     /** Carry forward the original recipient if we have a row for this message. */
-    const original = lookupEntry(msgArg);
-    const id = logOutbound(f, 'edit', line, text, platformId, msgArg, undefined, undefined, original?.to);
+    const id = logOutbound(f, { kind: 'edit', line, text, messageId: platformId, replyTo: msgArg, to: lookupEntry(msgArg)?.to });
     emit(f, `edited ${line}#${platformId} (${id})`, { ok: true, line, id, messageId: platformId });
 }
 export async function cmdReact(p, f) {
@@ -103,7 +96,7 @@ export async function cmdReact(p, f) {
     const [to, msgArg, emoji = ''] = p, line = asLine(to);
     const platformId = resolvePlatformId(msgArg);
     await chatStationOf(line).react(line, platformId, emoji);
-    const id = logOutbound(f, 'react', line, undefined, platformId, undefined, undefined, emoji, recipientFor(msgArg));
+    const id = logOutbound(f, { kind: 'react', line, messageId: platformId, emoji, to: lookupEntry(msgArg)?.from });
     const human = emoji ? `reacted ${emoji} on ${line}#${platformId}` : `cleared reaction on ${line}#${platformId}`;
     emit(f, human, { ok: true, line, id, messageId: platformId, emoji });
 }
@@ -144,13 +137,3 @@ export async function cmdFetch(p, f) {
     for (const m of messages)
         process.stdout.write(`${m.timestamp}  ${m.author}: ${m.text}\n`);
 }
-export async function cmdNotify(p, f) {
-    need(p, 1, 'metro notify <line> <text> [--from=<line>]');
-    loadMetroEnv();
-    const text = await resolveText(p, 1), line = asLine(p[0]);
-    const from = flagOne(f, 'from');
-    const resp = await ipcCall({ op: 'notify', line, from, text });
-    if (!resp.ok)
-        throw new Error(resp.error);
-    emit(f, `notified ${line}`, { ok: true, line });
-}

package/dist/cli/config.js

@@ -10,6 +10,7 @@ import { CONFIG_ENV_FILE, configuredPlatforms, loadMetroEnv, readDotenv, STATE_D
 import { emit, exitErr, isJson, writeJson } from './util.js';
 import { cmdSetupSkill, skillStatus } from './skill.js';
 const TOKEN_KEYS = { telegram: 'TELEGRAM_BOT_TOKEN', discord: 'DISCORD_BOT_TOKEN' };
+const stationFor = (p) => p === 'telegram' ? new TelegramStation() : new DiscordStation();
 const maskToken = (t) => !t ? '' : t.length <= 8 ? '••••' : `${t.slice(0, 6)}…${t.slice(-2)}`;
 /** Apply token across CONFIG_ENV_FILE (always set/cleared) AND cwd/.env (only if it exists). */
 function applyToken(key, value) {
@@ -62,7 +63,7 @@ export async function cmdSetup(p, f) {
         if (!f['no-validate']) {
             process.env[TOKEN_KEYS[sub]] = trimmed;
             try {
-                const me = await (sub === 'telegram' ? new TelegramStation() : new DiscordStation()).getMe();
+                const me = await stationFor(sub).getMe();
                 identity = sub === 'telegram' ? `@${me.username}` : me.username;
             }
             catch (err) {
@@ -103,26 +104,26 @@ function tokenSource(key) {
 export async function cmdDoctor(_, f) {
     loadMetroEnv();
     const cfg = configuredPlatforms();
-    const sources = [['telegram', 'TELEGRAM_BOT_TOKEN'], ['discord', 'DISCORD_BOT_TOKEN']]
-        .filter(([p]) => cfg[p]).map(([p, k]) => `${p}←${tokenSource(k)}`).join(', ');
-    const checks = [{
-            name: 'tokens', ok: cfg.telegram || cfg.discord,
-            detail: cfg.telegram || cfg.discord ? sources
-                : 'no platform configured — run `metro setup telegram|discord <token>`',
-        }];
+    const checks = [];
+    const sources = [];
     for (const p of ['telegram', 'discord']) {
         if (!cfg[p]) {
             checks.push({ name: p, ok: null, detail: 'not configured' });
             continue;
         }
+        sources.push(`${p}←${tokenSource(TOKEN_KEYS[p])}`);
         try {
-            const me = await (p === 'telegram' ? new TelegramStation() : new DiscordStation()).getMe();
+            const me = await stationFor(p).getMe();
             checks.push({ name: p, ok: true, detail: `getMe → ${p === 'telegram' ? '@' : ''}${me.username}` });
         }
         catch (err) {
             checks.push({ name: p, ok: false, detail: errMsg(err) });
         }
     }
+    checks.unshift({
+        name: 'tokens', ok: cfg.telegram || cfg.discord,
+        detail: sources.length ? sources.join(', ') : 'no platform configured — run `metro setup telegram|discord <token>`',
+    });
     const lockFile = join(STATE_DIR, '.tail-lock');
     if (!existsSync(lockFile))
         checks.push({ name: 'dispatcher', ok: null, detail: 'not running' });

package/dist/cli/index.js

@@ -4,10 +4,12 @@ import pkg from '../../package.json' with { type: 'json' };
 import { errMsg } from '../log.js';
 import { listLines } from '../cache.js';
 import { fmtCapabilities, listStations } from '../stations/index.js';
+import { listAgents } from '../registry.js';
 import { loadMetroEnv } from '../paths.js';
 import { readHistory } from '../history.js';
 import { cmdDoctor, cmdSetup, cmdUpdate } from './config.js';
-import { cmdDownload, cmdEdit, cmdFetch, cmdNotify, cmdReact, cmdReply, cmdSend, } from './actions.js';
+import { cmdDownload, cmdEdit, cmdFetch, cmdReact, cmdReply, cmdSend, } from './actions.js';
+import { cmdTunnel, cmdWebhook } from './webhook.js';
 import { flagOne, isJson, parseArgs, writeJson, } from './util.js';
 const USAGE = `metro — Telegram + Discord stream for your Claude Code / Codex agent
 
@@ -29,9 +31,12 @@ Usage:
   metro download <line> <message_id> [--out=<dir>]
                                               Download image attachments to disk.
   metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
-  metro notify <line> <text> [--from=<line>]  Emit a notification on the daemon's stream.
   metro history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
                                               Read the universal message log (newest first).
+  metro webhook add <label> [--secret=…]      Register an HTTP receive endpoint (GitHub, Intercom, …).
+  metro webhook list | remove <id>            List or remove webhook endpoints.
+  metro tunnel setup <name> <hostname>        Configure a Cloudflare named tunnel (run cloudflared tunnel login first).
+  metro tunnel status                         Show current tunnel config.
   metro update                                Upgrade in place.
   metro --version | --help
 
@@ -42,12 +47,23 @@ Exit codes: 0 success · 1 usage · 2 config · 3 upstream
 async function cmdStations(_, f) {
     loadMetroEnv();
     const rows = listStations();
+    const agentsByStation = {
+        claude: listAgents('claude'),
+        codex: listAgents('codex'),
+    };
     if (isJson(f))
-        return writeJson({ stations: rows });
+        return writeJson({ stations: rows, agents: agentsByStation });
     process.stdout.write('metro stations\n\n');
     for (const s of rows) {
         const mark = s.configured === true ? '✓' : s.configured === false ? '✗' : '·';
         process.stdout.write(`  ${mark} ${s.name.padEnd(10)} ${s.kind.padEnd(6)} ${fmtCapabilities(s.capabilities)}\n        ${s.detail}\n`);
+        if (s.kind === 'agent') {
+            const seen = agentsByStation[s.name] ?? [];
+            for (const inst of seen) {
+                const sessionsTxt = inst.sessions.length ? ` · sessions: ${inst.sessions.length}` : '';
+                process.stdout.write(`          seen: ${inst.agentId}${sessionsTxt}\n`);
+            }
+        }
     }
     process.stdout.write('\n');
 }
@@ -58,10 +74,8 @@ async function cmdLines(_, f) {
         .sort((a, b) => (b.lastSeenAt ?? '').localeCompare(a.lastSeenAt ?? ''));
     if (isJson(f))
         return writeJson({ lines: rows });
-    if (!rows.length) {
-        process.stdout.write('metro lines\n\n  (none yet — start the dispatcher and send a message)\n\n');
-        return;
-    }
+    if (!rows.length)
+        return void process.stdout.write('metro lines\n\n  (none yet — start the dispatcher and send a message)\n\n');
     const widest = Math.max(...rows.map(r => r.line.length));
     process.stdout.write('metro lines\n\n');
     for (const r of rows) {
@@ -128,7 +142,8 @@ const pad = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s.padEnd(n));
 const COMMANDS = {
     setup: cmdSetup, doctor: cmdDoctor, stations: cmdStations, lines: cmdLines,
     send: cmdSend, reply: cmdReply, edit: cmdEdit, react: cmdReact,
-    download: cmdDownload, fetch: cmdFetch, notify: cmdNotify,
+    download: cmdDownload, fetch: cmdFetch,
+    webhook: cmdWebhook, tunnel: cmdTunnel,
     history: cmdHistory, update: cmdUpdate,
 };
 async function main() {

package/dist/cli/webhook.js

@@ -0,0 +1,83 @@
+/** CLI subcommands: `metro webhook add|list|remove` + `metro tunnel setup`. */
+import { spawnSync } from 'node:child_process';
+import { addEndpoint, listEndpoints, removeEndpoint } from '../webhooks.js';
+import { loadTunnelConfig, saveTunnelConfig } from '../tunnel.js';
+import { emit, exitErr, flagOne, isJson, need, writeJson } from './util.js';
+const DEFAULT_PORT = 8420;
+const port = () => Number(process.env.METRO_WEBHOOK_PORT) || DEFAULT_PORT;
+function urlFor(endpointId) {
+    const t = loadTunnelConfig();
+    return t ? `https://${t.hostname}/wh/${endpointId}` : `http://127.0.0.1:${port()}/wh/${endpointId}`;
+}
+export async function cmdWebhook(p, f) {
+    const sub = p[0];
+    if (sub === 'add')
+        return cmdWebhookAdd(p.slice(1), f);
+    if (sub === 'list' || sub === undefined)
+        return cmdWebhookList(f);
+    if (sub === 'remove' || sub === 'rm')
+        return cmdWebhookRemove(p.slice(1), f);
+    throw exitErr('usage: metro webhook [add <label> [--secret=…] | list | remove <id>]', 1);
+}
+async function cmdWebhookAdd(p, f) {
+    need(p, 1, 'metro webhook add <label> [--secret=<shared-secret>]');
+    const ep = addEndpoint(p[0], flagOne(f, 'secret'));
+    const url = urlFor(ep.id);
+    emit(f, `webhook ${ep.id} (${ep.label}) → ${url}${ep.secret ? `\nshared secret: ${ep.secret}` : ''}`, { ok: true, endpoint: ep, url });
+}
+async function cmdWebhookList(f) {
+    const eps = listEndpoints().map(ep => ({ ...ep, url: urlFor(ep.id) }));
+    if (isJson(f))
+        return writeJson({ endpoints: eps });
+    if (!eps.length)
+        return void process.stdout.write('metro webhooks\n\n  (none — run `metro webhook add <label>`)\n\n');
+    process.stdout.write('metro webhooks\n\n');
+    for (const ep of eps) {
+        process.stdout.write(`  ${ep.id}  ${ep.label}${ep.secret ? '  (signed)' : ''}\n        ${ep.url}\n`);
+    }
+    process.stdout.write('\n');
+}
+async function cmdWebhookRemove(p, f) {
+    need(p, 1, 'metro webhook remove <id>');
+    const ok = removeEndpoint(p[0]);
+    if (!ok)
+        throw exitErr(`no webhook with id "${p[0]}"`, 1);
+    emit(f, `removed webhook ${p[0]}`, { ok: true, id: p[0] });
+}
+export async function cmdTunnel(p, f) {
+    const sub = p[0];
+    if (sub === 'setup')
+        return cmdTunnelSetup(p.slice(1), f);
+    if (sub === 'status' || sub === undefined)
+        return cmdTunnelStatus(f);
+    throw exitErr('usage: metro tunnel [setup <name> <hostname> | status]', 1);
+}
+async function cmdTunnelSetup(p, f) {
+    need(p, 2, 'metro tunnel setup <tunnel-name> <hostname>     (e.g. `metro tunnel setup metro webhook.example.com`)');
+    const [name, hostname] = p;
+    if (!hasCloudflared()) {
+        throw exitErr('cloudflared not on PATH — install with `brew install cloudflared` (or see https://developers.cloudflare.com/cloudflared/)', 2);
+    }
+    /** Idempotent: if tunnel exists, `tunnel create` errors with "already exists" — that's fine, continue. */
+    run('cloudflared', ['tunnel', 'create', name], { allowFail: true });
+    /** DNS route is also idempotent in newer cloudflared; older versions error if the CNAME exists. Same handling. */
+    run('cloudflared', ['tunnel', 'route', 'dns', name, hostname], { allowFail: true });
+    saveTunnelConfig({ name, hostname });
+    emit(f, `tunnel saved: ${name} → ${hostname}\n` +
+        'first run: `cloudflared tunnel login` if you haven\'t (browser OAuth).\n' +
+        'then start metro — the daemon will spawn `cloudflared tunnel run` for you.', { ok: true, name, hostname });
+}
+async function cmdTunnelStatus(f) {
+    const cfg = loadTunnelConfig();
+    if (isJson(f))
+        return writeJson({ configured: !!cfg, tunnel: cfg });
+    if (!cfg)
+        return void process.stdout.write('metro tunnel\n\n  (not configured — run `metro tunnel setup <name> <hostname>`)\n\n');
+    process.stdout.write(`metro tunnel\n\n  name:     ${cfg.name}\n  hostname: ${cfg.hostname}\n\n`);
+}
+const hasCloudflared = () => spawnSync('cloudflared', ['--version'], { stdio: 'ignore' }).status === 0;
+function run(cmd, args, opts = {}) {
+    const r = spawnSync(cmd, args, { stdio: 'inherit' });
+    if (r.status !== 0 && !opts.allowFail)
+        throw exitErr(`${cmd} ${args.join(' ')} exited ${r.status}`, 2);
+}

package/dist/codex-rc.js

@@ -32,6 +32,7 @@ export class CodexRC {
     nextId = 1;
     pending = new Map();
     threadId = null;
+    threadListener = null;
     queue = [];
     connected = false;
     connecting = false;
@@ -45,6 +46,14 @@ export class CodexRC {
         this.endpoint = parseUrl(url);
     }
     start() { void this.connect(); }
+    getThreadId() { return this.threadId; }
+    onThread(listener) { this.threadListener = listener; }
+    setThreadId(id) {
+        if (this.threadId === id)
+            return;
+        this.threadId = id;
+        this.threadListener?.(id);
+    }
     stop() {
         this.closed = true;
         this.clearTurnTimeout();
@@ -75,7 +84,7 @@ export class CodexRC {
             ws.on('close', () => this.onClose());
             const clientInfo = { name: 'metro', version: this.clientVersion, title: null };
             await this.call('initialize', { clientInfo });
-            this.threadId = await this.pickOrCreateThread();
+            this.setThreadId(await this.pickOrCreateThread());
             this.connected = true;
             log.info({ url: this.url, thread: this.threadId ?? '(none yet)' }, 'codex-rc connected');
             void this.drainQueue();
@@ -110,7 +119,7 @@ export class CodexRC {
             case 'thread/started': {
                 const id = msg.params?.thread?.id;
                 if (id) {
-                    this.threadId = id;
+                    this.setThreadId(id);
                     log.info({ thread: id }, 'codex-rc thread started');
                     void this.drainQueue();
                 }
@@ -142,7 +151,7 @@ export class CodexRC {
             case 'thread/closed':
             case 'thread/archived':
                 log.warn({ method: msg.method }, 'codex-rc thread closed/archived');
-                this.threadId = null;
+                this.setThreadId(null);
                 break;
         }
     }
@@ -186,7 +195,7 @@ export class CodexRC {
         if (!this.connected || this.turnInFlight || !this.queue.length)
             return;
         if (!this.threadId) {
-            this.threadId = await this.pickOrCreateThread();
+            this.setThreadId(await this.pickOrCreateThread());
             if (!this.threadId)
                 return;
         }
@@ -204,7 +213,7 @@ export class CodexRC {
             this.clearTurnTimeout();
             this.turnInFlight = false;
             if (dead)
-                this.threadId = null;
+                this.setThreadId(null);
             setTimeout(() => void this.drainQueue(), 1_000);
         }
     }