@stage-labs/metro 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/codex-rc.js

@@ -0,0 +1,236 @@
+/**
+ * JSON-RPC/WS client for codex app-server: each event → `turn/start` (Codex's Monitor equivalent).
+ */
+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 in case `turn/completed` never arrives — unstick the single-flight gate. */
+const TURN_TIMEOUT_MS = 120_000;
+/** Accept ws://, wss://, unix:///abs/path, or /abs/path (shorthand for unix). */
+function parseUrl(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 abs path)`);
+}
+function openSocket(endpoint) {
+    if (endpoint.kind === 'tcp')
+        return new WebSocket(endpoint.url);
+    return new WebSocket('ws://localhost/', {
+        createConnection: () => createConnection({ path: endpoint.path }),
+    });
+}
+export class CodexRC {
+    url;
+    clientVersion;
+    ws = null;
+    nextId = 1;
+    pending = new Map();
+    threadId = null;
+    queue = [];
+    connected = false;
+    connecting = false;
+    turnInFlight = false;
+    turnTimeout = null;
+    closed = false;
+    endpoint;
+    constructor(url, clientVersion) {
+        this.url = url;
+        this.clientVersion = clientVersion;
+        this.endpoint = parseUrl(url);
+    }
+    start() { void this.connect(); }
+    stop() {
+        this.closed = true;
+        this.clearTurnTimeout();
+        this.ws?.close();
+        this.ws = null;
+    }
+    push(line) {
+        if (this.queue.length >= MAX_QUEUE) {
+            log.warn({ url: this.url }, 'codex-rc queue full, dropping oldest');
+            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;
+            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());
+            const clientInfo = { name: 'metro', version: this.clientVersion, title: null };
+            await this.call('initialize', { clientInfo });
+            this.threadId = await this.pickOrCreateThread();
+            this.connected = true;
+            log.info({ url: this.url, thread: this.threadId ?? '(none yet)' }, 'codex-rc connected');
+            void this.drainQueue();
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err), url: this.url }, '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;
+        }
+        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;
+        }
+        switch (msg.method) {
+            case 'thread/started': {
+                const id = msg.params?.thread?.id;
+                if (id) {
+                    this.threadId = id;
+                    log.info({ thread: id }, 'codex-rc thread started');
+                    void this.drainQueue();
+                }
+                break;
+            }
+            case 'thread/status/changed': {
+                /* Codex 0.130+: status `{active}` means in-flight; anything else is idle. */
+                const p = msg.params;
+                if (p?.threadId !== this.threadId)
+                    break;
+                const active = typeof p.status === 'object' && p.status !== null && 'active' in p.status;
+                if (active)
+                    this.turnInFlight = true;
+                else {
+                    this.clearTurnTimeout();
+                    this.turnInFlight = false;
+                    void this.drainQueue();
+                }
+                break;
+            }
+            case 'turn/completed':
+                this.clearTurnTimeout();
+                this.turnInFlight = false;
+                void this.drainQueue();
+                break;
+            case 'turn/started':
+                this.turnInFlight = true;
+                break;
+            case 'thread/closed':
+            case 'thread/archived':
+                log.warn({ method: msg.method }, 'codex-rc thread closed/archived');
+                this.threadId = null;
+                break;
+        }
+    }
+    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);
+    }
+    /** Prefer the most-recently-loaded thread (the TUI's if attached); else create our own. */
+    async pickOrCreateThread() {
+        try {
+            const loaded = await this.call('thread/loaded/list', {});
+            const existing = loaded.data?.[loaded.data.length - 1];
+            if (existing)
+                return existing;
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err) }, 'codex-rc thread/loaded/list failed');
+        }
+        try {
+            const created = await this.call('thread/start', {});
+            return created.thread?.id ?? null;
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err) }, 'codex-rc thread/start failed');
+            return null;
+        }
+    }
+    async drainQueue() {
+        if (!this.connected || this.turnInFlight || !this.queue.length)
+            return;
+        if (!this.threadId) {
+            this.threadId = await this.pickOrCreateThread();
+            if (!this.threadId)
+                return;
+        }
+        const line = this.queue[0];
+        this.turnInFlight = true;
+        this.armTurnTimeout();
+        try {
+            const input = [{ type: 'text', text: line, textElements: [] }];
+            await this.call('turn/start', { threadId: this.threadId, input });
+            this.queue.shift();
+        }
+        catch (err) {
+            const dead = errMsg(err).includes('thread not found');
+            log.warn({ err: errMsg(err) }, dead ? 'codex-rc thread gone; will create a new one' : 'codex-rc turn/start failed; will retry');
+            this.clearTurnTimeout();
+            this.turnInFlight = false;
+            if (dead)
+                this.threadId = null;
+            setTimeout(() => void this.drainQueue(), 1_000);
+        }
+    }
+    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 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/dispatcher.js

@@ -0,0 +1,112 @@
+/**
+ * Daemon: chat inbound → JSON on stdout; optional codex-rc push; cross-agent `notify` over Unix socket.
+ */
+import { copyFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json' with { type: 'json' };
+import { DiscordStation } from './stations/discord.js';
+import { TelegramStation } from './stations/telegram.js';
+import { asLine } from './stations/index.js';
+import { CodexRC } from './codex-rc.js';
+import { startIpcServer, stopIpcServer } from './ipc.js';
+import { agentSelf, appendHistory, mintId } from './history.js';
+import { noteSeen, saveBotId } from './cache.js';
+import { errMsg, log } from './log.js';
+import { acquireLock, configuredPlatforms, loadMetroEnv, STATE_DIR, requireConfiguredPlatform } from './paths.js';
+loadMetroEnv();
+const platforms = configuredPlatforms();
+requireConfiguredPlatform(platforms);
+acquireLock(join(STATE_DIR, '.tail-lock'));
+const AGENTS_MD = join(STATE_DIR, 'AGENTS.md');
+try {
+    copyFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'docs', 'agents.md'), AGENTS_MD);
+}
+catch (err) {
+    log.warn({ err: errMsg(err), path: AGENTS_MD }, 'failed to install agent skill');
+}
+/** Suppress EPIPE so the daemon survives the agent (Monitor reader) restarting / dying. */
+process.stdout.on('error', err => {
+    if (err.code !== 'EPIPE')
+        log.warn({ err: errMsg(err) }, 'stdout error');
+});
+const codexRc = process.env.METRO_CODEX_RC ? new CodexRC(process.env.METRO_CODEX_RC, pkg.version) : null;
+codexRc?.start();
+const discord = new DiscordStation();
+const telegram = new TelegramStation();
+function emit(event) {
+    const json = JSON.stringify(event);
+    process.stdout.write(json + '\n');
+    codexRc?.push(json);
+    if ('lineName' in event)
+        noteSeen(event.line, event.lineName);
+    else
+        noteSeen(event.line);
+    if (event.type === 'inbound') {
+        appendHistory({
+            id: event.id, ts: event.ts, kind: 'inbound', station: event.station, line: event.line,
+            from: event.from, fromName: event.fromName, to: agentSelf(), text: event.text,
+            platformMessageId: event.messageId, attachments: event.attachmentNames,
+        });
+    }
+    else if (event.type === 'notification') {
+        appendHistory({
+            id: event.id, ts: event.ts, kind: 'notification',
+            station: event.line.replace(/^metro:\/\/([^/]+)\/.*$/, '$1'),
+            line: event.line, from: event.from ?? agentSelf(),
+            to: event.line, text: event.text,
+        });
+    }
+}
+const onInbound = (m) => emit({ type: 'inbound', ...m, to: agentSelf() });
+const ipc = startIpcServer(async (req) => {
+    if (req.op === 'notify') {
+        emit({
+            type: 'notification', id: mintId(), ts: new Date().toISOString(),
+            line: asLine(req.line),
+            from: req.from ? asLine(req.from) : agentSelf(), text: req.text,
+        });
+        return { ok: true };
+    }
+    if (req.op === 'download') {
+        const line = asLine(req.line);
+        const station = req.line.startsWith('metro://telegram/') ? telegram : discord;
+        const files = await station.download(line, req.messageId, req.outDir);
+        return { ok: true, files };
+    }
+    return { ok: false, error: 'unknown op' };
+});
+async function main() {
+    if (platforms.discord) {
+        discord.onMessage(onInbound);
+        const [, me] = await Promise.all([discord.start(), discord.getMe()]);
+        saveBotId('discord', me.id);
+        log.info({ bot: me.username }, 'discord ready');
+    }
+    if (platforms.telegram) {
+        telegram.onMessage(onInbound);
+        const [me] = await Promise.all([telegram.getMe(), telegram.start()]);
+        saveBotId('telegram', String(me.id));
+        log.info({ bot: `@${me.username}` }, 'telegram ready');
+    }
+    log.info({ codexRc: !!codexRc }, 'dispatcher ready');
+}
+let shuttingDown = false;
+async function shutdown() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    log.info('dispatcher shutting down');
+    codexRc?.stop();
+    await stopIpcServer(ipc).catch(() => { });
+    if (platforms.discord)
+        await discord.stop().catch(() => { });
+    if (platforms.telegram)
+        await telegram.stop().catch(() => { });
+    process.exit(0);
+}
+process.stdin.on('end', shutdown);
+process.stdin.on('close', shutdown);
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+await main();

package/dist/history.js

@@ -0,0 +1,84 @@
+/** Append-only JSONL history of every message that flows through metro (inbound + outbound). */
+import { randomBytes } from 'node:crypto';
+import { appendFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from './log.js';
+import { STATE_DIR } from './paths.js';
+const FILE = join(STATE_DIR, 'history.jsonl');
+/** Mint a universal metro message ID. Short, prefixed, URL-safe. */
+export const mintId = () => `msg_${randomBytes(6).toString('base64url')}`;
+/** Append one entry as a JSON line. POSIX-atomic for sub-PIPE_BUF writes (we're well under). */
+export function appendHistory(entry) {
+    try {
+        appendFileSync(FILE, JSON.stringify(entry) + '\n');
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err), path: FILE }, 'history append failed');
+    }
+}
+/** Read JSONL, parse, filter (most-recent-first), apply `limit`. Empty array if file is missing. */
+export function readHistory(filter = {}) {
+    if (!existsSync(FILE))
+        return [];
+    const lines = readFileSync(FILE, 'utf8').split('\n');
+    const out = [];
+    /** Walk backwards so `limit` clamps without scanning the whole file body twice. */
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const raw = lines[i].trim();
+        if (!raw)
+            continue;
+        let e;
+        try {
+            e = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        if (!matches(e, filter))
+            continue;
+        out.push(e);
+        if (filter.limit && out.length >= filter.limit)
+            break;
+    }
+    return out;
+}
+function matches(e, f) {
+    if (f.line && e.line !== f.line)
+        return false;
+    if (f.station && e.station !== f.station)
+        return false;
+    if (f.kind && e.kind !== f.kind)
+        return false;
+    if (f.from && e.from !== f.from)
+        return false;
+    if (f.textContains && !(e.text ?? '').toLowerCase().includes(f.textContains.toLowerCase()))
+        return false;
+    if (f.since && new Date(e.ts) < f.since)
+        return false;
+    return true;
+}
+/** Find an entry by universal id OR platform message id. */
+export function lookupEntry(id) {
+    const entries = readHistory({ limit: 5_000 });
+    return entries.find(e => e.id === id || e.platformMessageId === id);
+}
+/** Look up the platform messageId for a universal `msg_*` id; returns the input unchanged otherwise. */
+export function resolvePlatformId(id) {
+    if (!id.startsWith('msg_'))
+        return id;
+    const hit = lookupEntry(id);
+    if (hit?.platformMessageId)
+        return hit.platformMessageId;
+    throw new Error(`unknown universal id: ${id} (run \`metro history --limit=50\` to see recent ids)`);
+}
+/** Resolve the current agent's identity URI. Precedence: METRO_FROM > runtime env > generic. */
+export function agentSelf() {
+    const explicit = process.env.METRO_FROM;
+    if (explicit)
+        return explicit;
+    if (process.env.CLAUDECODE)
+        return 'metro://claude/agent';
+    if (process.env.METRO_CODEX_RC || process.env.CODEX_HOME)
+        return 'metro://codex/agent';
+    return 'metro://agent';
+}

