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

package/README.md

@@ -1,50 +1,70 @@
 # Metro
 
-Chat with your Claude Code or Codex agent over Telegram and Discord.
+Run a long-lived daemon that bridges Discord and Telegram to your Codex + Claude Code agents. Each chat thread/topic gets its own agent session with streaming responses and live tool-call status. Both agents run side-by-side — pick per-message with a `with claude` / `with codex` suffix.
 
-## Quickstart
+## Prereqs
+
+- **Node ≥ 22** (or Bun ≥ 1.3).
+- **One or both agent CLIs** installed and authenticated:
+  - **Claude Code** — run `claude` once interactively to log in. Metro shells out per turn and inherits your auth, plugins, settings.
+  - **Codex** — run `codex` once interactively to log in. Metro spawns `codex app-server` and inherits your auth, MCPs, sandboxing.
+- **Discord bot** (optional) with **Message Content Intent** enabled (Developer Portal → Bot → Privileged Gateway Intents).
+- **Telegram bot** (optional). In supergroup forums, the bot also needs the **Manage Topics** admin permission so it can auto-create topics on @-mention.
 
-In your shell:
+## Quickstart
 
 ```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 discord <token>              # https://discord.com/developers/applications
+metro setup telegram <token>             # https://t.me/BotFather
 
-metro setup skill                        # writes SKILL.md so Claude Code + Codex auto-onboard
 metro doctor                             # verify
+metro                                    # run the orchestrator
 ```
 
-> **Discord setup:** toggle **Message Content Intent** in Developer Portal → Bot → Privileged Gateway Intents.
+Metro starts both agents at boot and listens on whichever platforms are configured. Each scope defaults to **Claude** for the first turn; once you've used an agent there, follow-up messages stick with it. Switch per-message by suffixing `with claude` or `with codex` (any casing):
 
-### Run with Claude Code
+```
+@Metro draft a release note
+   → uses Claude (default for a new scope)
 
-```bash
-claude
-> Run metro in the background.
+How would Codex have done this? with codex
+   → routes this turn to Codex; stays Codex on subsequent turns
 ```
 
-Then DM your bot. The bundled skill auto-triggers — the agent launches metro via Bash + Monitor, watches stdout, and replies.
+### Discord
 
-### Run with Codex
+@-mention the bot in any channel:
+1. Metro creates a thread anchored on your message (named after the message).
+2. Spins up an agent session for that thread.
+3. Streams the agent's reply with tool-call status (`Running: <command>`, `Editing 3 files`, `Thinking…`).
 
-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:
+Follow-ups in the thread route automatically — no @-mention needed.
 
-```bash
-# Terminal 1 — daemon (must be running first)
-codex app-server --listen ws://127.0.0.1:8421
+### Telegram
 
-# Terminal 2 — TUI attached to the daemon
-codex --remote ws://127.0.0.1:8421
-> Run metro in the background.
-```
+- **DM the bot** — every message is implicitly addressed to it; one scope per chat.
+- **@-mention the bot in a forum supergroup's General topic** — metro auto-creates a new topic for the conversation (Discord-style "thread from message"). Subsequent messages in that topic route automatically.
+- **Inside an existing custom topic** — routes to that topic's scope on every message.
 
-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.
+Regular (non-forum) groups are not routed — they have no thread boundary.
 
-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.
+## How it works
 
-`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).
+```
+Discord gateway ──┐                       ┌─▶ codex app-server   (long-lived subprocess, UDS JSON-RPC)
+                  ├─▶ metro orchestrator ─┤
+Telegram poller ──┘                       └─▶ claude -p ...      (per-turn subprocess, stream-json)
+                            │
+                            └──── scope map (scopes.json)
+```
+
+- **One metro = one daemon.** Lockfile at `$METRO_STATE_DIR/.tail-lock` keeps things singleton.
+- **Both agents side-by-side.** A scope can have up to one session per agent — independent histories. Routing is per-message: explicit `with claude` / `with codex` suffix, otherwise the scope's last-used agent, otherwise Claude.
+- **Streaming.** Replies edit one message every ~1500 ms while deltas stream in (leading-edge first flush for fast initial feedback). Tool calls show as a status line; long replies split past ~1900 chars onto a follow-up message.
+- **Queueing.** Messages that arrive while a turn is running are buffered per-scope and answered together in the next reply.
+- **Catchup-on-restart.** Discord uses a per-scope `lastSeenMessageId` watermark and REST-fetches anything newer when metro comes back up. Telegram leans on its own update-id queue (persisted offset in `telegram-offset.json`).
 
 ## Config
 
