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

package/dist/stations/codex.js

@@ -0,0 +1,68 @@
+/** Resolve the Codex agent identity (account id + session id). */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { STATE_DIR } from '../paths.js';
+/** Short TTL so account switches via `codex login` propagate to the daemon within seconds. */
+const TTL_MS = 5_000;
+let cache = null;
+function authPath() {
+    return join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'auth.json');
+}
+export function codexAccountId() {
+    if (cache && Date.now() - cache.at < TTL_MS)
+        return cache.id;
+    const path = authPath();
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        throw new Error(`metro: failed to read ${path} — is Codex logged in? (${e.message})`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`metro: ${path} is not valid JSON`);
+    }
+    const id = parsed.tokens?.account_id;
+    if (!id) {
+        throw new Error(`metro: no Codex account_id in ${path} (auth_mode=${parsed.auth_mode ?? 'unknown'}) — sign in with 'codex login' (ChatGPT mode required)`);
+    }
+    cache = { id, at: Date.now() };
+    return id;
+}
+export function tryCodexAccountId() {
+    try {
+        return codexAccountId();
+    }
+    catch {
+        return null;
+    }
+}
+/** Agent-id for the line URI: `METRO_AGENT_ID` override, else the account id. */
+export function codexAgentId() {
+    return process.env.METRO_AGENT_ID || codexAccountId();
+}
+const SESSION_FILE = join(STATE_DIR, 'stations', 'codex', 'session-id');
+/** Session: codex-rc thread id (daemon persists; CLIs read state file). Override: `METRO_AGENT_SESSION_ID`. */
+export function codexSessionId() {
+    if (process.env.METRO_AGENT_SESSION_ID)
+        return process.env.METRO_AGENT_SESSION_ID;
+    try {
+        return readFileSync(SESSION_FILE, 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Daemon-side: persist the rc thread id so CLI processes can read it. Best-effort. */
+export function setCodexSessionId(threadId) {
+    try {
+        mkdirSync(dirname(SESSION_FILE), { recursive: true });
+        writeFileSync(SESSION_FILE, threadId ?? '');
+    }
+    catch { /* CLI just won't have a session segment */ }
+}

package/dist/stations/index.js

@@ -1,13 +1,29 @@
 /** Line URI scheme + ChatStation interface + station listing. The whole station surface. */
+import { tryClaudeAccountId } from './claude.js';
+import { tryCodexAccountId } from './codex.js';
+import { listAgents } from '../registry.js';
+import { listEndpoints } from '../webhooks.js';
+import { loadTunnelConfig } from '../tunnel.js';
 export const asLine = (s) => s;
 const PREFIX = 'metro://';
 const build = (station, ...seg) => asLine(`${PREFIX}${station}/${seg.map(String).join('/')}`);
+/** Shared parser for `metro://{claude,codex}/<agentId>/<sessionId>`. Skips participant URIs (`/user/…`, `/bot/…`). */
+function parseAgent(line, station) {
+    const p = Line.parse(line);
+    if (p?.station !== station || p.path[0] === 'user' || p.path[0] === 'bot' || p.path.length < 2)
+        return null;
+    return { agentId: p.path[0], sessionId: p.path[1] };
+}
 /** URI helpers. Lives on a const that doubles as the `Line` type's value-side namespace. */
 export const Line = {
     discord: (channelId) => build('discord', channelId),
     telegram: (chatId, topicId) => topicId !== undefined ? build('telegram', chatId, topicId) : build('telegram', chatId),
-    claude: (topic) => build('claude', topic),
-    codex: (topic) => build('codex', topic),
+    /** `metro://claude/<orgId>/<sessionId>` — orgId from `claude auth status`, session from `CLAUDE_CODE_SESSION_ID`. */
+    claude: (orgId, sessionId) => build('claude', orgId, sessionId),
+    /** `metro://codex/<accountId>/<threadId>` — accountId from auth.json, thread from codex-rc handshake. */
+    codex: (accountId, threadId) => build('codex', accountId, threadId),
+    /** `metro://webhook/<endpoint-id>` — one HTTP receive endpoint, registered via `metro webhook add`. */
+    webhook: (endpointId) => build('webhook', endpointId),
     /** Participant URIs — `metro://<station>/user/<id>` and `metro://<station>/bot/<id>`. */
     user: (station, id) => build(station, 'user', id),
     bot: (station, id) => build(station, 'bot', id),
@@ -38,17 +54,49 @@ export const Line = {
         const topicId = Number(p.path[1]);
         return Number.isFinite(topicId) ? { chatId, topicId } : null;
     },
+    parseClaude: (line) => parseAgent(line, 'claude'),
+    parseCodex: (line) => parseAgent(line, 'codex'),
+    parseWebhook(line) {
+        const p = Line.parse(line);
+        return p?.station === 'webhook' && p.path.length === 1 ? p.path[0] : null;
+    },
     isAgent: (line) => {
         const s = Line.station(line);
         return s === 'claude' || s === 'codex';
     },
 };
-const AGENT_CAPS = { in: ['text'], out: [], features: ['notify'] };
+/** `out: ['text']` + `send` reflects the IPC notify path (`metro send metro://<station>/...` re-emits on stdout). */
+const AGENT_CAPS = { in: ['text'], out: ['text'], features: ['send', 'notify'] };
 const CHAT_CAPS = {
     in: ['text', 'image'],
     out: ['text'],
     features: ['reply', 'send', 'edit', 'react', 'download', 'fetch'],
 };
+const WEBHOOK_CAPS = { in: ['text'], out: [], features: [] };
+function seenSummary(station) {
+    const agents = listAgents(station);
+    if (!agents.length)
+        return '';
+    const sessions = agents.reduce((n, a) => n + a.sessions.length, 0);
+    return ` · seen ${agents.length} agent${agents.length === 1 ? '' : 's'}, ${sessions} session${sessions === 1 ? '' : 's'}`;
+}
+function claudeStationDetail() {
+    const seen = seenSummary('claude');
+    if (!process.env.CLAUDECODE)
+        return `launch metro from inside a Claude Code session${seen}`;
+    const orgId = tryClaudeAccountId();
+    return `${orgId ? `account: ${orgId}` : 'logged out — run `claude auth login`'}${seen}`;
+}
+function codexStationDetail() {
+    const rc = process.env.METRO_CODEX_RC;
+    const accountId = tryCodexAccountId();
+    const seen = seenSummary('codex');
+    const parts = [
+        accountId ? `account: ${accountId}` : (rc ? '(no Codex account — run `codex login`)' : null),
+        rc ? `push → ${rc}` : (!accountId ? 'set METRO_CODEX_RC=ws://… to push' : null),
+    ].filter(Boolean);
+    return `${parts.join(' · ')}${seen}`;
+}
 export const listStations = () => [
     {
         name: 'discord', kind: 'chat', capabilities: CHAT_CAPS,
@@ -60,14 +108,26 @@ export const listStations = () => [
     },
     {
         name: 'claude', kind: 'agent', capabilities: AGENT_CAPS,
-        configured: null, detail: 'stdout stream (watch via Claude Code Monitor)',
+        configured: !!process.env.CLAUDECODE,
+        detail: claudeStationDetail(),
     },
     {
         name: 'codex', kind: 'agent', capabilities: AGENT_CAPS,
-        configured: process.env.METRO_CODEX_RC ? true : null,
-        detail: process.env.METRO_CODEX_RC
-            ? `push → ${process.env.METRO_CODEX_RC}`
-            : 'set METRO_CODEX_RC=ws://… to push',
+        configured: !!(process.env.METRO_CODEX_RC || process.env.CODEX_HOME),
+        detail: codexStationDetail(),
+    },
+    {
+        name: 'webhook', kind: 'service', capabilities: WEBHOOK_CAPS,
+        configured: listEndpoints().length > 0,
+        detail: webhookStationDetail(),
     },
 ];
+function webhookStationDetail() {
+    const eps = listEndpoints();
+    const t = loadTunnelConfig();
+    const base = t ? `https://${t.hostname}` : `http://127.0.0.1:${Number(process.env.METRO_WEBHOOK_PORT) || 8420}`;
+    if (!eps.length)
+        return `no endpoints (run \`metro webhook add <label>\`)${t ? ` · tunnel → ${t.hostname}` : ''}`;
+    return `${eps.length} endpoint${eps.length === 1 ? '' : 's'} · base ${base}${t ? '' : ' (no tunnel — run `metro tunnel setup`)'}`;
+}
 export const fmtCapabilities = (c) => `in: ${c.in.join('+') || '–'} · out: ${c.out.join('+') || '–'} · features: ${c.features.join(', ') || '–'}`;

package/dist/stations/webhook.js

@@ -0,0 +1,100 @@
+/** Receive-only HTTP station. Each registered endpoint = one path `/wh/<id>` → InboundMessage on stdout. */
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { errMsg, log } from '../log.js';
+import { mintId } from '../history.js';
+import { findEndpoint, listEndpoints } from '../webhooks.js';
+import { Line } from './index.js';
+const DEFAULT_PORT = 8420;
+/** Synthesize an `event` tag from common provider-specific headers (GitHub, Intercom). */
+function pickEvent(headers) {
+    return headers['x-github-event'] ?? headers['x-intercom-topic'] ?? 'event';
+}
+/** Constant-time signature check against `X-Hub-Signature-256: sha256=<hex>` (GitHub/Intercom style). */
+function verifySig(secret, raw, header) {
+    if (!header?.startsWith('sha256='))
+        return false;
+    const given = Buffer.from(header.slice(7), 'hex');
+    const want = createHmac('sha256', secret).update(raw).digest();
+    return given.length === want.length && timingSafeEqual(given, want);
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    return Buffer.concat(chunks);
+}
+export class WebhookStation {
+    name = 'webhook';
+    server = null;
+    handler = null;
+    port() { return Number(process.env.METRO_WEBHOOK_PORT) || DEFAULT_PORT; }
+    onMessage(h) { this.handler = h; }
+    start() {
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => this.handle(req, res).catch(err => {
+                log.warn({ err: errMsg(err) }, 'webhook handler error');
+                if (!res.headersSent)
+                    res.writeHead(500).end();
+            }));
+            this.server.on('error', reject);
+            this.server.listen(this.port(), '127.0.0.1', () => {
+                log.info({ port: this.port(), endpoints: listEndpoints().length }, 'webhook station ready');
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        const srv = this.server;
+        if (!srv)
+            return;
+        await new Promise(resolve => srv.close(() => resolve()));
+        this.server = null;
+    }
+    async handle(req, res) {
+        const m = req.url?.match(/^\/wh\/([A-Za-z0-9_-]+)/);
+        if (!m) {
+            res.writeHead(404).end();
+            return;
+        }
+        const endpointId = m[1];
+        const endpoint = findEndpoint(endpointId);
+        if (!endpoint) {
+            res.writeHead(404).end();
+            return;
+        }
+        if (req.method === 'GET') {
+            res.writeHead(200).end(`metro webhook ${endpointId} ready\n`);
+            return;
+        }
+        if (req.method !== 'POST') {
+            res.writeHead(405).end();
+            return;
+        }
+        const raw = await readBody(req);
+        const headers = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(',') : v ?? '']));
+        if (endpoint.secret && !verifySig(endpoint.secret, raw, headers['x-hub-signature-256'])) {
+            log.warn({ endpoint: endpointId }, 'webhook signature mismatch — rejecting');
+            res.writeHead(401).end('signature mismatch');
+            return;
+        }
+        let body = raw.toString('utf8');
+        try {
+            body = JSON.parse(body);
+        }
+        catch { /* keep as string */ }
+        const line = Line.webhook(endpointId);
+        this.handler?.({
+            id: mintId(),
+            ts: new Date().toISOString(),
+            station: 'webhook',
+            line,
+            lineName: endpoint.label,
+            from: line,
+            messageId: headers['x-github-delivery'] || headers['x-request-id'] || randomUUID(),
+            text: `${pickEvent(headers)} ${req.method} ${req.url}`,
+            payload: { headers, body },
+        });
+        res.writeHead(200).end('ok');
+    }
+}

package/dist/tunnel.js

@@ -0,0 +1,66 @@
+/** Cloudflared tunnel manager. Prefers token-from-env so a missing local credentials JSON does not block startup. */
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATE_DIR } from './paths.js';
+import { errMsg, log } from './log.js';
+const FILE = join(STATE_DIR, 'tunnel.json');
+const RESTART_DELAY_MS = 2_000;
+export const loadTunnelConfig = () => existsSync(FILE)
+    ? JSON.parse(readFileSync(FILE, 'utf8'))
+    : null;
+export function saveTunnelConfig(c) { writeFileSync(FILE, JSON.stringify(c, null, 2)); }
+/** Fetch the tunnel's auth token. Null when CLI is unavailable, not logged in, or no such tunnel. */
+function fetchTunnelToken(name) {
+    const r = spawnSync('cloudflared', ['tunnel', 'token', name], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    const token = r.stdout.trim();
+    return token.length > 0 ? token : null;
+}
+export class Tunnel {
+    cfg;
+    port;
+    child = null;
+    closed = false;
+    token = null;
+    tokenResolved = false;
+    constructor(cfg, port) {
+        this.cfg = cfg;
+        this.port = port;
+    }
+    get hostname() { return this.cfg.hostname; }
+    start() {
+        if (this.closed)
+            return;
+        if (!this.tokenResolved) {
+            this.token = fetchTunnelToken(this.cfg.name);
+            this.tokenResolved = true;
+        }
+        const mode = this.token ? 'token' : 'named';
+        log.info({ name: this.cfg.name, hostname: this.cfg.hostname, port: this.port, mode }, 'cloudflared tunnel starting');
+        /** `--no-autoupdate` is a global cloudflared flag — must come before the `tunnel` subcommand. */
+        const args = ['--no-autoupdate', 'tunnel', 'run', '--url', `http://127.0.0.1:${this.port}`];
+        /** Token form resolves the tunnel from TUNNEL_TOKEN so the trailing name arg must be omitted. */
+        if (!this.token)
+            args.push(this.cfg.name);
+        const env = this.token
+            ? { ...process.env, TUNNEL_TOKEN: this.token }
+            : process.env;
+        this.child = spawn('cloudflared', args, { stdio: ['ignore', 'pipe', 'pipe'], env });
+        this.child.stderr?.on('data', d => log.debug({ cloudflared: d.toString().trim() }, 'cloudflared'));
+        this.child.on('exit', code => {
+            this.child = null;
+            if (this.closed)
+                return;
+            log.warn({ code }, 'cloudflared exited; restarting');
+            setTimeout(() => this.start(), RESTART_DELAY_MS);
+        });
+        this.child.on('error', err => log.warn({ err: errMsg(err) }, 'cloudflared spawn error'));
+    }
+    stop() {
+        this.closed = true;
+        this.child?.kill();
+        this.child = null;
+    }
+}

package/dist/webhooks.js

@@ -0,0 +1,40 @@
+/** Webhook endpoint registry: persists `(id, label, secret?)` for each receive endpoint. */
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { STATE_DIR } from './paths.js';
+const FILE = join(STATE_DIR, 'webhooks.json');
+function read() {
+    if (!existsSync(FILE))
+        return { endpoints: [] };
+    try {
+        return JSON.parse(readFileSync(FILE, 'utf8'));
+    }
+    catch {
+        return { endpoints: [] };
+    }
+}
+function write(s) { writeFileSync(FILE, JSON.stringify(s, null, 2)); }
+export const listEndpoints = () => read().endpoints;
+export const findEndpoint = (id) => read().endpoints.find(e => e.id === id);
+/** Mint a 16-char URL-safe random id (~96 bits of entropy — collision-proof for any reasonable count). */
+const mintEndpointId = () => randomBytes(12).toString('base64url');
+export function addEndpoint(label, secret) {
+    const s = read();
+    const ep = {
+        id: mintEndpointId(), label, createdAt: new Date().toISOString(),
+        ...(secret ? { secret } : {}),
+    };
+    s.endpoints.push(ep);
+    write(s);
+    return ep;
+}
+export function removeEndpoint(id) {
+    const s = read();
+    const before = s.endpoints.length;
+    s.endpoints = s.endpoints.filter(e => e.id !== id);
+    if (s.endpoints.length === before)
+        return false;
+    write(s);
+    return true;
+}

package/docs/agents.md

@@ -1,6 +1,6 @@
 # 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, and other agents on its stdout. Your job is to consume that stream and post replies back via subcommands.
+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
 
@@ -34,11 +34,11 @@ Run `metro doctor` if anything seems off.
 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/agent","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"}}}}
+{"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/deploys","from":"metro://codex/ci","to":"metro://claude/deploys","text":"deploy succeeded"}
+{"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
@@ -47,14 +47,15 @@ Every event is a **history entry** — the same record that's appended to `histo
 
 - **`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/<topic>` / `metro://codex/<topic>` for an agent, `metro://<station>/<channelId>` as a fallback `to` when sending to a group with no single recipient.
+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/agent` (from `$CLAUDECODE`) or `metro://codex/agent` (from `$METRO_CODEX_RC`/`$CODEX_HOME`). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is auto-set to the original sender (history lookup).
+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.
+- `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`.
@@ -70,8 +71,9 @@ Derive from `payload`. Bot id per station is in `$METRO_STATE_DIR/bot-ids.json`
 
 - **`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: only reply on DM or ping; otherwise stay silent or `metro react` to ack.
+Default for chat: only reply on DM or ping; otherwise stay silent or `metro react` to ack. Webhooks just consume — no ack mechanism.
 
 ## Subcommands
 
@@ -84,8 +86,11 @@ Default: only reply on DM or ping; otherwise stay silent or `metro react` to ack
 | 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).
+`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
 
@@ -146,13 +151,39 @@ Lines sorted by recency. Use when the user says "the Telegram channel" or "that
 
 ```
 $ metro stations
-  ✓ discord    chat   in: text+image · out: text · features: reply, send, edit, react, download, fetch
-  ✓ telegram   chat   in: text+image · out: text · features: reply, send, edit, react, download, fetch
-  · claude     agent  in: text · out: – · features: notify
-  ✓ codex      agent  in: text · out: – · features: notify
+  ✓ 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, `✗` = configured-but-broken, `·` = informational (agent stations have no setup).
+`✓` = 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
 
@@ -164,11 +195,11 @@ When an inbound has an `[image]` tag in `text`:
 
 ## Cross-agent notification
 
-Both agents can post to each other's "agent line" — a logical channel under `metro://claude/<topic>` or `metro://codex/<topic>`. 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:
+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/deploys "build green, ready to ship"
-metro send metro://claude/deploys "build green" --from=metro://codex/ci   # override sender
+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.

package/docs/uri-scheme.md

@@ -6,7 +6,7 @@ Universal identifier for every conversational scope and notification sink in met
 
 ```
 line       = "metro://" station "/" path
-station    = lowercase identifier (claude | codex | discord | telegram | …)
+station    = lowercase identifier (claude | codex | discord | telegram | webhook | …)
 path       = station-specific, "/"-separated segments
 ```
 
@@ -14,27 +14,73 @@ The URI parses cleanly with the WHATWG `URL` parser: `new URL(line)` gives `prot
 
 ## 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/<topic>`                  | `metro://claude/deploys`              |
-| `codex`    | agent | `metro://codex/<topic>`                   | `metro://codex/ci`                    |
+| 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`  |
-| agent | `metro://{claude,codex}/<topic>`         | `metro://claude/agent`           |
+| 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`.
 
-`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 (`metro://claude/agent` if `$CLAUDECODE` is detected, `metro://codex/agent` if `$METRO_CODEX_RC`/`$CODEX_HOME` is set, else `metro://agent`). 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_`).
+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 are notification sinks — 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.
+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
 
@@ -61,7 +107,15 @@ 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.isAgent(Line.claude('deploys'));            // true
+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