package/dist/ipc.js

@@ -0,0 +1,71 @@
+/** Unix-socket IPC: `notify` re-emits on daemon stdout; `download` resolves Telegram attachments. */
+import { createConnection, createServer } from 'node:net';
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from './log.js';
+import { STATE_DIR } from './paths.js';
+const SOCKET_PATH = join(STATE_DIR, 'metro.sock');
+export function startIpcServer(handler) {
+    if (existsSync(SOCKET_PATH)) {
+        try {
+            unlinkSync(SOCKET_PATH);
+        }
+        catch { /* ignore */ }
+    }
+    const server = createServer(socket => handleConnection(socket, handler));
+    server.on('error', err => log.warn({ err: errMsg(err) }, 'ipc server error'));
+    server.listen(SOCKET_PATH, () => log.debug({ path: SOCKET_PATH }, 'ipc socket listening'));
+    return server;
+}
+export async function stopIpcServer(server) {
+    await new Promise(resolve => server.close(() => resolve()));
+    try {
+        if (existsSync(SOCKET_PATH))
+            unlinkSync(SOCKET_PATH);
+    }
+    catch { /* ignore */ }
+}
+async function handleConnection(socket, handler) {
+    let buf = '';
+    socket.setEncoding('utf8');
+    socket.on('data', chunk => { buf += chunk; });
+    socket.on('end', async () => {
+        let resp;
+        try {
+            const req = JSON.parse(buf.trim());
+            resp = await handler(req);
+        }
+        catch (err) {
+            resp = { ok: false, error: errMsg(err) };
+        }
+        socket.end(JSON.stringify(resp) + '\n');
+    });
+    socket.on('error', err => log.debug({ err: errMsg(err) }, 'ipc connection error'));
+}
+/** CLI-side: send one request, get one response. Throws if the daemon isn't running. */
+export function ipcCall(req, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+        if (!existsSync(SOCKET_PATH)) {
+            reject(new Error('metro daemon is not running (start it with `metro`)'));
+            return;
+        }
+        const socket = createConnection({ path: SOCKET_PATH });
+        let buf = '';
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error(`ipc timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+        socket.on('connect', () => { socket.end(JSON.stringify(req)); });
+        socket.on('data', chunk => { buf += chunk.toString('utf8'); });
+        socket.on('end', () => {
+            clearTimeout(timer);
+            try {
+                resolve(JSON.parse(buf.trim()));
+            }
+            catch (err) {
+                reject(new Error(`ipc bad response: ${errMsg(err)}`));
+            }
+        });
+        socket.on('error', err => { clearTimeout(timer); reject(err); });
+    });
+}

package/dist/log.js

@@ -1,6 +1,11 @@
-/** Pino → stderr. Stdout reserved for command output / --json. */
+/** Pino → stderr. TTY → pino-pretty (colorized, hostname/pid stripped); else JSON. */
 import pino from 'pino';
-export const log = pino({ name: 'metro', level: process.env.METRO_LOG_LEVEL || 'info' }, pino.destination(2));
+import pinoPretty from 'pino-pretty';
+const stream = process.stderr.isTTY
+    ? pinoPretty({ colorize: true, translateTime: 'HH:MM:ss', ignore: 'pid,hostname,name', destination: 2 })
+    : pino.destination(2);
+/** `base: { name }` strips pino's default pid+hostname from JSON output too (not just from the TTY pretty stream). */
+export const log = pino({ base: { name: 'metro' }, level: process.env.METRO_LOG_LEVEL || 'info' }, stream);
 export const errMsg = (err) => {
     if (err instanceof Error)
         return err.message;