@stage-labs/metro 0.1.0-beta.0 → 0.1.0-beta.10

package/README.md

@@ -1,93 +1,249 @@
 # Metro
 
-Chat with your Claude Code or Codex agent over Telegram and Discord. Messages land in the session live, the agent reacts, types while it works, and replies — ~700 lines of TypeScript, one stdio MCP, no hosted infra.
+> **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, 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]
+
+$ metro &                              # backgrounded
+$ Monitor( … metro's stdout … )
+
+>>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","messageId":"9876",
+     "text":"@bot we got a 5xx spike from /v1/sync. Look?",
+     "payload":{"channelId":"123…","guildId":"456…","content":"<@…> we got a 5xx spike…",
+                "mentions":{"users":["<bot-id>"],"roles":[],"everyone":false},…}}
+
+  [I'd run git log + read services/sync.ts, then…]
+  Bash: metro reply metro://discord/123… 9876 "three deploys in the last 24h…"
+```
+
+The agent owns its own streaming, tool calls, and reply timing. Metro is the wire.
+
+---
 
 ## Quickstart
 
 ```bash
 npm install -g @stage-labs/metro@beta    # or: bun add -g @stage-labs/metro@beta
+
+metro setup discord <token>              # https://discord.com/developers/applications
+metro setup telegram <token>             # https://t.me/BotFather
+metro doctor                             # verify
+metro                                    # run the daemon
 ```
 
-> The `@beta` tag is required while Metro is in prerelease.
+Requires **Node ≥ 22 or Bun ≥ 1.3**. Metro doesn't launch Claude or Codex — you do, and the agent launches metro. See [`docs/agents.md`](docs/agents.md).
 
-Register Metro with your agent (use `claude` or `codex` interchangeably):
+In **Discord**: DM the bot, or `@<bot>` in any channel. In **Telegram**: DM, or `@<bot>` in a forum supergroup. Every inbound becomes one JSON line on `metro`'s stdout.
 
-```bash
-claude mcp add metro \
-  --env TELEGRAM_BOT_TOKEN=123:ABC… \
-  --env DISCORD_BOT_TOKEN=MTIz… \
-  -- metro mcp
+---
+
+## Architecture
+
+```
+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)
 ```
 
-Both `--env` flags are optional — configure at least one of Telegram or Discord.
+- **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/<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.
+
+---
+
+## Stations
 
-In your agent session, ask it to start the inbound stream:
+Each endpoint is a **station** with declared capabilities:
 
-> Run `metro tail` in the background and Monitor its stdout for inbound Telegram/Discord messages.
+| 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)            |
 
-DM your bot. The agent reacts on its next decision boundary (see Caveats for latency notes).
+Run `metro stations` to see live config status (`✓` configured, `✗` not, `·` informational).
 
-## Bot tokens
+Behaviors worth knowing:
+- **No streaming / no edit machinery in metro.** The agent runs the show; metro is one-shot REST.
+- **No link previews.** Outgoing messages set `link_preview_options.is_disabled` on Telegram and `SUPPRESS_EMBEDS` on Discord.
+- **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.
 
