@pimote/pimote 0.1.1 → 0.3.0

package/server/dist/voice/index.js

@@ -0,0 +1,319 @@
+// @pimote/voice — voice extension for pimote.
+//
+// This is the imperative shell around the pure FSM in `./fsm/`. It does
+// three things:
+//
+//   1. Translates external stimuli (pi-coding-agent SDK hooks, EventBus
+//      messages, speechmux WS frames) into typed `Event` values.
+//   2. Calls `reduce(state, event)` and writes back the new state.
+//   3. Interprets the emitted `Action` values into actual side effects:
+//      pi.sendUserMessage, ctx.abort, WS open/close/send, EventBus emit.
+//
+// **Why the redesign.** The previous monolithic implementation conflated
+// lifecycle, streaming, and walkback into a single record of orthogonal
+// flags whose invariants drifted out of sync. The most visible symptom
+// was per-content-block streaming state leaking across assistant
+// messages because it was reset on the wrong event (a substring of
+// `assistantMessageEvent` that never fires inside `message_update`). The
+// FSM split + correct reset-on-message_start eliminates that bug class.
+import { Type } from '@sinclair/typebox';
+import { renderInterpreterPrompt } from './interpreter-prompt.js';
+import { createDefaultSpeechmuxClientFactory } from './speechmux-client.js';
+import { ensureIdleWithImplicitAbort } from './wait-for-idle.js';
+import { initialState } from './fsm/state.js';
+import { reduce } from './fsm/reducer.js';
+// ---- Diagnostic helpers ---------------------------------------------------
+/** Render a compact event description for tracing. Returns null when the
+ *  event type is enough on its own (the dispatcher logs the bare type). */
+function traceEvent(event) {
+    switch (event.type) {
+        case 'sdk:toolcall_start':
+            return `sdk:toolcall_start(idx=${event.contentIndex}, partial.name=${partialName(event.partial, event.contentIndex)})`;
+        case 'sdk:toolcall_delta':
+            return `sdk:toolcall_delta(idx=${event.contentIndex}, deltaLen=${event.delta.length}, deltaPreview=${JSON.stringify(event.delta.slice(0, 40))})`;
+        case 'sdk:toolcall_end':
+            return `sdk:toolcall_end(idx=${event.contentIndex}, name=${event.toolCall.name ?? null}, finalTextLen=${typeof event.toolCall.arguments?.text === 'string' ? event.toolCall.arguments.text.length : 0})`;
+        case 'ws:incoming':
+            return `ws:incoming(${event.frame.type}${event.frame.type === 'user' ? `, textLen=${event.frame.text.length}` : ''})`;
+        case 'sdk:message_start':
+            return `sdk:message_start(role=${event.message.role})`;
+        case 'sdk:context':
+            return `sdk:context(messages=${event.messages.length})`;
+        case 'eb:activate':
+            return `eb:activate(${event.msg.sessionId})`;
+        default:
+            return null;
+    }
+}
+function partialName(partial, idx) {
+    const c = partial.content;
+    if (!Array.isArray(c))
+        return null;
+    const b = c[idx];
+    if (!b || typeof b !== 'object')
+        return null;
+    const name = b.name;
+    return typeof name === 'string' ? name : null;
+}
+function blockSummary(blocks) {
+    const out = {};
+    for (const [k, v] of blocks.entries()) {
+        out[k] = blockKind(v);
+    }
+    return out;
+}
+function blockKind(b) {
+    if (b.kind === 'speak_streaming')
+        return `speak_streaming(emitted=${b.emittedLength})`;
+    return b.kind;
+}
+// ---- Re-exports kept for back-compat with callers/tests -------------------
+export { walkBack, isAbortedEmptyAssistant } from './walk-back.js';
+export { VOICE_CALL_STARTED_SENTINEL } from './state-machine.js';
+export { renderInterpreterPrompt, RAW_INTERPRETER_PROMPT } from './interpreter-prompt.js';
+export { createDefaultSpeechmuxClientFactory } from './speechmux-client.js';
+export function createVoiceExtension(opts) {
+    const interpreterPrompt = renderInterpreterPrompt({
+        workerProvider: opts.defaultWorkerModel.provider,
+        workerModel: opts.defaultWorkerModel.modelId,
+    });
+    const clientFactory = opts.speechmuxClientFactory ?? createDefaultSpeechmuxClientFactory();
+    return (pi) => {
+        // ---- Per-extension-instance state (per pimote session) ---------------
+        let state = initialState();
+        let lastCtx = null;
+        let speechmuxClient = null;
+        /** Slot read by the `context` hook to return rewritten messages. */
+        let pendingContextRewrite = null;
+        // ---- Reducer driver --------------------------------------------------
+        const dispatch = async (event) => {
+            const evtTrace = traceEvent(event);
+            const lifecycleBefore = state.lifecycle.kind;
+            const { next, actions } = reduce(state, event, {
+                config: { defaultInterpreterModel: opts.defaultInterpreterModel },
+            });
+            state = next;
+            if (evtTrace || lifecycleBefore !== state.lifecycle.kind || actions.length > 0) {
+                console.log('[voice_trace] dispatch', JSON.stringify({
+                    event: evtTrace ?? event.type,
+                    lifecycle: `${lifecycleBefore}→${state.lifecycle.kind}`,
+                    actions: actions.map((a) => a.kind),
+                    blocks: blockSummary(state.message.blocks),
+                }));
+            }
+            for (const action of actions) {
+                try {
+                    await execute(action);
+                }
+                catch (err) {
+                    console.warn('[voice] action failed', action.kind, err);
+                }
+            }
+        };
+        const execute = async (action) => {
+            switch (action.kind) {
+                case 'set_interpreter_model': {
+                    if (!lastCtx) {
+                        console.warn('[voice] set_interpreter_model: no ExtensionContext yet');
+                        return;
+                    }
+                    const model = lastCtx.modelRegistry.find(action.provider, action.modelId);
+                    if (!model) {
+                        console.warn(`[voice] set_interpreter_model: no model ${action.provider}/${action.modelId}`);
+                        return;
+                    }
+                    await pi.setModel(model);
+                    return;
+                }
+                case 'send_user_message': {
+                    // Ensure the agent is idle before sending. If it isn't, fire
+                    // a synthesized barge-in (ctx.abort()) and wait for teardown
+                    // — covers the case where the user spoke while the worker
+                    // was silently reasoning, so speechmux didn't issue an abort
+                    // (no TTS in flight to abort). See wait-for-idle.ts.
+                    if (lastCtx) {
+                        const ready = await ensureIdleWithImplicitAbort(lastCtx);
+                        if (!ready) {
+                            console.warn(`[voice] send_user_message: agent did not become idle within 2000ms after implicit abort, dropping: ${action.text.slice(0, 60)}`);
+                            return;
+                        }
+                    }
+                    pi.sendUserMessage(action.text, action.deliverAs ? { deliverAs: action.deliverAs } : undefined);
+                    return;
+                }
+                case 'open_ws': {
+                    // Reentrancy guard: close any prior client first.
+                    try {
+                        speechmuxClient?.close();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    speechmuxClient = null;
+                    try {
+                        const client = await clientFactory({ wsUrl: action.url });
+                        speechmuxClient = client;
+                        client.onFrame((frame) => {
+                            void dispatch({ type: 'ws:incoming', frame });
+                        });
+                        await dispatch({ type: 'ws:opened' });
+                    }
+                    catch (err) {
+                        console.warn('[voice] speechmux open failed', err);
+                        await dispatch({ type: 'ws:open_failed', error: err });
+                    }
+                    return;
+                }
+                case 'close_ws': {
+                    try {
+                        speechmuxClient?.close();
+                    }
+                    catch {
+                        /* idempotent */
+                    }
+                    speechmuxClient = null;
+                    return;
+                }
+                case 'send_frame': {
+                    if (!speechmuxClient) {
+                        console.warn('[voice] send_frame with no client — dropping', action.frame.type);
+                        return;
+                    }
+                    const preview = action.frame.type === 'token' ? action.frame.text.slice(0, 60) : null;
+                    console.log('[voice_trace] send_frame', JSON.stringify({ type: action.frame.type, preview }));
+                    try {
+                        speechmuxClient.send(action.frame);
+                    }
+                    catch (err) {
+                        console.warn('[voice] speechmux send failed', action.frame.type, err);
+                    }
+                    return;
+                }
+                case 'abort_agent': {
+                    lastCtx?.abort();
+                    return;
+                }
+                case 'append_custom_entry': {
+                    pi.appendEntry(action.customType, action.data);
+                    return;
+                }
+                case 'emit_deactivate_request': {
+                    const sessionId = state.lifecycle.kind === 'active' || state.lifecycle.kind === 'activating' ? state.lifecycle.sessionId : '';
+                    const msg = {
+                        type: 'pimote:voice:deactivate',
+                        sessionId,
+                    };
+                    pi.events.emit('pimote:voice:deactivate', msg);
+                    return;
+                }
+                case 'rewrite_context': {
+                    // Stash; the `context` hook below reads this on its return.
+                    pendingContextRewrite = action.messages;
+                    return;
+                }
+            }
+        };
+        // ---- EventBus listeners ---------------------------------------------
+        pi.events.on('pimote:voice:activate', (data) => {
+            void dispatch({ type: 'eb:activate', msg: data });
+        });
+        pi.events.on('pimote:voice:deactivate', (data) => {
+            void dispatch({ type: 'eb:deactivate', msg: data });
+        });
+        // ---- speak() tool ---------------------------------------------------
+        //
+        // The streaming reducer is the sole emitter of speak `token`/`end`
+        // frames. The `execute` here only returns the synthetic success
+        // result so the agent loop progresses.
+        pi.registerTool({
+            name: 'speak',
+            label: 'Speak',
+            description: 'Speak text to the user via text-to-speech. This is the only way to produce audible output during a voice call. Keep messages short and TTS-friendly.',
+            promptSnippet: 'speak(text) — speak text to the user (voice-mode only).',
+            parameters: Type.Object({
+                text: Type.String({ description: 'The text to speak to the user.' }),
+            }),
+            execute: async () => {
+                if (state.lifecycle.kind === 'active' || state.lifecycle.kind === 'activating') {
+                    return { content: [{ type: 'text', text: 'ok' }], details: {} };
+                }
+                return {
+                    content: [{ type: 'text', text: 'speak() is only available during an active voice call.' }],
+                    details: {},
+                    isError: true,
+                };
+            },
+        });
+        // ---- SDK hooks ------------------------------------------------------
+        pi.on('before_agent_start', (event, ctx) => {
+            lastCtx = ctx;
+            if (state.lifecycle.kind === 'dormant')
+                return;
+            return { systemPrompt: `${interpreterPrompt}\n\n${event.systemPrompt ?? ''}`.trim() };
+        });
+        // The `tool_call` hook is intentionally NOT registered. The streaming
+        // reducer is the sole emitter of speak frames; bulk-emission via
+        // tool_call was the source of the double-emit class of bugs.
+        //
+        // The `turn_end` safety net is also intentionally NOT registered.
+        // With per-speak `end` framing driven by `toolcall_end`, it was
+        // redundant and contributed to double-end emissions.
+        pi.on('message_start', (event) => {
+            // Only assistant messages reset the streaming state. User and
+            // tool-result messages don't have content blocks we care about.
+            if (event.message.role !== 'assistant')
+                return;
+            void dispatch({ type: 'sdk:message_start', message: event.message });
+        });
+        pi.on('message_update', (event, ctx) => {
+            lastCtx = ctx;
+            // Walkback no longer needs a captured snapshot — it operates on
+            // the messages array passed to `sdk:context` directly.
+            if (state.lifecycle.kind === 'dormant')
+                return;
+            const ame = event.assistantMessageEvent;
+            if (!ame || typeof ame.contentIndex !== 'number')
+                return;
+            switch (ame.type) {
+                case 'toolcall_start':
+                    void dispatch({
+                        type: 'sdk:toolcall_start',
+                        contentIndex: ame.contentIndex,
+                        partial: (ame.partial ?? {}),
+                    });
+                    return;
+                case 'toolcall_delta':
+                    void dispatch({
+                        type: 'sdk:toolcall_delta',
+                        contentIndex: ame.contentIndex,
+                        delta: typeof ame.delta === 'string' ? ame.delta : '',
+                        partial: (ame.partial ?? {}),
+                    });
+                    return;
+                case 'toolcall_end':
+                    void dispatch({
+                        type: 'sdk:toolcall_end',
+                        contentIndex: ame.contentIndex,
+                        toolCall: (ame.toolCall ?? {}),
+                    });
+                    return;
+                default:
+                    // text_*, thinking_* — not relevant to outbound streaming.
+                    return;
+            }
+        });
+        pi.on('context', (event, ctx) => {
+            lastCtx = ctx;
+            // The walkback reducer always runs walkBack (even when no rewrite
+            // is pending — to strip aborted-empty-assistants). It writes the
+            // result into `pendingContextRewrite` via the `rewrite_context`
+            // action, which we read below.
+            void dispatch({ type: 'sdk:context', messages: event.messages });
+            const result = pendingContextRewrite;
+            pendingContextRewrite = null;
+            if (result)
+                return { messages: result };
+            return undefined;
+        });
+    };
+}

package/server/dist/voice/interpreter-prompt.js

@@ -0,0 +1,115 @@
+// Interpreter prompt for the pimote voice extension. Adapted from voxcoder's
+// interpreter prompt — see docs/plans/voice-mode.md (Step 2) and
+// /home/alenna/repos/voxcoder/server/src/interpreter/prompt.ts.
+//
+// Multimodal placeholders from voxcoder are removed (the PWA is a separate
+// text surface in v1 — it renders scrollback directly, not through the
+// interpreter). The interpreter's sole audio-output path is the `speak(text)`
+// pi custom tool; free-text assistant output is discarded from the audio
+// channel by the extension.
+//
+// Placeholders `{{workerProvider}}` / `{{workerModel}}` are substituted once
+// at factory time by `createVoiceExtension` so the registered string is
+// static by the time pi's `before_agent_start` hook sees it.
+/** Raw template — contains `{{workerProvider}}` / `{{workerModel}}` placeholders. */
+export const RAW_INTERPRETER_PROMPT = `You are a voice interpreter — the conversational hub between a human user speaking over a phone-like call and a coding worker subagent that does the actual software engineering work.
+
+<role>
+
+You receive all user speech as user messages. You decide what to say back (via the \`speak\` tool) and when to delegate work to a worker. From the user's point of view you and the worker are one entity — use "I" when relaying what the worker is doing.
+
+You have exactly one way to produce audio: the \`speak(text)\` tool. Any free-text assistant output you emit is discarded — the user will never hear it. If you have nothing to say and nothing to do, emit a single \`speak\` call with a brief acknowledgement (e.g. "ok") or simply end your turn.
+
+</role>
+
+<session_start>
+
+When you see the sentinel user message \`<voice_call_started/>\`, the call has just connected. Greet the user proactively with a brief \`speak(...)\` — one or two sentences — and then end your turn so the user can reply. Example greetings:
+
+- "Hey, I'm here. What are we working on?"
+- "Hi — what can I help you with?"
+
+Do not dispatch any worker task on the greeting turn. Just speak and wait.
+
+</session_start>
+
+<acknowledge_first>
+
+**Every time the user speaks, your very first action in the response turn must be a \`speak(...)\` call that acknowledges what you heard and, if you're about to do something, what you're going to do about it.** Do not start a turn with a tool call, a subagent spawn, a read, or silent thinking — speak first, always.
+
+The acknowledgement and any tool calls happen in the same turn. Emit the \`speak\` call first, then immediately follow with whatever tool calls you need (typically a worker subagent). The user hears the acknowledgement while the tools run in the background — that's the point.
+
+Keep the ack short and concrete:
+
+- "Okay, taking a look at the auth module now."
+- "Got it — I'll check the test failures."
+- "Sure, one sec while I read that file."
+
+For purely conversational turns where no tool call is needed, the \`speak\` call alone *is* the response — same rule, just nothing after it.
+
+The only exception is the \`<voice_call_started/>\` greeting turn, which is already a \`speak\`-first turn by definition.
+
+</acknowledge_first>
+
+<speaking>
+
+All audible output goes through \`speak(text)\`:
+
+- One or two short sentences per call. Natural spoken English.
+- Never read code aloud. Describe what the code does instead.
+- No markdown, backticks, bullet points, or code fences — they sound terrible as TTS.
+- For long updates, break them into multiple \`speak\` calls in the same turn; each call is streamed to the user as you emit it.
+
+You may emit multiple \`speak\` calls per turn. The user hears them concatenated in order. End your turn once you have nothing more to say on the current topic.
+
+</speaking>
+
+<worker_delegation>
+
+For any real software-engineering task (reading files, editing code, running tests, investigating a bug, writing a new feature), spawn a worker via the \`my-pi\` \`subagent\` tool. The worker is a full pi coding agent — give it a clear task description and let it work.
+
+**The worker is long-lived.** Spawn it once — either at the start of the call or the first time you need it — and then keep it alive for the rest of the call. Do **not** tear it down when it goes idle. For every subsequent task, use \`send\` to dispatch new work to the existing worker. This preserves the worker's context across the whole call so it remembers prior files, decisions, and reasoning. Only tear it down at the end of the call or if it gets into a clearly broken state.
+
+**IMPORTANT:** When spawning a worker via \`my-pi\` \`subagent\`, always pass \`model: "{{workerModel}}"\` and \`provider: "{{workerProvider}}"\` in the agent configuration so the worker runs on the configured worker model rather than the interpreter model.
+
+On the turn where you spawn the worker, emit the acknowledging \`speak(...)\` call as the first tool call in the list, with the \`subagent\` call right after it in the same response. Both fire in parallel — the user hears the ack while the worker is already starting up.
+
+While the worker runs:
+
+- When the worker reports progress or completion, summarise it briefly for the user — outcomes, not step-by-step narration.
+- If the worker asks a question or flags a decision, relay it to the user and wait for their answer before forwarding it back.
+
+For purely conversational turns (greetings, thanks, chit-chat, clarifying a previous answer) you can handle the turn with \`speak\` alone — no worker needed.
+
+</worker_delegation>
+
+<interruptions>
+
+The user can interrupt you mid-sentence. When that happens, your in-flight turn is aborted and the user's new message arrives as the next user turn. Do not apologise for being interrupted or try to resume the old sentence — just respond to what the user said.
+
+</interruptions>
+
+<tts_guidelines>
+
+The user is likely driving, cooking, or otherwise unable to look at a screen. Audio must be:
+
+- Brief enough not to distract.
+- Clear enough to understand without visual context.
+- Natural enough not to sound robotic.
+
+Rules of thumb:
+
+- 1–3 sentences per \`speak\` call.
+- Focus on outcomes, not internal state.
+- Never read code, file paths with slashes, or long identifiers aloud verbatim — paraphrase.
+- When the worker finishes, summarise the result in a sentence or two.
+
+</tts_guidelines>
+`;
+/**
+ * Substitute the `{{workerProvider}}` / `{{workerModel}}` placeholders with
+ * concrete values. Called once at factory time.
+ */
+export function renderInterpreterPrompt(vars) {
+    return RAW_INTERPRETER_PROMPT.replace(/\{\{workerProvider\}\}/g, vars.workerProvider).replace(/\{\{workerModel\}\}/g, vars.workerModel);
+}

package/server/dist/voice/speechmux-client.js

@@ -0,0 +1,153 @@
+// Speechmux LlmBackend WS protocol — minimal interface the voice extension
+// consumes.  Full protocol: speechmux/docs/llm-ws-protocol.md.
+//
+// The voice extension uses this as the seam between itself and speechmux so
+// tests can substitute an in-memory fake without running a real WebSocket.
+// ---------------------------------------------------------------------------
+// Default `ws`-backed implementation.
+// ---------------------------------------------------------------------------
+/**
+ * Default `SpeechmuxClient` factory backed by the `ws` package. Opens a
+ * WebSocket to `wsUrl` and routes incoming JSON text frames to registered
+ * listeners. The LLM-WS protocol has no hello frame — the harness simply
+ * connects and exchanges `user` / `token` / `end` / `abort` / `rollback`
+ * frames (see speechmux/docs/llm-ws-protocol.md).
+ *
+ * Resolves once the socket is open. Rejects if the socket errors or closes
+ * before opening.
+ */
+export function createDefaultSpeechmuxClientFactory() {
+    // Dynamic import so consumers that never call the factory (e.g. tests)
+    // don't pay the `ws` resolution cost. Cached after first load.
+    let WsCtor = null;
+    return async (opts) => {
+        const { wsUrl } = opts;
+        if (!WsCtor) {
+            const mod = await import('ws');
+            WsCtor = mod.WebSocket;
+        }
+        const ws = new WsCtor(wsUrl);
+        const listeners = new Set();
+        // Buffer frames that arrive after `hello` but before the caller has had a
+        // chance to attach an `onFrame` listener. Drained on the first attach.
+        const pending = [];
+        let closed = false;
+        // Install the message handler before resolving so frames sent between
+        // open and the caller's onFrame attach are buffered instead of dropped.
+        // See review finding 5 (speechmux-client race).
+        ws.on('message', (raw, isBinary) => {
+            if (isBinary)
+                return;
+            let text;
+            if (typeof raw === 'string')
+                text = raw;
+            else if (raw instanceof Buffer)
+                text = raw.toString('utf8');
+            else if (Array.isArray(raw))
+                text = Buffer.concat(raw).toString('utf8');
+            else
+                text = Buffer.from(raw).toString('utf8');
+            let frame;
+            try {
+                frame = JSON.parse(text);
+            }
+            catch {
+                return; // ignore non-JSON
+            }
+            if (!isIncomingFrame(frame))
+                return;
+            if (listeners.size === 0) {
+                pending.push(frame);
+                return;
+            }
+            for (const listener of listeners)
+                listener(frame);
+        });
+        const connectTimeoutMs = opts.connectTimeoutMs ?? 5000;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                clearTimeout(timer);
+                ws.off('open', onOpen);
+                ws.off('error', onError);
+            };
+            const onOpen = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve();
+            };
+            const onError = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(err);
+            };
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                try {
+                    ws.terminate();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(new Error(`SpeechmuxClient: connect timeout after ${connectTimeoutMs}ms (${wsUrl})`));
+            }, connectTimeoutMs);
+            ws.once('open', onOpen);
+            ws.once('error', onError);
+        });
+        ws.on('close', () => {
+            closed = true;
+        });
+        return {
+            send(frame) {
+                if (closed || ws.readyState !== ws.OPEN) {
+                    throw new Error('SpeechmuxClient: socket is not open');
+                }
+                ws.send(JSON.stringify(frame));
+            },
+            onFrame(listener) {
+                const firstListener = listeners.size === 0;
+                listeners.add(listener);
+                if (firstListener && pending.length > 0) {
+                    // Drain any frames that arrived before the listener attached.
+                    const drained = pending.splice(0, pending.length);
+                    for (const frame of drained)
+                        listener(frame);
+                }
+                return () => listeners.delete(listener);
+            },
+            close() {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    ws.close();
+                }
+                catch {
+                    // ignore
+                }
+            },
+        };
+    };
+}
+function isIncomingFrame(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    switch (v.type) {
+        case 'user':
+            return typeof v.text === 'string';
+        case 'abort':
+            return true;
+        case 'rollback':
+            return typeof v.heard_text === 'string';
+        default:
+            return false;
+    }
+}

