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

package/README.md

@@ -1,93 +1,55 @@
 # 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.
+Chat with your Claude Code or Codex agent over Telegram and Discord.
 
 ## Quickstart
 
+In your shell:
+
 ```bash
 npm install -g @stage-labs/metro@beta    # or: bun add -g @stage-labs/metro@beta
-```
-
-> The `@beta` tag is required while Metro is in prerelease.
 
-Register Metro with your agent (use `claude` or `codex` interchangeably):
+metro setup telegram <token>             # https://t.me/BotFather
+metro setup discord  <token>             # https://discord.com/developers/applications
 
-```bash
-claude mcp add metro \
-  --env TELEGRAM_BOT_TOKEN=123:ABC… \
-  --env DISCORD_BOT_TOKEN=MTIz… \
-  -- metro mcp
+metro setup skill                        # writes SKILL.md so Claude Code + Codex auto-onboard
+metro doctor                             # verify
 ```
 
-Both `--env` flags are optional — configure at least one of Telegram or Discord.
-
-In your agent session, ask it to start the inbound stream:
-
-> Run `metro tail` in the background and Monitor its stdout for inbound Telegram/Discord messages.
-
-DM your bot. The agent reacts on its next decision boundary (see Caveats for latency notes).
-
-## Bot tokens
-
-- **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
+> **Discord setup:** toggle **Message Content Intent** in Developer Portal → Bot → Privileged Gateway Intents.
 
-Metro ships two commands:
+Open Claude Code (`claude`) or Codex (`codex`), and tell it:
 
-- **`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.
+> Run `metro` in the background.
 
-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.
-
-## MCP tools
-
-Registered by `metro mcp` — the agent calls these to act on the messages it sees from `metro tail`:
-
-| 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 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.
+DM your bot. The agent picks up the next inbound and replies — the bundled skill handles launching, stdout watching, reactions, and replies.
 
 ## Config
 
-All settings come from environment variables passed via the MCP server's `--env` block:
-
 | 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_CONFIG_DIR` | `~/.config/metro` | Where the global `.env` lives. |
+| `METRO_STATE_DIR` | `~/.cache/metro` | Lockfile, attachment cache, default download dir. |
+| `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`.
+Token precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs 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.
+## Reference
 
-## Troubleshooting
+- `metro --help` — command surface
+- `metro doctor` — health check
+- [SKILL.md](skills/metro/SKILL.md) — agent-facing flow
 
