@cosmovex/agentpager 0.1.0

package/dist/agents/claude.js

@@ -0,0 +1,279 @@
+// Claude Code through the official Agent SDK: resume the desk session by id, approvals via canUseTool.
+import { explainAgentError } from './explain.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { getSessionMessages, listSessions, query, } from '@anthropic-ai/claude-agent-sdk';
+import { findTranscript, spendOf } from '../guard/spend.js';
+import { classify, describe } from '../risk.js';
+import { SHELL, clip, withDeadline } from './types.js';
+const run = promisify(execFile);
+/** An async queue the SDK reads prompts from, so one live query takes many turns. */
+class PromptQueue {
+    items = [];
+    waiters = [];
+    ended = false;
+    push(text) {
+        const msg = {
+            type: 'user',
+            message: { role: 'user', content: text },
+            parent_tool_use_id: null,
+            origin: { kind: 'human' },
+        };
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value: msg, done: false });
+        else
+            this.items.push(msg);
+    }
+    end() {
+        this.ended = true;
+        for (const w of this.waiters.splice(0))
+            w({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const item = this.items.shift();
+                if (item)
+                    return Promise.resolve({ value: item, done: false });
+                if (this.ended)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+        };
+    }
+}
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('\n')
+        .trim();
+}
+/** Turn an SDK error code into something a person can act on. */
+function explainError(code) {
+    switch (code) {
+        case 'rate_limit':
+            return 'You have hit your plan usage limit. Work stops until the window resets.';
+        case 'overloaded':
+            return 'Anthropic is overloaded right now. This usually clears on its own — try again shortly.';
+        case 'billing_error':
+            return 'Billing problem on the account. Nothing will run until it is sorted.';
+        case 'authentication_failed':
+        case 'oauth_org_not_allowed':
+            return 'Claude Code is not signed in on that computer any more. Run `claude` there once to sign in.';
+        case 'account_on_hold':
+            return 'The Anthropic account is on hold.';
+        case 'verification_required':
+            return 'The account needs verification before it can run again.';
+        case 'max_output_tokens':
+            return 'The reply hit the maximum length and was cut off.';
+        case 'model_not_found':
+            return 'That model is not available to this account.';
+        case 'invalid_request':
+            return 'The agent rejected the request as malformed.';
+        case 'server_error':
+            return 'Anthropic returned a server error.';
+        default:
+            return `The agent stopped: ${code}.`;
+    }
+}
+export class ClaudeAgent {
+    id = 'claude';
+    name = 'Claude Code';
+    async status() {
+        const unavailable = { id: this.id, name: this.name, available: false, reason: 'Claude Code is not installed on this computer' };
+        return withDeadline((async () => {
+            const { stdout } = await run('claude', ['--version'], { timeout: 8000, killSignal: 'SIGKILL', shell: SHELL });
+            return { id: this.id, name: this.name, available: true, version: stdout.trim().split(' ')[0] };
+        })(), 9000, unavailable);
+    }
+    async list() {
+        const sessions = await listSessions({ limit: 40 });
+        return sessions.map((s) => ({
+            id: s.sessionId,
+            title: clip(s.customTitle || s.summary || s.firstPrompt || 'Untitled session', 120),
+            cwd: s.cwd,
+            updatedAt: s.lastModified,
+        }));
+    }
+    async usage(id) {
+        const path = findTranscript(id);
+        return path ? await spendOf(path) : null;
+    }
+    async history(id) {
+        const messages = await getSessionMessages(id);
+        const items = [];
+        for (const m of messages) {
+            if (m.parent_tool_use_id)
+                continue; // subagent chatter
+            const content = m.message?.content;
+            if (m.type === 'user') {
+                const text = textOf(content);
+                // Tool results arrive as user messages; they carry no text blocks.
+                if (text && !text.startsWith('<'))
+                    items.push({ role: 'user', text: clip(text, 4000) });
+            }
+            else if (m.type === 'assistant') {
+                const text = textOf(content);
+                if (text)
+                    items.push({ role: 'agent', text: clip(text, 4000) });
+                if (Array.isArray(content)) {
+                    for (const b of content) {
+                        if (b?.type === 'tool_use')
+                            items.push({ role: 'tool', text: `${b.name} ${describe(b.name, b.input ?? {}).detail}`.slice(0, 200) });
+                    }
+                }
+            }
+        }
+        return items.slice(-60);
+    }
+    async open(id, cwd, sink) {
+        const prompts = new PromptQueue();
+        const abort = new AbortController();
+        let lastText = '';
+        /** What the deltas have already sent for the message currently being written. */
+        let streamed = '';
+        const q = query({
+            prompt: prompts,
+            options: {
+                resume: id ?? undefined,
+                cwd,
+                // Tells the guard hook this session is driven from the phone, so it does not count as "you are
+                // at the desk" (src/guard/desk.ts).
+                env: { ...process.env, AGENTPAGER_BRIDGE: '1' },
+                abortController: abort,
+                // Behave exactly like the desk session: same settings, CLAUDE.md, permissions.
+                settingSources: ['user', 'project', 'local'],
+                // Without this the SDK only emits whole `assistant` messages, so the phone got the entire
+                // reply in one lump after a long silence — no different from a page load. Claude Code is the
+                // agent most people use here, so "live output" was untrue for exactly the headline case.
+                includePartialMessages: true,
+                // One suggestion per turn, after the result. Cheap, and it is the agent telling you what it
+                // thinks you should ask next — which on a phone keyboard is worth a lot more than on a desk.
+                promptSuggestions: true,
+                systemPrompt: { type: 'preset', preset: 'claude_code' },
+                canUseTool: async (tool, input, opts) => {
+                    const { summary, detail } = describe(tool, input);
+                    const answer = await sink.ask({ tool, summary, detail, risk: classify(tool, input) });
+                    if (answer.decision === 'deny') {
+                        return { behavior: 'deny', message: answer.message || 'Denied from AgentPager on the phone.' };
+                    }
+                    return {
+                        behavior: 'allow',
+                        updatedInput: input,
+                        updatedPermissions: answer.decision === 'allow_session' ? opts.suggestions : undefined,
+                    };
+                },
+            },
+        });
+        // The command list is a property of the session, not of any turn — fetch it once it exists.
+        void (async () => {
+            try {
+                const list = await q.supportedCommands?.();
+                if (Array.isArray(list) && list.length) {
+                    sink.commands(list.map((c) => ({
+                        name: String(c.name ?? ''),
+                        description: String(c.description ?? ''),
+                        argumentHint: String(c.argumentHint ?? ''),
+                    })));
+                }
+            }
+            catch {
+                /* an older CLI has no supportedCommands; the composer simply offers no autocomplete */
+            }
+        })();
+        (async () => {
+            try {
+                for await (const m of q) {
+                    const msg = m;
+                    if (msg.type === 'system' && msg.subtype === 'init' && msg.session_id) {
+                        sink.identified(msg.session_id);
+                    }
+                    else if (msg.type === 'system' && msg.subtype === 'session_state_changed') {
+                        sink.state(msg.state === 'requires_action' ? 'needs_you' : msg.state === 'running' ? 'running' : 'idle');
+                    }
+                    else if (msg.type === 'prompt_suggestion' || msg.subtype === 'prompt_suggestion') {
+                        const t = String(msg.suggestion ?? msg.text ?? msg.prompt ?? '').trim();
+                        if (t)
+                            sink.suggestion(t);
+                    }
+                    else if (msg.type === 'stream_event') {
+                        // The Messages API streaming events. Only text deltas matter to a phone; the block
+                        // start/stop bookkeeping is the hub's job, not ours.
+                        const ev = msg.event;
+                        if (ev?.type === 'content_block_delta' && ev.delta?.type === 'text_delta') {
+                            const piece = String(ev.delta.text ?? '');
+                            if (piece) {
+                                streamed += piece;
+                                sink.delta(piece);
+                            }
+                        }
+                    }
+                    else if (msg.type === 'assistant' && !msg.parent_tool_use_id) {
+                        const content = msg.message?.content;
+                        const text = textOf(content);
+                        if (text) {
+                            lastText = text;
+                            // Do NOT re-send what the deltas already delivered — that would print the reply twice.
+                            // The whole message still arrives here, so it remains the fallback whenever partial
+                            // events did not (older CLI, a provider that does not stream, partials turned off).
+                            if (streamed.trim() === text.trim())
+                                streamed = '';
+                            else
+                                sink.text(text);
+                        }
+                        if (Array.isArray(content)) {
+                            for (const b of content) {
+                                if (b?.type === 'tool_use')
+                                    sink.tool(b.name, describe(b.name, b.input ?? {}).detail);
+                            }
+                        }
+                    }
+                    else if (msg.type === 'assistant' && msg.error) {
+                        sink.error(explainError(String(msg.error)));
+                    }
+                    else if (msg.type === 'result') {
+                        streamed = '';
+                        // The one number people are desperate for. "I used up Max 5 in 1 hour of working,
+                        // before I could work 8 hours" — the agent knew all along; nothing told the phone.
+                        const rl = msg.rate_limits;
+                        if (msg.rate_limits_available && rl) {
+                            const win = (w) => (w ? { used: w.utilization ?? null, resetsAt: w.resets_at ?? null } : null);
+                            sink.limits({
+                                plan: msg.subscription_type ?? null,
+                                fiveHour: win(rl.five_hour),
+                                sevenDay: win(rl.seven_day),
+                            });
+                        }
+                        const ok = msg.subtype === 'success' && !msg.is_error;
+                        sink.done(ok, clip(String(msg.result ?? lastText ?? ''), 1200));
+                    }
+                }
+            }
+            catch (e) {
+                if (!abort.signal.aborted) {
+                    const x = explainAgentError(e, 'Claude Code');
+                    sink.error(x.message, x.code);
+                }
+            }
+        })();
+        return {
+            send: (text) => {
+                sink.state('running');
+                prompts.push(text);
+            },
+            interrupt: async () => {
+                await q.interrupt();
+            },
+            close: () => {
+                prompts.end();
+                abort.abort();
+            },
+        };
+    }
+}

