@shogo-ai/voice 1.9.13 → 2.4.1

package/dist/server.d.cts

@@ -1,5 +1,5 @@
 import * as node_http from 'node:http';
-import { y as VoiceUser, r as ElevenLabsClient, f as CompanionStore, V as VoiceMemoryStore } from './types-W9y6eMj3.cjs';
+import { V as VoiceUser, E as ElevenLabsClient, C as CompanionStore, a as VoiceMemoryStore } from './types-CadjTXNH.cjs';
 
 type GetVoiceUser = (req: Request) => Promise<VoiceUser | null> | VoiceUser | null;
 /**
@@ -11,15 +11,33 @@ type GetVoiceUser = (req: Request) => Promise<VoiceUser | null> | VoiceUser | nu
  * Auto-detection looks for:
  *   - `process.env.RUNTIME_AUTH_SECRET` (pod-injected runtime token)
  *   - `process.env.PROJECT_ID` (pod-injected project scope)
- *   - `process.env.SHOGO_API_URL` (defaults to `http://localhost:8002`)
+ *   - `process.env.SHOGO_API_URL` (falls back to `SHOGO_CLOUD_URL`)
+ *
+ * The API host is resolved per request, not at construction, so a pod
+ * that sets the token without a host still gets every local-only
+ * handler (body validation, 405s, the static audio-tags catalog) and
+ * only the call that actually leaves the process refuses to guess.
  */
 interface VoiceProxyOptions {
     runtimeToken: string;
     projectId: string;
+    /**
+     * Base URL of the Shogo API. Empty string when the proxy was derived
+     * from env: the host is then re-read from `SHOGO_API_URL` /
+     * `SHOGO_CLOUD_URL` on each proxied call.
+     */
     apiUrl: string;
     /** Custom fetch impl (forwarded to the proxy fetches). */
     fetch?: typeof fetch;
 }
