handmux 0.29.2 → 0.31.0

package/dist/src/agents/codebuddyPaneInput.js

@@ -0,0 +1,76 @@
+// CodeBuddy's pane input: the delivery and interrupt semantics for its TUI. The mechanics are shared
+// (paneInput.ts owns the per-pane critical section, the text+submit gap and the one-line editor reader);
+// what is CodeBuddy's is the editor's own shape and the keys its keybindings document.
+//
+// Measured on 2.156.0, its editor is the same one-line box Claude draws, with `>` as the prompt and a
+// right-aligned `↵ send` footer painted inside the same line once there is draft text:
+//
+//     ────────────────────────────────────────────────
+//     > 检查文件是否创建成功                            ↵ send
+//     ────────────────────────────────────────────────
+//     ? for shortcuts  ← for agents
+//
+// With no draft text the capture arrives as the bare `>`: the plain space CodeBuddy paints after its prompt
+// is a trailing blank, which `capture-pane` drops (Claude's non-breaking space survives). The reader treats
+// that as the empty editor it is — see `singleLineDraft`. The distinction matters downstream: the same line
+// is what a cleared editor looks like, so reading it as unrecognizable refused both the send itself and the
+// check that our own stale prompt had been cleared.
+//
+// Interrupt is `esc`: the pane's own footer says so (`✹ Buzzing… (esc to interrupt)`) and Escape really does
+// stop it — measured, see `interruptAgentPane` in paneInput.ts. CodeBuddy's published keybindings list
+// `ctrl+c → app:interrupt` (ctrl+d is exit); sending that one mid-tool did nothing at all.
+import { describeEditorArea, serializePaneInput, singleLineDraft } from '../paneInput.js';
+const SUBMIT_GAP_MS = 120;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// The footer the editor paints at the right edge of the draft line. Stripped before the draft is judged,
+// so `> draft  ↵ send` reads as `draft` while the footer itself can never be mistaken for typed text.
+const EDITOR_HINT_RE = /[\s\u00a0]*↵\s*\S+[\s\u00a0]*$/;
+export function codebuddySingleLineDraft(screen, cursor) {
+    return singleLineDraft(screen, cursor, '>', EDITOR_HINT_RE);
+}
+// Send a prompt the way the composer means it: replace only a draft this pane is KNOWN to own (the prompt
+// we restored from the run's own submission) and never a draft a human typed — that is a refusal the caller
+// can surface, not a silent deletion. Anything the reader cannot recognize refuses too.
+export function sendCodeBuddyPanePrompt(commands, paneId, text, restoredPrompt, guard, reportUnreadable) {
+    return serializePaneInput(paneId, async () => {
+        if (guard && !await guard.validate())
+            return { nativeMutation: false };
+        await commands.exitCopyModeIfActive(paneId);
+        await commands.sendKey(paneId, 'End');
+        await delay(SUBMIT_GAP_MS);
+        const readEditor = async () => {
+            const screen = await commands.capturePlain(paneId);
+            const cursor = await commands.paneInfo(paneId);
+            return { screen, cursor, draft: codebuddySingleLineDraft(screen, cursor) };
+        };
+        const draft = await readEditor();
+        if (draft.draft === null) {
+            // Unreadable: record the shape, never the text we could not read (see describeEditorArea).
+            reportUnreadable?.(describeEditorArea(draft.screen, draft.cursor));
+            return { nativeMutation: false, reason: 'terminal_draft_conflict' };
+        }
+        if (draft.draft !== '' && draft.draft !== restoredPrompt()) {
+            return { nativeMutation: false, reason: 'terminal_draft_conflict' };
+        }
+        if (guard && !await guard.validate())
+            return { nativeMutation: false };
+        if (draft.draft) {
+            // Clear our own stale prompt. The key is unverified against a live CodeBuddy editor (its published
+            // keybindings cover app-level keys only), so the result is verified before anything is sent — a
+            // binding that does not clear leaves us refusing, never appending to unseen text.
+            await commands.sendKey(paneId, 'C-u');
+            await delay(SUBMIT_GAP_MS);
+            const cleared = await readEditor();
+            if (cleared.draft !== '') {
+                if (cleared.draft === null)
+                    reportUnreadable?.(describeEditorArea(cleared.screen, cleared.cursor));
+                return { nativeMutation: false, reason: 'terminal_draft_conflict' };
+            }
+        }
+        await commands.sendText(paneId, text);
+        if (text)
+            await delay(SUBMIT_GAP_MS);
+        await commands.sendEnter(paneId);
+        return { nativeMutation: true };
+    });
+}