@@ -52,27 +72,43 @@ Bare `codex` (no `--remote`) can't work with metro — the agent has no daemon t
 |---|---|---|
 | `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_STATE_DIR` | `~/.cache/metro` | Lockfile, scope cache, codex socket, telegram offset, claude session set. |
 | `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.
 
+## Develop locally
+
+```bash
+git clone https://github.com/bonustrack/metro && cd metro
+bun install && bun run build
+bun link                                 # makes `metro` resolve to this checkout
+METRO_LOG_LEVEL=debug metro
+```
+
 ## Reference
 
 - `metro --help` — command surface
-- `metro doctor` — health check
-- [SKILL.md](skills/metro/SKILL.md) — agent-facing flow
+- `metro doctor` — health check (tokens + gateway/poller reachability + orchestrator status)
+- State files (`$METRO_STATE_DIR`, defaults to `~/.cache/metro/`):
+  - `scopes.json` — Discord-thread / Telegram-topic ↔ agent-session map
+  - `.tail-lock` — orchestrator pid
+  - `codex-app-server.sock` — codex's UDS
+  - `telegram-offset.json` — last processed update id (used for catchup on restart)
+  - `claude-sessions.json` — set of started Claude session uuids (so restarts use `--resume` instead of `--session-id`)
 
 ## Uninstall
 
 ```bash