package/dist/agents/codex.js

@@ -0,0 +1,271 @@
+// OpenAI Codex through `codex app-server` (JSON-RPC over stdio, one process for all threads).
+import { explainAgentError } from './explain.js';
+import { execFile, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { promisify } from 'node:util';
+import { classify, describe } from '../risk.js';
+import { SHELL, clip, killTree, withDeadline } from './types.js';
+const run = promisify(execFile);
+class Rpc {
+    proc;
+    nextId = 1;
+    pending = new Map();
+    onNotify = () => { };
+    onRequest = async () => {
+        throw new Error('unsupported');
+    };
+    onExit = () => { };
+    constructor() {
+        this.proc = spawn('codex', ['app-server'], { stdio: ['pipe', 'pipe', 'pipe'], shell: SHELL });
+        createInterface({ input: this.proc.stdout }).on('line', (line) => this.receive(line));
+        this.proc.stderr.on('data', () => { }); // app-server logs to stderr; not ours to surface
+        this.proc.on('exit', () => {
+            for (const p of this.pending.values())
+                p.reject(new Error('codex app-server exited'));
+            this.pending.clear();
+            this.onExit();
+        });
+    }
+    write(obj) {
+        this.proc.stdin.write(`${JSON.stringify(obj)}\n`);
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        this.write({ id, method, params });
+        return new Promise((resolve, reject) => this.pending.set(id, { resolve, reject }));
+    }
+    notify(method, params) {
+        this.write(params === undefined ? { method } : { method, params });
+    }
+    receive(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (msg.id !== undefined && msg.method) {
+            // A request from the server (approvals).
+            this.onRequest(msg.method, msg.params).then((result) => this.write({ id: msg.id, result }), (e) => this.write({ id: msg.id, error: { code: -32601, message: String(e?.message ?? e) } }));
+        }
+        else if (msg.id !== undefined) {
+            const p = this.pending.get(msg.id);
+            if (!p)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error)
+                p.reject(new Error(msg.error.message ?? 'codex error'));
+            else
+                p.resolve(msg.result);
+        }
+        else if (msg.method) {
+            this.onNotify(msg.method, msg.params);
+        }
+    }
+    kill() {
+        killTree(this.proc);
+    }
+}
+export class CodexAgent {
+    id = 'codex';
+    name = 'Codex';
+    rpc = null;
+    ready = null;
+    routes = new Map();
+    /// The session we most recently heard from, so a request we cannot place still reaches a human.
+    lastRoute;
+    async status() {
+        const unavailable = { id: this.id, name: this.name, available: false, reason: 'Codex CLI is not installed on this computer' };
+        return withDeadline((async () => {
+            const { stdout } = await run('codex', ['--version'], { timeout: 8000, killSignal: 'SIGKILL', shell: SHELL });
+            return { id: this.id, name: this.name, available: true, version: stdout.trim().split(' ').pop() };
+        })(), 9000, unavailable);
+    }
+    connect() {
+        if (this.ready)
+            return this.ready;
+        this.ready = (async () => {
+            const rpc = new Rpc();
+            rpc.onExit = () => {
+                this.rpc = null;
+                this.ready = null;
+                for (const r of this.routes.values())
+                    r.sink.error('Codex stopped on this computer.');
+                this.routes.clear();
+            };
+            rpc.onNotify = (method, params) => this.notification(method, params);
+            rpc.onRequest = (method, params) => this.serverRequest(method, params);
+            await rpc.request('initialize', { clientInfo: { name: 'mdpilot', title: 'AgentPager', version: '0.1.0' }, capabilities: null });
+            rpc.notify('initialized');
+            this.rpc = rpc;
+            return rpc;
+        })();
+        return this.ready;
+    }
+    async list() {
+        const rpc = await this.connect();
+        // The default source filter returns nothing on codex 0.138; name the kinds explicitly.
+        const res = await rpc.request('thread/list', { limit: 40, modelProviders: [], sourceKinds: ['cli', 'vscode', 'exec', 'appServer'] });
+        return (res?.data ?? [])
+            .filter((t) => !t.parentThreadId && !t.ephemeral)
+            .map((t) => ({
+            id: t.id,
+            title: clip(t.name || t.preview || 'Untitled thread', 120),
+            cwd: t.cwd,
+            updatedAt: (t.updatedAt ?? t.createdAt ?? 0) * 1000,
+        }));
+    }
+    async history(id) {
+        const rpc = await this.connect();
+        const res = await rpc.request('thread/read', { threadId: id, includeTurns: true });
+        const items = [];
+        for (const turn of res?.thread?.turns ?? []) {
+            for (const item of turn.items ?? []) {
+                if (item.type === 'userMessage') {
+                    const text = (item.content ?? []).filter((c) => c.type === 'text').map((c) => c.text).join('\n');
+                    if (text)
+                        items.push({ role: 'user', text: clip(text, 4000) });
+                }
+                else if (item.type === 'agentMessage' && item.text) {
+                    items.push({ role: 'agent', text: clip(item.text, 4000) });
+                }
+                else if (item.type === 'commandExecution') {
+                    items.push({ role: 'tool', text: clip(`shell ${item.command}`, 200) });
+                }
+                else if (item.type === 'fileChange') {
+                    items.push({ role: 'tool', text: clip(`edit ${(item.changes ?? []).map((c) => c.path).join(', ')}`, 200) });
+                }
+            }
+        }
+        return items.slice(-60);
+    }
+    async open(id, cwd, sink) {
+        const rpc = await this.connect();
+        const res = id ? await rpc.request('thread/resume', { threadId: id }) : await rpc.request('thread/start', { cwd: cwd ?? null });
+        const threadId = res.thread.id;
+        const created = { sink, lastText: '', files: new Map() };
+        this.routes.set(threadId, created);
+        this.lastRoute = created;
+        if (!id)
+            sink.identified(threadId);
+        return {
+            send: (text) => {
+                sink.state('running');
+                rpc.request('turn/start', { threadId, input: [{ type: 'text', text, text_elements: [] }] }).catch((e) => {
+                    const x = explainAgentError(e, 'Codex');
+                    sink.error(x.message, x.code);
+                });
+            },
+            interrupt: async () => {
+                const route = this.routes.get(threadId);
+                if (route?.turnId)
+                    await rpc.request('turn/interrupt', { threadId, turnId: route.turnId });
+            },
+            close: () => {
+                this.routes.delete(threadId);
+                rpc.request('thread/unsubscribe', { threadId }).catch(() => { });
+            },
+        };
+    }
+    notification(method, p) {
+        const route = p?.threadId ? this.routes.get(p.threadId) : undefined;
+        if (route)
+            this.lastRoute = route;
+        if (!route)
+            return;
+        switch (method) {
+            case 'turn/started':
+                route.turnId = p.turn?.id;
+                route.sink.state('running');
+                break;
+            case 'item/started':
+                if (p.item?.type === 'commandExecution')
+                    route.sink.tool('shell', clip(p.item.command ?? '', 500));
+                if (p.item?.type === 'fileChange')
+                    route.files.set(p.item.id, (p.item.changes ?? []).map((c) => c.path).join(', '));
+                break;
+            case 'item/completed':
+                // Whole messages only — streaming every token would multiply relay traffic for no one.
+                if (p.item?.type === 'agentMessage' && p.item.text) {
+                    route.lastText = p.item.text;
+                    route.sink.text(p.item.text);
+                }
+                else if (p.item?.type === 'fileChange') {
+                    route.sink.tool('edit', clip((p.item.changes ?? []).map((c) => c.path).join(', '), 500));
+                }
+                break;
+            case 'turn/completed': {
+                const status = p.turn?.status;
+                route.turnId = undefined;
+                route.sink.done(status === 'completed', clip(p.turn?.error?.message ?? route.lastText, 1200));
+                break;
+            }
+            case 'thread/tokenUsage/updated': {
+                // Cumulative for the thread. Codex reports tokens, not dollars, and a plan user has no
+                // per-token price — so tokens only; the hub will not invent a figure.
+                const total = Number(p.tokenUsage?.total?.totalTokens ?? p.usage?.total?.totalTokens);
+                if (Number.isFinite(total) && total > 0)
+                    route.sink.usage({ tokens: total });
+                break;
+            }
+            case 'error':
+                {
+                    const x = explainAgentError(p.error?.message ?? p.message ?? 'Codex error', 'Codex');
+                    route.sink.error(x.message, x.code);
+                }
+                break;
+        }
+    }
+    async serverRequest(method, p) {
+        // Attribute an approval to a session ONLY when that is unambiguous. A card that says "this
+        // session needs your OK" under the wrong session buys consent for something the user never saw;
+        // refusing and saying so is the honest failure.
+        const route = p?.threadId
+            ? this.routes.get(p.threadId)
+            : this.routes.size === 1
+                ? [...this.routes.values()][0]
+                : undefined;
+        if (method === 'item/commandExecution/requestApproval' || method === 'item/fileChange/requestApproval') {
+            if (!route)
+                return this.cannotAsk(method);
+            const isShell = method.includes('commandExecution');
+            const paths = route.files.get(p.itemId) ?? '';
+            const input = isShell ? { command: p.command ?? '' } : { file_path: paths.split(', ')[0] ?? '', detail: paths || p.reason || 'File changes' };
+            const tool = isShell ? 'shell' : 'edit';
+            const { summary, detail } = describe(tool, input);
+            const answer = await route.sink.ask({ tool, summary: p.reason ? clip(p.reason, 120) : summary, detail, risk: classify(tool, input) });
+            return { decision: answer.decision === 'allow' ? 'accept' : answer.decision === 'allow_session' ? 'acceptForSession' : 'decline' };
+        }
+        // 🧨 This used to answer "decline" to every approval it did not recognise, WITHOUT telling
+        // anyone. The agent then stopped mid-task and the phone was never paged, so from the user's side
+        // it was indistinguishable from the agent simply failing — and Codex's app-server keeps renaming
+        // these methods, so one upstream rename turns the product into "denies everything".
+        // Now an unfamiliar approval is still a question: ask, at the highest friction, and say plainly
+        // that we don't recognise it.
+        if (method.endsWith('requestApproval') || method.endsWith('Approval')) {
+            if (!route)
+                return this.cannotAsk(method);
+            const what = String(p?.command ?? p?.reason ?? p?.path ?? p?.itemId ?? '');
+            const answer = await route.sink.ask({
+                tool: method.split('/').pop() ?? method,
+                summary: `Codex is asking for something this app does not recognise (${method})`,
+                detail: clip(what || JSON.stringify(p ?? {}), 1200),
+                risk: 'danger', // unknown means unknown: it takes a press-and-hold, never a stray tap
+            });
+            return { decision: answer.decision === 'deny' ? 'decline' : answer.decision === 'allow_session' ? 'acceptForSession' : 'accept' };
+        }
+        throw new Error(`unsupported request ${method}`);
+    }
+    /// An approval we cannot attach to any session. We must not silently answer for the user, so we
+    /// decline — but we say so, loudly, where they will see it.
+    cannotAsk(method) {
+        const message = `Codex asked for approval (${method}) on a session this app has lost track of, so it was declined. Reopen the session on your phone and try again.`;
+        console.error(message);
+        this.lastRoute?.sink.error(message);
+        return { decision: 'decline' };
+    }
+    shutdown() {
+        this.rpc?.kill();
+    }
+}

