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

package/README.md

@@ -1,23 +1,26 @@
 # Metro
 
-> **Bridge Discord, Telegram, and GitHub to Claude Code + Codex.**
+> **A live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session.**
 
-Metro is a small daemon that turns any chat thread, forum topic, or GitHub issue into a live conversation with your local coding agents. Each thread is its own agent session — Claude and Codex run side-by-side, replies stream in real time with tool calls visible inline, and you can stop a turn with one click.
+Metro is a small daemon you launch from inside your agent. It connects to Discord and Telegram, emits each inbound as one JSON line on stdout (which Claude Code's `Monitor` consumes natively, and Codex picks up via an app-server WebSocket push), and exposes a tiny CLI — `metro reply`, `metro send`, `metro edit`, `metro react`, `metro download`, `metro fetch` — for posting back. Cross-agent: any agent can ping any other via `metro send metro://claude/<topic>` and the daemon re-emits it on the stream.
 
 ```
-[Discord — #infra]
+[Claude Code session]
 
-less        @bot we got a 5xx spike from /v1/sync. Look?
-sandboxbot  > 🛠 Bash  git log --since=24h --oneline
-            > 🛠 Read  services/sync.ts
+$ metro &                              # backgrounded
+$ Monitor( … metro's stdout … )
 
-            Three deploys in the last 24h. The 14:02 one swallows a
-            timeout into a 500 on line 47 instead of retrying. Want
-            me to open a PR?
+>>> {"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},…}}
 
-            [ ⏹ Stop ]
+  [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
@@ -28,141 +31,107 @@ 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 dispatcher
+metro                                    # run the daemon
 ```
 
-Requires **Node ≥ 22 or Bun ≥ 1.3** and at least one of [Claude Code](https://claude.com/claude-code) or [Codex](https://github.com/openai/codex) installed and logged in (run them once interactively first; metro inherits your auth).
-
-In **Discord**: DM the bot, or `@<bot>` in any channel. In **Telegram**: DM, or `@<bot>` in a forum's General topic. In **GitHub**: see [Testing GitHub](#testing-github).
-
----
-
-## Stations
-
-Everything in metro is a **station** with declared capabilities:
-
-| Station    | Kind  | Modalities    | Features                            | Config                                                            |
-|------------|-------|---------------|-------------------------------------|-------------------------------------------------------------------|
-| `claude`   | agent | text + image  | stream, tools, cancel, attachments  | `claude` CLI on PATH, logged in                                   |
-| `codex`    | agent | text + image  | stream, tools, cancel, attachments  | `codex` CLI on PATH, logged in                                    |
-| `discord`  | chat  | text + image  | stream, edit, attachments           | `DISCORD_BOT_TOKEN` + Message Content Intent                      |
-| `telegram` | chat  | text + image  | stream, edit, attachments           | `TELEGRAM_BOT_TOKEN` + Manage Topics admin (for forums)           |
-| `github`   | chat  | text          | edit                                | `GITHUB_WEBHOOK_SECRET` + `GITHUB_BOT_USERNAME` + `GITHUB_TOKEN`  |
+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).
 
-Run `metro stations` to see the same matrix with live config status (`✓` configured, `✗` not).
-
-Each chat platform behaves slightly differently — what's universal is captured by the capabilities; the rest is in [Conversations](#conversations).
+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.
 
 ---
 
-## Lines
-
-Every conversational scope is identified by a **Line** — a URI in the form `metro://<station>/<path>`:
+## Architecture
 
 ```
-metro://discord/1234567890123456789
-metro://telegram/-1001234567890                 # main chat / DM
-metro://telegram/-1001234567890/42              # forum topic 42
-metro://github/bonustrack/metro/issues/123      # GitHub issue
-metro://github/bonustrack/metro/pull/456        # GitHub PR
+Discord gateway ──┐
+Telegram poller ──┤
+                  │
+                  ├─▶ metro daemon ───▶ stdout (JSON events; Claude Code's Monitor reads here)
+                  │                ───▶ codex-rc WebSocket (Codex turn/start; opt-in)
+                  │                ◀── IPC Unix socket  (metro send to agent lines)
+                  │
+agent CLI calls ──┴── REST → Discord / Telegram   (metro reply / send / edit / react / download / fetch)
 ```
 
-Lines map 1:1 to agent sessions in `scopes.json`. Anyone can post to a line via [`metro send`](#cli) — daemon optional. Full grammar in [`docs/uri-scheme.md`](docs/uri-scheme.md).
+- **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.
+- **Codex push (opt-in).** Set `METRO_CODEX_RC=ws://127.0.0.1:8421` and metro pushes each event via JSON-RPC `turn/start` to the Codex app-server. Codex's TUI must be attached with `--remote` to the same URL.
+- **Cross-agent notification.** `metro send metro://claude/<topic>` (or `metro://codex/<topic>`) routes through the daemon's IPC socket; the daemon re-emits on its stdout (and pushes to codex-rc), so the peer agent sees it.
 
 ---
 
-## Conversations
-
-### Discord
-
-- **DM the bot** — every message is implicit; one line per DM.
-- **`@<bot>` in any guild channel** — metro creates a thread from your message, allocates an agent session, and streams the reply. Follow-ups in the thread route automatically.
-- **Tool calls** — render as `🛠 <tool>` headers plus two fenced code blocks (input → output). Outputs cap at 50 lines / 1500 chars with a `_(N more lines)_` note when truncated. Parallel tool calls are paired by id and don't collide.
-- **Stop button** — every in-flight turn carries an `⏹ Stop` button that aborts the underlying subprocess (Claude via `SIGTERM`, Codex via `turn/interrupt`).
-- **Catchup on restart** — Discord uses a per-line `lastSeenMessageId` watermark; metro REST-fetches anything newer when it comes back up.
-
-### Telegram
-
-- **DM the bot** — implicit; one line per chat.
-- **`@<bot>` in a forum supergroup's General topic** — metro creates a new forum topic for the conversation and posts a deep link back in General so it's one tap away. Follow-ups in that topic route automatically.
-- **Inside an existing custom topic** — routes to that topic's line on every message.
-- **Markdown → Telegram HTML** — agent markdown (`**bold**`, `*italic*`, `` `code` ``, fences, `[link](url)`, blockquotes) is converted on the way out. Plain-text fallback if Telegram rejects the HTML.
-
-Regular (non-forum) groups are skipped — without a per-thread boundary the routing model breaks down.
-
-### GitHub
-
-`@<bot-user>` in an **issue body, issue comment, PR body, or PR comment** allocates a per-issue agent session and the bot replies as a comment on the same issue/PR. Streaming is simulated via `PATCH /issues/comments` edits to the bot's own comment. Each issue/PR holds its own session across follow-ups.
+## Stations
 
-Setup:
+Each endpoint is a **station** with declared capabilities:
 
-```
-GITHUB_WEBHOOK_SECRET=<random>     # any high-entropy string
-GITHUB_BOT_USERNAME=<github user>  # whose @-mentions trigger the bot
-GITHUB_TOKEN=<PAT>                 # issues:write (+ pull_requests:write for PRs)
-METRO_GITHUB_PORT=4321             # optional, default 4321
-```
+| Station    | Kind  | Modalities    | Features                                              | Config                                                      |
+|------------|-------|---------------|-------------------------------------------------------|-------------------------------------------------------------|
+| `discord`  | chat  | text + image  | reply, send, edit, react, download, fetch             | `DISCORD_BOT_TOKEN` + Message Content Intent                |
+| `telegram` | chat  | text + image  | reply, send, edit, react, download                    | `TELEGRAM_BOT_TOKEN`                                        |
+| `claude`   | agent | text          | notify                                                | watches metro stdout via Claude Code's `Monitor`            |
+| `codex`    | agent | text          | notify                                                | set `METRO_CODEX_RC=ws://…` to push                         |
 
-In your repo's *Settings → Webhooks*: payload URL `https://<your-public-url>/webhook`, content type `application/json`, the secret matches `GITHUB_WEBHOOK_SECRET`, events: **Issues** + **Issue comments**. For local development tunnel with [smee.io](https://smee.io), [cloudflared](https://github.com/cloudflare/cloudflared), or [ngrok](https://ngrok.com).
+Run `metro stations` to see live config status (`✓` configured, `✗` not, `·` informational).
 
-End-to-end recipe: [Testing GitHub](#testing-github).
+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.
 
 ---
 
-## Agents
-
-Both agents run side-by-side at boot. Each line defaults to **Claude** for the first turn; once you've used an agent in a line, it sticks. Switch per-message with a `with claude` / `with codex` suffix:
+## Lines
 
-```
-@bot draft a release note
-   → uses Claude (default for a new line)
+Every conversational scope is identified by a **Line** — a URI in the form `metro://<station>/<path>`:
 
-How would Codex have done this? with codex
-   → routes this turn to Codex; the line stays Codex on follow-ups
 ```
-
-A line can hold one session per agent — independent histories — so switching back later resumes where that agent left off. If only one agent is installed, metro still starts and asks-for-the-missing-one error inline.
-
----
-
-## Cross-station relay
-
-Agents can post to any line through the CLI:
-
-```bash
-metro send metro://telegram/-1001234567890/42 "patch deployed"
-metro send metro://github/bonustrack/metro/issues/1 "all clear"
+metro://discord/1234567890123456789
+metro://telegram/-1001234567890                 # main chat / DM
+metro://telegram/-1001234567890/42              # forum topic 42
+metro://claude/deploys                          # agent notification sink
+metro://codex/ci
 ```
 
-`metro send` uses the same env tokens as the dispatcher and doesn't require the daemon — useful when an agent in one place needs to relay to another.
+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).
 
 ---
 
-## Architecture
+## CLI
 
 ```
-Discord gateway ──┐
-Telegram poller ──┤                          ┌─▶ codex station   (long-lived `codex app-server`, UDS JSON-RPC)
-GitHub webhook ───┼─▶ metro dispatcher ──────┤
-                  │                          └─▶ claude station  (per-turn `claude -p`, stream-json)
-                  └─── line → agent-thread map (`scopes.json`)
+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 update                                Upgrade in place.
 ```
 
-The codebase is built on a small protocol in [`src/stations/types.ts`](src/stations/types.ts):
-
-- **`Station`** — name, capabilities, `start`/`stop` lifecycle.
-  - **`AgentStation`** — `createThread()`, `sendTurn(req)` returns an `AsyncIterable<TurnEvent>` of `delta` / `tool-start` / `tool-end`. Cancellation via `AbortSignal`.
-  - **`ChatStation<TMeta>`** — `onMessage`/`onStop` event hooks, `send`/`edit` for posting back. Typed meta carries platform extras (`inGuild`, `inForum`, `isPR`, …).
-- **`Line`** — branded URI string. Each station owns its parse/format helpers in [`src/stations/line.ts`](src/stations/line.ts).
+All commands accept `--json`. `reply` / `send` / `edit` read multi-line `<text>` from stdin if no positional is given.
 
-Adding a backend (Slack, Matrix, SMS, another LLM) = `class XStation implements ChatStation` + a `Line.x(...)` helper. The dispatcher picks it up polymorphically.
-
-Behaviors worth knowing:
-- **One daemon per machine.** Lockfile at `$METRO_STATE_DIR/.tail-lock` enforces singleton.
-- **Streaming.** Replies edit one message every ~1500 ms while deltas arrive (leading-edge first flush so feedback feels instant). Long replies split past ~1900 chars onto follow-up messages.
-- **No link previews.** Outgoing messages set `link_preview_options.is_disabled` on Telegram and `SUPPRESS_EMBEDS` on Discord so URLs don't unfurl.
-- **Image attachments.** Discord and Telegram image uploads are forwarded as vision inputs (Anthropic `image/base64` for Claude; `image_url` data URI for Codex). 20 MB cap; non-images surface as `[file: name]` text.
-- **In-flight queueing.** Messages arriving during a turn are buffered per-line and answered as one combined follow-up.
+**State files** in `$METRO_STATE_DIR` (default `~/.cache/metro`):
+- `AGENTS.md` — agent skill copied from the package on every start (so the path is stable across upgrades)
+- `history.jsonl` — universal message log (one JSON object per line; append-only). Read with `metro history`. Each entry carries `from` and `to` as universal participant URIs (`metro://<station>/user/<id>`, `metro://claude/<topic>`, `metro://codex/<topic>`) plus a `fromName` display field. The dispatcher auto-detects the consuming agent for `to` on inbound (`$CLAUDECODE` → `metro://claude/agent`; `$METRO_CODEX_RC`/`$CODEX_HOME` → `metro://codex/agent`).
+- `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`)
+- `.tail-lock` — dispatcher pid
+- `metro.sock` — daemon IPC socket
+- `telegram-offset.json` — last processed update id
 
 ---
 
@@ -171,40 +140,15 @@ Behaviors worth knowing:
 | Variable | Default | Description |
 |---|---|---|
 | `TELEGRAM_BOT_TOKEN`, `DISCORD_BOT_TOKEN` | — | Bot tokens. `metro setup` writes them here. |
-| `GITHUB_WEBHOOK_SECRET`, `GITHUB_BOT_USERNAME`, `GITHUB_TOKEN` | — | Enables GitHub. Token needs `issues:write` (+ `pull_requests:write` for PR comments). Webhook listens on `METRO_GITHUB_PORT` (default `4321`). |
+| `METRO_CODEX_RC` | — | Codex app-server URL (`ws://…`, `wss://…`, `unix:///…`). When set, the daemon pushes each event via JSON-RPC `turn/start`. |
 | `METRO_CONFIG_DIR` | `~/.config/metro` | Where the global `.env` lives. |
-| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, codex socket, telegram offset, claude session set. |
+| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, line cache, IPC socket, telegram offset. |
 | `METRO_LOG_LEVEL` | `info` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
 
 Precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs go to stderr.
 
 ---
 
-## CLI
-
-```
-metro                                       Run the dispatcher daemon.
-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 active conversations (sorted by recency, with names).
-metro send <line> <text>                    Post to any metro:// line.
-metro update                                Upgrade in place.
-```
-
-All commands accept `--json` for machine-readable output.
-
-**State files** in `$METRO_STATE_DIR`:
-- `scopes.json` — Line → agent-session map
-- `AGENTS.md` — skill doc copied from the package on every dispatcher start; surfaced into each agent's per-turn context so it knows about `metro lines` / `metro send` / `metro stations`
-- `.tail-lock` — dispatcher pid
-- `codex-app-server.sock` — codex Unix socket
-- `telegram-offset.json` — last processed update id
-- `claude-sessions.json` — known Claude session uuids (so restarts use `--resume`)
-
----
-
 ## Develop
 
 ```bash
@@ -219,52 +163,24 @@ bun run lint                             # eslint
 
 Source map:
 
-- [`src/cli/`](src/cli/) — the `metro` binary entry ([`cli/index.ts`](src/cli/index.ts)) plus subcommand handlers (`lines.ts`, `update.ts`).
-- [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: wires stations together, routes inbounds, installs `AGENTS.md` into state on each start.
-- [`src/stations/`](src/stations/) — one folder per station (`claude/`, `codex/`, `discord/`, `github/`, `telegram/`) plus the shared `types.ts`, `line.ts`, `listing.ts`, `send.ts`.
-- [`src/helpers/`](src/helpers/) — `streaming.ts`, `turn.ts`, `scope-cache.ts`, `async-queue.ts`.
-- [`docs/uri-scheme.md`](docs/uri-scheme.md) specs the Line format; [`docs/agents.md`](docs/agents.md) is the in-context skill copied to `$METRO_STATE_DIR/AGENTS.md`.
+- [`src/cli/`](src/cli/) — `metro` binary entry ([`index.ts`](src/cli/index.ts)) + admin commands ([`config.ts`](src/cli/config.ts): setup/doctor/update) + shared CLI primitives ([`util.ts`](src/cli/util.ts)).
+- [`src/dispatcher.ts`](src/dispatcher.ts) — the daemon: starts each chat station, emits events on stdout, listens on the IPC socket, optionally pushes to codex-rc.
+- [`src/stations/`](src/stations/) — Line URI scheme + ChatStation interface + listing ([`index.ts`](src/stations/index.ts)), the two chat-station impls (`discord.ts`, `telegram.ts`), plus the Telegram markdown→HTML helper ([`telegram-md.ts`](src/stations/telegram-md.ts)). Agent stations have no impl — they're notification sinks expressed only as URI prefixes.
+- [`src/codex-rc.ts`](src/codex-rc.ts) — Codex app-server WebSocket push client.
+- [`src/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`.
+- [`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).
 
 ---
 
-## Testing GitHub
-
-1. **Pick a GitHub user** the bot acts as (your own account works for testing) and generate a token. Two options:
-   - **Fine-grained PAT** at `github.com/settings/tokens?type=beta` — scoped to a test repo with **Issues: Read & write** (+ **Pull requests: Read & write** for PR comments). Works for *your* repos. For org repos, an org admin must enable fine-grained PATs in *Organization settings → Personal access tokens*.
-   - **Classic PAT** at `github.com/settings/tokens?type=classic` — pick the `repo` scope. Works for any repo you have access to, no org opt-in needed.
-2. **Set env vars**:
-   ```bash
-   export GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
-   export GITHUB_BOT_USERNAME="metrobot"   # see solo-testing note below
-   export GITHUB_TOKEN="ghp_..."
-   ```
-3. **Tunnel** your local webhook port to the internet:
-   ```bash
-   npx smee-client --target http://localhost:4321/webhook --url <https://smee.io/your-channel>
-   ```
-4. **Add a webhook** on the test repo (*Settings → Webhooks*): payload URL = the smee channel, content type `application/json`, the same secret, events **Issues** + **Issue comments**.
-5. **Run metro**: `METRO_LOG_LEVEL=debug metro` — you should see `github station: listening`.
-6. **Open an issue** with body `@metrobot hello, what's this repo?` — the bot comments back (as the token's owner).
-
-**Solo testing note.** Metro filters out self-mentions (`sender === bot`) to prevent reply loops. If you set `GITHUB_BOT_USERNAME` to your *own* username and then try to `@<yourself>` on an issue, the filter drops it — you can't trigger the bot alone. Workaround: use a pseudo-name like `metrobot` (doesn't need to be a real GitHub user — it's just a string match). The bot still replies as the token owner, but the filter passes because `your-username ≠ metrobot`.
-
-**Common gotchas:**
-- Webhook 401 → secret mismatch between `.env` and the webhook config.
-- Webhook 200 but no reply → token lacks `issues:write`, or `GITHUB_BOT_USERNAME` doesn't appear in the body verbatim (case-sensitive).
-- Bot replies in a loop → the bot's own comment somehow includes `@<bot-username>`; rare with the default prompt, but check `AGENTS.md` if it happens.
-
----
-
 ## Caveats
 
-- **No allowlist.** Anyone who can DM/`@`-mention your bot can spawn a session. Run against bots you own.
-- **Per-agent histories are separate.** `with codex` mid-line starts a fresh Codex session; it doesn't see what Claude saw, and vice versa.
-- **Telegram non-forum groups are skipped.** No thread boundary to scope on. DMs and forum topics work normally.
+- **No allowlist.** Anyone who can DM/`@`-mention your bot can produce events. Run against bots you own.
 - **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.
-- **GitHub needs a public URL.** Webhooks are HMAC-verified, so a leaked URL only lets attackers spam rejected POSTs — but use a high-entropy `GITHUB_WEBHOOK_SECRET`.
-- **Pre-1.0 line URIs aren't migrated.** Older `discord:ID` / `telegram:CHAT:TOPIC` keys in `scopes.json` are ignored after upgrade.
+- **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.
 
 ---
 

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`);
+}