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

package/README.md

@@ -1,50 +1,73 @@
 # 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 inline, persistent tool-call traces. 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 each tool call as its own block: plain header `🛠 **Read**` followed by two fenced code blocks — input (`src/foo.ts`) above, output (file contents) below. Outputs are capped at 50 lines / 1500 chars per tool with a `_(N more lines)_` note if truncated. `Thinking…` shows as a transient status that vanishes once real content arrives.
 
-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") and posts a deep link back in General so the new topic is one tap away. 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). Long replies split past ~1900 chars onto a follow-up message.
+- **Tool-call visibility.** Each tool call is rendered as a plain `🛠 **<tool>**` header plus two fenced code blocks — input then output — paired by tool id so parallel calls don't collide. Both blocks are fully visible (no collapse). Outputs are capped at 50 lines / 1500 chars per tool.
+- **Telegram formatting.** Agent markdown (`**bold**`, `*italic*`, `` `code` ``, fenced blocks, `[link](url)`, blockquotes) is converted to Telegram's HTML parse mode on the way out, so it renders as formatted text instead of literal characters.
+- **No link previews.** Outgoing messages set `link_preview_options.is_disabled` on Telegram and the `SUPPRESS_EMBEDS` flag on Discord, so URLs in agent replies don't unfurl into giant auto-embeds.
+- **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 +75,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,207 @@
+/** Claude Code adapter: per-turn `claude -p` subprocess; --session-id then --resume (persisted across restarts). */
+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';
+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: started cache read failed');
+        return new Set();
+    }
+}
+export class ClaudeAgent {
+    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: started cache write failed');
+        }
+    }
+    async start() {
+        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() {
+        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'];
+        args.push(this.started.has(threadId) ? '--resume' : '--session-id', threadId, text);
+        const child = spawn('claude', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        this.children.add(child);
+        log.debug({ thread: threadId }, '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 (!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); });
+    }
+}
+class TurnSession {
+    cb;
+    done = false;
+    thinking = true;
+    /** tool_use_id → kind; survives until the matching tool_result lands. */
+    byUseId = new Map();
+    /** Pending tool_use blocks: input JSON streams in over multiple `input_json_delta` events before the input is complete. */
+    pendingTools = new Map();
+    constructor(cb) {
+        this.cb = cb;
+        cb.onToolStart({ id: 'thinking', kind: 'thinking', name: 'Thinking…', transient: true });
+    }
+    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 === 'user') {
+            this.handleToolResults(ev);
+            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();
+            const idx = e.index ?? -1;
+            const kind = e.content_block.name ?? 'tool';
+            const id = e.content_block.id ?? `${kind}:${idx}`;
+            this.byUseId.set(id, kind);
+            this.pendingTools.set(idx, { id, kind, toolName: e.content_block.name, inputJson: '' });
+        }
+        else if (e.type === 'content_block_delta' && e.delta?.type === 'input_json_delta') {
+            const tool = this.pendingTools.get(e.index ?? -1);
+            if (tool)
+                tool.inputJson += e.delta.partial_json ?? '';
+        }
+        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 tool = this.pendingTools.get(e.index ?? -1);
+            if (!tool)
+                return;
+            this.pendingTools.delete(e.index ?? -1);
+            let input;
+            try {
+                input = tool.inputJson ? JSON.parse(tool.inputJson) : undefined;
+            }
+            catch { /* malformed mid-stream — show name only */ }
+            const { name, detail } = summarizeTool(tool.toolName, input);
+            this.cb.onToolStart({ id: tool.id, kind: tool.kind, name, detail });
+        }
+    }
+    /** Claude emits `tool_result` blocks inside a follow-up `user` message after the tool runs. */
+    handleToolResults(ev) {
+        for (const block of ev.message?.content ?? []) {
+            if (block.type !== 'tool_result' || !block.tool_use_id)
+                continue;
+            if (!this.byUseId.has(block.tool_use_id))
+                continue;
+            this.byUseId.delete(block.tool_use_id);
+            this.cb.onToolEnd(block.tool_use_id, extractResultText(block.content));
+        }
+    }
+}
+function extractResultText(content) {
+    if (typeof content === 'string')
+        return content.trim() || undefined;
+    if (!Array.isArray(content))
+        return undefined;
+    const text = content.filter(b => b?.type === 'text').map(b => b.text ?? '').join('\n').trim();
+    return text || undefined;
+}
+function summarizeTool(name, input) {
+    const display = (name ?? 'Tool')[0].toUpperCase() + (name ?? 'Tool').slice(1);
+    if (!input)
+        return { name: display };
+    const path = (input.file_path ?? input.path);
+    const cmd = input.command;
+    const pattern = input.pattern;
+    switch (name) {
+        case 'Bash': return { name: 'Bash', detail: cmd };
+        case 'Edit':
+        case 'Write':
+        case 'NotebookEdit': return { name: display, detail: path };
+        case 'Read': return { name: 'Read', detail: path };
+        case 'Grep':
+        case 'Glob': return { name: display, detail: pattern };
+        case 'WebFetch': return { name: 'WebFetch', detail: input.url };
+        case 'WebSearch': return { name: 'WebSearch', detail: input.query };
+        case 'Task': return { name: 'Task', detail: (input.description ?? input.subagent_type) };
+        default: return { name: display };
+    }
+}

