@pimote/pimote 0.2.0 → 0.3.1

package/server/dist/voice/index.js

@@ -0,0 +1,336 @@
+// @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 'inject_silent_user_message': {
+                    // sendMessage() with a `custom` role + triggerTurn:false appends
+                    // an entry that converts to a `role:"user"` message for the LLM
+                    // (see core/messages.ts convertToLlm) but does not start a turn
+                    // now. Exactly what we want for the end-of-call sentinel.
+                    pi.sendMessage({
+                        customType: action.customType,
+                        content: action.text,
+                        display: true,
+                    }, { triggerTurn: false });
+                    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: 'Voice call has ended. The user is now in text mode — do NOT call speak() again. Reply with normal assistant text. Any further speak() calls in this session will be rejected.',
+                        },
+                    ],
+                    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,14 @@
+// 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/>';
+/**
+ * Sentinel user message appended on exit from `active`/`activating` back to
+ * `dormant`. Gives the agent an explicit in-history signal that the voice
+ * call has ended, so subsequent turns (including future text-mode pickups
+ * of the same session) don't keep mimicking prior `speak()` calls.
+ */
+export const VOICE_CALL_ENDED_SENTINEL = '<voice_call_ended/>';