package/dist/src/agents/codebuddyTranscriptParse.js

@@ -0,0 +1,178 @@
+const record = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null);
+// A bare slash command (`/compact`, `/clear`, `/model sonnet`) is logged as an ordinary user turn. It IS
+// part of the conversation, so it becomes a quiet 'slash' marker instead of a prominent bubble. Anchored to
+// a single leading lowercase command token followed by whitespace/EOL, so "/Users/demo/foo.js" (uppercase,
+// then a path separator) and prose mentioning a path are never eaten.
+const SLASH_CMD_RE = /^\s*\/([a-z][\w-]*)(?:\s+([\s\S]*?))?\s*$/i;
+// The compaction summary wrapper: `<cb_summary>` / `<conversation_history_summary>` around the real text.
+const SUMMARY_WRAP_RE = /^\s*<(?:cb_summary|conversation_history_summary)>([\s\S]*?)(?:<\/(?:cb_summary|conversation_history_summary)>)?\s*$/i;
+const SUMMARY_LEAD_RE = /^\s*Summary(?: of the conversation so far)?:\s*/i;
+const SUMMARY_CAP = 4_096;
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+// The record's wall-clock, in the ISO form the shared model carries. CodeBuddy logs epoch milliseconds
+// (Claude logs an ISO string), and a record without a usable one simply gets no time.
+function isoTime(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return undefined;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+// `arguments` is a JSON STRING (measured). Parse it so the projection can sanitize a real object; an
+// unparsable payload is passed through as the raw string rather than dropped — a tool call the user cannot
+// see is worse than one whose arguments are opaque.
+function toolInput(value) {
+    if (typeof value !== 'string')
+        return value ?? {};
+    const trimmed = value.trim();
+    if (!trimmed)
+        return {};
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+}
+function contentText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value))
+        return '';
+    return value
+        .map(record)
+        .filter((block) => block !== null)
+        .map((block) => text(block.text))
+        .join('');
+}
+export function createCodeBuddyTranscriptParser() {
+    const messages = [];
+    const pending = new Map();
+    let i = 0;
+    function push(lines) {
+        for (const raw of lines) {
+            const line = typeof raw === 'string' ? raw.trim() : '';
+            if (!line) {
+                i++;
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                i++;
+                continue;
+            }
+            const row = record(parsed);
+            const type = text(row?.type);
+            if (!row || !type) {
+                i++;
+                continue;
+            }
+            const provider = record(row.providerData) ?? {};
+            const ts = isoTime(row.timestamp);
+            const index = i;
+            if (type === 'message') {
+                if (provider.isMeta === true || provider.skipRun === true || provider.isPartialAborted === true) {
+                    i++;
+                    continue;
+                }
+                const role = row.role === 'user' ? 'user' : row.role === 'assistant' ? 'assistant' : null;
+                if (!role) {
+                    i++;
+                    continue;
+                }
+                const body = contentText(row.content);
+                if (provider.isCompacted === true || provider.isSummary === true) {
+                    // A compaction happened here. Keep the divider (the 对话 lens shows "上下文已压缩"), cap the text.
+                    const wrapped = SUMMARY_WRAP_RE.exec(body);
+                    const summary = (wrapped?.[1] ?? body).replace(SUMMARY_LEAD_RE, '').trim();
+                    const message = { i, type: 'compact', ts };
+                    if (summary) {
+                        message.summary = summary.length > SUMMARY_CAP ? summary.slice(0, SUMMARY_CAP - 1) + '…' : summary;
+                        if (summary.length > SUMMARY_CAP) {
+                            message.summaryTruncated = true;
+                            message.summaryOriginalBytes = Buffer.byteLength(summary, 'utf8');
+                        }
+                    }
+                    messages.push(message);
+                    i++;
+                    continue;
+                }
+                // The synthetic "continue from the summary" prompt is not a human turn.
+                if (provider.isCompactInternal === true) {
+                    i++;
+                    continue;
+                }
+                if (role === 'user') {
+                    const command = SLASH_CMD_RE.exec(body);
+                    if (command?.[1]) {
+                        const message = { i, type: 'slash', name: `/${command[1]}`, ts };
+                        if (command[2]?.trim())
+                            message.args = command[2].trim();
+                        messages.push(message);
+                        i++;
+                        continue;
+                    }
+                }
+                if (!body.trim()) {
+                    i++;
+                    continue;
+                }
+                const message = { i, type: 'text', role, text: body, ts };
+                messages.push(message);
+                i++;
+                continue;
+            }
+            if (type === 'reasoning') {
+                // Only the provider's PUBLIC projection; `rawContent` is the raw chain of thought.
+                const reasoning = contentText(row.content).trim();
+                if (reasoning) {
+                    const message = { i, type: 'thinking', role: 'assistant', text: reasoning, ts };
+                    messages.push(message);
+                }
+                i++;
+                continue;
+            }
+            if (type === 'function_call') {
+                const tool = {
+                    name: text(row.name),
+                    input: toolInput(row.arguments),
+                    result: null,
+                    isError: false,
+                };
+                const message = {
+                    i, type: 'tool', role: 'assistant', ts, tool,
+                };
+                const callId = text(row.callId);
+                if (callId)
+                    pending.set(callId, message);
+                messages.push(message);
+                i++;
+                continue;
+            }
+            if (type === 'function_call_result') {
+                const message = pending.get(text(row.callId));
+                if (message) {
+                    const result = record(row.providerData);
+                    const toolResult = record(result?.toolResult);
+                    const output = record(row.output);
+                    const body = text(output?.text) || text(toolResult?.content);
+                    message.tool.result = body;
+                    // `status` is the provider's own verdict (measured: 'completed'); an `error` on the tool result
+                    // is the same fact stated a second way. Either one marks the failure.
+                    message.tool.isError = (text(row.status) !== 'completed' && text(row.status) !== '')
+                        || toolResult?.error !== undefined;
+                    pending.delete(text(row.callId));
+                }
+                i++;
+                continue;
+            }
+            i++;
+        }
+        return messages;
+    }
+    return { push, messages };
+}