-- **Telegram**: DM [@BotFather](https://t.me/BotFather), `/newbot`, copy the token.
-- **Discord**: [discord.com/developers/applications](https://discord.com/developers/applications) → New Application → Bot → Reset Token. **Toggle Message Content Intent** in the same Bot tab (Privileged Gateway Intents) — without it, message bodies arrive empty. Generate an OAuth invite with the `bot` scope, or DM the bot directly.
+---
 
-## How it works
+## Webhooks
 
-Metro ships two commands:
+Receive HTTP events from third parties (GitHub, Intercom, Fireflies, anything that POSTs) as standard metro inbound events. Each registered endpoint is one Line.
 
-- **`metro mcp`** — a stdio MCP server. Registers the tools below so the agent can reply, react, edit, and download attachments. Started once when the agent boots (via `claude mcp add` / `codex mcp add` above).
-- **`metro tail`** — the inbound runtime. Polls Telegram and connects to Discord's WebSocket gateway, then prints one JSON line per inbound message to stdout. The agent watches that stdout (Bash+Monitor in Claude Code, unified_exec in Codex) and acts on each line at its next decision boundary. Started on demand from inside an agent session.
+```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)
 
-While the agent works on a reply, both platforms show a typing indicator; when it replies, the indicator stops and the auto-ack reaction (👀) is cleared on the exact message replied to.
+metro                                          # daemon binds 8420 + spawns cloudflared automatically
+```
 
-## MCP tools
+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.
 
-Registered by `metro mcp` — the agent calls these to act on the messages it sees from `metro tail`:
+| 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` |
 
-| Tool | Telegram | Discord | Purpose |
-|---|---|---|---|
-| Reply | `telegram-reply` | `discord-reply` | Quote-reply, threading under the original message. Clears the 👀 auto-ack. |
-| React | `telegram-react` | `discord-react` | Set or clear an emoji reaction. |
-| Edit | `telegram-edit-message` | `discord-edit-message` | Edit a message the bot previously sent. |
-| Download attachment | `telegram-download-attachment` | `discord-download-attachment` | Pull image attachments back as `image` content blocks. |
-| Fetch recent messages | — | `discord-fetch-messages` | Lookback for context. (Discord exposes no search API for bots; Telegram has none either.) |
+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.
 
-The agent reads `chat_id` / `channel_id` and `message_id` from the inbound JSON and threads them through. Voice / audio surface as `[voice]` / `[audio]` text placeholders — the agent sees them but can't download.
+---
 
-## Config
+## Lines
 
-All settings come from environment variables passed via the MCP server's `--env` block:
+Every conversational scope is identified by a **Line** — a URI in the form `metro://<station>/<path>`:
+
+```
+metro://discord/1234567890123456789
+metro://telegram/-1001234567890                 # main chat / DM
+metro://telegram/-1001234567890/42              # forum topic 42
+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).
+
+---
+
+## CLI
+
+```
+metro                                       Run the daemon (emits JSON events on stdout).
+metro setup [telegram|discord <token>]      Save token, or show status.
+metro setup clear [telegram|discord|all]    Remove tokens.
+metro doctor                                Health check.
+metro stations                              List stations + capabilities.
+metro lines                                 List recently-seen conversations.
+metro send <line> <text> [--image=…]… [--document=…]… [--voice=…] [--buttons=…]
+                                            Post a fresh message; --image/--document repeat for albums.
+metro reply <line> <message_id> <text> [--image|--document|--voice|--buttons]
+                                            Threaded reply (same flags as send).
+metro edit <line> <message_id> <text> [--buttons=<json>]
+                                            Edit a previously-sent message (text + URL-button keyboard).
+metro react <line> <message_id> <emoji>     Set or clear ('') a reaction.
+metro download <line> <message_id> [--out=<dir>]
+                                            Download image attachments to disk.
+metro fetch <line> [--limit=N]              Recent-message lookback (Discord only).
+metro 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.
+```
+
+All commands accept `--json`. `reply` / `send` / `edit` read multi-line `<text>` from stdin if no positional is given.
+
+**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/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
+
+---
+
+## Configuration
 
 | Variable | Default | Description |
 |---|---|---|
-| `TELEGRAM_BOT_TOKEN` | — | Telegram bot token. Required for the Telegram channel. |
-| `DISCORD_BOT_TOKEN` | — | Discord bot token. Required for the Discord channel. |
-| `METRO_LOG_LEVEL` | `info` | `trace`/`debug`/`info`/`warn`/`error`/`fatal`. |
-| `METRO_STATE_DIR` | `~/.cache/metro` | Where the lockfile, typing-stop signals, and the Telegram attachment cache live. |
+| `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, registries, tunnel config. |
+| `METRO_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
 
-Logs go to stderr. Claude Code captures them at `~/Library/Caches/claude-cli-nodejs/…/mcp-logs-plugin-metro-metro/*.jsonl`.
+Precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs go to stderr.
 
-For local dev (cloned repo, no host agent): `cp .env.example .env && chmod 600 .env`, then run `metro tail` / `metro mcp` from the repo dir — `.env` is read as a fallback when env vars aren't set.
+---
 
-## Troubleshooting
+## Develop
 
 ```bash
-which metro                                # → e.g. ~/.bun/bin/metro
-metro                                      # prints usage
+git clone https://github.com/bonustrack/metro && cd metro
+bun install && bun run build
+bun link                                 # makes `metro` resolve to this checkout
+METRO_LOG_LEVEL=debug metro
 
-ps aux | grep metro | grep -v grep         # one `metro mcp`, optionally one `metro tail`
+bun run typecheck                        # ts
+bun run lint                             # eslint
+```
 
-rm -rf ~/.cache/metro/                     # clean stuck state — or whatever METRO_STATE_DIR points at
+Source map:
 
-# Latest agent-side log (Claude Code):
-ls -t ~/Library/Caches/claude-cli-nodejs/-Users-*-metro/mcp-logs-plugin-metro-metro/*.jsonl | head -1 | xargs cat
-```
+- [`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`, 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).
+
+---
 
 ## Caveats
 
-- **Discord Message Content Intent** is privileged — toggle it in the Developer Portal. See above.
-- **Telegram single-poller.** Telegram allows one `getUpdates` consumer per bot token. If two `metro tail` instances start, the second-comer detects the lockfile (`$METRO_STATE_DIR/.tail-lock`) and exits cleanly. Re-run after the first exits to take over.
-- **No allowlist.** Anyone who can DM your bot or @-mention it can talk to your session. Run against bots you own.
-- **Mid-task latency.** New messages surface at the next agent decision boundary — sub-second on Claude Code (lots of small tool calls), longer on Codex turns. Neither runtime can interrupt an in-progress LLM generation.
-- **UI visibility.** Claude Code's `Monitor` collapses stdout into a card; Codex dims MCP tool args. Metro's MCP `instructions` direct the agent to echo each inbound in its visible reply so you see what arrived without expanding cards.
+- **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.
+
+---
+
+## Uninstall
+
+```bash
+metro setup clear
+rm -rf ~/.cache/metro
+npm uninstall -g @stage-labs/metro
+```

package/dist/cache.js

@@ -0,0 +1,75 @@
+/** Per-machine caches: seen lines (lines.json) + bot ids (bot-ids.json). */
+import { existsSync, readFileSync, writeFileSync } 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';
+const cacheFile = join(STATE_DIR, 'lines.json');
+const FLUSH_DELAY_MS = 5_000;
+let cache = null;
+let dirty = false;
+let flushTimer = null;
+function read() {
+    if (cache)
+        return cache;
+    if (!existsSync(cacheFile))
+        return cache = {};
+    try {
+        cache = JSON.parse(readFileSync(cacheFile, 'utf8'));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err), path: cacheFile }, 'lines cache read failed; treating as empty');
+        cache = {};
+    }
+    return cache;
+}
+function flush() {
+    if (!dirty || !cache)
+        return;
+    try {
+        writeFileSync(cacheFile, JSON.stringify(cache, null, 2));
+        dirty = false;
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err), path: cacheFile }, 'lines cache write failed');
+    }
+}
+process.on('exit', flush);
+export function noteSeen(line, name) {
+    const c = read();
+    const entry = c[line] ??= { createdAt: new Date().toISOString() };
+    entry.lastSeenAt = new Date().toISOString();
+    if (name && entry.name !== name)
+        entry.name = name;
+    dirty = true;
+    if (!flushTimer)
+        flushTimer = setTimeout(() => { flushTimer = null; flush(); }, FLUSH_DELAY_MS);
+}
+export const listLines = () => Object.entries(read()).map(([line, entry]) => ({ line: line, entry }));
+/** Bot identity cache: `{discord: "<userId>", telegram: "<userId>"}`. Daemon writes after getMe(). */
+const botIdsFile = join(STATE_DIR, 'bot-ids.json');
+const readBotIds = () => {
+    try {
+        return existsSync(botIdsFile) ? JSON.parse(readFileSync(botIdsFile, 'utf8')) : {};
+    }
+    catch {
+        return {};
+    }
+};
+export function saveBotId(station, id) {
+    const cur = readBotIds();
+    if (cur[station] === id)
+        return;
+    cur[station] = id;
+    try {
+        writeFileSync(botIdsFile, JSON.stringify(cur, null, 2));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err) }, 'bot-ids cache write failed');
+    }
+}
+/** Resolve the bot's URI for a station. Returns `metro://<station>/bot/<id>` or the placeholder. */
+export function botLine(station) {
+    const id = readBotIds()[station];
+    return id ? Line.bot(station, id) : `metro://${station}/bot`;
+}

