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

package/README.md

@@ -9,8 +9,8 @@ In your shell:
 ```bash
 npm install -g @stage-labs/metro@beta    # or: bun add -g @stage-labs/metro@beta
 
-metro setup telegram <token>             # https://t.me/BotFather
-metro setup discord  <token>             # https://discord.com/developers/applications
+metro setup telegram <token>    # https://t.me/BotFather
+metro setup discord <token>     # https://discord.com/developers/applications
 
 metro setup skill                        # writes SKILL.md so Claude Code + Codex auto-onboard
 metro doctor                             # verify
@@ -18,11 +18,33 @@ metro doctor                             # verify
 
 > **Discord setup:** toggle **Message Content Intent** in Developer Portal → Bot → Privileged Gateway Intents.
 
-Open Claude Code (`claude`) or Codex (`codex`), and tell it:
+### Run with Claude Code
 
-> Run `metro` in the background.
+```bash
+claude
+> Run metro in the background.
+```
+
+Then DM your bot. The bundled skill auto-triggers — the agent launches metro via Bash + Monitor, watches stdout, and replies.
+
+### Run with Codex
+
+Codex's `unified_exec` is poll-only ([#4751](https://github.com/openai/codex/issues/4751)) — there's no Monitor equivalent. Metro instead pushes each inbound into the agent's history via JSON-RPC. Two terminals plus a prompt — the TUI's `--remote` flag only accepts `ws://`, so daemon and TUI share one URL:
+
+```bash
+# Terminal 1 — daemon (must be running first)
+codex app-server --listen ws://127.0.0.1:8421
+
+# Terminal 2 — TUI attached to the daemon
+codex --remote ws://127.0.0.1:8421
+> Run metro in the background.
+```
+
+The agent launches `metro` (with `METRO_CODEX_RC=ws://127.0.0.1:8421` set) via its shell tool. Metro connects to the daemon and pushes each inbound as a `turn/start` on the active thread — the agent in terminal 2 reacts on its next turn. `codex remote-control` is stdio-only (no listener), so don't use it for this flow.
+
+Bare `codex` (no `--remote`) can't work with metro — the agent has no daemon to push to. The TUI must be attached to a running app-server.
 
