@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.151

package/docs/monitor.md

@@ -1,241 +0,0 @@
-# Metro monitor endpoints
-
-Read-only HTTP endpoints for an external observer (the `apps/app` mobile app, an admin
-dashboard, a curl one-liner) to view live daemon state without touching the JSONL files
-directly.
-
-These endpoints mount on the **existing** webhook HTTP server (default port `8420`).
-There is no separate daemon, no separate port, no extra process to launch. The
-implementation lives in [`src/cli/monitor-api.ts`](../src/cli/monitor-api.ts) (re-exported
-by `src/cli/tail.ts` for backwards compatibility) and is wired into the HTTP server in
-[`src/dispatcher/server.ts`](../src/dispatcher/server.ts) via `handleMonitorRequest`.
-
-## Routes
-
-| Method | Path                            | Returns                                                                                  |
-|--------|---------------------------------|------------------------------------------------------------------------------------------|
-| GET    | `/api/state`                    | JSON snapshot — `{ claims, lines, recent_history (last 100), bot_ids }`.                 |
-| GET    | `/api/tail`                     | Server-Sent Events stream — `history.jsonl` entries, claim-aware filtered.                |
-| POST   | `/api/call/<train>/<action>`    | Forward an action call to a train via `forward-call` IPC; returns `{result}`.            |
-| POST   | `/api/messenger/send`           | In-daemon chat: emits a history entry on `metro://messenger/owner`. Accepts `{text?, attachments?[], as?}`. |
-| POST   | `/api/messenger/register`       | Store an Expo push token so agent replies push to the phone.                              |
-| POST   | `/api/messenger/upload`         | Raw binary upload (up to 25 MiB). Body = file bytes; headers `Content-Type`, optional `X-Filename`. Returns `{id, url, kind, mime, size, name?}`. |
-| GET    | `/api/messenger/files/<name>`   | Stream a previously uploaded attachment. Accepts `?token=…` as an alternative to the bearer header for `<img>` / `<audio>` tags. |
-
-`/api/state` and `/api/tail` are read-only. `/api/call/<train>/<action>` is the single
-write endpoint — it never touches the on-disk history; the train running on the daemon
-emits its own outbound event after delivering the message, which then flows through the
-normal SSE stream like any other entry.
-
-## Authentication
-
-Bearer token in env: `METRO_MONITOR_TOKEN`.
-
-- If unset, both routes respond **503** with `{"error":"monitor endpoints not configured (METRO_MONITOR_TOKEN unset)"}`. Anonymous access is never allowed by accident.
-- If set, requests **must** carry `Authorization: Bearer <token>`. Missing/wrong/malformed → **401**. The comparison is constant-time (`crypto.timingSafeEqual`).
-
-Set in `~/.config/metro/.env`:
-
-```
-METRO_MONITOR_TOKEN=<a long random string — `openssl rand -base64 32`>
-```
-
-The daemon picks up the env var on next start.
-
-## `GET /api/state`
-
-Returns a one-shot JSON snapshot:
-
-```jsonc
-{
-  "claims": {
-    "metro://discord/123456789": "metro://claude/user/abc"
-  },
-  "lines": [
-    "metro://discord/123456789",
-    "metro://telegram/-100…"
-  ],
-  "recent_history": [/* most-recent-first, up to 100 HistoryEntry objects */],
-  "bot_ids": { "discord": "1234567890", "telegram": "987654321" },
-  "version": "x.y.z"
-}
-```
-
-- `claims` — verbatim contents of `claims.json`.
-- `lines` — the set of conversation URIs seen across recent history and current claims (good-enough proxy for "what lines exist right now"). Subject to refinement; not authoritative.
-- `recent_history` — same shape as `HistoryEntry` in `src/history.ts`, ordered most-recent-first, capped at 100 entries.
-- `bot_ids` — verbatim contents of `bot-ids.json`.
-- `version` — the daemon's package version (handy for clients gating on capabilities).
-
-### Pagination
-
-For backlog scrolling, pass `?before=<N>&limit=<M>` (both non-negative integers, `limit` clamped to 500):
-
-```bash
-curl -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
-  "https://monitor.metro.box/api/state?before=200&limit=100" | jq .recent_history
-```
-
-When `before` is set, only `recent_history` is returned (the older slice). Without
-`before`, the full snapshot above is returned.
-
-### Example
-
-```bash
-curl -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
-  https://monitor.metro.box/api/state | jq
-```
-
-## `GET /api/tail` (SSE)
-
-Server-Sent Events stream of new `history.jsonl` entries. Each event has:
-
-```
-id: <metro-msg-id>
-event: history
-data: <one HistoryEntry as JSON>
-
-```
-
-The stream stays open until the client disconnects. A `: keepalive` comment is emitted
-every 25 seconds to keep proxies happy.
-
-### Query parameters
-
-All optional. Mirror the `metro tail` CLI flags.
-
-| Param              | Default     | Effect                                                                  |
-|--------------------|-------------|-------------------------------------------------------------------------|
-| `as=<line>`        | (none)      | Self URI — enables "mine + free" claim-aware filtering.                  |
-| `mode=strict\|unclaimed\|all` | derived | Override the mode (`strict` needs `as=`).                            |
-| `chat=<line>`      | (none)      | Only emit events matching this exact `line`.                            |
-| `station=<name>`   | (none)      | Only emit events matching this station (`discord`, `telegram`, …).      |
-| `include_webhooks=true` | `false`  | Include webhook-station events in personal modes.                       |
-| `since=tail\|0\|<offset>` | `tail` | Where to start in `history.jsonl`. `tail` = EOF; `0` = full replay; or a byte offset. |
-
-### Filter rule
-
-Same predicate as `metro tail --as=<id> [--strict|--unclaimed|--all] [--include-webhooks]`:
-
-> An event is delivered when its `line` is **claimed by `as=`** *or* **claimed by no one**,
-> minus webhooks (unless `include_webhooks=true`), minus anything failing `chat=`/`station=`.
-
-See [broker.md](./broker.md) for the underlying broker semantics.
-
-### Example: live tail for a claude user
-
-```bash
-curl -N \
-  -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
-  "https://monitor.metro.box/api/tail?as=metro://claude/user/abc&include_webhooks=true"
-```
-
-The `-N` flag disables curl's output buffering so SSE frames appear as they arrive.
-
-### Example: full backlog replay for debugging
-
-```bash
-curl -N \
-  -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
-  "https://monitor.metro.box/api/tail?since=0"
-```
-
-## `POST /api/call/<train>/<action>`
-
-Forwards an action call to a train (same as `metro call <train> <action> <args>` on the
-command line) via the daemon's existing `forward-call` IPC. Use this from the mobile or
-web app to send a message, react, edit, etc. without needing shell access.
-
-### Request
-
-```http
-POST /api/call/discord/send HTTP/1.1
-Host: monitor.metro.box
-Authorization: Bearer <METRO_MONITOR_TOKEN>
-Content-Type: application/json
-
-{"args": {"line": "metro://discord/123", "text": "hello from the web"}}
-```
-
-The body is one of:
-
-- `{"args": <object|array|string>}` — explicit `args` wrapper (recommended).
-- `<object>` — any other JSON object is forwarded as the args verbatim (useful for terse
-  clients).
-- Empty body — forwarded as `{}`.
-
-`<train>` must match a train running under `~/.metro/trains/`; `<action>` is whatever
-that train expects (`send`, `react`, `edit`, …).
-
-### Response
-
-| Status | Body                                                | Meaning                                                  |
-|--------|-----------------------------------------------------|----------------------------------------------------------|
-| 200    | `{"result": <whatever the train returned>}`         | Train accepted the call and returned a result.           |
-| 400    | `{"error": "bad JSON body: …"}`                      | Body was not valid JSON.                                 |
-| 401    | `{"error": "unauthorized"}`                          | Missing / wrong bearer token.                            |
-| 405    | `{"error": "method not allowed"}`                    | Wrong verb (only `POST` is accepted on this path).       |
-| 500    | `{"error": "…"}`                                     | Daemon IPC unavailable (e.g. socket missing).            |
-| 502    | `{"error": "…"}`                                     | Train returned an error or the IPC handshake malformed.  |
-
-Request bodies larger than 256 KiB are rejected with HTTP 500.
-
-### Example: send a message
-
-```bash
-curl -X POST \
-  -H "Authorization: Bearer $METRO_MONITOR_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"args":{"line":"metro://discord/123","text":"hi"}}' \
-  https://monitor.metro.box/api/call/discord/send
-```
-
-Because the daemon's `send` adapter writes a history entry once the message lands, an
-active `/api/tail` subscriber will receive the corresponding event a moment later
-(`from` = local user). UIs typically clear the input on HTTP 200 and let the SSE replay
-show the sent message.
-
-## Exposing publicly via Cloudflare tunnel
-
-The daemon listens on `127.0.0.1:8420` only. To reach `/api/*` from a phone or a
-remote machine, route a public hostname through the existing `webhook.metro.box`
-cloudflared tunnel.
-
-Add a second hostname route to your `cloudflared` config (typically
-`~/.cloudflared/config.yml`):
-
-```yaml
-ingress:
-  - hostname: webhook.metro.box
-    service: http://127.0.0.1:8420
-  - hostname: monitor.metro.box     # new — same backing service
-    service: http://127.0.0.1:8420
-  - service: http_status:404
-```
-
-Then create the DNS record:
-
-```bash
-cloudflared tunnel route dns <tunnel-name> monitor.metro.box
-```
-
-Restart the tunnel; both hostnames now reach the same metro daemon. `webhook.metro.box`
-keeps serving inbound webhooks; `monitor.metro.box` serves the bearer-token-gated
-monitor routes.
-
-There's no harm in serving `/api/*` from `webhook.metro.box` too — the bearer-token
-gate is the same either way. The separate hostname is purely a routing convenience
-(and lets you put different access policies in front of each, e.g., Cloudflare Access
-on `monitor.metro.box` only).
-
-## Failure modes
-
-| Condition                          | Response                                                          |
-|------------------------------------|-------------------------------------------------------------------|
-| `METRO_MONITOR_TOKEN` not set      | 503 `{"error":"monitor endpoints not configured (...)"}`         |
-| Missing `Authorization` header     | 401 `{"error":"unauthorized"}`                                    |
-| Wrong / malformed token            | 401 `{"error":"unauthorized"}`                                    |
-| Unknown `/api/*` path              | 404 `{"error":"not found"}`                                       |
-| `POST` (or any non-`GET`) to `/api/*` | 405 `{"error":"method not allowed"}`                            |
-| `history.jsonl` doesn't exist yet  | 200 with empty `recent_history` / SSE stream w/ no events.       |
-| Client disconnects mid-SSE         | Handler clears its interval + closes the file watcher cleanly.   |