+/**
+ * How the handlers should reach ElevenLabs:
+ *   - `'byo'`   — always use the supplied `apiKey`, even inside a pod
+ *   - `'proxy'` — always go through the Shogo API with the runtime token
+ *   - `'auto'`  — (default) an explicit `apiKey` wins, otherwise use the
+ *                 ambient pod runtime token when present
+ */
+type VoiceHandlerMode = 'proxy' | 'byo' | 'auto';
 interface VoiceHandlersConfig {
     /**
      * 11Labs API key. Required in BYO-EL mode; ignored / optional when
@@ -28,16 +46,23 @@ interface VoiceHandlersConfig {
     apiKey?: string;
     /**
      * Resolve the authenticated user from a request, or `null` for
-     * unauthenticated. Required in BYO-EL mode; optional in proxy mode —
-     * the Shogo API handles user-less project-scoped auth via the runtime
-     * token, and per-user memory is out of scope for pod apps.
+     * unauthenticated. Required for the user-scoped handlers (`signedUrl`,
+     * `agent.*`); optional for `tts` / `music`, which are project-scoped and
+     * work without a user context.
      */
     getUser?: GetVoiceUser;
     /**
-     * Consumer-owned persistence layer for Companion records. Required
-     * in BYO-EL mode; unused in proxy mode.
+     * Consumer-owned persistence layer for Companion records. Required for
+     * the user-scoped handlers (`signedUrl`, `agent.*`); unused by `tts` /
+     * `music` and by proxy mode.
      */
     companionStore?: CompanionStore;
+    /**
+     * Force a transport: `'byo'` always uses `apiKey`, `'proxy'` always uses
+     * the runtime token, `'auto'` (default) prefers an explicit `apiKey` and
+     * falls back to the ambient pod runtime token.
+     */
+    mode?: VoiceHandlerMode;
     /** Optional memory store — when present, `signedUrl` preloads context bullets. */
     memoryStore?: (userId: string) => VoiceMemoryStore;
     /**
@@ -81,6 +106,13 @@ interface VoiceHandlers {
     };
     /** `GET /voice/audio-tags` — static catalog + defaults (no auth required). */
     audioTags: (req: Request) => Promise<Response>;
+    /**
+     * Any op in the {@link VOICE_OPS} registry — `handlers.op(req, 'speech-to-speech')`.
+     * `opId` may be omitted when the request URL carries it (last path segment,
+     * e.g. `/api/voice/op/speech-to-speech`). Adding a registry row makes it
+     * callable here with no other change.
+     */
+    op: (req: Request, opId?: string) => Promise<Response>;
     /**
      * The underlying ElevenLabsClient, exposed for consumers who need to build
      * additional endpoints (e.g. an agent-driven God Mode settings editor).
@@ -91,4 +123,4 @@ declare function createVoiceHandlers(config: VoiceHandlersConfig): VoiceHandlers
 /** Wrap a handler for Node `http.createServer` style callbacks. */
 declare function toNodeListener(handler: (req: Request) => Promise<Response>): (req: node_http.IncomingMessage, res: node_http.ServerResponse) => void;
 
-export { type GetVoiceUser, type VoiceHandlers, type VoiceHandlersConfig, type VoiceProxyOptions, createVoiceHandlers, toNodeListener };
+export { type GetVoiceUser, type VoiceHandlerMode, type VoiceHandlers, type VoiceHandlersConfig, type VoiceProxyOptions, createVoiceHandlers, toNodeListener };

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import * as node_http from 'node:http';
-import { y as VoiceUser, r as ElevenLabsClient, f as CompanionStore, V as VoiceMemoryStore } from './types-W9y6eMj3.js';
+import { V as VoiceUser, E as ElevenLabsClient, C as CompanionStore, a as VoiceMemoryStore } from './types-CadjTXNH.js';
 
 type GetVoiceUser = (req: Request) => Promise<VoiceUser | null> | VoiceUser | null;
 /**
@@ -11,15 +11,33 @@ type GetVoiceUser = (req: Request) => Promise<VoiceUser | null> | VoiceUser | nu
  * Auto-detection looks for:
  *   - `process.env.RUNTIME_AUTH_SECRET` (pod-injected runtime token)
  *   - `process.env.PROJECT_ID` (pod-injected project scope)
- *   - `process.env.SHOGO_API_URL` (defaults to `http://localhost:8002`)
+ *   - `process.env.SHOGO_API_URL` (falls back to `SHOGO_CLOUD_URL`)
+ *
+ * The API host is resolved per request, not at construction, so a pod
+ * that sets the token without a host still gets every local-only
+ * handler (body validation, 405s, the static audio-tags catalog) and
+ * only the call that actually leaves the process refuses to guess.
  */
 interface VoiceProxyOptions {
     runtimeToken: string;
     projectId: string;
+    /**
+     * Base URL of the Shogo API. Empty string when the proxy was derived
+     * from env: the host is then re-read from `SHOGO_API_URL` /
+     * `SHOGO_CLOUD_URL` on each proxied call.
+     */
     apiUrl: string;
     /** Custom fetch impl (forwarded to the proxy fetches). */
     fetch?: typeof fetch;
 }
+/**
+ * How the handlers should reach ElevenLabs:
+ *   - `'byo'`   — always use the supplied `apiKey`, even inside a pod
+ *   - `'proxy'` — always go through the Shogo API with the runtime token
+ *   - `'auto'`  — (default) an explicit `apiKey` wins, otherwise use the
+ *                 ambient pod runtime token when present
+ */
+type VoiceHandlerMode = 'proxy' | 'byo' | 'auto';
 interface VoiceHandlersConfig {
     /**
      * 11Labs API key. Required in BYO-EL mode; ignored / optional when
@@ -28,16 +46,23 @@ interface VoiceHandlersConfig {
     apiKey?: string;
     /**
      * Resolve the authenticated user from a request, or `null` for
-     * unauthenticated. Required in BYO-EL mode; optional in proxy mode —
-     * the Shogo API handles user-less project-scoped auth via the runtime
-     * token, and per-user memory is out of scope for pod apps.
+     * unauthenticated. Required for the user-scoped handlers (`signedUrl`,
+     * `agent.*`); optional for `tts` / `music`, which are project-scoped and
+     * work without a user context.
      */
     getUser?: GetVoiceUser;
     /**
-     * Consumer-owned persistence layer for Companion records. Required
-     * in BYO-EL mode; unused in proxy mode.
+     * Consumer-owned persistence layer for Companion records. Required for
+     * the user-scoped handlers (`signedUrl`, `agent.*`); unused by `tts` /
+     * `music` and by proxy mode.
      */
     companionStore?: CompanionStore;
+    /**
+     * Force a transport: `'byo'` always uses `apiKey`, `'proxy'` always uses
+     * the runtime token, `'auto'` (default) prefers an explicit `apiKey` and
+     * falls back to the ambient pod runtime token.
+     */
+    mode?: VoiceHandlerMode;
     /** Optional memory store — when present, `signedUrl` preloads context bullets. */
     memoryStore?: (userId: string) => VoiceMemoryStore;
     /**
@@ -81,6 +106,13 @@ interface VoiceHandlers {
     };
     /** `GET /voice/audio-tags` — static catalog + defaults (no auth required). */
     audioTags: (req: Request) => Promise<Response>;
+    /**
+     * Any op in the {@link VOICE_OPS} registry — `handlers.op(req, 'speech-to-speech')`.
+     * `opId` may be omitted when the request URL carries it (last path segment,
+     * e.g. `/api/voice/op/speech-to-speech`). Adding a registry row makes it
+     * callable here with no other change.
+     */
+    op: (req: Request, opId?: string) => Promise<Response>;
     /**
      * The underlying ElevenLabsClient, exposed for consumers who need to build
      * additional endpoints (e.g. an agent-driven God Mode settings editor).
@@ -91,4 +123,4 @@ declare function createVoiceHandlers(config: VoiceHandlersConfig): VoiceHandlers
 /** Wrap a handler for Node `http.createServer` style callbacks. */
 declare function toNodeListener(handler: (req: Request) => Promise<Response>): (req: node_http.IncomingMessage, res: node_http.ServerResponse) => void;
 
-export { type GetVoiceUser, type VoiceHandlers, type VoiceHandlersConfig, type VoiceProxyOptions, createVoiceHandlers, toNodeListener };
+export { type GetVoiceUser, type VoiceHandlerMode, type VoiceHandlers, type VoiceHandlersConfig, type VoiceProxyOptions, createVoiceHandlers, toNodeListener };

package/dist/server.js

@@ -1,8 +1,8 @@
 import {
   createVoiceHandlers,
   toNodeListener
-} from "./chunk-O362EJQR.js";
-import "./chunk-B4JC3DK2.js";
+} from "./chunk-CLF25CZC.js";
+import "./chunk-XE4LLC7Z.js";
 import "./chunk-Q3TJAJ54.js";
 export {
   createVoiceHandlers,

package/dist/types-Bfhu-aQH.d.cts

@@ -0,0 +1,199 @@
+/**
+ * Shared option / result types for `useVoiceConversation` across
+ * platforms. The web hook ([packages/sdk/src/voice/react]) and the
+ * native hook ([packages/sdk/src/voice/native]) both export their own
+ * `UseVoiceConversationOptions` / `UseVoiceConversationResult`
+ * types — typically by re-exporting `BaseVoiceConversationOptions` /
+ * `BaseVoiceConversationResult` from this module — so consumers can
+ * import them from whichever subpath they're using.
+ */
+interface BaseVoiceConversationOptions {
+    /** Name of the companion the user is talking to (passed as a dynamic variable). */
+    characterName: string;
+    /** Server path that mints an 11Labs signed URL for this user. Default: `/api/voice/signed-url`. */
+    signedUrlPath?: string;
+    /** Server path the built-in `add_memory` tool POSTs to. Default: `/api/memory/add`. */
+    memoryAddPath?: string;
+    /** Server path used to auto-inject memory context. Default: `/api/memory/retrieve`. */
+    memoryRetrievePath?: string;
+    /** Server path the transcript is POSTed to when the session ends. Default: `/api/memory/ingest`. */
+    transcriptIngestPath?: string;
+    /** Disable the built-in memory context auto-injection. Default: `true` (enabled). */
+    autoInjectMemory?: boolean;
+    /** Disable the built-in `add_memory` client tool. Default: `true` (enabled). */
+    includeMemoryTool?: boolean;
+    /**
+     * Additional client tools merged onto `add_memory`. Tools defined here with
+     * the name `add_memory` override the built-in implementation.
+     */
+    clientTools?: Record<string, (params: Record<string, unknown>) => Promise<string> | string>;
+    /**
+     * Called once per session with the accumulated transcript when the session
+     * disconnects. Defaults to POST `transcriptIngestPath`; set this to suppress
+     * or replace that behaviour.
+     */
+    onTranscript?: (transcript: string) => void | Promise<void>;
+    /**
+     * Credentials mode for built-in fetch calls.
+     *
+     * - Defaults to `same-origin` in the legacy cookie path.
+     * - Defaults to `omit` when `shogoApiKey` is provided (bearer auth is
+     *   self-contained and you don't want browsers to attach unrelated
+     *   third-party cookies cross-origin).
+     * - Explicit values always win — pass `'include'` to carry both a cookie
+     *   and the bearer in a hybrid same-origin app.
+     */
+    fetchCredentials?: RequestCredentials;
+    /**
+     * Shogo API key (`shogo_sk_*`) used to authenticate voice routes. When
+     * provided, the hook attaches `Authorization: Bearer <key>` to the
+     * signed-URL fetch and memory fetches, and appends `?projectId=` to
+     * the signed-URL path. Either `shogoApiKey` or a session cookie must
+     * be resolvable by the server — both may be passed; the server's
+     * `apiKeyOrSession` middleware picks bearer first.
+     */
+    shogoApiKey?: string;
+    /**
+     * Project id (Shogo's `projectId`). Required alongside `shogoApiKey`
+     * for Mode B voice. The server uses it to look up / provision the
+     * project's ElevenLabs agent and resolve the workspace.
+     */
+    projectId?: string;
+    /**
+     * Optional named agent to talk to. Forwarded as `?agentName=` on
+     * the signed-URL fetch and resolved server-side to a project-scoped
+     * `ProjectAgent` row (created via `shogo deploy`). When omitted,
+     * the server resolves the project's `default` agent.
+     *
+     * The same `agentName` reaches the same persona via
+     * `useChatConversation({ agentName })` — voice and chat are two
+     * transports for one agent record.
+     */
+    agentName?: string;
+    /** Called on connection errors. */
+    onError?: (error: unknown) => void;
+    /** Called on each message (user or agent) for debugging / custom UI. */
+    onMessage?: (message: {
+        source: string;
+        message: string;
+    }) => void;
+    /**
+     * Stable conversation id used to correlate this voice session with
+     * a sibling text thread (see `BaseChatConversationOptions.conversationId`).
+     *
+     * When set, forwarded to ElevenLabs as a `conversation_id` dynamic
+     * variable so the agent's prompt can reference it (`{{conversation_id}}`),
+     * and surfaced on `BaseVoiceConversationResult.conversationId` so a
+     * single bridge component can read the same value from either hook.
+     *
+     * Independent of the convai-side conversation id — see
+     * `BaseVoiceConversationResult.convaiConversationId` for that. The
+     * caller-supplied value wins on `result.conversationId` so consumers
+     * who keep their own thread store don't have to special-case the
+     * default. Optional; when omitted, `result.conversationId` mirrors
+     * the convai conversation id once the session connects.
+     */
+    conversationId?: string;
+    /**
+     * Extra dynamic variables forwarded to ElevenLabs at session start.
+     * Merged on top of the SDK's built-in variables — `character_name`,
+     * `user_context`, and `conversation_id` (when supplied) always win
+     * on collision so consumers can't accidentally override them.
+     *
+     * Typical use: surface per-user fields from the consumer's own
+     * `Companion` row (display name, relationship stage, custom greeting
+     * tokens) so the agent's prompt can reference them via
+     * `{{var_name}}`. Variables also need to be declared in the agent's
+     * `dynamic_variable_placeholders` (set at deploy time) for EL to
+     * pick up the value.
+     *
+     * Non-string values are coerced via `String(...)` before being
+     * forwarded; `null` / `undefined` values are silently dropped.
+     */
+    dynamicVariables?: Record<string, unknown> | null;
+}
+interface BaseVoiceConversationResult {
+    /**
+     * Begin a new session. Requests microphone permission and fetches a
+     * signed URL.
+     *
+     * `suppressFirstMessage` mirrors the option on `restart()` — when
+     * `true`, the new session is opened with `overrides.agent.firstMessage = ''`
+     * so the agent skips its opening greeting. Useful when the consumer
+     * is programmatically reconnecting (e.g. to deliver a one-shot spoken
+     * summary) and does not want to hear the configured intro.
+     */
+    start: (options?: {
+        suppressFirstMessage?: boolean;
+    }) => Promise<void>;
+    /** End the current session (if any). */
+    end: () => void;
+    /**
+     * Tear down the active session and immediately reconnect. Primarily
+     * used as a programmatic barge-in: ElevenLabs doesn't expose a public
+     * `interrupt()` on `useConversation`, so stopping the agent mid-
+     * utterance requires a fast disconnect + reconnect. When
+     * `suppressFirstMessage` is `true` (the default), the new session is
+     * started with `overrides.agent.firstMessage = ''` so the agent does
+     * not replay its intro. The accumulated transcript is preserved
+     * across the reconnect gap.
+     */
+    restart: (options?: {
+        suppressFirstMessage?: boolean;
+    }) => Promise<void>;
+    /** `'disconnected' | 'connecting' | 'connected'`. */
+    status: 'disconnected' | 'connecting' | 'connected';
+    /** Whether the agent is currently speaking. */
+    isSpeaking: boolean;
+    /** Whether the agent is currently listening. */
+    isListening: boolean;
+    /** Whether the microphone is currently muted (input audio is gated off). */
+    isMuted: boolean;
+    /**
+     * Toggle the microphone mute state without tearing down the session.
+     * Wraps `@elevenlabs/react` (or `@elevenlabs/react-native`)'s
+     * `setMuted`, which in turn calls `conversation.setMicMuted()`.
+     * Muting does not end the WebSocket or release the underlying media
+     * stream; it simply stops input audio from being forwarded to the
+     * server.
+     */
+    setMuted: (isMuted: boolean) => void;
+    /** For consumers who want to drive their own visualisation / lipsync. */
+    getOutputByteFrequencyData: () => Uint8Array | null;
+    /** Imperatively send a contextual update (e.g. "user navigated to X"). */
+    sendContextualUpdate: (text: string) => void;
+    /**
+     * Imperatively inject a user-role message, forcing the agent to take
+     * its next turn immediately (rather than waiting for the human to
+     * speak). Useful for out-of-band prompts like "please summarise what
+     * just happened". The injected text is *not* spoken aloud — the agent
+     * treats it as if the user said it.
+     */
+    sendUserMessage: (text: string) => void;
+    /**
+     * Low-level signal that the user is active (typing, clicking) so the
+     * agent doesn't try to fill silence. Used as a fallback nudge when we
+     * want to keep the session "warm" without forcing a full turn.
+     */
+    sendUserActivity: () => void;
+    /**
+     * Stable conversation id for cross-transport correlation. Returns the
+     * caller-supplied `BaseVoiceConversationOptions.conversationId` when
+     * one was provided; otherwise mirrors the convai conversation id once
+     * the session connects (and is `null` while disconnected).
+     *
+     * Pass this same value to `useChatConversation({ conversationId })`
+     * to stitch a text thread onto the same logical conversation.
+     */
+    conversationId: string | null;
+    /**
+     * The convai-side conversation id reported by ElevenLabs on connect.
+     * Always reflects the underlying transport id (or `null` while
+     * disconnected) regardless of whether the consumer supplied an id.
+     * Useful for log correlation against ElevenLabs dashboards even
+     * when the consumer is using their own ids on `conversationId`.
+     */
+    convaiConversationId: string | null;
+}
+
+export type { BaseVoiceConversationOptions as B, BaseVoiceConversationResult as a };

package/dist/types-Bfhu-aQH.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Shared option / result types for `useVoiceConversation` across
+ * platforms. The web hook ([packages/sdk/src/voice/react]) and the
+ * native hook ([packages/sdk/src/voice/native]) both export their own
+ * `UseVoiceConversationOptions` / `UseVoiceConversationResult`
+ * types — typically by re-exporting `BaseVoiceConversationOptions` /
+ * `BaseVoiceConversationResult` from this module — so consumers can
+ * import them from whichever subpath they're using.
+ */
+interface BaseVoiceConversationOptions {
+    /** Name of the companion the user is talking to (passed as a dynamic variable). */
+    characterName: string;
+    /** Server path that mints an 11Labs signed URL for this user. Default: `/api/voice/signed-url`. */
+    signedUrlPath?: string;
+    /** Server path the built-in `add_memory` tool POSTs to. Default: `/api/memory/add`. */
+    memoryAddPath?: string;
+    /** Server path used to auto-inject memory context. Default: `/api/memory/retrieve`. */
+    memoryRetrievePath?: string;
+    /** Server path the transcript is POSTed to when the session ends. Default: `/api/memory/ingest`. */
+    transcriptIngestPath?: string;
+    /** Disable the built-in memory context auto-injection. Default: `true` (enabled). */
+    autoInjectMemory?: boolean;
+    /** Disable the built-in `add_memory` client tool. Default: `true` (enabled). */
+    includeMemoryTool?: boolean;
+    /**
+     * Additional client tools merged onto `add_memory`. Tools defined here with
+     * the name `add_memory` override the built-in implementation.
+     */
+    clientTools?: Record<string, (params: Record<string, unknown>) => Promise<string> | string>;
+    /**
+     * Called once per session with the accumulated transcript when the session
+     * disconnects. Defaults to POST `transcriptIngestPath`; set this to suppress
+     * or replace that behaviour.
+     */
+    onTranscript?: (transcript: string) => void | Promise<void>;
+    /**
+     * Credentials mode for built-in fetch calls.
+     *
+     * - Defaults to `same-origin` in the legacy cookie path.
+     * - Defaults to `omit` when `shogoApiKey` is provided (bearer auth is
+     *   self-contained and you don't want browsers to attach unrelated
+     *   third-party cookies cross-origin).
+     * - Explicit values always win — pass `'include'` to carry both a cookie
+     *   and the bearer in a hybrid same-origin app.
+     */
+    fetchCredentials?: RequestCredentials;
+    /**
+     * Shogo API key (`shogo_sk_*`) used to authenticate voice routes. When
+     * provided, the hook attaches `Authorization: Bearer <key>` to the
+     * signed-URL fetch and memory fetches, and appends `?projectId=` to
+     * the signed-URL path. Either `shogoApiKey` or a session cookie must
+     * be resolvable by the server — both may be passed; the server's
+     * `apiKeyOrSession` middleware picks bearer first.
+     */
+    shogoApiKey?: string;
+    /**
+     * Project id (Shogo's `projectId`). Required alongside `shogoApiKey`
+     * for Mode B voice. The server uses it to look up / provision the
+     * project's ElevenLabs agent and resolve the workspace.
+     */
+    projectId?: string;
+    /**
+     * Optional named agent to talk to. Forwarded as `?agentName=` on
+     * the signed-URL fetch and resolved server-side to a project-scoped
+     * `ProjectAgent` row (created via `shogo deploy`). When omitted,
+     * the server resolves the project's `default` agent.
+     *
+     * The same `agentName` reaches the same persona via
+     * `useChatConversation({ agentName })` — voice and chat are two
+     * transports for one agent record.
+     */
+    agentName?: string;
+    /** Called on connection errors. */
+    onError?: (error: unknown) => void;
+    /** Called on each message (user or agent) for debugging / custom UI. */
+    onMessage?: (message: {
+        source: string;
+        message: string;
+    }) => void;
+    /**
+     * Stable conversation id used to correlate this voice session with
+     * a sibling text thread (see `BaseChatConversationOptions.conversationId`).
+     *
+     * When set, forwarded to ElevenLabs as a `conversation_id` dynamic
+     * variable so the agent's prompt can reference it (`{{conversation_id}}`),
+     * and surfaced on `BaseVoiceConversationResult.conversationId` so a
+     * single bridge component can read the same value from either hook.
+     *
+     * Independent of the convai-side conversation id — see
+     * `BaseVoiceConversationResult.convaiConversationId` for that. The
+     * caller-supplied value wins on `result.conversationId` so consumers
+     * who keep their own thread store don't have to special-case the
+     * default. Optional; when omitted, `result.conversationId` mirrors
+     * the convai conversation id once the session connects.
+     */
+    conversationId?: string;
+    /**
+     * Extra dynamic variables forwarded to ElevenLabs at session start.
+     * Merged on top of the SDK's built-in variables — `character_name`,
+     * `user_context`, and `conversation_id` (when supplied) always win
+     * on collision so consumers can't accidentally override them.
+     *
+     * Typical use: surface per-user fields from the consumer's own
+     * `Companion` row (display name, relationship stage, custom greeting
+     * tokens) so the agent's prompt can reference them via
+     * `{{var_name}}`. Variables also need to be declared in the agent's
+     * `dynamic_variable_placeholders` (set at deploy time) for EL to
+     * pick up the value.
+     *
+     * Non-string values are coerced via `String(...)` before being
+     * forwarded; `null` / `undefined` values are silently dropped.
+     */
+    dynamicVariables?: Record<string, unknown> | null;
+}
+interface BaseVoiceConversationResult {
+    /**
+     * Begin a new session. Requests microphone permission and fetches a
+     * signed URL.
+     *
+     * `suppressFirstMessage` mirrors the option on `restart()` — when
+     * `true`, the new session is opened with `overrides.agent.firstMessage = ''`
+     * so the agent skips its opening greeting. Useful when the consumer
+     * is programmatically reconnecting (e.g. to deliver a one-shot spoken
+     * summary) and does not want to hear the configured intro.
+     */
+    start: (options?: {
+        suppressFirstMessage?: boolean;
+    }) => Promise<void>;
+    /** End the current session (if any). */
+    end: () => void;
+    /**
+     * Tear down the active session and immediately reconnect. Primarily
+     * used as a programmatic barge-in: ElevenLabs doesn't expose a public
+     * `interrupt()` on `useConversation`, so stopping the agent mid-
+     * utterance requires a fast disconnect + reconnect. When
+     * `suppressFirstMessage` is `true` (the default), the new session is
+     * started with `overrides.agent.firstMessage = ''` so the agent does
+     * not replay its intro. The accumulated transcript is preserved
+     * across the reconnect gap.
+     */
+    restart: (options?: {
+        suppressFirstMessage?: boolean;
+    }) => Promise<void>;
+    /** `'disconnected' | 'connecting' | 'connected'`. */
+    status: 'disconnected' | 'connecting' | 'connected';
+    /** Whether the agent is currently speaking. */
+    isSpeaking: boolean;
+    /** Whether the agent is currently listening. */
+    isListening: boolean;
+    /** Whether the microphone is currently muted (input audio is gated off). */
+    isMuted: boolean;
+    /**
+     * Toggle the microphone mute state without tearing down the session.
+     * Wraps `@elevenlabs/react` (or `@elevenlabs/react-native`)'s
+     * `setMuted`, which in turn calls `conversation.setMicMuted()`.
+     * Muting does not end the WebSocket or release the underlying media
+     * stream; it simply stops input audio from being forwarded to the
+     * server.
+     */
+    setMuted: (isMuted: boolean) => void;
+    /** For consumers who want to drive their own visualisation / lipsync. */
+    getOutputByteFrequencyData: () => Uint8Array | null;
+    /** Imperatively send a contextual update (e.g. "user navigated to X"). */
+    sendContextualUpdate: (text: string) => void;
+    /**
+     * Imperatively inject a user-role message, forcing the agent to take
+     * its next turn immediately (rather than waiting for the human to
+     * speak). Useful for out-of-band prompts like "please summarise what
+     * just happened". The injected text is *not* spoken aloud — the agent
+     * treats it as if the user said it.
+     */
+    sendUserMessage: (text: string) => void;
+    /**
+     * Low-level signal that the user is active (typing, clicking) so the
+     * agent doesn't try to fill silence. Used as a fallback nudge when we
+     * want to keep the session "warm" without forcing a full turn.
+     */
+    sendUserActivity: () => void;
+    /**
+     * Stable conversation id for cross-transport correlation. Returns the
+     * caller-supplied `BaseVoiceConversationOptions.conversationId` when
+     * one was provided; otherwise mirrors the convai conversation id once
+     * the session connects (and is `null` while disconnected).
+     *
+     * Pass this same value to `useChatConversation({ conversationId })`
+     * to stitch a text thread onto the same logical conversation.
+     */
+    conversationId: string | null;
+    /**
+     * The convai-side conversation id reported by ElevenLabs on connect.
+     * Always reflects the underlying transport id (or `null` while
+     * disconnected) regardless of whether the consumer supplied an id.
+     * Useful for log correlation against ElevenLabs dashboards even
+     * when the consumer is using their own ids on `conversationId`.
+     */
+    convaiConversationId: string | null;
+}
+
+export type { BaseVoiceConversationOptions as B, BaseVoiceConversationResult as a };