package/dist/src/agents/hookEvents.js

@@ -0,0 +1,143 @@
+// The shared Hook-event layer. Claude Code and CodeBuddy both drive Handmux through filesystem Hooks, and
+// CodeBuddy's Hook protocol is Claude Code's: the same `src` argument convention, the same raw payload on
+// stdin, and the same JSON latest-state file plus bounded durable spool written by the SHARED
+// server/hooks/handmux-write.cjs. So the two things those providers genuinely have in common live here:
+//
+//   1. the lifecycle VOCABULARY every Hook-driven Inbox state is normalized into;
+//   2. the on-disk RECORD FORMAT (state row, spool event, owning-process fingerprint).
+//
+// What stays per-Agent — and therefore does NOT live here — is which `src` string means what, which payload
+// fields carry the message, and how a pane proves the Agent is still its foreground process. Those are
+// product facts and belong with the provider (agents/claude.ts, codebuddyEvents.ts).
+import fs from 'node:fs';
+const EVENT_KINDS = new Set([
+    'done', 'working', 'permission', 'compacting', 'error', 'end', 'idle',
+]);
+// Validate an untrusted kind string against the shared vocabulary.
+export function hookEventKind(value) {
+    return typeof value === 'string' && EVENT_KINDS.has(value)
+        ? value : null;
+}
+// A normalized kind → the Inbox state the Core understands, or null when it carries no state at all
+// (`end`/`idle`/unknown). Compacted work is still work; a permission gate is waiting on the user.
+export function canonicalInboxState(kind) {
+    if (kind === 'working' || kind === 'compacting')
+        return 'working';
+    if (kind === 'permission')
+        return 'waiting';
+    if (kind === 'done')
+        return 'done';
+    if (kind === 'error')
+        return 'error';
+    return null;
+}
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const bounded = (value, max) => typeof value === 'string' && value.length > 0 && value.length <= max;
+// ---------------------------------------------------------------------------------------------
+// On-disk format shared with server/hooks/handmux-write.cjs
+// ---------------------------------------------------------------------------------------------
+export const HOOK_EVENT_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,255}$/;
+export function parseHookProcessFingerprint(value) {
+    if (!isRecord(value) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0
+        || typeof value.startedAt !== 'number' || !Number.isFinite(value.startedAt)
+        || value.startedAt < 0 || !bounded(value.tty, 1024))
+        return null;
+    return { pid: Number(value.pid), startedAt: value.startedAt, tty: value.tty };
+}
+export function normalizedTty(value) {
+    if (!value)
+        return undefined;
+    return value.startsWith('/dev/') ? value : `/dev/${value}`;
+}
+// An absent fingerprint is accepted: it is the additive field of a newer writer, and records produced by an
+// older installed Hook must keep working.
+export function matchesHookProcess(source, current) {
+    if (!source)
+        return true;
+    return source.pid === current.pid
+        && source.startedAt === current.startedAt
+        && normalizedTty(source.tty) === normalizedTty(current.tty);
+}
+// `acceptAgent` decides which provider's marking a row may carry: an absent `agent` is always legacy
+// compatibility, and every explicit foreign marking must fail closed rather than borrow another Agent's state.
+export function readHookStateRows(file, acceptAgent) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (!isRecord(value))
+            return new Map();
+        return new Map(Object.entries(value).flatMap(([paneId, raw]) => {
+            const row = isRecord(raw) ? raw : null;
+            const payload = isRecord(row?.payload) ? row.payload : null;
+            if (!bounded(paneId, 256) || !row || !payload || !bounded(row.src, 64)
+                || (row.agent !== undefined && !acceptAgent(row.agent)))
+                return [];
+            const ts = typeof row.ts === 'number' && Number.isFinite(row.ts) ? row.ts : 0;
+            const sequence = Number.isSafeInteger(row.sequence) && Number(row.sequence) > 0
+                ? Number(row.sequence) : undefined;
+            const process = row.process === undefined ? undefined : parseHookProcessFingerprint(row.process);
+            if (process === null)
+                return [];
+            return [[paneId, {
+                        ts,
+                        src: row.src,
+                        ...(typeof row.agent === 'string' ? { agent: row.agent } : {}),
+                        payload,
+                        ...(sequence === undefined ? {} : { sequence }),
+                        ...(process === undefined ? {} : { process }),
+                    }]];
+        }));
+    }
+    catch {
+        return new Map();
+    }
+}
+export function parseHookBridgeEvent(value, acceptAgent) {
+    if (!isRecord(value) || value.version !== 1 || (value.type !== 'event' && value.type !== 'gap')
+        || (value.agent !== undefined && !acceptAgent(value.agent))
+        || !bounded(value.eventId, 256) || !HOOK_EVENT_ID_RE.test(value.eventId)
+        || !bounded(value.paneId, 256)
+        || (value.sequence !== undefined && (!Number.isSafeInteger(value.sequence) || Number(value.sequence) <= 0))
+        || (value.src !== undefined && !bounded(value.src, 64))
+        || (value.sessionId !== undefined && !bounded(value.sessionId, 1024))
+        || (value.sourceOccurredAt !== undefined
+            && (typeof value.sourceOccurredAt !== 'number' || !Number.isFinite(value.sourceOccurredAt)))
+        || (value.process !== undefined && parseHookProcessFingerprint(value.process) === null)
+        || (value.payload !== undefined && !isRecord(value.payload)))
+        return null;
+    return {
+        ...value,
+        ...(value.process === undefined ? {} : { process: parseHookProcessFingerprint(value.process) }),
+    };
+}
+// The durable source sequence embedded in a spool event ID (`<agent>-hook-<n>`). The writer is shared, so
+// this deliberately reads the suffix rather than pinning one Agent's prefix: the prefix is the writer's
+// choice, not a contract this reader may tighten.
+export function hookEventSequence(eventId) {
+    const match = /^[a-z][a-z0-9-]*-hook-([1-9]\d*)$/.exec(eventId);
+    if (!match)
+        return null;
+    const sequence = Number(match[1]);
+    return Number.isSafeInteger(sequence) ? sequence : null;
+}
+// Friendly Chinese for an API-error turn end. The payload shape for a StopFailure is not verified against
+// every provider, so read the type defensively from several likely fields and always fall back to a bare
+// 本轮出错 — a wrong field name degrades to the generic label, never throws.
+const ERROR_LABEL = {
+    rate_limit: '触发限流', overloaded: '服务过载', authentication_failed: '认证失败',
+    oauth_org_not_allowed: '组织未授权', billing_error: '额度/账单问题', invalid_request: '请求无效',
+    model_not_found: '模型不可用', server_error: '服务端错误', max_output_tokens: '输出超长', unknown: '未知错误',
+};
+export function hookErrorMessage(body) {
+    const error = isRecord(body.error) ? body.error : null;
+    const type = typeof body.error_type === 'string' ? body.error_type
+        : typeof body.reason === 'string' ? body.reason
+            : typeof body.type === 'string' ? body.type
+                : typeof body.error === 'string' ? body.error
+                    : typeof error?.type === 'string' ? error.type : '';
+    const label = ERROR_LABEL[type];
+    if (label)
+        return label;
+    const raw = typeof body.error === 'string' ? body.error
+        : typeof body.message === 'string' ? body.message : '';
+    return raw ? raw.replace(/\s+/g, ' ').trim().slice(0, 80) : '';
+}