package/dist/agents/explain.js

@@ -0,0 +1,39 @@
+// One plain sentence a person can act on, from whatever text an agent CLI threw.
+//
+// Claude Code reports machine-readable error codes and claude.ts turns those into sentences. Codex
+// and the ACP agents (Gemini CLI, OpenCode, Qwen Code, Goose…) mostly just hand us a message
+// string, so this matches on the text. The codes stay machine-readable for the app; the message is
+// the sentence. Unknown text is passed through, clipped, rather than replaced by something vague.
+import { clip } from './types.js';
+// Order matters: the most specific / most actionable first. "401 Unauthorized" is an auth problem
+// even though it also contains a number; "connection timed out" is a network problem, not a timeout.
+const RULES = [
+    ['quota', /\b429\b|rate[\s_-]?limit|quota|usage limit|resource[_\s]exhausted|too many requests|insufficient[\s_](credit|fund|balance|quota)|out of (credits|tokens)|billing|exceeded your (current )?(plan|limit)|credit balance/i],
+    ['not_signed_in', /not (logged|signed)[\s-]?in|please (log ?in|sign ?in)|log ?in (required|first)|sign[\s-]?in (required|first)|\b401\b|unauthori[sz]ed|invalid (api[\s_-]?key|token|credentials)|api[\s_-]?key.{0,30}(missing|not set|not found|required|invalid|expired)|(missing|no|expired) (api[\s_-]?key|credentials|token)|authentication (failed|required|error)|(OPENAI|GEMINI|GOOGLE|ANTHROPIC|QWEN|DASHSCOPE|DEEPSEEK)_API_KEY|token (has )?expired|refresh token|\b403\b.{0,40}(forbidden|permission)/i],
+    ['model_not_found', /model[^.\n]{0,60}(not found|not available|does not exist|not supported|unsupported|unknown|no access|access denied)|(unknown|invalid|unsupported|unavailable) model|\b404\b[^.\n]{0,40}model/i],
+    ['not_installed', /\bENOENT\b|command not found|is not recognized as an internal|not recognized as the name of a cmdlet|no such file or directory.{0,40}(spawn|exec)|spawn [^\n]{0,60}(ENOENT|EINVAL)|not installed|executable (file )?not found/i],
+    ['protocol', /protocol version|unsupported protocol|incompatible (version|protocol)|method not found|unsupported request|unknown method|\-32601|\-32602|invalid params|invalid request|unexpected (token|end of json|response)|json parse|parse error|malformed|unsupported (version|capability)|initialize.{0,40}(fail|reject)/i],
+    ['network', /ENOTFOUND|ECONNREFUSED|ECONNRESET|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|EPIPE|network|fetch failed|socket hang up|getaddrinfo|unable to connect|connection (refused|reset|closed|timed out|error|lost)|offline|self[\s-]signed|certificate|\bproxy\b|\b50[234]\b|bad gateway|service unavailable|gateway time-?out|overloaded|temporarily unavailable/i],
+    ['timeout', /timed?[\s-]?out|timeout|deadline (exceeded|has passed)|did not (answer|respond)|no response/i],
+];
+const SAYS = {
+    not_signed_in: (n) => `${n} is not signed in on that computer any more. Open ${n} there once, sign in, then try again.`,
+    quota: (n) => `${n} has hit a usage or rate limit (or the account is out of credit). Wait for the window to reset, or check the plan and billing.`,
+    model_not_found: (n) => `${n} says that model is not available to this account. Pick another model in ${n}'s settings on that computer.`,
+    not_installed: (n) => `${n} could not be started on that computer — it is missing or not on the PATH. Install it or run \`agentpager doctor\` there.`,
+    network: (n) => `${n} could not reach its servers. Check that computer's internet connection (or proxy) and try again; this often clears on its own.`,
+    protocol: (n) => `${n} answered in a way this version of AgentPager does not understand — usually the agent was updated. Update AgentPager on that computer (\`npm update -g agentpager\`).`,
+    timeout: (n) => `${n} took too long to answer and the request timed out. Try again; if it keeps happening, restart ${n} on that computer.`,
+};
+/**
+ * `raw` is whatever the agent said; `name` is how the person knows it ("Codex", "Gemini CLI").
+ * Never throws, never returns an empty message.
+ */
+export function explainAgentError(raw, name) {
+    const text = String(raw?.message ?? raw ?? '').trim();
+    for (const [code, re] of RULES) {
+        if (re.test(text))
+            return { code, message: SAYS[code](name) };
+    }
+    return { code: 'agent', message: text ? `${name} reported a problem: ${clip(text.replace(/\s+/g, ' '), 300)}` : `${name} stopped without saying why.` };
+}

package/dist/agents/types.js

@@ -0,0 +1,29 @@
+import { execFile } from 'node:child_process';
+/**
+ * A version probe must never hang the bridge. execFile's own timeout kills the child, but the
+ * promise still waits for grandchildren to close the pipes — which is how the login service hung
+ * with no output at all. Race it and move on.
+ */
+export function withDeadline(p, ms, fallback) {
+    return Promise.race([
+        p.catch(() => fallback),
+        new Promise((resolve) => setTimeout(() => resolve(fallback), ms).unref?.()),
+    ]);
+}
+/**
+ * npm installs CLIs on Windows as `.cmd` shims, which spawn/execFile cannot start without a shell
+ * (ENOENT, or EINVAL on current Node). Elsewhere a shell would only add quoting risk.
+ */
+export const SHELL = process.platform === 'win32';
+/** With a shell in between, kill() only ends the shell; taskkill /T takes the agent under it too. */
+export function killTree(proc) {
+    if (SHELL && proc.pid) {
+        try {
+            execFile('taskkill', ['/pid', String(proc.pid), '/T', '/F'], () => { });
+            return;
+        }
+        catch { }
+    }
+    proc.kill();
+}
+export const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);