-DM your bot. The agent picks up the next inbound and replies — the bundled skill handles launching, stdout watching, reactions, and replies.
+`METRO_CODEX_RC` accepts `ws://host:port` (required for use with the codex TUI) or `unix:///abs/path` (headless only — the daemon supports UDS but the TUI doesn't).
 
 ## Config
 
@@ -32,6 +54,7 @@ DM your bot. The agent picks up the next inbound and replies — the bundled ski
 | `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`. |
+| `METRO_CODEX_RC` | — | Codex app-server URL (e.g. `ws://127.0.0.1:8421`). When set, metro pushes each inbound into the agent's history via JSON-RPC `turn/start` — the Codex equivalent of Claude Code's Monitor. Accepts `ws://host:port` (required for use with the codex TUI) or `unix:///abs/path` (headless only). See [Codex setup](#codex-setup). |
 
 Token precedence: process env → `./.env` → `$METRO_CONFIG_DIR/.env`. Logs to stderr.
 

package/dist/cli.js

@@ -30,7 +30,7 @@ Usage:
 setup verbs:
   metro setup                                 Status: tokens, skills, what's next.
   metro setup telegram <token>                Save TELEGRAM_BOT_TOKEN (validated via getMe; --no-validate skips).
-  metro setup discord  <token>                Save DISCORD_BOT_TOKEN (validated via getMe; --no-validate skips).
+  metro setup discord <token>                 Save DISCORD_BOT_TOKEN (validated via getMe; --no-validate skips).
   metro setup clear [telegram|discord|all]    Remove tokens.
   metro setup skill [--project] [--clear]     Install (or remove) the agent skill.
 
@@ -52,6 +52,18 @@ Exit codes:
   1  usage error (bad flags, unknown subcommand)
   2  configuration error (no tokens — run \`metro setup\`)
   3  upstream error (rate limit, auth, network — retry once, then surface)
+
+Codex push (opt-in):
+  Set METRO_CODEX_RC to the codex app-server URL — metro will push each
+  inbound into the agent's history via JSON-RPC \`turn/start\`, the Codex
+  equivalent of Claude Code's Monitor.
+
+  Three terminals share the same URL (codex 0.130's TUI --remote only
+  accepts ws://):
+
+    codex app-server --listen ws://127.0.0.1:8421       # daemon
+    METRO_CODEX_RC=ws://127.0.0.1:8421 metro            # bridge
+    codex --remote ws://127.0.0.1:8421                  # TUI
 `;
 function exitErr(message, code) {
     return Object.assign(new Error(message), { code });
@@ -255,8 +267,8 @@ async function cmdSetupStatus(flags) {
         `  codex        ${fmtSkill(skills.codex)}\n\n`);
     if (!tg && !dc) {
         process.stdout.write('Get started:\n' +
-            '  1. metro setup telegram <token>     # https://t.me/BotFather\n' +
-            '     metro setup discord  <token>    # https://discord.com/developers/applications\n' +
+            '  1. metro setup telegram <token>    # https://t.me/BotFather\n' +
+            '     metro setup discord <token>     # https://discord.com/developers/applications\n' +
             '  2. metro setup skill                # auto-onboard your agent (writes to both runtimes)\n' +
             '  3. metro doctor                     # verify everything works\n' +
             '  4. metro                            # start the inbound stream\n');

package/dist/lib/codex-rc.js

@@ -0,0 +1,274 @@
+// 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/log.js

@@ -3,4 +3,10 @@
 // parsing. Override level with METRO_LOG_LEVEL.
 import pino from 'pino';
 export const log = pino({ name: 'metro', level: process.env.METRO_LOG_LEVEL || 'info' }, pino.destination(2));
-export const errMsg = (err) => (err instanceof Error ? err.message : String(err));
+export const errMsg = (err) => {
+    if (err instanceof Error)
+        return err.message;
+    if (err && typeof err === 'object' && 'message' in err)
+        return String(err.message);
+    return String(err);
+};

package/dist/paths.js

@@ -11,6 +11,14 @@ mkdirSync(STATE_DIR, { recursive: true });
 const CONFIG_DIR = process.env.METRO_CONFIG_DIR ??
     join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'metro');
 export const CONFIG_ENV_FILE = join(CONFIG_DIR, '.env');
+// Default codex app-server WebSocket. The TUI's `--remote <ADDR>` flag
+// only accepts ws:// (no UDS), so this is the canonical URL we recommend
+// users align on across the daemon, the TUI, and metro:
+//   codex app-server --listen ws://127.0.0.1:8421
+//   codex --remote ws://127.0.0.1:8421
+//   METRO_CODEX_RC=ws://127.0.0.1:8421 metro
+// Override via METRO_CODEX_RC if a different port/host is needed.
+export const DEFAULT_CODEX_RC_URL = 'ws://127.0.0.1:8421';
 export function skillDir(runtime, scope) {
     const base = scope === 'user' ? homedir() : process.cwd();
     const root = runtime === 'claude-code' ? '.claude' : '.agents';

package/dist/tail.js

@@ -8,9 +8,11 @@
 // .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();
@@ -54,7 +56,20 @@ 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 });
-const emit = (line) => process.stdout.write(`${JSON.stringify(line)}\n`);
+// 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) {
@@ -134,6 +149,7 @@ 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'));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Chat with your Claude Code or Codex agent over Telegram and Discord. Ultra-lightweight: ~1.2K lines of TypeScript, pure CLI, no hosted infra.",
   "license": "MIT",
   "repository": {
@@ -34,10 +34,12 @@
   },
   "dependencies": {
     "discord.js": "^14.14.0",
-    "pino": "^9.5.0"
+    "pino": "^9.5.0",
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/ws": "^8.18.1",
     "eslint": "^10.3.0",
     "typescript": "^5",
     "typescript-eslint": "^8.59.2"

package/skills/metro/SKILL.md

@@ -1,19 +1,42 @@
 ---
 name: metro
-description: Run the metro Telegram/Discord bridge in this session — launch `metro` in the background, watch its stdout for inbound JSON lines, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"platform":..., "to":..., "text":...}`, or when handling a chat reply/react/edit/send/download/fetch.
+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 — running the Telegram & Discord bridge
+# Metro — handling the Telegram & Discord bridge
 
-Metro is a CLI bridge between this agent session and Telegram/Discord. You launch `metro` once when the user asks, then act on each inbound JSON line via `metro <subcommand>`.
+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 (or "start 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:
 
-1. Launch `metro` as a backgrounded Bash command (Claude Code: `run_in_background: true`; Codex: equivalent background spawn). Don't block on it.
-2. Attach a stdout watcher: `Monitor` on Claude Code, `unified_exec` polling on Codex. Each stdout line is one inbound JSON. Stderr is logs — don't act on it.
-3. If `metro` exits immediately or no inbounds arrive within a minute of a known DM, run `metro doctor` to diagnose. Common causes: missing tokens (tell the user to run `metro setup telegram <token>` and/or `metro setup discord <token>` in their shell), Discord Message Content Intent not toggled, or a stale lockfile from a previous session.
+### 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