package/docs/uri-scheme.md

@@ -1,127 +0,0 @@
-# Metro URI scheme
-
-Universal identifier for every conversational scope in metro. Lines pass around as opaque strings; only the owning station parses its own paths.
-
-## Grammar
-
-```
-line       = "metro://" station "/" path
-station    = lowercase identifier (claude | codex | discord | telegram | webhook | …)
-path       = station-specific, "/"-separated segments
-```
-
-The URI parses cleanly with the WHATWG `URL` parser: `new URL(line)` gives `protocol="metro:"`, `host=<station>`, `pathname="/<path>"`.
-
-## Registered stations
-
-| Station    | Pattern                                      | Example                                                                |
-|------------|----------------------------------------------|------------------------------------------------------------------------|
-| `discord`  | `metro://discord/<channel-id>`               | `metro://discord/1234567890123456789`                                  |
-| `telegram` | `metro://telegram/<chat-id>[/<topic-id>]`    | `metro://telegram/-1001234567890/42`                                   |
-| `claude`   | `metro://claude/<user-id>/<session-id>`      | `metro://claude/9bfc7af0-…/50b00d11-…`                                 |
-| `codex`    | `metro://codex/<user-id>/<session-id>`       | `metro://codex/8119ecb1-…/01997d4b-…`                                  |
-| `webhook`  | `metro://webhook/<endpoint-id>`              | `metro://webhook/fwaCgTKJuLAjS2K0`                                     |
-
-Claude / Codex lines mirror the `<root>/<sub>` structure of `metro://telegram/<chat-id>/<topic-id>`: `<user-id>` (the stable account id — same across devices) plays the role of `<chat-id>`, and `<session-id>` (one conversation) plays the role of `<topic-id>`. Both segments are derived per station (see [participants](#participants) below).
-
-## Participants
-
-Every chat station also exposes participant URIs — used as `from` on inbound/outbound events and history rows.
-
-| Kind   | Pattern                          | Example                                                       |
-|--------|----------------------------------|---------------------------------------------------------------|
-| user    | `metro://<station>/user/<id>`    | `metro://discord/user/87654321`                               |
-| claude  | `metro://claude/user/<orgId>`    | `metro://claude/user/9bfc7af0-2117-44c5-baf2-d22ba382d065`    |
-| codex   | `metro://codex/user/<accountId>` | `metro://codex/user/8119ecb1-b05e-48db-aa80-434584439df9`     |
-| webhook | `metro://webhook/<endpointId>`   | `metro://webhook/fwaCgTKJuLAjS2K0` (line + `from` are the same — no HTTP-side user identity) |
-
-`from` and `to` on history entries are always participant URIs. Discord/Telegram inbounds set `from` to the user URI; the daemon sets `to` to the local user 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://user`.
-
-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 user 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). Claude / Codex lines identify a *specific session* of a specific user (`<user-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  | `<user-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_USER_ID` / `METRO_USER_SESSION_ID` env vars.
-
-### User registry
-
-The daemon persists every `(station, user-id, session)` tuple it sees to `$METRO_STATE_DIR/user-registry.json`. `metro lines` lists the recently-seen conversation URIs.
-
-## 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; consumers narrow on `payload.body` for full event details.
-- **HMAC verification:** if `--secret` was set on `metro webhook add`, requests must include a matching `X-Hub-Signature-256: sha256=<hex>` (GitHub/Intercom format) — mismatches are rejected with 401 before reaching the stream.
-- **Public reachability:** provided by a Cloudflare named tunnel — see [Tunneling](#tunneling) below. Without one, the listener stays loopback-only (useful for `curl` testing).
-
-## Tunneling
-
-Webhook providers need a public URL. Metro integrates with **Cloudflare named tunnels** (free, stable, account-scoped):
-
-```bash
-cloudflared tunnel login                                   # one-time OAuth (browser)
-metro tunnel setup metro webhook.yourdomain.com            # creates the tunnel + DNS route
-metro                                                      # daemon spawns `cloudflared tunnel run`
-```
-
-After setup, `metro webhook list` prints `https://webhook.yourdomain.com/wh/<id>` for each endpoint. The URL is stable across restarts (bound to the tunnel UUID in `~/.cloudflared/<uuid>.json`, not the cloudflared process). Tunnel config persists at `$METRO_STATE_DIR/tunnel.json`. Without setup, endpoints fall back to `http://127.0.0.1:8420/wh/<id>` (local-only, useful for curl testing).
-
-## Message addressing
-
-Messages on chat lines are referenced by **line + message id** (two args), not as part of the URI. So:
-
-```bash
-metro call discord send '{"line":"metro://discord/123","text":"ack","replyTo":"4567"}'
-metro call discord edit '{"line":"metro://discord/123","messageId":"9876","text":"fixed typo"}'
-metro call telegram react '{"line":"metro://telegram/-100/42","messageId":"4567","emoji":"👍"}'
-```
-
-## Properties
-
-- **Stable**: a Line is valid for the lifetime of the scope.
-- **Self-describing**: the station name is encoded; the dispatcher routes by station prefix.
-- **Persistable**: safe as a JSON key on disk (used by `lines.json`).
-- **Branded**: TypeScript type `Line` prevents mixing with arbitrary strings.
-
-## API
-
-```ts
-import { Line } from './lines.js';            // value namespace + type
-
-const l: Line = Line.discord('1234567890');     // typed Line
-Line.parse(l);                                   // { station: 'discord', path: ['1234567890'] } | null
-Line.station(l);                                 // 'discord'
-Line.claude(orgId, sessionId);                   // metro://claude/<orgId>/<sessionId>
-Line.codex(accountId, threadId);                 // metro://codex/<accountId>/<threadId>
-Line.parseClaude(l);                             // { userId, sessionId } | null
-Line.parseCodex(l);                              // { userId, 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.isLocal(l);                                 // true for any metro://{claude,codex}/...
-```
-
-## Adding a new station
-
-A "station" in this URI scheme is just a namespace — anything a train emits with
-`metro://<name>/<path>` works. There is no required registration with core:
-
-1. Pick a lowercase station name (`slack`, `matrix`, …).
-2. In your train, emit envelopes with `line: "metro://<name>/<id>"`.
-3. Optionally add a `Line.<station>(...)` formatter to `src/lines.ts` for type-safe construction.

package/examples/README.md

@@ -1,32 +0,0 @@
-# Example train
-
-`telegram.ts` is a starting point, not runtime code. Copy to
-`~/.metro/trains/<name>.ts`, edit, save, restart the daemon:
-
-```
-cp telegram.ts ~/.metro/trains/telegram.ts
-echo 'TELEGRAM_BOT_TOKEN=…' >> ~/.metro/.env
-metro
-```
-
-For a Discord port: swap the API base + auth header (`Bot $TOKEN`), install
-`discord.js` for the gateway, and emit the same envelope shape — the
-stdin/stdout protocol below is platform-independent. Action names and payload
-shapes are entirely up to you.
-
-## Protocol (JSON lines over stdio)
-
-```
-metro  ─── stdin (one JSON line per action call) ──>  train
-       <── stdout (one JSON line per event OR response) ── train
-```
-
-- **Inbound event** (train → metro): `{ kind, station, line, from, from_name?, message_id?, line_name?, reply_to?, text?, is_private?, payload? }` — snake_case on the wire. Metro mints `id` + `display` if absent and translates to camelCase for `history.jsonl` / the broker (`HistoryEntry` in `src/history.ts`).
-- **Call** (metro → train): `{ "op": "call", "id": "req_abc", "action": "send", "args": {...} }`.
-- **Response** (train → metro): `{ "op": "response", "id": "req_abc", "result": {...} }` or `{ ..., "error": "..." }`.
-
-Anything on stdout without an `op` is treated as an inbound event.
-
-## Lifecycle
-
-Metro scans `~/.metro/trains/*.{ts,js,mjs}` at boot — one subprocess per file. Crashed trains restart with backoff (1s → 5s → 30s, up to 5 consecutive failures). `metro trains list` shows state. Restart the daemon to pick up edits. `~/.metro/.env` is auto-loaded into each train's `process.env`.

package/examples/telegram.ts

@@ -1,121 +0,0 @@
-/**
- * Reference train — Telegram (long-polling, no npm deps). Pattern is identical for any platform.
- *
- * Setup:
- *   cp <this-file> ~/.metro/trains/telegram.ts
- *   echo 'TELEGRAM_BOT_TOKEN=…' >> ~/.metro/.env
- *
- * Discord-flavoured port: swap the API base + `tg()` helper for `https://discord.com/api/v10`
- * with `Authorization: Bot $TOKEN`, install `discord.js` for the gateway, and emit the same
- * envelope shape. The stdin/stdout protocol is platform-independent. Discord adds `sticker_ids`
- * support on `sendMessage` payloads — preserve those in `payload` so downstream tooling sees them.
- */
-
-const TOKEN = process.env.TELEGRAM_BOT_TOKEN;
-if (!TOKEN) { process.stderr.write('TELEGRAM_BOT_TOKEN unset\n'); process.exit(2); }
-const API = `https://api.telegram.org/bot${TOKEN}`;
-
-const emit = (e: unknown): void => void process.stdout.write(JSON.stringify(e) + '\n');
-const respond = (id: string, body: { result?: unknown; error?: string }): void =>
-  void process.stdout.write(JSON.stringify({ op: 'response', id, ...body }) + '\n');
-const mintId = (): string => `msg_${Math.random().toString(36).slice(2, 10)}`;
-/** Self URI for outbound emissions. Set by the supervisor; trains echo their own sends so mobile + tail see them. */
-const SELF_URI = process.env.METRO_SELF_URI ?? '';
-const emitOutbound = (line: string, messageId: string, text: string, replyTo?: string): void => emit({
-  kind: 'outbound', id: mintId(), ts: new Date().toISOString(),
-  station: 'telegram', line, from: SELF_URI, to: line, message_id: messageId, text, reply_to: replyTo,
-});
-
-async function tg<T>(method: string, body: unknown, timeoutMs = 30_000): Promise<T> {
-  const res = await fetch(`${API}/${method}`, {
-    method: 'POST', headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs),
-  });
-  const json = (await res.json()) as { ok: boolean; description?: string; result?: T };
-  if (!json.ok) throw new Error(`telegram ${method}: ${json.description ?? 'unknown'}`);
-  return json.result as T;
-}
-
-type TgMsg = {
-  message_id: number; date: number;
-  chat: { id: number; type: string; title?: string; first_name?: string };
-  from?: { id: number; username?: string; first_name?: string; is_bot?: boolean };
-  text?: string; caption?: string;
-  message_thread_id?: number; is_topic_message?: boolean;
-  photo?: unknown[]; document?: { file_name?: string };
-};
-
-function envelope(m: TgMsg): Record<string, unknown> {
-  const tags = [...(m.photo?.length ? ['[image]'] : []), ...(m.document ? [`[file: ${m.document.file_name ?? 'doc'}]`] : [])];
-  const text = [m.text ?? m.caption, ...tags].filter(Boolean).join(' ');
-  const topicId = m.is_topic_message ? m.message_thread_id : undefined;
-  const line = topicId !== undefined ? `metro://telegram/${m.chat.id}/${topicId}` : `metro://telegram/${m.chat.id}`;
-  return {
-    kind: 'inbound', id: mintId(), ts: new Date(m.date * 1000).toISOString(),
-    station: 'telegram', line,
-    line_name: topicId === undefined ? (m.chat.title ?? m.chat.first_name ?? undefined) : undefined,
-    from: `metro://telegram/user/${m.from?.id ?? 'unknown'}`,
-    from_name: m.from?.username ? `@${m.from.username}` : m.from?.first_name,
-    message_id: String(m.message_id), text, payload: m, is_private: m.chat.type === 'private',
-  };
-}
-
-const targetOf = (line: string): { chatId: number; topicId?: number } => {
-  const m = line.match(/^metro:\/\/telegram\/(-?\d+)(?:\/(\d+))?/);
-  if (!m) throw new Error(`bad telegram line: ${line}`);
-  return { chatId: Number(m[1]), topicId: m[2] ? Number(m[2]) : undefined };
-};
-
-type CallMsg = { op: 'call'; id: string; action: string; args: Record<string, unknown> };
-async function handleCall({ id, action, args }: CallMsg): Promise<void> {
-  try {
-    if (action === 'send') {
-      const { line, text, replyTo } = args as { line: string; text: string; replyTo?: string };
-      const { chatId, topicId } = targetOf(line);
-      const body: Record<string, unknown> = { chat_id: chatId, text };
-      if (topicId !== undefined) body.message_thread_id = topicId;
-      if (replyTo) body.reply_parameters = { message_id: Number(replyTo) };
-      const sent = await tg<{ message_id: number }>('sendMessage', body);
-      const sentId = String(sent.message_id);
-      emitOutbound(line, sentId, text, replyTo);
-      respond(id, { result: { messageId: sentId } });
-    } else if (action === 'react') {
-      const { line, messageId, emoji } = args as { line: string; messageId: string; emoji: string };
-      await tg('setMessageReaction', {
-        chat_id: targetOf(line).chatId, message_id: Number(messageId),
-        reaction: emoji ? [{ type: 'emoji', emoji }] : [],
-      });
-      respond(id, { result: { ok: true } });
-    } else respond(id, { error: `unknown action '${action}' (have: send, react)` });
-  } catch (err) { respond(id, { error: (err as Error).message }); }
-}
-
-let buf = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => {
-  buf += chunk;
-  let nl;
-  while ((nl = buf.indexOf('\n')) !== -1) {
-    const line = buf.slice(0, nl).trim();
-    buf = buf.slice(nl + 1);
-    if (!line) continue;
-    try { const msg = JSON.parse(line); if (msg.op === 'call') void handleCall(msg); }
-    catch (err) { process.stderr.write(`bad stdin line: ${(err as Error).message}\n`); }
-  }
-});
-
-let offset = 0;
-process.stderr.write('telegram train ready\n');
-while (true) {
-  try {
-    const updates = await tg<{ update_id: number; message?: TgMsg }[]>('getUpdates',
-      { offset, timeout: 25, allowed_updates: ['message'] }, 60_000);
-    for (const u of updates) {
-      offset = u.update_id + 1;
-      if (u.message && !u.message.from?.is_bot) emit(envelope(u.message));
-    }
-  } catch (err) {
-    process.stderr.write(`telegram poll error: ${(err as Error).message}\n`);
-    await new Promise(r => setTimeout(r, 2_000));
-  }
-}

