@stage-labs/metro 0.1.0-beta.7 → 0.1.0-beta.9

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` — 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]
@@ -43,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 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://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.
 
 ---
 
@@ -64,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).
 
@@ -79,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.
 
 ---
 
@@ -90,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).
@@ -119,6 +157,10 @@ metro download <line> <message_id> [--out=<dir>]
 metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
 metro history [--limit=N] [--line=…] [--station=…] [--kind=…] [--from=…] [--text=…] [--since=…]
                                             Universal message log (every inbound + outbound), newest first.
+metro webhook add <label> [--secret=…]      Register an HTTP receive endpoint (GitHub, Intercom, …).
+metro webhook list | remove <id>            List or remove webhook endpoints.
+metro tunnel setup <name> <hostname>        Configure a Cloudflare named tunnel for public webhook URLs.
+metro tunnel status                         Show current tunnel config.
 metro update                                Upgrade in place.
 ```
 
@@ -126,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`. The token is resolved via `cloudflared tunnel token <name>` and passed through as `TUNNEL_TOKEN`, so the per-tunnel credentials JSON at `~/.cloudflared/<id>.json` is not required (the named-form spawn is the fallback when the token call fails)
 - `.tail-lock` — dispatcher pid
 - `metro.sock` — daemon IPC socket
 - `telegram-offset.json` — last processed update id
@@ -141,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.
@@ -163,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).
@@ -177,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/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, 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
 
@@ -31,6 +33,10 @@ Usage:
   metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
   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
 
@@ -41,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');
 }
@@ -126,6 +143,7 @@ const COMMANDS = {
     setup: cmdSetup, doctor: cmdDoctor, stations: cmdStations, lines: cmdLines,
     send: cmdSend, reply: cmdReply, edit: cmdEdit, react: cmdReact,
     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);
         }
     }

package/dist/dispatcher.js

@@ -7,17 +7,29 @@ import { fileURLToPath } from 'node:url';
 import pkg from '../package.json' with { type: 'json' };
 import { DiscordStation } from './stations/discord.js';
 import { TelegramStation } from './stations/telegram.js';
+import { WebhookStation } from './stations/webhook.js';
 import { asLine, Line } from './stations/index.js';
 import { CodexRC } from './codex-rc.js';
 import { startIpcServer, stopIpcServer } from './ipc.js';
-import { agentSelf, appendHistory, mintId } from './history.js';
+import { agentSelf, appendHistory, mintId, selfLine } from './history.js';
 import { noteSeen, saveBotId } from './cache.js';
 import { errMsg, log } from './log.js';
 import { acquireLock, configuredPlatforms, loadMetroEnv, STATE_DIR, requireConfiguredPlatform } from './paths.js';
+import { setCodexSessionId } from './stations/codex.js';
+import { noteAgentFromLine } from './registry.js';
+import { listEndpoints } from './webhooks.js';
+import { loadTunnelConfig, Tunnel } from './tunnel.js';
 loadMetroEnv();
 const platforms = configuredPlatforms();
-requireConfiguredPlatform(platforms);
+const endpoints = listEndpoints();
+requireConfiguredPlatform(platforms, endpoints.length > 0);
 acquireLock(join(STATE_DIR, '.tail-lock'));
+// Fail fast if launched from Claude Code without a logged-in account.
+const self = agentSelf();
+log.info({ self, line: selfLine() }, 'agent identity');
+const seedSelf = () => { const l = selfLine(); if (l)
+    noteAgentFromLine(l); };
+seedSelf();
 const AGENTS_MD = join(STATE_DIR, 'AGENTS.md');
 try {
     copyFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'docs', 'agents.md'), AGENTS_MD);
@@ -31,14 +43,21 @@ process.stdout.on('error', err => {
         log.warn({ err: errMsg(err) }, 'stdout error');
 });
 const codexRc = process.env.METRO_CODEX_RC ? new CodexRC(process.env.METRO_CODEX_RC, pkg.version) : null;
+codexRc?.onThread(id => { setCodexSessionId(id); seedSelf(); });
 codexRc?.start();
 const discord = new DiscordStation();
 const telegram = new TelegramStation();
+const webhook = new WebhookStation();
+const tunnelCfg = loadTunnelConfig();
+const tunnel = tunnelCfg ? new Tunnel(tunnelCfg, webhook.port()) : null;
 function emit(entry) {
     const json = JSON.stringify(entry);
     process.stdout.write(json + '\n');
     codexRc?.push(json);
     noteSeen(entry.line, entry.lineName);
+    for (const l of [entry.line, entry.from, entry.to])
+        if (l)
+            noteAgentFromLine(l);
     appendHistory(entry);
 }
 const onInbound = (m) => emit({ ...m, kind: 'inbound', to: agentSelf() });
@@ -73,7 +92,13 @@ async function main() {
         saveBotId('telegram', String(me.id));
         log.info({ bot: `@${me.username}` }, 'telegram ready');
     }
-    log.info({ codexRc: !!codexRc }, 'dispatcher ready');
+    /** Start the HTTP receiver only when ≥1 endpoint is registered — no point binding a port nobody listens to. */
+    if (endpoints.length) {
+        webhook.onMessage(onInbound);
+        await webhook.start();
+        tunnel?.start();
+    }
+    log.info({ codexRc: !!codexRc, tunnel: !!tunnel }, 'dispatcher ready');
 }
 let shuttingDown = false;
 async function shutdown() {
@@ -82,7 +107,9 @@ async function shutdown() {
     shuttingDown = true;
     log.info('dispatcher shutting down');
     codexRc?.stop();
+    tunnel?.stop();
     await stopIpcServer(ipc).catch(() => { });
+    await webhook.stop().catch(() => { });
     if (platforms.discord)
         await discord.stop().catch(() => { });
     if (platforms.telegram)

package/dist/history.js

@@ -4,6 +4,9 @@ import { appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { errMsg, log } from './log.js';
 import { STATE_DIR } from './paths.js';
+import { Line } from './stations/index.js';
+import { claudeAgentId, claudeSessionId } from './stations/claude.js';
+import { codexAgentId, codexSessionId } from './stations/codex.js';
 const FILE = join(STATE_DIR, 'history.jsonl');
 /** Mint a universal metro message ID. Short, prefixed, URL-safe. */
 export const mintId = () => `msg_${randomBytes(6).toString('base64url')}`;
@@ -71,14 +74,26 @@ export function resolvePlatformId(id) {
         return hit.messageId;
     throw new Error(`unknown universal id: ${id} (run \`metro history --limit=50\` to see recent ids)`);
 }
