@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.3

package/dist/lib/codex-rc.js

@@ -1,274 +0,0 @@
-// JSON-RPC over WebSocket client for the Codex app-server. By default
-// connects over the Unix domain socket exposed by `codex remote-control`
-// (see paths.DEFAULT_CODEX_SOCKET). On every metro inbound it calls
-// `turn/start`, which lands the JSON line in the agent's history as a
-// user message and wakes the agent — the Codex equivalent of Claude
-// Code's `Monitor`.
-//
-// Wire format: standard JSON-RPC 2.0 over WebSocket. Methods we use:
-//   - initialize      → handshake, declares clientInfo.
-//   - thread/list     → discover existing threads on connect.
-//   - thread/started  → notification; track new threads as they appear.
-//   - turn/started    → notification; mark a turn in flight.
-//   - turn/completed  → notification; drain queued inbounds.
-//   - turn/start      → push a user message and wake the agent.
-//
-// If no thread exists yet, inbounds queue in memory; they fire as soon
-// as a thread is started or learned. If the connection drops, reconnect
-// with linear backoff and replay the queue. Connection failures don't
-// break metro — stdout emit always runs first, so Claude Code Monitor
-// users keep working regardless.
-import { createConnection } from 'node:net';
-import { WebSocket } from 'ws';
-import { errMsg, log } from '../log.js';
-const RECONNECT_DELAY_MS = 2_000;
-const MAX_QUEUE = 100;
-// Backstop: if `turn/completed` never arrives (the daemon doesn't broadcast
-// it to all clients, or we miss it for any reason), unstick after this long.
-// Generous enough that any normal turn finishes well within it.
-const TURN_TIMEOUT_MS = 120_000;
-/**
- * Accept any of these forms for METRO_CODEX_RC:
- *   ws://host:port/    TCP WebSocket.
- *   wss://host/        TCP WebSocket over TLS.
- *   unix:///abs/path   UDS WebSocket (the default for `codex remote-control`).
- *   /abs/path          shorthand for unix:///abs/path.
- */
-export function parseCodexUrl(input) {
-    if (input.startsWith('ws://') || input.startsWith('wss://')) {
-        return { kind: 'tcp', url: input };
-    }
-    if (input.startsWith('unix://')) {
-        return { kind: 'unix', path: input.replace(/^unix:\/+/, '/') };
-    }
-    if (input.startsWith('/')) {
-        return { kind: 'unix', path: input };
-    }
-    throw new Error(`unsupported METRO_CODEX_RC: ${input} (expected ws://…, wss://…, unix://…, or absolute path)`);
-}
-function openSocket(endpoint) {
-    if (endpoint.kind === 'tcp')
-        return new WebSocket(endpoint.url);
-    // UDS WebSocket: ws library upgrades any duplex stream, so we feed it a
-    // unix-socket Net connection via `createConnection`. The `ws://localhost/`
-    // URL is a placeholder — only the framing matters at this point; the
-    // bytes flow over the UDS we just opened.
-    return new WebSocket('ws://localhost/', {
-        createConnection: () => createConnection({ path: endpoint.path }),
-    });
-}
-export class CodexRC {
-    clientVersion;
-    ws = null;
-    nextId = 1;
-    pending = new Map();
-    threadId = null;
-    queue = [];
-    connected = false;
-    connecting = false;
-    turnInFlight = false;
-    turnTimeout = null;
-    closed = false;
-    endpoint;
-    displayUrl;
-    constructor(url, clientVersion) {
-        this.clientVersion = clientVersion;
-        this.endpoint = parseCodexUrl(url);
-        this.displayUrl = url;
-    }
-    start() {
-        void this.connect();
-    }
-    stop() {
-        this.closed = true;
-        this.ws?.close();
-        this.ws = null;
-    }
-    /**
-     * Push an inbound JSON line to the Codex agent. If not yet connected or
-     * no thread is active, queues until ready (FIFO, capped).
-     */
-    push(line) {
-        if (this.queue.length >= MAX_QUEUE) {
-            log.warn({ url: this.displayUrl }, 'codex-rc queue full, dropping oldest inbound');
-            this.queue.shift();
-        }
-        this.queue.push(line);
-        void this.drainQueue();
-    }
-    async connect() {
-        if (this.closed || this.connected || this.connecting)
-            return;
-        this.connecting = true;
-        try {
-            const ws = openSocket(this.endpoint);
-            this.ws = ws;
-            // Register the persistent error handler BEFORE awaiting open — without
-            // it, an error fired during the upgrade (UDS missing, daemon down,
-            // bad URL) is "unhandled" and crashes the process under Bun. The
-            // once('error') below covers the connect-time rejection; this on()
-            // covers later errors and the rare double-emit.
-            ws.on('error', err => log.warn({ err: errMsg(err) }, 'codex-rc websocket error'));
-            await new Promise((resolve, reject) => {
-                ws.once('open', resolve);
-                ws.once('error', err => reject(err));
-            });
-            ws.on('message', data => this.onMessage(data));
-            ws.on('close', () => this.onClose());
-            await this.call('initialize', {
-                clientInfo: { name: 'metro', version: this.clientVersion, title: null },
-            });
-            try {
-                const list = await this.call('thread/list', {});
-                const active = (list.data ?? []).find(t => t.status !== 'archived');
-                if (active)
-                    this.threadId = active.id;
-            }
-            catch (err) {
-                log.warn({ err: errMsg(err) }, 'codex-rc thread/list failed (non-fatal)');
-            }
-            this.connected = true;
-            log.info({ url: this.displayUrl, thread: this.threadId ?? '(none yet)' }, 'codex-rc connected');
-            void this.drainQueue();
-        }
-        catch (err) {
-            log.warn({ err: errMsg(err), url: this.displayUrl }, 'codex-rc connect failed; retrying');
-            this.scheduleReconnect();
-        }
-        finally {
-            this.connecting = false;
-        }
-    }
-    onMessage(raw) {
-        let msg;
-        try {
-            msg = JSON.parse(raw.toString());
-        }
-        catch (err) {
-            log.warn({ err: errMsg(err) }, 'codex-rc malformed message');
-            return;
-        }
-        log.debug({ id: msg.id, method: msg.method, hasError: !!msg.error }, 'codex-rc ← message');
-        if (msg.id !== undefined && this.pending.has(msg.id)) {
-            const p = this.pending.get(msg.id);
-            this.pending.delete(msg.id);
-            if (msg.error)
-                p.reject(new Error(msg.error.message ?? 'rpc error'));
-            else
-                p.resolve(msg.result);
-            return;
-        }
-        if (msg.method === 'thread/started') {
-            const params = msg.params;
-            if (params?.thread?.id) {
-                this.threadId = params.thread.id;
-                log.info({ thread: this.threadId }, 'codex-rc thread started');
-                void this.drainQueue();
-            }
-        }
-        else if (msg.method === 'thread/status/changed') {
-            // Codex 0.130 doesn't emit turn/started or turn/completed to a non-
-            // owner connection (the TUI gets them; metro doesn't). Instead the
-            // daemon broadcasts thread/status/changed transitions: status is
-            // either a string (`"idle"` / `"notLoaded"` / `"systemError"`) or an
-            // object (`{"active": {...}}`) per the v2 protocol enum. Treat
-            // anything other than `active` as ready-for-next-turn.
-            const params = msg.params;
-            if (params?.threadId === this.threadId) {
-                const isActive = typeof params.status === 'object' && params.status !== null && 'active' in params.status;
-                log.debug({ thread: this.threadId, isActive, status: params.status }, 'codex-rc thread status changed');
-                if (isActive) {
-                    this.turnInFlight = true;
-                }
-                else {
-                    this.clearTurnTimeout();
-                    this.turnInFlight = false;
-                    void this.drainQueue();
-                }
-            }
-        }
-        else if (msg.method === 'turn/completed') {
-            // Backstop in case some codex version does emit turn lifecycle
-            // notifications on the metro connection.
-            log.debug({ thread: this.threadId, queue: this.queue.length }, 'codex-rc turn/completed; draining');
-            this.clearTurnTimeout();
-            this.turnInFlight = false;
-            void this.drainQueue();
-        }
-        else if (msg.method === 'turn/started') {
-            log.debug({ thread: this.threadId }, 'codex-rc turn/started');
-            this.turnInFlight = true;
-        }
-        else if (msg.method === 'thread/closed' || msg.method === 'thread/archived') {
-            log.warn({ method: msg.method, params: msg.params }, 'codex-rc thread closed/archived; clearing thread reference');
-            this.threadId = null;
-        }
-    }
-    onClose() {
-        if (this.closed)
-            return;
-        this.connected = false;
-        this.ws = null;
-        for (const p of this.pending.values())
-            p.reject(new Error('websocket closed'));
-        this.pending.clear();
-        this.scheduleReconnect();
-    }
-    scheduleReconnect() {
-        if (this.closed)
-            return;
-        this.connected = false;
-        setTimeout(() => void this.connect(), RECONNECT_DELAY_MS);
-    }
-    async drainQueue() {
-        if (!this.connected || !this.threadId || this.turnInFlight)
-            return;
-        if (this.queue.length === 0)
-            return;
-        const line = this.queue[0];
-        this.turnInFlight = true;
-        this.armTurnTimeout();
-        log.debug({ thread: this.threadId, queue: this.queue.length }, 'codex-rc → turn/start');
-        try {
-            await this.call('turn/start', {
-                threadId: this.threadId,
-                input: [{ type: 'text', text: line, textElements: [] }],
-            });
-            this.queue.shift();
-        }
-        catch (err) {
-            log.warn({ err: errMsg(err) }, 'codex-rc turn/start failed; will retry');
-            this.clearTurnTimeout();
-            this.turnInFlight = false;
-            setTimeout(() => void this.drainQueue(), 1_000);
-        }
-    }
-    // If `turn/completed` never arrives (the daemon doesn't broadcast it to
-    // metro's connection, or we miss it for any reason), unstick after the
-    // backstop so subsequent inbounds don't queue forever.
-    armTurnTimeout() {
-        this.clearTurnTimeout();
-        this.turnTimeout = setTimeout(() => {
-            log.warn({ thread: this.threadId, queue: this.queue.length }, `codex-rc turn/completed not received within ${TURN_TIMEOUT_MS}ms; force-clearing single-flight gate`);
-            this.turnInFlight = false;
-            this.turnTimeout = null;
-            void this.drainQueue();
-        }, TURN_TIMEOUT_MS);
-    }
-    clearTurnTimeout() {
-        if (this.turnTimeout) {
-            clearTimeout(this.turnTimeout);
-            this.turnTimeout = null;
-        }
-    }
-    call(method, params) {
-        if (!this.ws)
-            return Promise.reject(new Error('not connected'));
-        const id = this.nextId++;
-        const ws = this.ws;
-        return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve: resolve, reject });
-            ws.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
-        });
-    }
-}