package/dist/cli/actions.js

@@ -0,0 +1,139 @@
+/** CLI action handlers: send/reply/edit/react/download/fetch + helpers. */
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg } from '../log.js';
+import { DiscordStation } from '../stations/discord.js';
+import { TelegramStation } from '../stations/telegram.js';
+import { ipcCall } from '../ipc.js';
+import { agentSelf, appendHistory, lookupEntry, mintId, resolvePlatformId, } from '../history.js';
+import { asLine, Line } from '../stations/index.js';
+import { loadMetroEnv } from '../paths.js';
+import { emit, flagList, flagOne, isJson, need, resolveText, writeJson, } from './util.js';
+export function chatStationOf(line) {
+    const s = Line.station(line);
+    if (s === 'discord')
+        return new DiscordStation();
+    if (s === 'telegram')
+        return new TelegramStation();
+    throw new Error(`no chat station for line "${line}" (try metro://{discord|telegram}/...)`);
+}
+function parseButtons(f) {
+    const raw = flagOne(f, 'buttons');
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--buttons must be JSON like '[[{"text":"…","url":"…"}]]': ${errMsg(err)}`);
+    }
+}
+function richOpts(f) {
+    const opts = {};
+    const images = flagList(f, 'image');
+    if (images.length)
+        opts.images = images;
+    const documents = flagList(f, 'document');
+    if (documents.length)
+        opts.documents = documents;
+    const voice = flagOne(f, 'voice');
+    if (voice)
+        opts.voice = voice;
+    const buttons = parseButtons(f);
+    if (buttons)
+        opts.buttons = buttons;
+    return opts;
+}
+/** Append an outbound action to history.jsonl; `to` = the original sender when replying/reacting. */
+function logOutbound(f, e) {
+    const id = mintId();
+    const fromOverride = flagOne(f, 'from');
+    appendHistory({
+        id, ts: new Date().toISOString(), station: Line.station(e.line) ?? '?',
+        from: fromOverride ? asLine(fromOverride) : agentSelf(), to: e.to ?? e.line, ...e,
+    });
+    return id;
+}
+export async function cmdSend(p, f) {
+    need(p, 1, 'metro send <line> <text> [--image=<path>]… [--document=<path>]… [--voice=<path>] [--buttons=<json>]');
+    loadMetroEnv();
+    const text = await resolveText(p, 1), line = asLine(p[0]);
+    if (Line.isAgent(line)) {
+        const from = flagOne(f, 'from');
+        const resp = await ipcCall({ op: 'notify', line, from, text });
+        if (!resp.ok)
+            throw new Error(resp.error);
+        return emit(f, `notified ${line}`, { ok: true, line, id: null, messageId: null });
+    }
+    const messageId = await chatStationOf(line).send(line, text, richOpts(f));
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId });
+    emit(f, `sent ${id} (${messageId}) to ${line}`, { ok: true, line, id, messageId });
+}
+export async function cmdReply(p, f) {
+    need(p, 2, 'metro reply <line> <message_id> <text> [--image=… --document=… --voice=… --buttons=…]');
+    loadMetroEnv();
+    const [to, replyToArg] = p, text = await resolveText(p, 2), line = asLine(to);
+    const replyTo = resolvePlatformId(replyToArg);
+    const messageId = await chatStationOf(line).send(line, text, { ...richOpts(f), replyTo });
+    const id = logOutbound(f, { kind: 'outbound', line, text, messageId, replyTo: replyToArg, to: lookupEntry(replyToArg)?.from });
+    emit(f, `replied ${id} (${messageId}) to ${line}#${replyTo}`, { ok: true, line, id, replyTo: replyToArg, messageId });
+}
+export async function cmdEdit(p, f) {
+    need(p, 2, 'metro edit <line> <message_id> <text> [--buttons=<json>]');
+    loadMetroEnv();
+    const [to, msgArg] = p, text = await resolveText(p, 2), line = asLine(to);
+    const platformId = resolvePlatformId(msgArg);
+    const buttons = parseButtons(f);
+    await chatStationOf(line).edit(line, platformId, text, buttons ? { buttons } : undefined);
+    /** Carry forward the original recipient if we have a row for this message. */
+    const id = logOutbound(f, { kind: 'edit', line, text, messageId: platformId, replyTo: msgArg, to: lookupEntry(msgArg)?.to });
+    emit(f, `edited ${line}#${platformId} (${id})`, { ok: true, line, id, messageId: platformId });
+}
+export async function cmdReact(p, f) {
+    need(p, 2, 'metro react <line> <message_id> <emoji>   (empty emoji clears)');
+    loadMetroEnv();
+    const [to, msgArg, emoji = ''] = p, line = asLine(to);
+    const platformId = resolvePlatformId(msgArg);
+    await chatStationOf(line).react(line, platformId, emoji);
+    const id = logOutbound(f, { kind: 'react', line, messageId: platformId, emoji, to: lookupEntry(msgArg)?.from });
+    const human = emoji ? `reacted ${emoji} on ${line}#${platformId}` : `cleared reaction on ${line}#${platformId}`;
+    emit(f, human, { ok: true, line, id, messageId: platformId, emoji });
+}
+export async function cmdDownload(p, f) {
+    need(p, 2, 'metro download <line> <message_id> [--out=<dir>]');
+    loadMetroEnv();
+    const [to, msgArg] = p, line = asLine(to);
+    const messageId = resolvePlatformId(msgArg);
+    const outDir = typeof f.out === 'string' ? f.out : join(tmpdir(), 'metro-downloads');
+    mkdirSync(outDir, { recursive: true });
+    /** Telegram has no get-message-by-id REST endpoint — daemon holds the in-memory snapshot. */
+    let files;
+    if (Line.station(line) === 'telegram') {
+        const resp = await ipcCall({ op: 'download', line, messageId, outDir });
+        if (!resp.ok)
+            throw new Error(resp.error);
+        files = 'files' in resp ? resp.files : [];
+    }
+    else {
+        files = await chatStationOf(line).download(line, messageId, outDir);
+    }
+    if (isJson(f))
+        return writeJson({ ok: true, line, files });
+    if (!files.length)
+        process.stdout.write(`(no image attachments on ${line}#${messageId})\n`);
+    for (const file of files)
+        process.stdout.write(file.path + '\n');
+}
+export async function cmdFetch(p, f) {
+    need(p, 1, 'metro fetch <line> [--limit=N]');
+    loadMetroEnv();
+    const line = asLine(p[0]);
+    const messages = await chatStationOf(line).fetch(line, Number(flagOne(f, 'limit')) || 20);
+    if (isJson(f))
+        return writeJson({ ok: true, line, messages });
+    if (!messages.length)
+        process.stdout.write(`(no messages on ${line})\n`);
+    for (const m of messages)
+        process.stdout.write(`${m.timestamp}  ${m.author}: ${m.text}\n`);
+}