-/** Resolve the current agent's identity URI. Precedence: METRO_FROM > runtime env > generic. */
+/** The current agent's **participant** URI for `from`/`to`. Precedence: METRO_FROM > runtime env > generic. */
 export function agentSelf() {
     const explicit = process.env.METRO_FROM;
     if (explicit)
         return explicit;
     if (process.env.CLAUDECODE)
-        return 'metro://claude/agent';
+        return Line.user('claude', claudeAgentId());
     if (process.env.METRO_CODEX_RC || process.env.CODEX_HOME)
-        return 'metro://codex/agent';
+        return Line.user('codex', codexAgentId());
     return 'metro://agent';
 }
+/** The current agent's **line** URI `<agent-id>/<session>`. Null until session is known (rc thread pending). */
+export function selfLine() {
+    if (process.env.CLAUDECODE) {
+        const s = claudeSessionId();
+        return s ? Line.claude(claudeAgentId(), s) : null;
+    }
+    if (process.env.METRO_CODEX_RC || process.env.CODEX_HOME) {
+        const s = codexSessionId();
+        return s ? Line.codex(codexAgentId(), s) : null;
+    }
+    return null;
+}

package/dist/paths.js

@@ -36,10 +36,10 @@ export function loadMetroEnv() {
 export function configuredPlatforms() {
     return { telegram: !!process.env.TELEGRAM_BOT_TOKEN, discord: !!process.env.DISCORD_BOT_TOKEN };
 }
-export function requireConfiguredPlatform(p) {
-    if (p.telegram || p.discord)
+export function requireConfiguredPlatform(p, hasWebhooks) {
+    if (p.telegram || p.discord || hasWebhooks)
         return;
-    log.fatal('no platforms configured — run `metro setup telegram <token>` or `metro setup discord <token>`');
+    log.fatal('no inputs configured — run `metro setup telegram <token>`, `metro setup discord <token>`, or `metro webhook add <label>`');
     process.exit(2);
 }
 /** Singleton pidfile. Exits if another instance owns it; reclaims stale locks. */

package/dist/registry.js

@@ -0,0 +1,48 @@
+/** Append-only registry of `(station, agent-id, sessions[])` tuples metro has seen. */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATE_DIR } from './paths.js';
+import { Line } from './stations/index.js';
+import { errMsg, log } from './log.js';
+const REGISTRY_FILE = join(STATE_DIR, 'agent-registry.json');
+function readRegistry() {
+    if (!existsSync(REGISTRY_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'agent-registry: malformed, resetting');
+        return {};
+    }
+}
+function record(station, agentId, sessionId) {
+    const reg = readRegistry();
+    const rows = (reg[station] ??= []);
+    let row = rows.find(r => r.agentId === agentId);
+    if (!row) {
+        row = { agentId, sessions: [], lastSeen: '' };
+        rows.push(row);
+    }
+    if (sessionId && !row.sessions.includes(sessionId))
+        row.sessions.push(sessionId);
+    row.lastSeen = new Date().toISOString();
+    try {
+        writeFileSync(REGISTRY_FILE, JSON.stringify(reg, null, 2));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'agent-registry: write failed');
+    }
+}
+/** Scan a line URI for `(station, agentId, sessionId)` and record it. No-op on non-agent or participant URIs. */
+export function noteAgentFromLine(line) {
+    const station = Line.station(line);
+    if (station !== 'claude' && station !== 'codex')
+        return;
+    const p = station === 'claude' ? Line.parseClaude(line) : Line.parseCodex(line);
+    if (p)
+        record(station, p.agentId, p.sessionId);
+}
+export function listAgents(station) {
+    return readRegistry()[station] ?? [];
+}

