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

package/skills/metro/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: metro
-description: Run the metro Telegram/Discord bridge in this session — launch `metro` in the background, watch its stdout for inbound JSON events, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"kind":"inbound","station":...,"line":"metro://...","messageId":...,"text":...}`, or when handling a chat reply/edit/react/send/download/fetch/notify.
+description: Run the metro Telegram/Discord/webhook bridge in this session — launch `metro` in the background, watch its stdout for inbound JSON events, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"kind":"inbound","station":...,"line":"metro://...","messageId":...,"text":...}`, or when handling a chat/webhook reply/edit/react/send/download/fetch/notify.
 ---
 
-# Metro — running the Telegram & Discord bridge
+# Metro — running the Telegram / Discord / webhook bridge
 
-Metro is a CLI bridge between this agent session and Telegram/Discord. You launch `metro` once when the user asks, then act on each inbound JSON line via `metro <subcommand>`.
+Metro is a CLI bridge between this agent session and external sources: Telegram, Discord, and HTTP webhooks from third parties (GitHub, Intercom, Fireflies, …). You launch `metro` once when the user asks, then act on each inbound JSON line via `metro <subcommand>`.
 
 ## Starting the bridge
 
@@ -44,8 +44,8 @@ Every line on stdout is one **history entry** — the same record appended to `h
 - `kind` — `"inbound"`, `"notification"`, `"outbound"`, `"edit"`, or `"react"`
 - `id` (`msg_…`) — universal message ID minted by metro
 - `ts` — ISO timestamp
-- `station` — `"discord"`, `"telegram"`, `"claude"`, `"codex"`
-- `line` — conversation URI; `lineName?` is the channel/topic display name
+- `station` — `"discord"`, `"telegram"`, `"claude"`, `"codex"`, `"webhook"`
+- `line` — conversation URI; `lineName?` is the channel/topic display name (for webhooks: the label you gave it)
 - `from` / `fromName?` — sender participant URI + optional display name
 - `to` — recipient participant URI (agent for inbound, line for notification, original sender for replies/reacts)
 - `text` — universal display projection. Includes `[image]`/`[file: …]`/`[voice]`/`[audio]` tags inline.
@@ -53,11 +53,11 @@ Every line on stdout is one **history entry** — the same record appended to `h
 - `payload?` — raw platform-native message object. Set on inbound only. Shape varies per `station`.
 
 ```json
-{"kind":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","lineName":"infra","from":"metro://telegram/user/12345","fromName":"@alice","to":"metro://claude/agent","messageId":"4567","text":"hi [image]","payload":{"message_id":4567,"chat":{"id":-100,"type":"supergroup","is_forum":true},"from":{"id":12345,"username":"alice"},"text":"hi","photo":[{"file_id":"…"}],"reply_to_message":{"message_id":4500,"text":"earlier","from":{"id":99,"username":"bob"}}}}
+{"kind":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","lineName":"infra","from":"metro://telegram/user/12345","fromName":"@alice","to":"metro://claude/user/9bfc7af0-…","messageId":"4567","text":"hi [image]","payload":{"message_id":4567,"chat":{"id":-100,"type":"supergroup","is_forum":true},"from":{"id":12345,"username":"alice"},"text":"hi","photo":[{"file_id":"…"}],"reply_to_message":{"message_id":4500,"text":"earlier","from":{"id":99,"username":"bob"}}}}
 ```
 
 ```json
-{"kind":"notification","id":"msg_pQ4r5sT0","ts":"…","station":"claude","line":"metro://claude/deploys","from":"metro://codex/ci","to":"metro://claude/deploys","text":"deploy green"}
+{"kind":"notification","id":"msg_pQ4r5sT0","ts":"…","station":"claude","line":"metro://claude/9bfc7af0-…/50b00d11-…","from":"metro://codex/user/8119ecb1-…","to":"metro://claude/9bfc7af0-…/50b00d11-…","text":"deploy green"}
 ```
 
 ### `payload` by station
@@ -66,6 +66,7 @@ Every line on stdout is one **history entry** — the same record appended to `h
 
 - **`discord`** — discord.js `Message.toJSON()`: camelCase fields (`channelId`, `guildId`, `content`, `author`, `mentions: { users[], roles[], everyone }`, `attachments[]`, `reference`, …). Collections come back as **arrays of IDs**. `referencedMessage` is added inline on replies (auto-fetched).
 - **`telegram`** — raw Bot API `Message` (snake_case): `{ message_id, chat, from, text, caption, entities[], photo[], document, voice, audio, reply_to_message, … }`. `reply_to_message` is inline on replies.
+- **`webhook`** — `{ headers, body }`. The provider lives in `headers['x-github-event']`, `headers['x-intercom-topic']`, etc. Full event payload is `body` (parsed JSON when possible). `text` is a short summary; always narrow on `body` for real routing.
 
 Use `payload` for anything the envelope doesn't surface — mentions, reply chains, embeds, entities.
 
@@ -75,15 +76,18 @@ Derive from `payload`. Bot id per station is cached in `$METRO_STATE_DIR/bot-ids
 
 - **discord** — DM when `payload.guildId == null`; otherwise pinged when `payload.mentions.users.includes(<bot-id>)`.
 - **telegram** — DM when `payload.chat.type === 'private'`; otherwise pinged when any entity in `payload.entities` (or `caption_entities`) is `{type:"mention"}` matching `@<bot-username>` or `{type:"text_mention", user:{id:<bot-id>}}`.
