@iloveagents/foundry-web-voice 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iLoveAgents, a brand of Leitwolf GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @iloveagents/foundry-web-voice
+
+Spoken conversation for [Foundry UI](https://github.com/iLoveAgents/foundry-ui), backed by
+[Microsoft Foundry Voice Live](https://learn.microsoft.com/azure/ai-services/speech-service/voice-live).
+
+Optional by construction: no other `@iloveagents/foundry-*` package imports this one, so an app
+that never installs it has an unchanged composer and an unchanged runtime.
+
+```bash
+npm install @iloveagents/foundry-web-voice
+```
+
+```ts
+import { bootstrapShell } from "@iloveagents/foundry-web-shell";
+import { createVoiceModule } from "@iloveagents/foundry-web-voice";
+
+bootstrapShell({
+  modules: [
+    createVoiceModule({
+      connection: { proxyUrl: import.meta.env.VITE_VOICE_PROXY_URL },
+    }),
+  ],
+});
+```
+
+That is the whole integration. A voice button appears in the composer (holding the Send corner
+until there is something to send), and while a call is live the conversation is replaced by a
+theme-aware visualiser — or the avatar, if you configure one — and comes straight back when the
+call ends. Pass `stage: false` to keep the transcript visible instead.
+
+## The two modes
+
+|                         | `relay` (default)                                     | `realtime`                      |
+| ----------------------- | ----------------------------------------------------- | ------------------------------- |
+| Who answers             | **your AG-UI agent** — retrieval, tools, citations    | the Voice Live model            |
+| Voice Live's job        | speech in, speech out (and the avatar)                | the whole conversation          |
+| Turns in the thread     | ordinary turns — tool cards, citations, **persisted** | live transcript, session-scoped |
+| First word of the reply | as fast as your agent                                 | sub-second                      |
+
+**`relay`** keeps the answer yours. Voice Live transcribes what the user said, the transcript goes
+through the composer exactly as if it had been typed, your agent answers with its full tool and
+retrieval surface, and the reply is spoken back in the Azure voice you configured. Under the hood
+that is `turn_detection.create_response: false` plus `pre_generated_assistant_message` — both
+documented Voice Live features, not tricks.
+
+**`realtime`** hands the conversation to the Voice Live model for the lowest possible latency. It
+can still call your client-side tools: the schemas in `clientToolRegistry` are sent with the
+session, and a call is dispatched through the same registry the typed chat uses, so `ui_navigate`
+and your `page_*` tools work by voice with no second declaration.
+
+```ts
+createVoiceModule({
+  mode: "realtime",
+  connection: { proxyUrl: VOICE_PROXY_URL },
+  session: { instructions: "You are a helpful assistant. Keep answers to one or two sentences." },
+});
+```
+
+### One thing to know about `realtime` and history
+
+assistant-ui merges realtime transcripts into the thread while the session is live and clears them
+on disconnect (`disconnectVoice()` empties `_voiceMessages`). They are never handed to a
+`ThreadHistoryAdapter`. That is the framework's design for realtime voice, not a gap here — and it
+is why `relay` is the default. Pass `onTranscript` if you want to persist them yourself.
+
+## An avatar
+
+Configure one on the session and the panel renders itself once the video track arrives:
+
+```ts
+import { sessionConfig } from "@iloveagents/foundry-voice-live-react";
+
+createVoiceModule({
+  connection: { proxyUrl: VOICE_PROXY_URL },
+  session: sessionConfig()
+    .hdVoice("en-US-Ava:DragonHDLatestNeural")
+    .avatar("lisa", "casual-sitting", { codec: "h264" })
+    .build(),
+});
+```
+
+In `relay` mode the avatar lip-syncs your own agent's answer, because the words are sent as a
+pre-generated assistant message rather than generated by the Voice Live model.
+
+## Options that matter in a room
+
+- `halfDuplex: true` — mute the microphone while the assistant speaks, so on laptop speakers it
+  cannot hear itself and answer its own voice. Costs barge-in; right on speakerphones, wrong with
+  headsets. It never overrides a mute the user set themselves.
+- `chromaKey` — tune the avatar's green-screen removal. The default cuts a _tighter_ edge than the
+  SDK's, which left a green fringe on the silhouette in live runs. Tighter, not softer: the subject
+  sits closer to the key colour than it looks, so widening the blend band does not soften the edge —
+  it turns the whole figure translucent.
+- `stage: false` — keep the thread visible during a call instead of replacing it.
+
+## You need a proxy
+
+A browser cannot set an `Authorization` header on a WebSocket, so the credential has to live
+somewhere else. Run the SDK's proxy and point `proxyUrl` at it:
+
+```bash
+docker run -p 8080:8080 \
+  -e FOUNDRY_RESOURCE_NAME=your-foundry-resource \
+  -e FOUNDRY_API_KEY="…" \
+  -e ALLOWED_ORIGINS="https://your-app.example.com" \
+  ghcr.io/iloveagents/foundry-voice-live-proxy:latest
+```
+
+`connection` accepts everything
+[`@iloveagents/foundry-voice-live-react`](https://www.npmjs.com/package/@iloveagents/foundry-voice-live-react)
+does, including a per-user MSAL token and Foundry Agent Service. An `apiKey` in the browser is for
+local development only.
+
+> The default model (`gpt-realtime`) is available in **East US 2** and **Sweden Central**.
+
+## Without the shell
+
+If you compose the runtime yourself, render `FoundryVoice` anywhere inside `AGUIRuntimeProvider`:
+
+```tsx
+<AGUIRuntimeProvider>
+  <FoundryVoice connection={{ proxyUrl: VOICE_PROXY_URL }} />
+  <ChatContent />
+</AGUIRuntimeProvider>
+```
+
+Pass `chrome: false` to keep the composer untouched and place `VoiceMicButton` /
+`VoiceStatusStrip` wherever you want them.
+
+## How it fits together
+
+assistant-ui 0.15 already models realtime voice: `useLocalRuntime` accepts a
+`RealtimeVoiceAdapter`, the thread runtime merges the transcripts it emits into `thread.messages`,
+and `useVoiceControls()` / `useVoiceState()` / `useVoiceVolume()` expose the session. This package
+implements that one interface over Voice Live — which is why the mic button is ordinary
+assistant-ui code and would work for any other voice backend registered the same way.
+
+`foundry-web-ui` contributes only the seams: `registerVoiceAdapter()` and a `composerActions` chat
+slot. Neither mentions Voice Live.
+
+## API
+
+| Export                                                   | What it is                                                                      |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `createVoiceModule(config)`                              | a `bootstrapShell` module                                                       |
+| `FoundryVoice`                                           | the same thing as a component, for shell-less apps                              |
+| `installVoice(config)`                                   | `{ bridge, Host, dispose }` for full control                                    |
+| `VoiceMicButton`, `VoiceStatusStrip`, `VoiceAvatarPanel` | the chrome, for `chrome: false`                                                 |
+| `VoiceBridge`                                            | the protocol layer — no components or hooks; driven by `VoiceTransportControls` |
+| `buildVoiceSession`, `toVoiceLiveTools`                  | mode → Voice Live session; registry → function tools                            |
+| `SentenceStream`, `SpeechQueue`, `toSpeakableText`       | the markdown-to-speech pipeline                                                 |
+| `VoiceStage`, `VoiceVisualizer`                          | the in-call surface and its theme-aware canvas                                  |
+| `HalfDuplexGate`                                         | when the mic closes/opens around assistant speech (pure, tested)                |
+
+## License
+
+MIT

package/dist/adapter/half-duplex.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `HalfDuplexGate` — decides when the microphone opens and closes while the
+ * assistant is speaking.
+ *
+ * Half-duplex exists for speakers: the assistant's own voice trips the
+ * service's VAD and it starts answering itself. The naive version — "mute
+ * while speaking, unmute after" — has two failure modes that only show up
+ * with a person in the loop, which is why this is a pure machine with a test
+ * for each of them rather than a pair of booleans inside a React effect:
+ *
+ * - **The mic must never end up hot behind a muted UI.** If the user mutes
+ *   *while* the auto-mute is engaged, a release that only remembers "I
+ *   muted" un-mutes on their behalf: the runtime still shows muted, the SDK
+ *   is capturing, and the user is being recorded while the button says they
+ *   are not. Releasing therefore also requires that the user has not asked
+ *   for mute in the meantime.
+ *
+ * - **An explicit unmute is a decision, not a glitch.** If the user unmutes
+ *   mid-answer they are choosing barge-in over echo protection; re-muting
+ *   them on the next tick makes interruption impossible. The gate engages
+ *   only on the *transition* into speaking, so a mid-answer unmute stands
+ *   until the next assistant turn.
+ */
+export interface HalfDuplexInputs {
+    /** The feature switch (`VoiceConfig.halfDuplex`). */
+    enabled: boolean;
+    /** The assistant is currently speaking. */
+    speaking: boolean;
+    /** The SDK's capture-mute state (what the microphone is actually doing). */
+    sdkMuted: boolean;
+    /** The user's own intent, as expressed through the runtime's mute control. */
+    userMuted: boolean;
+}
+export type HalfDuplexAction = "mute" | "unmute" | "none";
+export declare class HalfDuplexGate {
+    /** True while a mute this gate applied is outstanding. */
+    private autoMuted;
+    private wasSpeaking;
+    next({ enabled, speaking, sdkMuted, userMuted }: HalfDuplexInputs): HalfDuplexAction;
+    /** A session ended; whatever was outstanding no longer is. */
+    reset(): void;
+}

package/dist/adapter/half-duplex.js

@@ -0,0 +1,65 @@
+/**
+ * `HalfDuplexGate` — decides when the microphone opens and closes while the
+ * assistant is speaking.
+ *
+ * Half-duplex exists for speakers: the assistant's own voice trips the
+ * service's VAD and it starts answering itself. The naive version — "mute
+ * while speaking, unmute after" — has two failure modes that only show up
+ * with a person in the loop, which is why this is a pure machine with a test
+ * for each of them rather than a pair of booleans inside a React effect:
+ *
+ * - **The mic must never end up hot behind a muted UI.** If the user mutes
+ *   *while* the auto-mute is engaged, a release that only remembers "I
+ *   muted" un-mutes on their behalf: the runtime still shows muted, the SDK
+ *   is capturing, and the user is being recorded while the button says they
+ *   are not. Releasing therefore also requires that the user has not asked
+ *   for mute in the meantime.
+ *
+ * - **An explicit unmute is a decision, not a glitch.** If the user unmutes
+ *   mid-answer they are choosing barge-in over echo protection; re-muting
+ *   them on the next tick makes interruption impossible. The gate engages
+ *   only on the *transition* into speaking, so a mid-answer unmute stands
+ *   until the next assistant turn.
+ */
+export class HalfDuplexGate {
+    constructor() {
+        /** True while a mute this gate applied is outstanding. */
+        this.autoMuted = false;
+        this.wasSpeaking = false;
+    }
+    next({ enabled, speaking, sdkMuted, userMuted }) {
+        if (!enabled) {
+            // Turning the feature off mid-session must not strand an auto-mute.
+            const release = this.autoMuted && sdkMuted && !userMuted;
+            this.autoMuted = false;
+            this.wasSpeaking = speaking;
+            return release ? "unmute" : "none";
+        }
+        const startedSpeaking = speaking && !this.wasSpeaking;
+        this.wasSpeaking = speaking;
+        if (speaking) {
+            // Edge-triggered: engage once per assistant turn. A level-triggered
+            // gate would instantly undo a user's mid-answer unmute, and with it
+            // any possibility of barging in.
+            if (startedSpeaking && !sdkMuted && !userMuted) {
+                this.autoMuted = true;
+                return "mute";
+            }
+            return "none";
+        }
+        if (this.autoMuted) {
+            this.autoMuted = false;
+            // Release only what this gate took. If the user asked for mute while
+            // the auto-mute was engaged, unmuting here would leave the microphone
+            // hot behind a UI that says muted.
+            if (!userMuted && sdkMuted)
+                return "unmute";
+        }
+        return "none";
+    }
+    /** A session ended; whatever was outstanding no longer is. */
+    reset() {
+        this.autoMuted = false;
+        this.wasSpeaking = false;
+    }
+}

package/dist/adapter/session-config.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Derive the Voice Live session from the chosen mode.
+ *
+ * Two settings carry the whole behavioural difference between the modes, and
+ * both are documented Voice Live features rather than anything clever:
+ *
+ *   - `turn_detection.create_response` — "Enable or disable whether a
+ *     response is generated (default: true)". `relay` sets it false, so the
+ *     Voice Live model never answers; the app's AG-UI agent does, and the
+ *     answer is spoken back with `pre_generated_assistant_message`.
+ *   - `tools` — only `realtime` gets them, because only there is the Voice
+ *     Live model the one deciding to call something.
+ *
+ * `input_audio_transcription` is forced on for both modes. The SDK's
+ * `DEFAULT_SESSION_CONFIG` omits it, and without it no user transcript ever
+ * arrives — which silently reduces `relay` to a microphone that does
+ * nothing and `realtime` to an assistant-only transcript.
+ */
+import type { FunctionTool, Tool, VoiceLiveSessionConfig } from "@iloveagents/foundry-voice-live-react";
+import type { ToolRegistry } from "@iloveagents/foundry-agent";
+import type { VoiceMode } from "./types.ts";
+/**
+ * AG-UI tool schemas → Voice Live function tools.
+ *
+ * The two shapes are the same object plus a discriminator, which is the
+ * point: a tool the typed chat can call is callable by voice with no second
+ * declaration and no drift between them.
+ */
+export declare function toVoiceLiveTools(registry: ToolRegistry): FunctionTool[];
+export interface BuildVoiceSessionOptions {
+    mode: VoiceMode;
+    /** Host overrides, applied last — an explicit value always wins. */
+    overrides?: VoiceLiveSessionConfig;
+    /** Present only when the host opted into exposing client tools in `realtime`. */
+    registry?: ToolRegistry;
+}
+/**
+ * Build the session config for a mode.
+ *
+ * Precedence is deliberate and shallow-per-key: mode defaults, then host
+ * overrides. `turnDetection` merges key-by-key so a host can retune VAD
+ * (threshold, eagerness, filler words) without having to re-state
+ * `createResponse` and silently break the mode.
+ */
+export declare function buildVoiceSession({ mode, overrides, registry, }: BuildVoiceSessionOptions): VoiceLiveSessionConfig;
+/**
+ * The tool catalogue a session carries: the registry's client tools merged
+ * with whatever the host declared.
+ *
+ * Exported because `session.update` REPLACES the catalogue rather than adding
+ * to it, so the live re-sync has to rebuild the very same list this file
+ * builds at connect time. Two places deriving it independently is precisely
+ * how the host's MCP tools went missing the moment a session became ready.
+ */
+export declare function sessionTools(registry: ToolRegistry | undefined, hostTools: Tool[] | undefined): Tool[] | undefined;

package/dist/adapter/session-config.js

@@ -0,0 +1,148 @@
+/**
+ * Derive the Voice Live session from the chosen mode.
+ *
+ * Two settings carry the whole behavioural difference between the modes, and
+ * both are documented Voice Live features rather than anything clever:
+ *
+ *   - `turn_detection.create_response` — "Enable or disable whether a
+ *     response is generated (default: true)". `relay` sets it false, so the
+ *     Voice Live model never answers; the app's AG-UI agent does, and the
+ *     answer is spoken back with `pre_generated_assistant_message`.
+ *   - `tools` — only `realtime` gets them, because only there is the Voice
+ *     Live model the one deciding to call something.
+ *
+ * `input_audio_transcription` is forced on for both modes. The SDK's
+ * `DEFAULT_SESSION_CONFIG` omits it, and without it no user transcript ever
+ * arrives — which silently reduces `relay` to a microphone that does
+ * nothing and `realtime` to an assistant-only transcript.
+ */
+/**
+ * Transcription model. `mai-transcribe` is the Voice Live model that works
+ * with every model and agent, rather than only the OpenAI-native ones.
+ */
+const DEFAULT_TRANSCRIPTION_MODEL = "mai-transcribe";
+/**
+ * Green screen, so the avatar can be keyed out and sit on the app's own
+ * background.
+ *
+ * `VoiceLiveAvatar` chroma-keys by default, but only the *session* can ask
+ * Azure to render a keyable background — without this the service composites
+ * the avatar onto opaque white, the chroma key finds no green, and the
+ * result is a white rectangle pasted over the page.
+ */
+const GREEN_SCREEN = "#00FF00FF";
+/**
+ * AG-UI tool schemas → Voice Live function tools.
+ *
+ * The two shapes are the same object plus a discriminator, which is the
+ * point: a tool the typed chat can call is callable by voice with no second
+ * declaration and no drift between them.
+ */
+export function toVoiceLiveTools(registry) {
+    return registry.getActiveSchemas().map((schema) => ({
+        type: "function",
+        name: schema.name,
+        description: schema.description ?? "",
+        parameters: (schema.parameters ?? {}),
+    }));
+}
+/**
+ * Build the session config for a mode.
+ *
+ * Precedence is deliberate and shallow-per-key: mode defaults, then host
+ * overrides. `turnDetection` merges key-by-key so a host can retune VAD
+ * (threshold, eagerness, filler words) without having to re-state
+ * `createResponse` and silently break the mode.
+ */
+export function buildVoiceSession({ mode, overrides, registry, }) {
+    const isRelay = mode === "relay";
+    const tools = registry ? toVoiceLiveTools(registry) : undefined;
+    const base = {
+        modalities: ["text", "audio"],
+        inputAudioTranscription: { model: DEFAULT_TRANSCRIPTION_MODEL },
+        turnDetection: {
+            type: "azure_semantic_vad",
+            // Barge-in, and keep the server's transcript honest about what was
+            // actually heard before the interruption.
+            interruptResponse: true,
+            autoTruncate: true,
+            createResponse: !isRelay,
+        },
+    };
+    // An empty tool list is not the same as "no tools": sending `tools: []`
+    // states there are none, which is right for relay and wrong to send when
+    // the host simply did not opt in.
+    if (tools !== undefined) {
+        base.tools = tools;
+        base.toolChoice = "auto";
+    }
+    if (!overrides)
+        return withKeyableAvatarBackground(base);
+    return withKeyableAvatarBackground({
+        ...base,
+        ...overrides,
+        // Tools MERGE rather than replace. A host declaring an MCP server or a
+        // Foundry agent tool is adding server-side capability, not withdrawing
+        // the browser's — and a plain spread would silently drop every client
+        // tool the moment one was declared, leaving the model unable to touch
+        // the UI with no error to explain why.
+        tools: sessionTools(registry, overrides.tools),
+        turnDetection: overrides.turnDetection === undefined
+            ? base.turnDetection
+            : overrides.turnDetection === null
+                ? null
+                : { ...base.turnDetection, ...overrides.turnDetection },
+    });
+}
+/**
+ * Give a configured avatar a keyable background unless the host chose one.
+ *
+ * A host that wants the avatar composited on a colour or an image says so and
+ * is left alone; the default is the one that composes with any theme.
+ */
+function withKeyableAvatarBackground(session) {
+    const avatar = session.avatar;
+    if (!avatar || avatar.video?.background !== undefined)
+        return session;
+    return {
+        ...session,
+        avatar: {
+            ...avatar,
+            video: { ...avatar.video, background: { color: GREEN_SCREEN } },
+        },
+    };
+}
+/**
+ * The tool catalogue a session carries: the registry's client tools merged
+ * with whatever the host declared.
+ *
+ * Exported because `session.update` REPLACES the catalogue rather than adding
+ * to it, so the live re-sync has to rebuild the very same list this file
+ * builds at connect time. Two places deriving it independently is precisely
+ * how the host's MCP tools went missing the moment a session became ready.
+ */
+export function sessionTools(registry, hostTools) {
+    return mergeTools(registry ? toVoiceLiveTools(registry) : undefined, hostTools);
+}
+/**
+ * Combine the registry's function tools with whatever the host declared.
+ *
+ * Function tools are keyed by name so a host can deliberately override one
+ * of the registry's; everything else (MCP servers, Foundry agent tools) is
+ * additive, since those are distinct capabilities rather than replacements.
+ */
+function mergeTools(base, extra) {
+    if (!base)
+        return extra;
+    if (!extra)
+        return base;
+    const byName = new Map();
+    const others = [];
+    for (const tool of [...base, ...extra]) {
+        if (tool.type === "function")
+            byName.set(tool.name, tool);
+        else
+            others.push(tool);
+    }
+    return [...byName.values(), ...others];
+}

package/dist/adapter/speech-queue.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Turning a streaming markdown answer into spoken audio.
+ *
+ * Three separate problems, kept separate:
+ *
+ * 1. **What to say.** The agent writes markdown for a reader. Read aloud
+ *    verbatim it becomes "asterisk asterisk important asterisk asterisk",
+ *    and foundry's `[1]` citation markers become "bracket one". `toSpeakableText`
+ *    strips the notation and keeps the prose.
+ *
+ * 2. **When to say it.** Waiting for the whole answer wastes the seconds the
+ *    agent spends writing it. `SentenceStream` takes cumulative text and
+ *    hands back complete sentences as they finish, so speech starts on the
+ *    first full sentence.
+ *
+ * 3. **One at a time.** Voice Live rejects overlapping responses. The SDK's
+ *    own `ResponseGate` serializes them, but it deliberately collapses
+ *    everything queued during one response into a *single* follow-up — the
+ *    right behaviour for turns, fatal for a sentence queue, where
+ *    collapsing three pending sentences into one would drop two of them.
+ *    `SpeechQueue` therefore keeps its own FIFO and releases the next
+ *    utterance only once the previous response is done.
+ */
+/**
+ * Markdown → text a voice can read.
+ *
+ * Deliberately lossy: code blocks and table rules are dropped rather than
+ * spelled out, because hearing punctuation read aloud is worse than not
+ * hearing it at all. What survives is the prose.
+ */
+export declare function toSpeakableText(markdown: string, options?: {
+    final?: boolean;
+}): string;
+/**
+ * Cuts cumulative streaming text into speakable utterances.
+ *
+ * Fed the *whole* answer so far on each call (which is what assistant-ui
+ * exposes — parts carry cumulative text, not deltas) and returns only what
+ * has not been emitted yet.
+ */
+export declare class SentenceStream {
+    /** How much of the answer has been turned into emitted utterances. */
+    private consumed;
+    /** Exactly that prefix, kept so a rewrite of it can be detected. */
+    private consumedText;
+    /**
+     * Every position an utterance has ended at, 0 first.
+     *
+     * A rewrite inside already-spoken text can only be repaired at one of these.
+     * Rewinding to the raw point of divergence resumes mid-word — "…ly different
+     * answer" — because the divergence lands wherever the two strings happen to
+     * part, which is usually inside a word.
+     */
+    private boundaries;
+    /** The last cumulative answer seen, kept so `flush()` can finish it. */
+    private text;
+    /**
+     * @param cumulative the full answer so far, already run through `toSpeakableText`
+     * @returns complete utterances that became available with this update
+     */
+    push(cumulative: string): string[];
+    /** Emit whatever is left, complete sentence or not. Call when the answer ends. */
+    flush(): string[];
+    reset(): void;
+    private take;
+    private advanceTo;
+}
+/**
+ * A strict FIFO of utterances, one on the wire at a time.
+ *
+ * `send` puts one utterance on the wire. `onResponseDone` must be called
+ * when the service reports that response finished — that is the only thing
+ * that releases the next one.
+ */
+export declare class SpeechQueue {
+    private readonly send;
+    private readonly pending;
+    private speaking;
+    constructor(send: (text: string) => void);
+    get isSpeaking(): boolean;
+    get pendingCount(): number;
+    enqueue(text: string): void;
+    /** The in-flight response finished; release the next utterance. */
+    onResponseDone(): void;
+    /**
+     * Barge-in or a new turn: forget everything still queued.
+     *
+     * `speaking` is cleared too. The caller cancels the in-flight response on
+     * the wire, and a cancelled response may never produce the `response.done`
+     * that would otherwise release the queue — leaving it wedged shut for the
+     * rest of the session.
+     */
+    cancel(): void;
+    private pump;
+}