package/dist/stations/claude.js

@@ -0,0 +1,45 @@
+/** Resolve the Claude Code agent identity (account id + session id). */
+import { execFileSync } from 'node:child_process';
+/** Short TTL so account switches via `claude auth login` propagate to the daemon within seconds. */
+const TTL_MS = 5_000;
+let cache = null;
+/** Stable per-Anthropic-account UUID. Same across devices for the same login. */
+export function claudeAccountId() {
+    if (cache && Date.now() - cache.at < TTL_MS)
+        return cache.id;
+    let raw;
+    try {
+        raw = execFileSync('claude', ['auth', 'status', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch (e) {
+        throw new Error(`metro: failed to run 'claude auth status --json' — is Claude Code installed and on PATH? (${e.message})`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`metro: 'claude auth status --json' returned non-JSON: ${raw.slice(0, 200)}`);
+    }
+    if (!parsed.loggedIn || !parsed.orgId) {
+        throw new Error('metro: Claude Code is not logged in — run \'claude auth login\'');
+    }
+    cache = { id: parsed.orgId, at: Date.now() };
+    return parsed.orgId;
+}
+export function tryClaudeAccountId() {
+    try {
+        return claudeAccountId();
+    }
+    catch {
+        return null;
+    }
+}
+/** Agent-id for the line URI: `METRO_AGENT_ID` override, else the account id. */
+export function claudeAgentId() {
+    return process.env.METRO_AGENT_ID || claudeAccountId();
+}
+/** Session: `CLAUDE_CODE_SESSION_ID` (stable across `--resume`). Override: `METRO_AGENT_SESSION_ID`. */
+export function claudeSessionId() {
+    return process.env.METRO_AGENT_SESSION_ID || process.env.CLAUDE_CODE_SESSION_ID || null;
+}