package/server/dist/voice/state-machine.js

@@ -0,0 +1,7 @@
+// Voice extension activation state machine.
+//
+// Defined in docs/plans/voice-mode.md — "Voice extension" section under
+// "Interfaces". The state machine is driven by EventBus messages from the
+// server-side VoiceOrchestrator.
+/** Sentinel user message appended on entry to the `active` state. */
+export const VOICE_CALL_STARTED_SENTINEL = '<voice_call_started/>';

package/server/dist/voice/wait-for-idle.js

@@ -0,0 +1,67 @@
+// Wait-for-idle helper for the voice extension.
+//
+// The speechmux abort/user frame pair on barge-in arrives as two
+// independent reducer calls. The `abort` action calls `ctx.abort()`
+// (fire-and-forget — the actual teardown completes asynchronously). If
+// the user frame arrives before the teardown is done, `sendUserMessage`
+// throws ("Agent is already processing…") and the user's utterance is
+// silently dropped.
+//
+// Steering doesn't help: pi-agent-core doesn't drain the steer queue on
+// the abort exit path of `runLoop`. Pimote has a separate
+// `autoDrainOnAbort` listener (see `auto-drain-on-abort.ts`) that
+// rescues queued messages after an aborted run, but that only catches
+// messages that *were* queued — it doesn't help an unqueued
+// `sendUserMessage` that throws.
+//
+// So the voice extension polls `ctx.isIdle()` before calling
+// `sendUserMessage` (without `deliverAs`), guaranteeing the SDK won't
+// throw. Auto-drain remains a belt-and-braces safety net for any
+// queued path that races an abort.
+/**
+ * Resolve once the agent is idle, polling with exponential backoff
+ * (start 5 ms, doubling, capped at 50 ms). Returns false if the agent
+ * never becomes idle within `timeoutMs`. Returns true immediately
+ * when already idle.
+ *
+ * Timeout default of 2 s is well above any normal abort-teardown
+ * latency (tens to a few hundred ms). If a real agent doesn't reach
+ * idle within 2 s, something is genuinely stuck and dropping the
+ * message is preferable to hanging the executor.
+ */
+export async function waitForAgentIdle(ctx, timeoutMs = 2000) {
+    if (ctx.isIdle())
+        return true;
+    const start = Date.now();
+    let delay = 5;
+    while (!ctx.isIdle()) {
+        if (Date.now() - start >= timeoutMs)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(50, delay * 2);
+    }
+    return true;
+}
+/**
+ * Ensure the agent is idle, synthesising a barge-in when it isn't.
+ *
+ * Speechmux only emits `abort` while it is actively playing TTS — i.e.
+ * during the harness's `token`/`end` stream. While the worker is
+ * silently reasoning between a `user` frame and its first `speak()`
+ * call, speechmux has no signal that the agent is busy and won't
+ * pre-empt. If the user starts a new utterance during that window, the
+ * `user` frame arrives at the harness with no preceding `abort`, so the
+ * agent is still mid-turn and `sendUserMessage` would race / be
+ * dropped.
+ *
+ * This helper closes that gap: when the agent isn't idle on entry, we
+ * fire `ctx.abort()` ourselves (idempotent if a real barge-in already
+ * issued one) and then poll for idle the same way the abort/user pair
+ * already does. Returns true once idle, false on timeout.
+ */
+export async function ensureIdleWithImplicitAbort(ctx, timeoutMs = 2000) {
+    if (ctx.isIdle())
+        return true;
+    ctx.abort();
+    return waitForAgentIdle(ctx, timeoutMs);
+}