package/dist/src/agents/hookInteraction.js

@@ -0,0 +1,178 @@
+// The pending-interaction adapter shared by the Hook-driven Agents (Claude, CodeBuddy). Their TUIs are the
+// same one-line-editor lineage, so the prompts they put on screen have the same shape — a cursor-marked
+// numbered option list with a description row under an option — and they parse with the SAME
+// `parsePendingPrompt`. What differs is the KEYSTROKE that picks an option, and that turns out to depend on
+// the SCREEN rather than on the provider — so both bind one shared sender (paneInput.sendPaneMenuChoice):
+//
+//   question menu    a digit only MOVES the highlight. Measured live on CodeBuddy 2.156.0, whose picker
+//                    ignores the digit outright (the highlight does not budge); and read out of Claude
+//                    Code's own bundle (2.1.278), where `1`–`9` go through the same `nme` that ↑/↓ call
+//                    while only the `return` branch commits. Answering therefore means walking to the
+//                    option and pressing Enter — on both providers.
+//   permission gate  the digit commits: measured on CodeBuddy, where a `1` approved a command that really
+//                    ran. It is also the safer key there — it names the row instead of stepping to it, so a
+//                    misread cursor cannot commit a different answer than the user tapped.
+//
+// A provider supplies its own naming (the ids the phone stores and the fallback wording a user reads);
+// everything else is the shared contract. Where a provider's wording is NOT verifiable — a permission gate
+// whose screen shows no options — the adapter emits a `local_only` prompt with no options rather than
+// guessing what the buttons mean.
+import { createHash } from 'node:crypto';
+import { parsePendingPrompt } from '../pendingPrompt.js';
+// A pane that is mid-turn says so on its own screen: both providers print the interrupt hint while the model
+// or a tool is running — `✹ Buzzing… (esc to interrupt)`, measured on CodeBuddy 2.156.0, and Claude prints the
+// same hint. A gate that is really up cannot be mid-turn; the pane is blocked ON the gate. So this is what
+// keeps the no-options fallback quiet in the one window where its `permreq` row is stale by construction:
+// CodeBuddy fires no Hook when a gate is answered, so an approved tool keeps its row (and the roster at 需要你)
+// until the turn's next Hook — measured on pane %211, where an approved `sleep 90` said 需要你授权：Bash for the
+// whole minute while the tool ran, and the fallback turned that into a 去终端 card nothing was waiting for.
+const INTERRUPT_HINT_RE = /esc to interrupt/i;
+function normalizedPrompt(text, provider, pendingKind) {
+    const prompt = parsePendingPrompt(text);
+    if (!prompt) {
+        if (pendingKind !== 'permission' || INTERRUPT_HINT_RE.test(text))
+            return null;
+        const tail = text.split('\n').map((line) => line.trim()).filter(Boolean).slice(-3).join('\n');
+        const promptText = tail.slice(0, 2_000) || `${provider.label} is waiting for permission in the terminal.`;
+        const id = `${provider.id}-permission:${createHash('sha256').update(promptText).digest('hex').slice(0, 24)}`;
+        return {
+            id, type: 'local_only', prompt: promptText,
+        };
+    }
+    // The card must survive a re-render. The parse carries two volatile pieces: `cursor`, which moves whenever
+    // anyone navigates the menu, and the lead-in prose above the question, which the turn retypes as it streams.
+    // Hashing the whole parse therefore minted a NEW card whenever either changed, retiring the live one as
+    // "resolved" while its gate was still on screen — so an answer could be swallowed AND its card taken away
+    // (measured: a user's answer to a live question was accepted by the server and never reached the pane).
+    // Identify the gate by what IS the gate: the menu kind, its own question line, and the options offered.
+    //
+    // The price of a shape-named id is that two DIFFERENT gates of the same shape carry the same id — every
+    // review screen, for one. That is Core's problem to tell apart, and it does: a shape that comes back after
+    // its card was settled is published as a new interaction with a new id and token, never silently dropped.
+    // So this id must stay shape-stable within one occurrence and must NOT try to encode an instance number,
+    // which this adapter cannot know (a fresh observation has no memory of what it saw before).
+    const signature = JSON.stringify({
+        kind: prompt.kind,
+        question: prompt.title.split(' — ').at(-1) ?? prompt.title,
+        options: prompt.options.map((option) => option.label),
+        submit: prompt.submit === true,
+    });
+    const id = `${provider.id}-prompt:${createHash('sha256').update(signature).digest('hex').slice(0, 24)}`;
+    return {
+        id,
+        type: 'select',
+        prompt: prompt.leadIn ? `${prompt.leadIn}\n${prompt.title}` : prompt.title,
+        options: prompt.options.map((option) => ({
+            id: `choice:${option.n}`,
+            label: option.description ? `${option.label} — ${option.description}` : option.label,
+        })),
+    };
+}
+export function createHookInteractionAdapter(control, provider, pollMs = 750, reportHealth = () => { }) {
+    if (!control || typeof control.capturePlain !== 'function'
+        || typeof control.sendChoice !== 'function' || !Number.isFinite(pollMs) || pollMs <= 0) {
+        throw new TypeError('Interaction adapter requires pane capture and choice control');
+    }
+    const active = new Map();
+    return {
+        apiVersion: 1,
+        async observeNative(run, sink) {
+            let closed = false;
+            let cursor = 0;
+            let pending = normalizedPrompt(await control.capturePlain(run.ref.paneId), provider, control.pendingKind?.(run.ref.paneId));
+            let timer;
+            let tail = Promise.resolve();
+            let failures = 0;
+            const binding = { run, pending };
+            active.set(run.ref.runId, binding);
+            const close = () => {
+                closed = true;
+                if (timer)
+                    clearTimeout(timer);
+                timer = undefined;
+                if (active.get(run.ref.runId) === binding)
+                    active.delete(run.ref.runId);
+            };
+            const schedule = (delay = pollMs) => {
+                if (closed || run.signal.aborted)
+                    return;
+                timer = setTimeout(() => {
+                    tail = tail.then(async () => {
+                        if (closed || run.signal.aborted)
+                            return;
+                        const next = normalizedPrompt(await control.capturePlain(run.ref.paneId), provider, control.pendingKind?.(run.ref.paneId));
+                        if (failures > 0)
+                            reportHealth('ready');
+                        failures = 0;
+                        if (pending?.id === next?.id)
+                            return;
+                        if (pending)
+                            await sink({
+                                type: 'resolved', sourceCursor: `${provider.id}-interaction:${++cursor}`,
+                                interactionId: pending.id,
+                            });
+                        pending = next;
+                        binding.pending = next;
+                        if (next)
+                            await sink({
+                                type: 'opened', sourceCursor: `${provider.id}-interaction:${++cursor}`, interaction: next,
+                            });
+                    }).catch(async () => {
+                        failures += 1;
+                        if (failures >= 2) {
+                            reportHealth('degraded', 'Interaction polling is temporarily unavailable');
+                            if (pending) {
+                                const abandoned = pending;
+                                pending = null;
+                                binding.pending = null;
+                                await Promise.resolve(sink({
+                                    type: 'cancelled', sourceCursor: `${provider.id}-interaction:${++cursor}`,
+                                    interactionId: abandoned.id, reason: 'temporarily_unavailable',
+                                })).catch(close);
+                            }
+                        }
+                    }).finally(() => schedule(Math.min(10_000, pollMs * (2 ** Math.min(failures, 4)))));
+                }, delay);
+                timer.unref?.();
+            };
+            const onAbort = () => close();
+            run.signal.addEventListener('abort', onAbort, { once: true });
+            schedule();
+            return {
+                checkpoint: {
+                    sourceCursor: `${provider.id}-interaction:${cursor}`,
+                    pending: pending ? [pending] : [],
+                },
+                close() {
+                    run.signal.removeEventListener('abort', onAbort);
+                    close();
+                },
+            };
+        },
+        async dispatchResponse(run, request) {
+            const binding = active.get(run.ref.runId);
+            if (!binding || binding.run !== run || run.signal.aborted)
+                return { status: 'stale_run' };
+            if (!binding.pending || binding.pending.id !== request.interactionId) {
+                return { status: 'already_resolved' };
+            }
+            const optionIds = request.value.type === 'selection' ? request.value.optionIds
+                : request.value.type === 'approval' ? [request.value.optionId] : [];
+            if (optionIds.length !== 1) {
+                return { status: 'rejected', reason: 'invalid_value' };
+            }
+            const optionId = optionIds[0];
+            const match = optionId.match(/^choice:(\d+)$/);
+            if (!match || !binding.pending.options?.some((option) => option.id === optionId)) {
+                return { status: 'rejected', reason: 'invalid_value' };
+            }
+            try {
+                await control.sendChoice(run.ref.paneId, match[1]);
+                return { status: 'accepted' };
+            }
+            catch {
+                return { status: 'unknown', reason: 'temporarily_unavailable' };
+            }
+        },
+    };
+}

