@oshara/voice-sdk 0.1.0

package/dist/core/events.d.ts

@@ -0,0 +1,103 @@
+import { AppearanceConfig } from './appearance';
+import { FormDefinition, FieldValidationError } from './forms';
+import { AudioStateSnapshot } from './voice';
+import { OrbState, ConnectionPhase, ControlsState } from './types';
+export interface VoiceAgentEvents {
+    /** Orb state machine + contextual status line (e.g. "Searching…"). */
+    state: {
+        orb: OrbState;
+        statusLabel: string | null;
+    };
+    /** Free-form call status text (Connecting…, Connected, Muted, errors). */
+    "call:status": {
+        status: string;
+    };
+    /** Remaining call time in ms, or null to hide the timer. */
+    "call:timer": {
+        remainingMs: number | null;
+    };
+    /** Connection lifecycle. UI maps this to which screen to show. */
+    connection: {
+        phase: ConnectionPhase;
+        error?: string;
+    };
+    /** Which call controls should be enabled. */
+    controls: ControlsState;
+    /** A transcript segment (interim or final) for either party. */
+    transcript: {
+        role: "user" | "agent";
+        segmentId: string;
+        text: string;
+        isFinal: boolean;
+    };
+    /** Clear all transcript content (new call). */
+    "transcript:clear": Record<string, never>;
+    /** A system transcript line (e.g. agent handoff transition message). */
+    "transcript:system": {
+        text: string;
+    };
+    /** Mute state changed. */
+    mute: {
+        muted: boolean;
+    };
+    /** Audio preferences / applied settings snapshot changed. */
+    audio: AudioStateSnapshot;
+    /** Raw JSON data message received from the agent over LiveKit. */
+    data: {
+        data: unknown;
+        topic: string | undefined;
+    };
+    /** A form should be shown (agent-triggered or programmatic). */
+    "form:show": {
+        definition: FormDefinition;
+        draft: Record<string, string>;
+        stepIndex: number;
+        inCall: boolean;
+        transcriptionEnabled: boolean;
+    };
+    /** The form values / current step changed (agent merge or step nav). */
+    "form:update": {
+        values: Record<string, string>;
+        stepIndex: number;
+    };
+    /** Client-side validation failed; render these inline errors. */
+    "form:validation": {
+        errors: FieldValidationError[];
+    };
+    /** A submit POST is in flight. */
+    "form:submitting": Record<string, never>;
+    /** A form was submitted successfully. */
+    "form:submitted": {
+        formId: string;
+        values: Record<string, string>;
+        successMessage: string;
+    };
+    /** A submit POST failed. */
+    "form:error": {
+        message: string;
+    };
+    /** The active form was closed. */
+    "form:close": Record<string, never>;
+    /** Mid-call handoff to another agent. */
+    "agent:handoff": {
+        agentName: string;
+    };
+    /** Appearance config resolved (after init fetch). */
+    appearance: AppearanceConfig;
+    /** A non-fatal error occurred in some scope. */
+    error: {
+        scope: string;
+        error: Error;
+    };
+}
+export type EventName = keyof VoiceAgentEvents;
+export type EventHandler<K extends EventName> = (payload: VoiceAgentEvents[K]) => void;
+export type Emit = <K extends EventName>(event: K, payload: VoiceAgentEvents[K]) => void;
+/** Minimal typed event emitter. No deps, works in browser and Node. */
+export declare class Emitter {
+    private listeners;
+    on<K extends EventName>(event: K, handler: EventHandler<K>): () => void;
+    off<K extends EventName>(event: K, handler: EventHandler<K>): void;
+    emit: Emit;
+    clear(): void;
+}

package/dist/core/formController.d.ts

@@ -0,0 +1,28 @@
+import { Emit } from './events';
+import { FormDefinition } from './forms';
+import { VoiceController } from './voice';
+export interface FormControllerOptions {
+    emit: Emit;
+    voice: VoiceController;
+    apiUrl: string;
+    agentSlug: string;
+    apiKey?: string;
+    fetch?: typeof fetch;
+}
+export interface FormController {
+    open: (definition: FormDefinition, draft?: Record<string, string>) => void;
+    merge: (draft: Record<string, string>) => void;
+    close: () => void;
+    current: () => string | null;
+    step: (direction: "next" | "back" | number) => void;
+    submit: () => void;
+    /** Push on-screen edits into the values model (replaces readFormValues). */
+    updateValues: (values: Record<string, string>) => void;
+    /** Snapshot of the active form, or null. */
+    getActive: () => {
+        definition: FormDefinition;
+        values: Record<string, string>;
+        stepIndex: number;
+    } | null;
+}
+export declare function createFormController(opts: FormControllerOptions): FormController;