+- **webhook** — every POST is "for you" by design (it's an endpoint you registered). Route on `payload.headers['x-github-event']` / `x-intercom-topic` etc. to decide which provider event you're handling.
 
-Default: 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 have no "ack" mechanism — just consume the event.
 
 Both `from` and `to` are **participant URIs** (the conversation context lives in `line`):
 - `metro://<station>/user/<id>` — a person on a chat platform
-- `metro://claude/<topic>` / `metro://codex/<topic>` — an agent
+- `metro://claude/user/<orgId>` — a Claude Code agent (orgId = stable Anthropic-account UUID, same across devices for the same account)
+- `metro://codex/user/<accountId>` — a Codex agent (accountId = stable ChatGPT-account UUID, same across devices)
+- `metro://webhook/<endpoint-id>` — a webhook endpoint (line + `from` are the same — no HTTP-side user identity)
 - `metro://<station>/<channelId>` — a channel (used as `to` for fresh sends to a group, where no single recipient)
 
-When **you** send via `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from = metro://claude/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 automatically the original sender (looked up via the universal id).
+When **you** send via `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from = metro://claude/user/<orgId>` (when `$CLAUDECODE` is set; resolved from `claude auth status --json`) or `metro://codex/user/<accountId>` (from `$METRO_CODEX_RC` / `$CODEX_HOME`; resolved from `$CODEX_HOME/auth.json`). Switching accounts via `claude auth login` / `codex login` flips the id on the next event (within ~5 s for the daemon). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is automatically the original sender (looked up via the universal id).
 
 The `id` is the **canonical handle** for that message across all stations — store it if you want to refer back to it later.
 
@@ -111,7 +115,10 @@ All take positional args (no `--to=`/`--text=` flags). Append `--json` to any fo
 | Reaction (empty emoji clears) | `metro react <line> <messageId> <emoji>` |
 | Download `[image]` attachments → paths | `metro download <line> <messageId> [--out=<dir>]` |
 | Recent channel history (Discord only) | `metro fetch <line> [--limit=20]` |
-| Ping another agent (cross-agent line) | `metro send metro://claude/<topic> <text> [--from=<line>]` |
+| Ping another agent (cross-agent line) | `metro send metro://claude/<agent-id>/<session-id> <text> [--from=<line>]` |
+| Register webhook endpoint | `metro webhook add <label> [--secret=<hmac-secret>]` |
+| List / remove webhook endpoints | `metro webhook list` · `metro webhook remove <id>` |
+| Configure Cloudflare named tunnel | `metro tunnel setup <tunnel-name> <hostname>` |
 
 `reply` / `send` / `edit` accept multi-line text via stdin (heredoc).
 
@@ -152,8 +159,9 @@ Limits / quirks:
 |------------|-------------------------------------------|--------------------------------------|
 | `discord`  | `metro://discord/<channel-id>`            | `metro://discord/1234567890`         |
 | `telegram` | `metro://telegram/<chat-id>[/<topic-id>]` | `metro://telegram/-1001234567890/42` |
-| `claude`   | `metro://claude/<topic>`                  | `metro://claude/deploys`             |
-| `codex`    | `metro://codex/<topic>`                   | `metro://codex/ci`                   |
+| `claude`   | `metro://claude/<agent-id>/<session-id>`  | `metro://claude/9bfc7af0-…/50b00d11-…` |
+| `codex`    | `metro://codex/<agent-id>/<session-id>`   | `metro://codex/8119ecb1-…/01997d4b-…`  |
+| `webhook`  | `metro://webhook/<endpoint-id>`           | `metro://webhook/fwaCgTKJuLAjS2K0`     |
 
 The `messageId` is **not** part of the URI — it's a separate positional arg for `reply` / `edit` / `react` / `download`.
 
@@ -174,8 +182,8 @@ When an event's `text` contains `[image]`:
 Both agents can post to each other's "agent line":
 
 ```bash
-metro send metro://claude/deploys "build green, ready to ship"
-metro send metro://codex/ci "build green" --from=metro://claude/deploys   # override sender
+metro send metro://claude/9bfc7af0-…/50b00d11-… "build green, ready to ship"
+metro send metro://codex/8119ecb1-…/01997d4b-… "build green" --from=metro://claude/user/9bfc7af0-…   # override sender
 ```
 
 The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer agent sees a `{"kind":"notification",...}` event. Requires the metro daemon to be running on the machine — agent-line sends error with `metro daemon is not running` otherwise.
@@ -187,7 +195,7 @@ The daemon re-emits the post on its stdout stream (and pushes via codex-rc if co
 - `metro history` — universal message log (every inbound + outbound + notification across all stations). Newest first. Filters:
   - `--limit=N` (default 50)
   - `--line=<metro://…>` — only this conversation
-  - `--station=<discord|telegram|claude|codex>`
+  - `--station=<discord|telegram|claude|codex|webhook>`
   - `--kind=<inbound|outbound|edit|react|notification>`
   - `--from=<sender>`
   - `--text=<substring>`