package/skills/metro/SKILL.md

@@ -1,110 +0,0 @@
----
-name: metro
-description: Run the metro train-supervisor 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 `{"station":"…","line":"metro://…","from":"…","to":"…","text":"…"}`, or when handling a chat/webhook reply/edit/react/send via `metro call`.
----
-
-# Metro — event-interception wire
-
-Metro is the wire between this session and any number of platforms. Platform code lives in
-**trains** under `~/.metro/trains/` — single TS files that you (the agent) write, edit, or
-replace on demand.
-
-## What metro does
-
-1. Spawns each file in `~/.metro/trains/*.{ts,js,mjs}` as a long-running Bun subprocess.
-2. Multiplexes their stdout (JSON lines) into one unified event stream on metro's stdout.
-3. Routes `metro call <train> <action> <args>` requests back to the matching train's stdin.
-4. Two builtin event sources stay in core: **webhooks** (HTTP receiver) and **messenger** (in-daemon chat).
-
-## Starting metro
-
-**Claude Code:** `Bash(command: "metro", run_in_background: true)`, then attach `Monitor` to its stdout.
-
-**Codex:** `shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)` — metro pushes each event via JSON-RPC `turn/start`. The user must run a Codex daemon + TUI on the same WebSocket URL (`codex app-server --listen ws://127.0.0.1:8421` + `codex --remote ws://127.0.0.1:8421`, type "hi" once to seed a thread).
-
-`metro doctor` reports trains found, deps installed, dispatcher running, codex-rc, skill install.
-
-## Envelope
-
-Every event on stdout is a single JSON line:
-
-```json
-{"id":"msg_…","ts":"2026-05-17T18:00:00Z","station":"discord","line":"metro://discord/123","line_name":"infra","from":"metro://discord/user/456","from_name":"alice","to":"metro://claude/user/9bfc…","text":"hi","message_id":"789","reply_to":"…","payload":{…}}
-```
-
-Wire fields are `snake_case` on the train protocol; the dispatcher translates to camelCase for `history.jsonl`. Trains supply `line`, `from`, `to`, `text`, plus `payload` (the platform's native message). Metro mints `id` + `display` if missing.
-
-**No `kind` field.** Direction is derived: `Line.isLocal(from)` → outbound (📤), else inbound (📩). Reactions and edits are train-specific — encode them in `text` (e.g. `[react 👀]`) plus whatever you need in `payload`.
-
-## Outbound: `metro call <train> <action> <args>`
-
-```
-metro call discord send '{"line":"metro://discord/123","text":"hi","replyTo":"789"}'
-metro call telegram react '{"line":"metro://telegram/-100/1","messageId":"42","emoji":"👀"}'
-metro call discord edit  '{"line":"metro://discord/123","messageId":"999","text":"new"}'
-```
-
-`[args]` can be JSON, `@path/to/args.json`, `-` (stdin), or a bare string. Action names are whatever the train exposes — metro core knows nothing about them.
-
-## Writing a new train
-
-1. Start from `node_modules/@stage-labs/metro/examples/telegram.ts`.
-2. Copy → `~/.metro/trains/<name>.ts` and edit. Keep the inbound envelope shape and the `op:"call"` → `op:"response"` protocol.
-3. Deps (if needed): `cd ~/.metro && bun add <pkg>`. Credentials: `echo 'FOO_TOKEN=…' >> ~/.metro/.env`.
-4. Restart the metro daemon (or just `metro trains restart <name>`) to pick up the new train.
-
-Trains are throwaway — if the user asks for new functionality, rewrite the train rather than adding glue in core.
-
-## First-run setup (once per machine)
-
-```
-mkdir -p ~/.metro && cd ~/.metro && bun init -y
-cp node_modules/@stage-labs/metro/examples/telegram.ts ~/.metro/trains/
-echo 'TELEGRAM_BOT_TOKEN=…' >> ~/.metro/.env
-metro setup skill    # optional — installs this SKILL.md into ~/.claude / ~/.codex
-metro
-```
-
-## Detecting "is this for me?"
-
-Trains should set `is_private: true` for DMs. For groups, narrow on `payload`:
-
-- **discord** — DM when `payload.guildId == null`; otherwise look at `payload.mentions.users`.
-- **telegram** — DM when `payload.chat.type === 'private'`; otherwise look at `payload.entities` mentions.
-- **webhook** — every POST is for you by design. Route on `payload.headers['x-github-event']` / `x-intercom-topic`.
-- **messenger** — every event on the messenger line is between the user and the agent. No filtering needed.
-
-## CLI cheat sheet
-
-```
-metro                                       # start the daemon
-metro trains [list]                         # list trains + state
-metro trains new <name>                     # scaffold ~/.metro/trains/<name>.ts
-metro trains restart <name>                 # kill + respawn a train (resets backoff)
-metro call <train> <action> <args>          # forward an action call
-metro tail [--as=<user-uri>] [--follow]     # subscribe to the event log
-metro history [--limit=N] [--line=…] [--from=…] [--text=…] [--since=…]
-metro webhook add <label>                   # register an HTTP receive endpoint
-metro tunnel setup <name> <hostname>        # configure a Cloudflare named tunnel
-metro doctor                                # health check
-```
-
-## Webhooks (builtin source)
-
-Webhooks stay in core because they're shared HTTP infra (one Cloudflare tunnel routes many endpoints). `metro webhook add <label>` issues an endpoint id; the full URL is `https://<tunnel-host>/wh/<id>` (or `http://127.0.0.1:8420/wh/<id>` locally). Events arrive on `metro://webhook/<id>`.
-
-## Messenger (builtin source)
-
-Direct chat between the agent and the device. Five endpoints — all under the same bearer-token guard as `/api/state`:
-
-- `POST /api/messenger/send {text?, attachments?, as?}` — emit an envelope on `metro://messenger/owner`. Either text or attachments required.
-- `POST /api/messenger/react {messageId, emoji, as?}` — emit a slim `payload.reactTo` envelope. If the sender already has an active reaction with this emoji on this target, emits `{removed: true}` instead — reactions are toggleable.
-- `POST /api/messenger/upload` — raw binary upload (≤ 25 MiB, body = file bytes, `Content-Type` + optional `X-Filename` headers). Returns `{id, url, kind, mime, size, name?}`; files land in `$METRO_STATE_DIR/messenger-uploads/`.
-- `GET /api/messenger/files/<name>` — stream a stored upload. Accepts `Authorization: Bearer …` header *or* `?token=…` query (for `<img>` / `<audio>` tags). Content-Type derived from extension.
-- `POST /api/messenger/register {pushToken}` — store an Expo push token so agent replies push to the device.
-
-The mobile + web companion apps use these for chat with the agent. The envelope is the standard slim shape — no `kind` / `emoji` fields, direction derived from `Line.isLocal(from)`.
-
-## Crashes
-
-If a train crashes, metro restarts it with backoff (1s → 5s → 30s, then gives up after 5 consecutive failures). Use `metro trains` to check state.