-```bash
-which metro                                # → e.g. ~/.bun/bin/metro
-metro                                      # prints usage
-
-ps aux | grep metro | grep -v grep         # one `metro mcp`, optionally one `metro tail`
+## Uninstall
 
-rm -rf ~/.cache/metro/                     # clean stuck state — or whatever METRO_STATE_DIR points at
-
-# 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
+```bash
+metro setup clear; metro setup skill --clear
+rm -rf ~/.cache/metro/
+npm uninstall -g @stage-labs/metro
 ```
 
 ## 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.
+- **Latency.** Inbounds surface at the next agent decision boundary — sub-second on Claude Code, longer on Codex turns.

package/dist/channels/discord.js

@@ -1,11 +1,40 @@
 import { Client, Events, GatewayIntentBits, Partials } from 'discord.js';
 import { errMsg, log } from '../log.js';
+// Receive path: discord.js gateway, used by tail.ts only.
+// Send path: raw REST against discord.com/api — no gateway login required,
+// so cli.ts subcommands stay one-shot and fast.
+const API_BASE = 'https://discord.com/api/v10';
+function token() {
+    const t = process.env.DISCORD_BOT_TOKEN;
+    if (!t)
+        throw new Error('DISCORD_BOT_TOKEN is not set');
+    return t;
+}
+async function rest(method, path, body, timeoutMs = 30_000) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: {
+            'Authorization': `Bot ${token()}`,
+            'User-Agent': 'metro (https://github.com/bonustrack/metro, dev)',
+            ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`discord ${method} ${path}: ${res.status} ${text}`);
+    }
+    // 204 No Content for typing/reactions/clear.
+    if (res.status === 204)
+        return undefined;
+    return (await res.json());
+}
+// ---------- Receive path (gateway, discord.js) -----------------------------
 let client = null;
 function getClient() {
     if (client)
         return client;
-    if (!process.env.DISCORD_BOT_TOKEN)
-        throw new Error('DISCORD_BOT_TOKEN is not set');
     client = new Client({
         intents: [
             GatewayIntentBits.DirectMessages,
@@ -18,26 +47,26 @@ function getClient() {
     });
     return client;
 }
-async function getTextChannel(channelId) {
-    const channel = await getClient().channels.fetch(channelId);
-    if (!channel?.isTextBased() || !('messages' in channel)) {
-        throw new Error(`discord: channel ${channelId} is not text-capable`);
-    }
-    return channel;
-}
-async function fetchMessage(channelId, messageId) {
-    return (await getTextChannel(channelId)).messages.fetch(messageId);
-}
 let onInboundHandler = () => { };
 export function onInbound(handler) {
     onInboundHandler = handler;
 }
+export async function shutdownGateway() {
+    if (!client)
+        return;
+    await client.destroy();
+    client = null;
+}
 export async function startGateway() {
     const c = getClient();
     c.on(Events.MessageCreate, m => {
         if (m.author.bot)
             return;
         // Guild messages: only forward when the bot is mentioned. DMs always pass.
+        // The bot's own @-mention is preserved in `m.content` — stripping it would
+        // lose mid-sentence position ("Wdyt @Metro is this good?" → "Wdyt is this
+        // good?") and silently drop bare-mention pings. The agent recognizes
+        // `<@bot_id>` and acts on the request as a whole.
         if (m.guildId && c.user && !m.mentions.has(c.user.id))
             return;
         const tags = [...m.attachments.values()]
@@ -59,59 +88,61 @@ export async function startGateway() {
     await new Promise(r => c.once(Events.ClientReady, () => r()));
 }
 export async function getMe() {
-    const c = getClient();
-    if (!c.user)
-        throw new Error('discord: gateway not ready');
-    return { username: c.user.username };
+    const me = await rest('GET', '/users/@me');
+    return { username: me.username };
+}
+export async function sendMessage(channelId, text) {
+    const sent = await rest('POST', `/channels/${channelId}/messages`, { content: text });
+    return sent.id;
 }
 export async function replyToMessage(channelId, messageId, text) {
-    await (await fetchMessage(channelId, messageId)).reply(text);
+    const sent = await rest('POST', `/channels/${channelId}/messages`, {
+        content: text,
+        message_reference: { message_id: messageId, fail_if_not_exists: false },
+    });
+    return sent.id;
 }
 export async function editMessage(channelId, messageId, text) {
-    await (await fetchMessage(channelId, messageId)).edit(text);
+    const sent = await rest('PATCH', `/channels/${channelId}/messages/${messageId}`, { content: text });
+    return sent.id;
 }
 export async function sendTyping(channelId) {
-    const channel = await getClient().channels.fetch(channelId);
-    if (!channel?.isTextBased() || !('sendTyping' in channel))
-        return;
-    await channel.sendTyping();
+    await rest('POST', `/channels/${channelId}/typing`);
 }
 export async function setReaction(channelId, messageId, emoji) {
-    const target = await fetchMessage(channelId, messageId);
     if (emoji) {
-        await target.react(emoji);
+        await rest('PUT', `/channels/${channelId}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}/@me`);
         return;
     }
     // Clear only the bot's own reactions (matches Telegram's clear semantics).
-    const me = getClient().user;
-    if (!me)
-        return;
-    for (const r of target.reactions.cache.values()) {
-        if (r.users.cache.has(me.id))
-            await r.users.remove(me.id);
+    const msg = await rest('GET', `/channels/${channelId}/messages/${messageId}`);
+    for (const r of msg.reactions ?? []) {
+        if (!r.me || !r.emoji.name)
+            continue;
+        await rest('DELETE', `/channels/${channelId}/messages/${messageId}/reactions/${encodeURIComponent(r.emoji.name)}/@me`);
     }
 }
 export async function fetchAttachments(channelId, messageId) {
-    const target = await fetchMessage(channelId, messageId);
+    const msg = await rest('GET', `/channels/${channelId}/messages/${messageId}`);
     const out = [];
-    for (const a of target.attachments.values()) {
-        if (!a.contentType?.startsWith('image/'))
+    for (const a of msg.attachments) {
+        if (!a.content_type?.startsWith('image/'))
             continue;
-        const res = await fetch(a.url);
+        const res = await fetch(a.url, { signal: AbortSignal.timeout(30_000) });
         if (!res.ok)
             throw new Error(`discord: download ${a.url}: ${res.status}`);
-        out.push({ data: Buffer.from(await res.arrayBuffer()).toString('base64'), mime: a.contentType });
+        out.push({ data: Buffer.from(await res.arrayBuffer()).toString('base64'), mime: a.content_type });
     }
     return out;
 }
 export async function fetchRecentMessages(channelId, limit) {
-    const channel = await getTextChannel(channelId);
-    const msgs = await channel.messages.fetch({ limit: Math.min(Math.max(limit, 1), 100) });
+    const n = Math.min(Math.max(limit, 1), 100);
+    const msgs = await rest('GET', `/channels/${channelId}/messages?limit=${n}`);
     // Discord returns newest-first; reverse for chronological.
-    return [...msgs.values()].reverse().map(m => ({
+    return [...msgs].reverse().map(m => ({
         message_id: m.id,
         author: m.author.username,
         text: m.content,
-        timestamp: m.createdAt.toISOString(),
+        timestamp: m.timestamp,
     }));
 }

package/dist/channels/telegram.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { STATE_DIR } from '../config.js';
+import { STATE_DIR } from '../paths.js';
 import { errMsg, log } from '../log.js';
 const API_BASE = 'https://api.telegram.org';
 function token() {
@@ -69,8 +69,12 @@ export async function downloadAttachment(fileId, mime) {
     });
     if (!res.ok)
         throw new Error(`download failed: ${res.status}`);
-    const blob = await res.blob();
-    return { data: Buffer.from(await blob.arrayBuffer()).toString('base64'), mime: blob.type || mime };
+    const buf = Buffer.from(await res.arrayBuffer());
+    // Trust the cached mime — it's the authoritative one from the message
+    // metadata (`image/jpeg` for photos, the document's mime_type for files).
+    // The Telegram CDN often returns `application/octet-stream` as Content-Type,
+    // which would otherwise wipe out our extension classification downstream.
+    return { data: buf.toString('base64'), mime };
 }
 async function messageToText(m, chatId) {
     if (m.text)