package/dist/core/forms.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Agent-driven form support for the chat widget.
+ *
+ * The voice agent can prompt the visitor to fill a structured form (book a
+ * demo, table reservation, lead capture, etc.) by publishing a LiveKit data
+ * message. The widget listens on `RoomEvent.DataReceived`, matches the message
+ * against a registered form definition, prefills any draft fields, and opens
+ * a review screen so the user can confirm and submit.
+ *
+ * Form definitions are generic — `book-demo` ships as the default, but
+ * additional forms (reservation, support ticket, lead capture, etc.) can be
+ * added either by extending DEFAULT_FORM_DEFINITIONS below or by sending them
+ * from the backend through the appearance config (`appearance.forms`).
+ *
+ * ---------------------------------------------------------------------------
+ * Agent → widget protocol (LiveKit data message payload, UTF-8 JSON):
+ *
+ *   1. Topic-based match (preferred):
+ *        topic: "form.book-demo" | "book-demo.form" | "book-demo.review"
+ *        payload: { ...draft fields }
+ *
+ *   2. Form-id field:
+ *        payload: { form_id: "reservation", ...draft fields }
+ *
+ *   3. Event-type field (back-compat with the help-desk-call payload shape):
+ *        payload: { type: "book_demo_form", form: { ...draft fields } }
+ *
+ * Draft fields can live at the payload root or nested under `form`/`payload`/
+ * `data`/`fields`/`values` — extractFormDraft() looks in all of them.
+ */
+export type FormFieldType = "text" | "email" | "tel" | "textarea" | "select" | "number" | "date" | "time" | "checkbox" | "radio" | "display";
+/** Option for select/radio/checkbox-group. A plain string is shorthand for { value, label }. */
+export type FormFieldOption = string | {
+    value: string;
+    label?: string;
+};
+export interface FormFieldDef {
+    /** Field key — sent in the POST body and matched against incoming drafts.
+     *  Not required for `display` blocks (which render no input). */
+    name?: string;
+    label: string;
+    type: FormFieldType;
+    placeholder?: string;
+    required?: boolean;
+    /** Options for select/radio/checkbox-group. */
+    options?: FormFieldOption[];
+    /** Row count for `type: "textarea"`. */
+    rows?: number;
+    /** Optional default applied when the form is opened with no draft value. */
+    default_value?: string;
+    /** Helper text rendered beneath the input (or as the body of a `display` block). */
+    help_text?: string;
+    /** Optional regex (string form) to validate text-like fields on submit. */
+    pattern?: string;
+    /** Min/max for `type: "number"` (or min/max length for text — not enforced in v1). */
+    min?: number;
+    max?: number;
+    /** Layout width when the form's `field_layout: "grid"`. "full" (default) or "half". */
+    width?: "full" | "half";
+}
+export interface FormStep {
+    id: string;
+    title?: string;
+    subtitle?: string;
+    fields: FormFieldDef[];
+    next_label?: string;
+    back_label?: string;
+}
+export interface FormLayout {
+    field_layout?: "stack" | "grid";
+    density?: "comfortable" | "compact";
+    label_position?: "top" | "inline";
+}
+export interface FormDefinition {
+    /** Stable identifier — used to match topics, event types, and form_id. */
+    id: string;
+    title: string;
+    subtitle?: string;
+    /** Single-page fields. Ignored when `steps` is set. */
+    fields: FormFieldDef[];
+    /** When set, the form renders as a stepper wizard. */
+    steps?: FormStep[];
+    /** Form-level layout knobs. */
+    layout?: FormLayout;
+    /** When true, the auto-derived agent tool is skipped (form is hidden from the LLM). */
+    disabled?: boolean;
+    /**
+     * Where to POST the form on submit. Absolute URL (starts with http) is
+     * used as-is; otherwise treated as a path joined onto BootConfig.apiUrl.
+     * When null, the platform stores the response in managed storage.
+     */
+    submit_url: string | null;
+    submit_method?: "POST" | "PUT" | "PATCH";
+    submit_label?: string;
+    success_message?: string;
+    /** Extra LiveKit topics to match against (in addition to the id-based ones). */
+    topics?: string[];
+    /** Extra event-type aliases to match (e.g. legacy "book_demo_form"). */
+    event_types?: string[];
+    /**
+     * LiveKit topic used when echoing the confirmation back to the agent.
+     * Defaults to "voice.user_text".
+     */
+    confirmation_topic?: string;
+    /**
+     * `type` field on the confirmation payload sent back to the agent.
+     * Defaults to `<id>_submitted`.
+     */
+    confirmation_type?: string;
+}
+export interface FormSession {
+    definition: FormDefinition;
+    values: Record<string, string>;
+}
+/**
+ * Minimal surface a form controller must expose so the agent can drive it
+ * via data-channel messages (step / submit / close). The widget's
+ * `createFormController` returns an object that satisfies this shape; we
+ * keep the type narrow so the dispatcher below can't accidentally reach
+ * into internals.
+ */
+export interface FormActionTarget {
+    current: () => string | null;
+    step: (direction: "next" | "back" | number) => void;
+    submit: () => void;
+    close: () => void;
+}
+/**
+ * Snapshot of the open form that the widget publishes back to the agent on
+ * every meaningful change (field edit, step move, open, close). Lives on
+ * the `form.state` LiveKit topic.
+ */
+/** Compact field descriptor sent to the agent so it can build accurate,
+ *  enum-constrained voice-fill tools for forms that aren't defined in the
+ *  session token (appearance.forms). Mirrors the subset of FormFieldDef the
+ *  agent's _field_to_json_schema needs. */
+export interface FormFieldSchema {
+    name: string;
+    label: string;
+    type: FormFieldType;
+    required: boolean;
+    /** Zero-based step this field lives on (0 for single-page forms). Lets the
+     *  agent guide the visitor through a stepper one step at a time. */
+    step: number;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** Validation rules mirrored so the agent can reject malformed input in its
+     *  submit guard — before claiming success — exactly like the widget does. */
+    pattern?: string;
+    min?: number;
+    max?: number;
+}
+export interface FormStateSnapshot {
+    type: "form_state";
+    form_id: string;
+    is_open: boolean;
+    step_index: number;
+    total_steps: number;
+    values: Record<string, string>;
+    /** Schema of the form's input fields, so the agent can register
+     *  enum-aware render tools even without appearance.forms in the token. */
+    fields: FormFieldSchema[];
+}
+/** Build the compact field schema the agent needs to construct voice-fill
+ *  tools (enum values for select/radio/checkbox, types for the rest) and to
+ *  guide the visitor through a multi-step form one step at a time. */
+export declare function buildFieldSchema(definition: FormDefinition): FormFieldSchema[];
+/**
+ * Topic pattern the agent uses to drive form actions: `form.{id}.action`.
+ * Payload carries `{type: "form_step"|"form_submit"|"form_close", form_id,
+ * direction?, step_index?}`.
+ *
+ * Returns true if the message was a form-action and was dispatched (so the
+ * caller can short-circuit further matching), false otherwise.
+ */
+export declare function handleFormAction(topic: string | undefined, value: unknown, target: FormActionTarget): boolean;
+/** Flatten a form to its full field list — single-page or stepper. Excludes display blocks. */
+export declare function collectInputFields(definition: FormDefinition): FormFieldDef[];
+/** Fields for a specific step (or the whole form when no stepper). */
+export declare function fieldsForStep(definition: FormDefinition, stepIndex: number): FormFieldDef[];
+export declare function totalSteps(definition: FormDefinition): number;
+/** A single field that failed local validation. */
+export interface FieldValidationError {
+    name: string;
+    label: string;
+    message: string;
+}
+/**
+ * Validate the given values against their field definitions, returning one
+ * error per offending field. Runs entirely in the browser so obvious mistakes
+ * (missing required fields, malformed email/phone, out-of-range numbers, custom
+ * pattern mismatches) are caught before anything is sent to the server/agent.
+ *
+ * Format checks are skipped for empty optional fields — only `required` flags
+ * empties. `display` blocks and unnamed fields are ignored.
+ */
+export declare function validateFields(fields: FormFieldDef[], values: Record<string, string>): FieldValidationError[];
+export declare const DEFAULT_FORM_DEFINITIONS: FormDefinition[];
+/**
+ * Try to identify which form definition an incoming LiveKit data message is
+ * asking the widget to open. Returns null if no definition matches.
+ */
+export declare function matchForm(topic: string | undefined, value: unknown, forms: FormDefinition[]): FormDefinition | null;
+/**
+ * Pull a partial field/value draft out of an incoming data message. Looks at
+ * the payload root and common nested keys (`form`, `payload`, `data`,
+ * `fields`, `values`). Returns null when nothing matches the form's fields.
+ */
+export declare function extractFormDraft(value: unknown, definition: FormDefinition): Record<string, string> | null;
+export declare function initialFormValues(definition: FormDefinition): Record<string, string>;
+export declare function mergeFormDraft(current: Record<string, string>, draft: Record<string, string> | null | undefined): Record<string, string>;
+/** Plain-text summary of a submission — echoed back to the agent on confirm. */
+export declare function buildSubmissionText(definition: FormDefinition, values: Record<string, string>): string;
+export interface SubmitFormArgs {
+    definition: FormDefinition;
+    values: Record<string, string>;
+    apiUrl: string;
+    /** Agent slug — required when submit_url is null (managed storage path). */
+    slug: string;
+    /** Active session ID to link the form response to its billing session. */
+    sessionId?: string | null;
+    /** Secret key sent as `x-api-key` on the managed-storage POST. */
+    apiKey?: string;
+    /** Custom fetch (Node <18 / testing). Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+export declare function submitForm({ definition, values, apiUrl, slug, sessionId, apiKey, fetch: fetchImpl, }: SubmitFormArgs): Promise<unknown>;
+/**
+ * Accept a partial `forms` array from the appearance config (or anywhere
+ * else) and turn it into a clean array of FormDefinitions, dropping entries
+ * that don't have an id + at least one field.
+ */
+export declare function normalizeFormDefinitions(value: unknown): FormDefinition[];

package/dist/core/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @oshara/voice-sdk — headless core.
+ *
+ * `import { createVoiceAgent } from "@oshara/voice-sdk"` pulls in zero DOM/UI
+ * code. Build a custom UI on the events, or mount the prebuilt UI from
+ * `@oshara/voice-sdk/ui`.
+ */
+export { createVoiceAgent } from './createVoiceAgent';
+export type { VoiceAgentConfig, VoiceAgentClient } from './createVoiceAgent';
+export { Emitter } from './events';
+export type { VoiceAgentEvents, EventName, EventHandler, Emit, } from './events';
+export type { OrbState, SessionInit, ConnectionPhase, ControlsState, DeepFilterUrls, } from './types';
+export { DEFAULT_DEEPFILTER_MODULE_URL } from './types';
+export { createVoiceController, } from './voice';
+export type { VoiceController, VoiceControllerOptions, AudioStateSnapshot, AudioStats, } from './voice';
+export { createFormController, } from './formController';
+export type { FormController } from './formController';
+export { buildFieldSchema, collectInputFields, extractFormDraft, fieldsForStep, handleFormAction, initialFormValues, matchForm, mergeFormDraft, normalizeFormDefinitions, submitForm, totalSteps, validateFields, DEFAULT_FORM_DEFINITIONS, } from './forms';
+export type { FormDefinition, FormFieldDef, FormFieldType, FormFieldOption, FormStep, FormLayout, FormStateSnapshot, FieldValidationError, } from './forms';
+export { fetchAppearance, mergeAppearance, DEFAULT_APPEARANCE, } from './appearance';
+export type { AppearanceConfig, AppearanceTheme, AppearanceDimensions, AppearanceLayout, AppearanceLabels, AppearanceLanguage, WidgetPosition, } from './appearance';
+export { DEFAULT_AUDIO_PREFS, loadAudioPrefs, saveAudioPrefs, enumerateAudioDevices, probeAudioCapabilities, } from './audioSettings';
+export type { AudioPrefs, NoiseFilterEngine, AudioDevices, AudioCapabilities, } from './audioSettings';
+export { loadPrevContext, savePrevContext, clearPrevContext, formatPrevContextForAgent, } from './prevContext';
+export type { PrevTurn } from './prevContext';
+export { loadConsent, saveConsent, hasAcceptedTerms } from './consent';
+export { trackWidgetEvent, getVisitorId } from './analytics';
+export { buildHeaders, fetchSession, warnIfBrowserSecret, } from './transport';
+export type { TransportConfig, FetchSessionArgs } from './transport';

package/dist/core/prevContext.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-agent storage for the most-recent conversation transcript, so the
+ * agent can be primed with prior context when the user returns.
+ *
+ * The widget stores the *raw last turns* (not an LLM-generated summary) —
+ * the agent-side LLM is perfectly capable of using the transcript as
+ * context, and skipping a summarization step keeps the widget standalone.
+ */
+export interface PrevTurn {
+    role: "user" | "agent";
+    text: string;
+}
+export interface PrevContextRecord {
+    savedAt: number;
+    turns: PrevTurn[];
+    /** Agent-generated short user-profile summary (preferred over raw turns
+     *  when priming the next session). May be empty. */
+    summary?: string;
+}
+export declare function loadPrevContext(agentSlug: string): PrevContextRecord | null;
+export declare function savePrevContext(agentSlug: string, turns: PrevTurn[], summary?: string): void;
+export declare function clearPrevContext(agentSlug: string): void;
+/** Format stored context for the agent's system prompt.
+ *  Prefers the agent-generated user-profile summary when available; falls
+ *  back to a labelled raw-turn transcript otherwise. */
+export declare function formatPrevContextForAgent(record: PrevContextRecord): string;

package/dist/core/transport.d.ts

@@ -0,0 +1,30 @@
+import { SessionInit } from './types';
+export interface TransportConfig {
+    apiUrl: string;
+    /** Secret API key (sk_…). Sent as `x-api-key`. Omit for public embeds. */
+    apiKey?: string;
+    /** Custom fetch (Node <18 / testing). Defaults to globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+/** Merge auth headers onto a base header set. */
+export declare function buildHeaders(config: Pick<TransportConfig, "apiKey">, base?: Record<string, string>): Record<string, string>;
+/** Resolve a usable fetch implementation or throw a helpful error. */
+export declare function resolveFetch(fetchImpl?: typeof fetch): typeof fetch;
+/**
+ * Warn when a secret key is embedded in browser JS, where it is exposed to
+ * anyone who views source. Call once at init.
+ */
+export declare function warnIfBrowserSecret(apiKey?: string): void;
+export interface FetchSessionArgs {
+    apiUrl: string;
+    agentSlug: string;
+    language: string;
+    apiKey?: string;
+    fetch?: typeof fetch;
+    /** Page URL recorded server-side; defaults to window.location.href. */
+    originUrl?: string;
+    /** Optional extra fields honored only with a valid x-api-key (system_prompt, etc.). */
+    extra?: Record<string, unknown>;
+}
+/** Mint a LiveKit session token. Moved verbatim from the widget's fetchSession. */
+export declare function fetchSession(args: FetchSessionArgs): Promise<SessionInit>;

package/dist/core/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cross-cutting types shared between the headless core, the prebuilt UI, and
+ * external SDK consumers. Kept free of any DOM or LiveKit imports so this
+ * module is safe to import from anywhere (including Node).
+ */
+/** Visual state of the agent orb / call indicator. */
+export type OrbState = "idle" | "listening" | "speaking" | "connecting" | "thinking";
+/** Shape returned by Django's `POST /api/agents/agent-session/`. */
+export interface SessionInit {
+    token: string;
+    livekit_url: string;
+    room_name: string;
+    participant_identity: string;
+    expires_in_seconds: number;
+    session_id: string;
+    character_slug: string;
+    system_prompt: string;
+    greeting: string;
+    voice_inference_url: string;
+}
+/** High-level connection lifecycle phase, surfaced via the `connection` event. */
+export type ConnectionPhase = "connecting" | "connected" | "reconnecting" | "disconnected" | "failed";
+/**
+ * Which call controls the UI should enable. Replaces the direct
+ * `refs.startBtn.disabled = …` side effects the controller used to perform.
+ */
+export interface ControlsState {
+    canStart: boolean;
+    canMute: boolean;
+    canEnd: boolean;
+}
+/**
+ * DeepFilterNet3 asset overrides. Mirrors the widget's boot config exactly,
+ * including precedence: `wasmUrl`/`onnxUrl` take priority over `cdnUrl`.
+ * Passed to the voice controller per-instance (no module-level globals) so
+ * multiple agents can coexist on one page.
+ */
+export interface DeepFilterUrls {
+    /** Base CDN URL; the package appends `/v2/pkg/df_bg.wasm` etc. Empty = default. */
+    cdnUrl?: string;
+    /** Direct URL to `df_bg.wasm`. Takes precedence over `cdnUrl`. */
+    wasmUrl?: string;
+    /** Direct URL to `DeepFilterNet3_onnx.tar.gz`. Takes precedence over `cdnUrl`. */
+    onnxUrl?: string;
+    /** Where the DeepFilterNet3 ESM module is loaded from. Empty = esm.sh default. */
+    moduleUrl?: string;
+}
+/** Default DeepFilterNet3 ESM module mirror (esm.sh) when none is configured. */
+export declare const DEFAULT_DEEPFILTER_MODULE_URL = "https://esm.sh/deepfilternet3-noise-filter@1.2.1";

package/dist/core/voice.d.ts

@@ -0,0 +1,79 @@
+import { AudioPrefs, NoiseFilterEngine } from './audioSettings';
+import { AppearanceConfig } from './appearance';
+import { Emit } from './events';
+import { DeepFilterUrls, SessionInit } from './types';
+export type { SessionInit } from './types';
+/**
+ * Snapshot reported back to the UI after the mic publishes or when any
+ * audio setting changes. The `applied*` flags are read from the live
+ * MediaStreamTrack via getSettings(), so they reflect what the browser
+ * actually honored — which may differ from what we requested.
+ */
+export interface AudioStateSnapshot {
+    prefs: AudioPrefs;
+    applied: {
+        echoCancellation: boolean | undefined;
+        noiseSuppression: boolean | undefined;
+        autoGainControl: boolean | undefined;
+        voiceIsolation: boolean | undefined;
+        sampleRate: number | undefined;
+        channelCount: number | undefined;
+        deviceId: string | undefined;
+    };
+    /**
+     * Effective state of the deep-learning NS engine:
+     * - `engine` — what the user picked (off / krisp / deepfilter).
+     * - `status` — what actually happened: "active" if the processor is
+     *   attached, "unsupported" if the chosen engine isn't available in
+     *   this browser, "failed" if attach errored, "off" if engine === "off".
+     */
+    noiseFilter: {
+        engine: NoiseFilterEngine;
+        status: "active" | "off" | "unsupported" | "failed";
+    };
+}
+export interface AudioStats {
+    /** Local outbound audio level (0-1) from RTCStats. */
+    outboundAudioLevel: number;
+    /** Remote inbound audio level (0-1) from RTCStats. */
+    inboundAudioLevel: number;
+    /** Packets lost on inbound (agent → user) stream. */
+    packetsLost: number;
+    /** Inbound jitter in ms. */
+    jitter: number;
+    /** Round-trip time in ms (peer connection). */
+    roundTripTime: number;
+}
+export interface VoiceController {
+    start: () => Promise<void>;
+    end: () => Promise<void>;
+    toggleMute: () => Promise<boolean>;
+    isActive: () => boolean;
+    /** Returns the session_id for the active session, or null if no session is running. */
+    sessionId: () => string | null;
+    /** Publish a JSON data message back to the agent (used after form submit). */
+    publishData: (payload: unknown, topic: string) => Promise<void>;
+    /** Apply a partial update to the audio preferences (live, no reconnect). */
+    updateAudioSettings: (delta: Partial<AudioPrefs>) => Promise<AudioStateSnapshot>;
+    /** Read the current audio state (preferences + actually-applied values). */
+    getAudioState: () => AudioStateSnapshot;
+    /** Poll a snapshot of audio RTC stats (returns null if no call). */
+    getAudioStats: () => Promise<AudioStats | null>;
+}
+export interface VoiceControllerOptions {
+    /** Mint a LiveKit session (POST /api/agents/agent-session/). */
+    fetchSession: () => Promise<SessionInit>;
+    /** AICharacter slug — namespaces persisted prefs / context. */
+    agentSlug: string;
+    /** Read the live appearance config (labels, max_call_seconds). */
+    getAppearance: () => AppearanceConfig;
+    /** Typed event emitter — replaces all the old direct UI calls. */
+    emit: Emit;
+    /** Per-instance DeepFilterNet3 asset overrides. */
+    deepFilter?: DeepFilterUrls;
+    /** Pre-resolved audio prefs to start from. Defaults to loadAudioPrefs(slug). */
+    initialPrefs?: AudioPrefs;
+    /** Persist pref changes to localStorage (default true). */
+    persistPrefs?: boolean;
+}
+export declare function createVoiceController(opts: VoiceControllerOptions): VoiceController;