package/dist/tail.js

@@ -1,161 +0,0 @@
-// Standalone inbound stream. Polls Telegram + connects to Discord, prints
-// one JSON line per inbound message on stdout. Designed to be launched by
-// an agent and observed via Bash+Monitor (Claude Code) or unified_exec
-// polling (Codex).
-//
-// On every inbound: fires a 👀 reaction and starts a typing indicator that
-// refreshes until the agent replies (signaled by `metro reply` touching
-// .typing-stop/<key>) or the 60s safety cap is hit.
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import pkg from '../package.json' with { type: 'json' };
-import * as discord from './channels/discord.js';
-import * as telegram from './channels/telegram.js';
-import { tg } from './channels/telegram.js';
-import { CodexRC } from './lib/codex-rc.js';
-import { configuredPlatforms, loadMetroEnv, STATE_DIR, requireConfiguredPlatform } from './paths.js';
-import { errMsg, log } from './log.js';
-loadMetroEnv();
-const platforms = configuredPlatforms();
-requireConfiguredPlatform(platforms);
-// Telegram allows only one getUpdates poller per bot token. If another
-// `metro` instance is already running, exit cleanly instead of fighting
-// (409 spam). Stale lockfiles (PID dead) are reclaimed.
-const LOCK_FILE = join(STATE_DIR, '.tail-lock');
-function processIsAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-if (existsSync(LOCK_FILE)) {
-    const pid = Number(readFileSync(LOCK_FILE, 'utf8').trim());
-    if (Number.isInteger(pid) && pid > 0 && processIsAlive(pid)) {
-        log.info({ pid }, 'another `metro` instance is already polling; exiting');
-        process.exit(0);
-    }
-    try {
-        unlinkSync(LOCK_FILE);
-    }
-    catch { }
-}
-writeFileSync(LOCK_FILE, String(process.pid));
-function releaseLock() {
-    try {
-        if (existsSync(LOCK_FILE) && readFileSync(LOCK_FILE, 'utf8').trim() === String(process.pid)) {
-            unlinkSync(LOCK_FILE);
-        }
-    }
-    catch { }
-}
-process.on('exit', releaseLock);
-const TYPING_DIR = join(STATE_DIR, '.typing-stop');
-const TYPING_REFRESH_MS = 4_000;
-const TYPING_MAX_MS = 60_000;
-mkdirSync(TYPING_DIR, { recursive: true });
-// Codex push channel. Set METRO_CODEX_RC to the codex app-server URL
-// (typically `ws://127.0.0.1:8421` matching `codex app-server --listen
-// ws://127.0.0.1:8421`) to inject each inbound into the agent's history
-// via JSON-RPC `turn/start`. Codex's TUI `--remote` flag only accepts
-// ws://, so the daemon, the TUI, and metro must all share the same URL.
-// Unset → metro behaves exactly as before; stdout emit always runs first
-// so Claude Code Monitor users are unaffected.
-const codexRC = process.env.METRO_CODEX_RC ? new CodexRC(process.env.METRO_CODEX_RC, pkg.version) : null;
-codexRC?.start();
-const emit = (line) => {
-    const json = JSON.stringify(line);
-    process.stdout.write(`${json}\n`);
-    codexRC?.push(json);
-};
-const typingActive = new Map();
-const typingKey = (platform, chat) => `${platform}_${chat}`;
-function fireTyping(platform, chat) {
-    if (platform === 'telegram') {
-        void tg('sendChatAction', { chat_id: chat, action: 'typing' }).catch(err => log.warn({ err: errMsg(err) }, 'telegram typing failed'));
-    }
-    else {
-        void discord.sendTyping(chat).catch(err => log.warn({ err: errMsg(err) }, 'discord typing failed'));
-    }
-}
-function startTyping(platform, chat) {
-    const k = typingKey(platform, chat);
-    typingActive.set(k, { platform, chat, started: Date.now() });
-    // Clear any stale stop signal so the new typing actually fires.
-    const stopFile = join(TYPING_DIR, k);
-    if (existsSync(stopFile)) {
-        try {
-            unlinkSync(stopFile);
-        }
-        catch { }
-    }
-    fireTyping(platform, chat);
-}
-setInterval(() => {
-    const now = Date.now();
-    for (const [k, e] of typingActive) {
-        const stopFile = join(TYPING_DIR, k);
-        if (existsSync(stopFile)) {
-            try {
-                unlinkSync(stopFile);
-            }
-            catch { }
-            typingActive.delete(k);
-            continue;
-        }
-        if (now - e.started > TYPING_MAX_MS) {
-            typingActive.delete(k);
-            continue;
-        }
-        fireTyping(e.platform, e.chat);
-    }
-}, TYPING_REFRESH_MS);
-if (platforms.telegram) {
-    const me = await telegram.getMe();
-    log.info({ bot: `@${me.username}` }, 'telegram ready');
-    telegram.onInbound(m => {
-        void tg('setMessageReaction', {
-            chat_id: m.chat_id,
-            message_id: m.message_id,
-            reaction: [{ type: 'emoji', emoji: '👀' }],
-        }).catch(err => log.warn({ err: errMsg(err) }, 'telegram auto-react failed'));
-        const chat = String(m.chat_id);
-        startTyping('telegram', chat);
-        emit({ platform: 'telegram', to: `telegram:${chat}/${m.message_id}`, text: m.text });
-    });
-    void telegram.startPolling();
-}
-if (platforms.discord) {
-    await discord.startGateway();
-    const me = await discord.getMe();
-    log.info({ bot: me.username }, 'discord ready');
-    discord.onInbound(m => {
-        void discord
-            .setReaction(m.channel_id, m.message_id, '👀')
-            .catch(err => log.warn({ err: errMsg(err) }, 'discord auto-react failed'));
-        startTyping('discord', m.channel_id);
-        emit({ platform: 'discord', to: `discord:${m.channel_id}/${m.message_id}`, text: m.text });
-    });
-}
-// `process.on('exit', releaseLock)` above runs whenever process.exit is
-// called. We also `await discord.shutdownGateway()` here so the bot flips
-// offline immediately on SIGTERM / SIGINT instead of waiting ~45s for the
-// gateway's missed-heartbeat timeout. SIGKILL bypasses this (nothing we can
-// do); the lockfile auto-reclaims on the next start either way.
-let shuttingDown = false;
-async function shutdown() {
-    if (shuttingDown)
-        return;
-    shuttingDown = true;
-    codexRC?.stop();
-    if (platforms.discord) {
-        await discord.shutdownGateway().catch(err => log.warn({ err: errMsg(err) }, 'discord shutdown failed'));
-    }
-    process.exit(0);
-}
-process.stdin.on('end', shutdown);
-process.stdin.on('close', shutdown);
-process.on('SIGINT', shutdown);
-process.on('SIGTERM', shutdown);