-metro setup clear; metro setup skill --clear
+metro setup clear
 rm -rf ~/.cache/metro/
 npm uninstall -g @stage-labs/metro
 ```
 
 ## Caveats
 
-- **No allowlist.** Anyone who can DM your bot or @-mention it can talk to your session. Run against bots you own.
-- **Latency.** Inbounds surface at the next agent decision boundary — sub-second on Claude Code, longer on Codex turns.
+- **No allowlist.** Anyone who can DM/@-mention your bot can spawn an agent session. Run against bots you own.
+- **Per-agent histories are separate.** Switching with `with codex` mid-scope spins up a fresh Codex session — it has no idea what you discussed with Claude in the same scope. Each agent only sees what was sent to it.
+- **One agent missing is OK.** If only `claude` or only `codex` is installed/authenticated, metro still starts; messages asking for the missing one surface an error in chat.
+- **Telegram non-forum groups are skipped.** Without a per-topic thread boundary the routing model breaks down. DMs and forum topics (incl. auto-created ones from General) work normally.
+- **Telegram bot privacy.** Default Telegram bot privacy is *enabled*, which can block group messages even with @-mentions. Disable in [@BotFather](https://t.me/BotFather) → Bot Settings → Group Privacy → Turn off, then kick + re-invite the bot.

package/dist/agents/claude.js

@@ -0,0 +1,229 @@
+// Claude Code agent adapter. Spawns `claude -p --output-format stream-json
+// --include-partial-messages --verbose` per turn, parses the line-delimited
+// JSON event stream, and exposes the same `Agent` surface as codex.ts.
+//
+// Unlike codex (long-running app-server daemon), Claude Code has no daemon
+// mode — each turn is a fresh subprocess. Session continuity is achieved
+// by passing the same uuid via `--session-id` for the first turn and
+// `--resume` for every subsequent turn.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { errMsg, log } from '../log.js';
+import { STATE_DIR } from '../paths.js';
+// Persisted across metro restarts. Without this, the first message after
+// a restart would call `claude -p --session-id <uuid>` on an existing
+// session, which fails silently (no result event) and leaves the user
+// staring at "Thinking…" forever. Codex doesn't have this problem
+// because codex app-server is the state authority and reads its on-disk
+// thread store on spawn.
+const STARTED_FILE = join(STATE_DIR, 'claude-sessions.json');
+function loadStarted() {
+    if (!existsSync(STARTED_FILE))
+        return new Set();
+    try {
+        return new Set(JSON.parse(readFileSync(STARTED_FILE, 'utf8')));
+    }
+    catch (err) {
+        log.warn({ err: errMsg(err), path: STARTED_FILE }, 'claude agent: started cache read failed; treating as empty');
+        return new Set();
+    }
+}
+export class ClaudeAgent {
+    // Threads that have had at least one turn run (so `--session-id` was
+    // already consumed and subsequent turns must use `--resume`).
+    started = loadStarted();
+    children = new Set();
+    persistStarted() {
+        try {
+            writeFileSync(STARTED_FILE, JSON.stringify([...this.started]));
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err), path: STARTED_FILE }, 'claude agent: started cache write failed');
+        }
+    }
+    async start() {
+        // No daemon to bring up — sanity-check that `claude` is on PATH so we
+        // fail loud at boot rather than on the first inbound message.
+        await new Promise((resolve, reject) => {
+            const c = spawn('claude', ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
+            let out = '';
+            c.stdout.on('data', d => { out += String(d); });
+            c.on('error', reject);
+            c.on('exit', code => {
+                if (code === 0) {
+                    log.info({ version: out.trim() }, 'claude agent: ready');
+                    resolve();
+                }
+                else
+                    reject(new Error(`claude --version exited with ${code}`));
+            });
+        });
+    }
+    async stop() {
+        for (const c of this.children) {
+            try {
+                c.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+        }
+        this.children.clear();
+    }
+    async createThread() {
+        // Pre-allocate a uuid so the Discord thread can be named with it before
+        // the first turn runs. Claude Code accepts any valid uuid via
+        // `--session-id` and persists the session under that id.
+        const id = randomUUID();
+        log.info({ thread: id }, 'claude agent: thread allocated');
+        return id;
+    }
+    async sendTurn(threadId, text, callbacks) {
+        const args = [
+            '-p',
+            '--output-format', 'stream-json',
+            '--include-partial-messages',
+            '--verbose',
+        ];
+        if (this.started.has(threadId))
+            args.push('--resume', threadId);
+        else
+            args.push('--session-id', threadId);
+        args.push(text);
+        const child = spawn('claude', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        this.children.add(child);
+        log.debug({ thread: threadId, args: args.slice(0, -1) }, 'claude agent: turn started');
+        const session = new TurnSession(callbacks);
+        let buffer = '';
+        child.stdout?.on('data', d => {
+            buffer += String(d);
+            let nl;
+            while ((nl = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, nl).trim();
+                buffer = buffer.slice(nl + 1);
+                if (!line)
+                    continue;
+                try {
+                    session.handle(JSON.parse(line));
+                }
+                catch (err) {
+                    log.warn({ err: errMsg(err) }, 'claude agent: malformed event');
+                }
+            }
+        });
+        child.stderr?.on('data', d => log.trace({ src: 'claude-stderr' }, String(d).trim()));
+        child.on('exit', code => {
+            this.children.delete(child);
+            if (!this.started.has(threadId)) {
+                this.started.add(threadId);
+                this.persistStarted();
+            }
+            // If the subprocess exits without a `result` event (crash, OOM, kill),
+            // surface that as an error so the orchestrator unsticks the thread.
+            if (!session.done) {
+                if (code === 0)
+                    session.fireComplete();
+                else
+                    session.fireError(new Error(`claude exited with code ${code}`));
+            }
+        });
+        child.on('error', err => {
+            this.children.delete(child);
+            if (!session.done)
+                session.fireError(err);
+        });
+    }
+}
+// Owns the once-only firing of onComplete/onError and the per-index tool
+// tracking so block_stop events can fire onToolEnd correctly.
+class TurnSession {
+    cb;
+    done = false;
+    // Show "Thinking…" until the first real text/tool event lands. Claude
+    // Code doesn't emit a separate reasoning event the way codex does, so
+    // without this the user sees nothing while the agent is still on its
+    // initial API call — feels like the bot's frozen.
+    thinking = true;
+    // Track which content-block indexes belong to tool_use vs text so
+    // block_stop fires onToolEnd only for tool blocks.
+    tools = new Map();
+    constructor(cb) {
+        this.cb = cb;
+        cb.onToolStart('thinking', 'Thinking…');
+    }
+    fireComplete() {
+        if (this.done)
+            return;
+        this.done = true;
+        this.clearThinking();
+        this.cb.onComplete();
+    }
+    fireError(err) {
+        if (this.done)
+            return;
+        this.done = true;
+        this.clearThinking();
+        this.cb.onError(err);
+    }
+    clearThinking() {
+        if (!this.thinking)
+            return;
+        this.thinking = false;
+        this.cb.onToolEnd('thinking');
+    }
+    handle(ev) {
+        if (ev.type === 'result') {
+            if (ev.is_error)
+                this.fireError(new Error(typeof ev.result === 'string' ? ev.result : 'claude error'));
+            else
+                this.fireComplete();
+            return;
+        }
+        if (ev.type !== 'stream_event' || !ev.event)
+            return;
+        const e = ev.event;
+        if (e.type === 'content_block_start' && e.content_block?.type === 'tool_use') {
+            this.clearThinking();
+            this.tools.set(e.index ?? -1, e.content_block.name ?? 'tool');
+            this.cb.onToolStart(e.content_block.name ?? 'tool', summarizeTool(e.content_block.name, e.content_block.input));
+        }
+        else if (e.type === 'content_block_delta' && e.delta?.type === 'text_delta') {
+            this.clearThinking();
+            this.cb.onDelta(e.delta.text ?? '');
+        }
+        else if (e.type === 'content_block_stop') {
+            const kind = this.tools.get(e.index ?? -1);
+            if (kind !== undefined) {
+                this.tools.delete(e.index ?? -1);
+                this.cb.onToolEnd(kind);
+            }
+        }
+    }
+}
+function summarizeTool(name, input) {
+    const n = (name ?? 'Tool')[0].toUpperCase() + (name ?? 'Tool').slice(1);
+    if (!input)
+        return n;
+    const path = (input.file_path ?? input.path);
+    const cmd = input.command;
+    const pattern = input.pattern;
+    const url = input.url;
+    switch (name) {
+        case 'Bash': return cmd ? `Running: ${truncate(cmd, 60)}` : n;
+        case 'Edit':
+        case 'Write':
+        case 'NotebookEdit':
+            return path ? `Editing ${path}` : n;
+        case 'Read': return path ? `Reading ${path}` : n;
+        case 'Grep':
+        case 'Glob':
+            return pattern ? `Searching: ${truncate(pattern, 60)}` : n;
+        case 'WebFetch': return url ? `Fetching ${url}` : n;
+        case 'WebSearch': return 'Searching the web';
+        case 'Task': return 'Spawning subagent';
+        default: return n;
+    }
+}
+function truncate(s, n) {
+    return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}

package/dist/agents/codex.js

@@ -0,0 +1,282 @@
+// Codex agent adapter. Spawns `codex app-server --listen unix://…` as a
+// child process, talks to it over WebSocket-over-UDS, manages one codex
+// thread per scope, and streams per-turn events back to the orchestrator
+// (text deltas, tool-call lifecycle, completion).
+//
+// The orchestrator never speaks codex directly — it asks this adapter to
+// `ensureThread(scopeKey)` and `sendTurn(threadId, text, callbacks)`.
+import { spawn } from 'node:child_process';
+import { existsSync, unlinkSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { join } from 'node:path';
+import { WebSocket } from 'ws';
+import { errMsg, log } from '../log.js';
+import { STATE_DIR } from '../paths.js';
+const SOCKET_PATH = join(STATE_DIR, 'codex-app-server.sock');
+const READY_TIMEOUT_MS = 15_000;
+const READY_POLL_MS = 100;
+export class CodexAgent {
+    clientVersion;
+    ws = null;
+    daemon = null;
+    nextId = 1;
+    pending = new Map();
+    turnCallbacks = new Map(); // keyed by thread_id
+    constructor(clientVersion) {
+        this.clientVersion = clientVersion;
+    }
+    async start() {
+        // Fail loud at boot if codex isn't installed, rather than 15s later
+        // via a "socket didn't appear" timeout.
+        await this.checkCodexInstalled();
+        // Stale socket file from a previous run would let us connect to nothing
+        // (no listener) — wipe before spawning so codex binds fresh.
+        try {
+            unlinkSync(SOCKET_PATH);
+        }
+        catch { /* missing is fine */ }
+        log.info({ socket: SOCKET_PATH }, 'codex agent: starting app-server');
+        // Spawn the daemon listening on our UDS. Inherits CODEX_HOME so it picks
+        // up the user's auth, settings, MCPs, etc.
+        this.daemon = spawn('codex', ['app-server', '--listen', `unix://${SOCKET_PATH}`], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // Capture daemon stderr so a startup failure surfaces with the actual
+        // error message, not just a generic timeout. Once the daemon is ready,
+        // stderr goes back to trace (its own tracing is noisy).
+        let bootStderr = '';
+        let daemonExited = false;
+        let daemonExitCode = null;
+        const onBootStderr = (d) => {
+            bootStderr += String(d);
+            log.trace({ src: 'codex-stderr' }, String(d).trim());
+        };
+        this.daemon.stdout?.on('data', d => log.trace({ src: 'codex-stdout' }, String(d).trim()));
+        this.daemon.stderr?.on('data', onBootStderr);
+        this.daemon.on('exit', code => {
+            daemonExited = true;
+            daemonExitCode = code;
+            log.warn({ code }, 'codex daemon exited');
+        });
+        try {
+            await this.waitForSocket(() => daemonExited, () => bootStderr.trim() || `exit code ${daemonExitCode}`);
+            await this.connect();
+        }
+        catch (err) {
+            // Make the failure self-explanatory in the orchestrator's catch log.
+            const detail = bootStderr.trim() ? ` (codex stderr: ${bootStderr.trim().slice(0, 200)})` : '';
+            throw new Error(`${errMsg(err)}${detail}`);
+        }
+        log.info('codex agent: ready');
+    }
+    async checkCodexInstalled() {
+        await new Promise((resolve, reject) => {
+            const c = spawn('codex', ['--version'], { stdio: ['ignore', 'ignore', 'pipe'] });
+            let stderr = '';
+            c.stderr?.on('data', d => { stderr += String(d); });
+            c.on('error', err => reject(new Error(`codex CLI not found on PATH: ${errMsg(err)}`)));
+            c.on('exit', code => code === 0
+                ? resolve()
+                : reject(new Error(`codex --version exited ${code}: ${stderr.trim()}`)));
+        });
+    }
+    async stop() {
+        this.ws?.close();
+        this.ws = null;
+        this.daemon?.kill('SIGTERM');
+        this.daemon = null;
+    }
+    /**
+     * Create a new codex thread and return its id. The caller is responsible
+     * for caching the mapping `scopeKey → threadId` and only calling this
+     * once per scope (subsequent inbounds reuse the thread via `sendTurn`).
+     */
+    async createThread() {
+        const result = await this.call('thread/start', {});
+        log.info({ thread: result.thread.id }, 'codex agent: thread created');
+        return result.thread.id;
+    }
+    /**
+     * Send a user message to a thread and stream the agent's response via
+     * the provided callbacks. Resolves immediately after `turn/start`
+     * acknowledges; callbacks fire as notifications arrive and conclude
+     * with `onComplete` or `onError`.
+     */
+    async sendTurn(threadId, text, callbacks) {
+        this.turnCallbacks.set(threadId, callbacks);
+        try {
+            // Wire format per codex's generated TS bindings: `text_elements`
+            // (snake_case), not camelCase. Sending camelCase silently degrades
+            // — accepted by the server but doesn't echo back in items.
+            await this.call('turn/start', {
+                threadId,
+                input: [{ type: 'text', text, text_elements: [] }],
+            });
+        }
+        catch (err) {
+            this.turnCallbacks.delete(threadId);
+            callbacks.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    // --- transport ---
+    async waitForSocket(exited, exitReason) {
+        const deadline = Date.now() + READY_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (exited())
+                throw new Error(`codex app-server exited before listening: ${exitReason()}`);
+            if (existsSync(SOCKET_PATH))
+                return;
+            await new Promise(r => setTimeout(r, READY_POLL_MS));
+        }
+        throw new Error(`codex app-server didn't appear at ${SOCKET_PATH} within ${READY_TIMEOUT_MS}ms`);
+    }
+    async connect() {
+        // perMessageDeflate disabled: codex 0.130's WS upgrade handler closes
+        // the connection if a client offers `Sec-WebSocket-Extensions:
+        // permessage-deflate` (the `ws` library's default). Disabling it makes
+        // the upgrade succeed cleanly. Compression is irrelevant over a UDS.
+        const ws = new WebSocket('ws://localhost/', {
+            perMessageDeflate: false,
+            createConnection: () => {
+                const sock = createConnection({ path: SOCKET_PATH });
+                // Swallow socket-level errors so a transport hiccup during the HTTP
+                // upgrade doesn't surface as an uncaught error on the http_client
+                // request (Node's http.ClientRequest re-emits this).
+                sock.on('error', err => log.warn({ err: errMsg(err) }, 'codex agent: socket error'));
+                return sock;
+            },
+        });
+        this.ws = ws;
+        ws.on('error', err => log.warn({ err: errMsg(err) }, 'codex agent: 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', () => {
+            log.warn('codex agent: websocket closed');
+            this.ws = null;
+            // Drain stranded turns + RPC promises so the orchestrator can
+            // release its in-flight gate and the user sees an error rather
+            // than a permanent "Thinking…".
+            this.drainPending('codex websocket closed');
+        });
+        await this.call('initialize', {
+            clientInfo: { name: 'metro', version: this.clientVersion, title: null },
+        });
+    }
+    onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch (err) {
+            log.warn({ err: errMsg(err) }, 'codex agent: malformed message');
+            return;
+        }
+        // RPC response
+        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;
+        }
+        // Notifications.
+        if (!msg.method)
+            return;
+        log.trace({ method: msg.method }, 'codex agent: notification');
+        const params = msg.params;
+        const threadId = params?.threadId;
+        if (!threadId)
+            return;
+        const cb = this.turnCallbacks.get(threadId);
+        if (!cb)
+            return; // no active turn for this thread (yet or anymore)
+        if (msg.method === 'item/agentMessage/delta') {
+            const p = msg.params;
+            cb.onDelta(p.delta);
+        }
+        else if (msg.method === 'item/started') {
+            const p = msg.params;
+            const summary = summarizeItem(p.item);
+            if (summary && p.item.type !== 'agentMessage' && p.item.type !== 'userMessage') {
+                cb.onToolStart(p.item.type, summary);
+            }
+        }
+        else if (msg.method === 'item/completed') {
+            const p = msg.params;
+            if (p.item.type !== 'agentMessage' && p.item.type !== 'userMessage')
+                cb.onToolEnd(p.item.type);
+        }
+        else if (msg.method === 'thread/status/changed') {
+            // Codex 0.130 doesn't reliably emit `turn/completed` — `thread/status`
+            // returning to `idle` is the dependable completion signal. The same
+            // notification fires on `active` when a turn starts; ignore those.
+            const p = msg.params;
+            if (p.status?.type === 'idle') {
+                this.turnCallbacks.delete(threadId);
+                cb.onComplete();
+            }
+            else if (p.status?.type === 'systemError') {
+                this.turnCallbacks.delete(threadId);
+                cb.onError(new Error('codex thread entered systemError'));
+            }
+        }
+        else if (msg.method === 'turn/completed') {
+            // Belt-and-braces: if codex does emit it, take it.
+            this.turnCallbacks.delete(threadId);
+            cb.onComplete();
+        }
+        else if (msg.method === 'error') {
+            const p = msg.params;
+            this.turnCallbacks.delete(threadId);
+            cb.onError(new Error(p.error?.message ?? 'codex error notification'));
+        }
+    }
+    call(method, params) {
+        if (!this.ws)
+            return Promise.reject(new Error('codex agent: 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 }));
+        });
+    }
+    /** Fail every in-flight turn + RPC. Used when the transport dies. */
+    drainPending(reason) {
+        const err = new Error(reason);
+        for (const cb of this.turnCallbacks.values()) {
+            try {
+                cb.onError(err);
+            }
+            catch (e) {
+                log.warn({ err: errMsg(e) }, 'codex agent: drain callback threw');
+            }
+        }
+        this.turnCallbacks.clear();
+        for (const p of this.pending.values())
+            p.reject(err);
+        this.pending.clear();
+    }
+}
+function summarizeItem(item) {
+    if (item.type === 'commandExecution' && 'command' in item) {
+        return `Running: ${truncate(item.command ?? '', 60)}`;
+    }
+    if (item.type === 'fileChange' && 'changes' in item) {
+        const n = item.changes?.length ?? 0;
+        return n > 0 ? `Editing ${n} file${n === 1 ? '' : 's'}` : 'Editing files';
+    }
+    if (item.type === 'reasoning')
+        return 'Thinking…';
+    if (item.type === 'agentMessage')
+        return ''; // text deltas handled separately
+    return item.type;
+}
+function truncate(s, n) {
+    return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}

package/dist/agents/types.js

@@ -0,0 +1,3 @@
+// Shared interface so the orchestrator can talk to either Codex or Claude
+// Code (or future agents) through the same surface.
+export {};