package/dist/agents/codex.js

@@ -0,0 +1,207 @@
+/** Codex adapter: spawns `codex app-server` over UDS WebSocket; one thread/scope, streams turn events. */
+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();
+    constructor(clientVersion) {
+        this.clientVersion = clientVersion;
+    }
+    async start() {
+        await this.checkCodexInstalled();
+        try {
+            unlinkSync(SOCKET_PATH);
+        }
+        catch { /* missing is fine */ }
+        log.info({ socket: SOCKET_PATH }, 'codex agent: starting app-server');
+        this.daemon = spawn('codex', ['app-server', '--listen', `unix://${SOCKET_PATH}`], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let bootStderr = '';
+        let daemonExited = false;
+        let daemonExitCode = null;
+        this.daemon.stdout?.on('data', d => log.trace({ src: 'codex-stdout' }, String(d).trim()));
+        this.daemon.stderr?.on('data', (d) => { bootStderr += String(d); log.trace({ src: 'codex-stderr' }, String(d).trim()); });
+        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) {
+            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;
+    }
+    async createThread() {
+        const result = await this.call('thread/start', {});
+        log.info({ thread: result.thread.id }, 'codex agent: thread created');
+        return result.thread.id;
+    }
+    async sendTurn(threadId, text, callbacks) {
+        this.turnCallbacks.set(threadId, callbacks);
+        try {
+            /** `text_elements` is snake_case per codex's generated bindings. */
+            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)));
+        }
+    }
+    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`);
+    }
+    /** perMessageDeflate disabled: codex 0.130 closes connections offering it. */
+    async connect() {
+        const ws = new WebSocket('ws://localhost/', {
+            perMessageDeflate: false,
+            createConnection: () => {
+                const sock = createConnection({ path: SOCKET_PATH });
+                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', reject); });
+        ws.on('message', data => this.onMessage(data));
+        ws.on('close', () => { log.warn('codex agent: websocket closed'); this.ws = null; 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;
+        }
+        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)
+            return;
+        log.trace({ method: msg.method }, 'codex agent: notification');
+        const threadId = msg.params?.threadId;
+        if (!threadId)
+            return;
+        const cb = this.turnCallbacks.get(threadId);
+        if (!cb)
+            return;
+        if (msg.method === 'item/agentMessage/delta') {
+            cb.onDelta(msg.params.delta);
+        }
+        else if (msg.method === 'item/started') {
+            const a = summarizeItem(msg.params.item);
+            if (a)
+                cb.onToolStart(a);
+        }
+        else if (msg.method === 'item/completed') {
+            const item = msg.params.item;
+            if (item.type !== 'agentMessage' && item.type !== 'userMessage')
+                cb.onToolEnd(item.id, itemOutput(item));
+        }
+        else if (msg.method === 'thread/status/changed') {
+            /** codex 0.130: `thread/status=idle` is the dependable completion signal. */
+            const status = msg.params.status?.type;
+            if (status === 'idle') {
+                this.turnCallbacks.delete(threadId);
+                cb.onComplete();
+            }
+            else if (status === 'systemError') {
+                this.turnCallbacks.delete(threadId);
+                cb.onError(new Error('codex thread entered systemError'));
+            }
+        }
+        else if (msg.method === 'turn/completed') {
+            this.turnCallbacks.delete(threadId);
+            cb.onComplete();
+        }
+        else if (msg.method === 'error') {
+            this.turnCallbacks.delete(threadId);
+            cb.onError(new Error(msg.params.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 }));
+        });
+    }
+    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) {
+    const id = item.id;
+    if (item.type === 'commandExecution' && 'command' in item) {
+        return { id, kind: 'commandExecution', name: 'Bash', detail: item.command || undefined };
+    }
+    if (item.type === 'fileChange' && 'changes' in item) {
+        const paths = (item.changes ?? []).map(c => c.path).filter((p) => !!p);
+        return { id, kind: 'fileChange', name: 'Edit', detail: paths.length === 1 ? paths[0] : paths.length ? `${paths.length} files` : undefined };
+    }
+    if (item.type === 'reasoning')
+        return { id, kind: 'reasoning', name: 'Thinking…', transient: true };
+    if (item.type === 'agentMessage' || item.type === 'userMessage')
+        return null;
+    return { id, kind: item.type, name: item.type };
+}
+const itemOutput = (item) => item.type === 'commandExecution' && 'output' in item ? item.output?.trim() || undefined : undefined;

package/dist/agents/types.js

@@ -0,0 +1,2 @@
+/** Shared interface across agent backends (Codex, Claude Code). */
+export {};