package/skills/metro/SKILL.md

@@ -1,122 +0,0 @@
----
-name: metro
-description: Handle Telegram/Discord messages from `metro` for this agent session. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout or as user input shaped `{"platform":..., "to":..., "text":...}`, or when handling chat reply/react/edit/send/download/fetch.
----
-
-# Metro — handling the Telegram & Discord bridge
-
-Metro is a CLI bridge between this agent session and Telegram/Discord. Each inbound message arrives as a JSON line; you act on it via `metro <subcommand>`. The launch mechanics differ between Claude Code (you launch metro via shell) and Codex (the user launches metro outside the agent and the daemon pushes turns to you).
-
-## Starting the bridge
-
-When the user asks to run/start/launch metro, you launch it as a backgrounded shell command. The exact invocation depends on the runtime:
-
-### Claude Code
-
-```
-Bash(command: "metro", run_in_background: true)
-```
-
-Then attach `Monitor` to its stdout. Each stdout line is one inbound JSON event you act on directly.
-
-### Codex
-
-```
-shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)
-```
-
-Don't watch its stdout — Codex has no Monitor equivalent. Instead, metro pushes each inbound into your thread via JSON-RPC `turn/start`, so events arrive as user input on your next turn. The user must have a daemon and the TUI running for this to work — refer them to:
-
-```
-codex app-server --listen ws://127.0.0.1:8421       # daemon (terminal 1)
-codex --remote ws://127.0.0.1:8421                  # TUI (this session — terminal 2)
-```
-
-If `metro` exits immediately or the daemon isn't on 8421, ask the user. (`codex remote-control` is stdio-only and doesn't work for this flow.)
-
-### Diagnostics
-
-If something seems off, run `metro doctor`. Common causes: missing tokens (`metro setup telegram <token>` / `metro setup discord <token>`), Discord Message Content Intent not toggled, stale lockfile. On Codex, also: app-server not listening on the expected URL, or the TUI not attached via `--remote`.
-
-## Inbound shape
-
-Each `metro` line on stdout:
-
-```json
-{"platform":"telegram"|"discord","to":"<platform>:<chat>/<message_id>","text":"…"}
-```
-
-`text` may include placeholders for non-text content: `[image]`, `[voice]`, `[audio]`, `[file: <name>]`. Voice/audio are opaque markers — you can't download them.
-
-Discord guild messages preserve the user's raw mention markup, including the bot's own `<@bot_id>` (the gate that made the message visible). Treat the bot's own mention as metadata; other users' mentions (`<@some_other_id>`) can be addressee context. Reply normally — the message is addressed to you regardless of where the mention sits.
-
-## Required flow on every inbound
-
-1. **Echo to the visible reply.** Write `[<to>] <text>` on its own line in your visible output. Both Claude Code's Monitor and Codex dim/collapse tool output, so this echo is the only way the user sees what arrived without expanding cards.
-2. **Decide and act.** Pick the matching subcommand below.
-
-> 👀 is already on the message — `metro` auto-reacts server-side on every inbound and clears the reaction when you reply. Don't call `metro react --emoji=👀` yourself; you'd just flicker it on/off and waste a tool call.
-
-## Subcommands
-
-`reply` / `react` / `edit` / `download` take `--to=<platform>:<chat>/<message_id>` copied verbatim from the inbound `to` field. `send` and `fetch` take a channel-only `--to=<platform>:<chat>` (no message id). Append `--json` to any of them for a single JSON result line you can parse.
-
-| Action | Command |
-|---|---|
-| Quote-reply (threads under original; clears 👀) | `metro reply --to=<to> --text=<reply>` |
-| Quick ack reaction | `metro react --to=<to> --emoji=👍` |
-| Edit your previous bot message | `metro edit --to=<to> --text=<new text>` |
-| Send a proactive message (no reply context) | `metro send --to=<platform>:<chat_id> --text=<msg>` |
-| Download `[image]` attachments → file paths | `metro download --to=<to>` |
-| Fetch recent channel history (Discord only) | `metro fetch --to=discord:<channel_id> --limit=20` |
-
-`reply` / `edit` / `send` accept multi-line `--text` via stdin (heredoc).
-
-## When to use `send` vs `reply`
-
-- **`reply`** — responding to a specific inbound message. Threads under it. This is the default when handling a `metro` inbound line.
-- **`send`** — initiating without a triggering message: a long task you kicked off finished, a scheduled job fired, a follow-up the user asked you to deliver later. The chat/channel id you target must be one the bot can reach (existing DM, joined guild channel).
-
-## Address format
-
-- `telegram:<chat_id>/<message_id>` — copied straight from inbound `to`
-- `discord:<channel_id>/<message_id>` — same
-- `discord:<channel_id>` — channel-only, used for `metro fetch`
-
-## Image attachments
-
-When `text` contains `[image]`:
-
-1. Run `metro download --to=<to>` — writes images to disk and prints absolute paths (one per line).
-2. `Read` each path with the Read tool — the image enters your context as a vision input.
-3. Reply normally with `metro reply`.
-
-## Opaque attachment markers
-
-`[voice]`, `[audio: <name>]`, and `[file: <name>]` are opaque — `metro download` only handles images. Acknowledge in text (e.g., "got your voice note — could you type it out?") or, if your runtime accepts audio/file input directly, ask the user to resend as a regular file.
-
-## Exit codes
-
-- `0` success
-- `1` usage error (bad flags, unknown subcommand)
-- `2` configuration error (no tokens; tell the user to run `metro setup`)
-- `3` upstream error (rate limit, auth, network) — wait a few seconds and retry once before surfacing to the user
-
-If anything's misbehaving, run `metro doctor` to see which check fails.
-
-## --json output
-
-Every action command supports `--json` for stable, parseable output:
-
-```bash
-metro reply --to=… --text=… --json
-# {"ok":true,"platform":"discord","to":"discord:123/456","sent_message_id":"…"}
-
-metro fetch --to=discord:1234 --limit=10 --json
-# [{"message_id":"…","author":"…","text":"…","timestamp":"…"}, …]
-
-metro download --to=… --json
-# {"images":[{"path":"/abs/…png","mime":"image/png"}]}
-```
-
-Use `--json` when you need to chain calls or capture the new message_id for a later edit.