package/dist/src/agents/index.js

@@ -1,10 +1,11 @@
 // The single built-in Agent registry. Runtime consumes the root AgentAdapter contract; legacy
 // orphan/transcript code sees a filtered projection of the same objects until those services migrate.
 import { claude } from './claude.js';
+import { codebuddy } from './codebuddy.js';
 import { codex } from './codex.js';
 import { piAgentAdapter } from './pi.js';
 import { validateAgentAdapters } from '../agent-runtime/adapter.js';
-export const BUILTIN_AGENT_ADAPTERS = [claude, codex, piAgentAdapter];
+export const BUILTIN_AGENT_ADAPTERS = [claude, codex, piAgentAdapter, codebuddy];
 export const BUILTIN_AGENT_ADAPTER_VALIDATION = validateAgentAdapters(BUILTIN_AGENT_ADAPTERS);
 function isLegacyDriver(adapter) {
     const candidate = adapter;

package/dist/src/claudeEvents.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getAgent, agentForProc } from './agents/index.js';
+import { hookEventKind } from './agents/hookEvents.js';
 import { resolveVersionedComms } from './agents/claude.js';
 import { resolveCodexComms } from './agents/codex.js';
 import { defaultRun } from './agents/scanUtils.js';
@@ -14,14 +15,12 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 export const DEFAULT_STATE_FILE = process.env.CLAUDE_STATE_FILE || path.resolve(here, '../data/claude-state.json');
 // Classify a Claude hook event → inbox kind. Re-exported because tests and callers import this path.
 export const classifyEvent = claude.classify;
-const EVENT_KINDS = new Set([
-    'done', 'working', 'permission', 'compacting', 'error', 'end', 'idle',
-]);
 const VIEW_LABEL = { needs: '需要你', done: '已完成' };
 const recordOf = (value) => value && typeof value === 'object' && !Array.isArray(value)
     ? value : null;
-const eventKind = (value) => typeof value === 'string' && EVENT_KINDS.has(value)
-    ? value : null;
+// The kind vocabulary itself is shared with every other Hook-driven provider; only Claude's own
+// classification decisions live in agents/claude.ts.
+const eventKind = hookEventKind;
 const pushView = (kind) => kind === 'permission' ? 'needs' : kind === 'done' ? 'done' : null;
 // The dedup key for a pane's current push view. `needs` is view-only: Claude signals one permission gate via
 // TWO hooks (permreq then permission_prompt) at different ts, and both must collapse to a SINGLE 需要你. But