lua-cli 3.15.3 → 3.16.0

package/dist/voice/test/index.d.ts

@@ -0,0 +1,1217 @@
+import { llm } from '@livekit/agents';
+import { voice } from '@livekit/agents';
+import { z } from 'zod';
+import { ZodType } from 'zod';
+
+/**
+ * Assert the run invoked a specific tool. Optional args matcher narrows
+ * to a specific call shape.
+ */
+export declare function expectCalledTool(result: RunResult, toolName: string, expectedArgs?: Record<string, unknown> | ((args: unknown) => boolean)): void;
+
+/**
+ * Assert the run produced an agent handoff. By name (the LuaVoice's
+ * `name` field), since the test harness doesn't have access to the
+ * Agent constructor types LiveKit's `containsAgentHandoff` expects.
+ */
+export declare function expectContainsHandoff(result: RunResult, voiceName: string): void;
+
+/**
+ * Assert the run produced an assistant message matching the predicate.
+ * Predicate can be a substring, a regex, or a custom function.
+ */
+export declare function expectContainsMessage(result: RunResult, matcher: string | RegExp | ((text: string) => boolean)): void;
+
+/**
+ * Throwing variant for jest-style tests. Throws an Error with the
+ * judge's verdict + the original criterion when the judge says no, so
+ * the failure message in the test report is self-explanatory.
+ */
+export declare function expectJudge(response: string, criterion: string, options: JudgeOptions): Promise<void>;
+
+declare type FakeLLMResponse = voice.testing.FakeLLMResponse;
+
+/**
+ * Returns true when the judge LLM concludes the response satisfies the
+ * criterion. False on disagreement OR on any judge failure (network,
+ * malformed response, timeout) — fail-closed so a flaky judge doesn't
+ * mask a real assertion failure.
+ */
+export declare function judge(response: string, criterion: string, options: JudgeOptions): Promise<boolean>;
+
+export declare interface JudgeOptions {
+    /** LLM instance the judge prompt runs against. */
+    llm: llm.LLM;
+    /**
+     * Optional system instruction override. The default keeps the judge
+     * strict ("answer yes or no, no explanation"). Override when you need
+     * the judge to score on a scale or return structured output — though
+     * structured output is more brittle than yes/no.
+     */
+    systemInstruction?: string;
+    /**
+     * Optional context. When set, the judge sees additional facts
+     * before scoring the response. Useful for "did the agent answer
+     * factually given these facts": pass the facts as `context`.
+     */
+    context?: string;
+}
+
+export { llm }
+
+declare interface LuaTool<TInput extends ZodType = ZodType> {
+    /** Unique tool name (alphanumeric, hyphens, underscores only) */
+    name: string;
+    /** Description of what the tool does */
+    description: string;
+    /** Zod schema for input validation */
+    inputSchema: TInput;
+    /**
+     * Async function that executes the tool logic.
+     *
+     * `ctx` is `undefined` when the tool runs from the chat path (lua-core's
+     * vm-execution doesn't pass a second arg today). When the tool runs
+     * inside a voice session, `ctx` carries the voice runtime's delegates
+     * (`ctx.voice.say(...)` to emit a spoken acknowledgement, plus the
+     * `toolCallId` LiveKit assigned). Tools that want to bridge both modes
+     * read `ctx?.voice` and branch.
+     */
+    execute: (input: any, ctx?: LuaToolCtx) => Promise<any>;
+    /** Optional async function that determines if the tool should be available */
+    condition?: () => Promise<boolean>;
+    /**
+     * Optional voice-only metadata. When present, the lua-livekit worker
+     * applies these flags to the wrapped LiveKit `llm.tool()` registration.
+     * Tools without this field work in chat and voice unchanged.
+     */
+    voice?: {
+        flags?: ToolFlag[];
+    };
+}
+
+/**
+ * Per-call context passed to a `LuaTool.execute` running inside a voice
+ * session. Imported here (rather than in `voice.ts`) to break a circular
+ * import — `LuaVoiceTool` extends `LuaTool` and would otherwise loop.
+ *
+ * The chat path (lua-core's vm-execution) doesn't pass a second arg, so
+ * `ctx` is `undefined` for chat. The voice path passes `{ toolCallId,
+ * voice: { say } }`. Tools that want to act differently inside a voice
+ * call check for `ctx?.voice` and use the typed surface.
+ */
+declare interface LuaToolCtx {
+    /** LiveKit's tool-call id (voice only). */
+    toolCallId?: string;
+    /** Voice-runtime delegates. Only set when the tool runs over voice. */
+    voice?: {
+        say(text: string): Promise<void>;
+    };
+}
+
+/**
+ * Code-defined voice agent. Pushed via `lua push`, attached to channels through
+ * the owning `LuaAgent.voice` field. Auto-dispatched into LiveKit rooms when a
+ * channel bound to that agent receives a voice event.
+ *
+ * @example
+ * ```typescript
+ * import { LuaVoice } from 'lua-cli';
+ *
+ * export default new LuaVoice({
+ *   name: 'support-line',
+ *   llm: 'openai/gpt-5.2-chat-latest',
+ *   stt: 'deepgram/nova-3',
+ *   tts: { model: 'cartesia/sonic-3', voice: '9626c31c-bec5-4cca-baa8-f8ba9e84c8bc' },
+ *   vad: 'silero',
+ *   turnDetection: 'multilingual',
+ *   greeting: 'Hi, how can I help today?',
+ *   maxToolSteps: 3,
+ *   interruption: { mode: 'adaptive', falseInterruptionTimeout: 2.0 },
+ *
+ *   onEnter: async (ctx) => {
+ *     if (ctx.caller?.phoneNumber) {
+ *       const user = await User.get({ phone: ctx.caller.phoneNumber });
+ *       ctx.session.userdata = { user, returning: !!user };
+ *     }
+ *   },
+ *
+ *   onUserTurnCompleted: async (turnCtx, message) => {
+ *     const docs = await Data.search('kb', message.content, 3);
+ *     for (const doc of docs) turnCtx.addMessage({ role: 'system', content: doc.text });
+ *   },
+ * });
+ * ```
+ */
+declare class LuaVoice {
+    readonly name: string;
+    readonly description?: string;
+    readonly llm: LuaVoiceModelInput;
+    readonly stt: LuaVoiceModelInput;
+    readonly tts: LuaVoiceModelInput;
+    readonly vad: LuaVoiceConfig['vad'];
+    readonly vadOptions: LuaVoiceConfig['vadOptions'];
+    readonly turnDetection: LuaVoiceConfig['turnDetection'];
+    readonly greeting: LuaVoiceConfig['greeting'];
+    readonly maxToolSteps: LuaVoiceConfig['maxToolSteps'];
+    readonly userAwayTimeout: LuaVoiceConfig['userAwayTimeout'];
+    readonly preemptiveGeneration: LuaVoiceConfig['preemptiveGeneration'];
+    readonly interruption: LuaVoiceConfig['interruption'];
+    readonly sttLanguage: LuaVoiceConfig['sttLanguage'];
+    readonly tools: ReadonlyArray<LuaTool<any> | LuaVoiceTool<any>>;
+    readonly onEnter?: LuaVoiceConfig_2['onEnter'];
+    readonly onUserTurnCompleted?: LuaVoiceConfig_2['onUserTurnCompleted'];
+    readonly onExit?: LuaVoiceConfig_2['onExit'];
+    constructor(config: LuaVoiceConfig_2);
+}
+
+declare type LuaVoiceConfig = z.infer<typeof LuaVoiceConfigSchema>;
+
+/**
+ * Full LuaVoice config — data fields (validated by zod in shared-types)
+ * plus function-bearing fields (detected by the compiler via AST).
+ */
+/**
+ * LuaVoice config — uses loose input types for `llm` / `stt` / `tts` so devs can
+ * pass either a string descriptor or a plugin class instance. The wire schema
+ * (validated server-side) is the discriminated union in `@lua/shared-types`;
+ * the compiler is what bridges the two.
+ */
+declare interface LuaVoiceConfig_2 extends Omit<LuaVoiceConfig, 'llm' | 'stt' | 'tts'> {
+    llm: LuaVoiceModelInput;
+    stt: LuaVoiceModelInput;
+    tts: LuaVoiceModelInput;
+    /** Optional human-readable description (surfaced in manifest + admin listings). */
+    description?: string;
+    /** Voice-only tools, in addition to skills attached to the owning agent. */
+    tools?: Array<LuaTool<any> | LuaVoiceTool<any>>;
+    /**
+     * Fired after the session connects to the room and before the greeting.
+     * Use to hydrate `session.userdata` from `User`/`Data`, set up state, etc.
+     */
+    onEnter?: (ctx: LuaVoiceHookContext) => Promise<void>;
+    /**
+     * Fired after the user finishes a turn, before the LLM is invoked. Canonical
+     * RAG injection point — `turnCtx.addMessage(...)` adds context the LLM sees.
+     */
+    onUserTurnCompleted?: (turnCtx: LuaVoiceTurnContext, message: {
+        content: string;
+    }) => Promise<void>;
+    /**
+     * Fired when the session is closing. Use for transcript persistence or
+     * outcome reporting.
+     */
+    onExit?: (ctx: LuaVoiceHookContext) => Promise<void>;
+}
+
+declare const LuaVoiceConfigSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    llm: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"inference">;
+        /** Provider-prefixed model id (e.g. `'openai/gpt-5.2-chat-latest'`). */
+        model: z.ZodString;
+        /**
+         * TTS-only — provider voice id. Inference's TTS API takes voice
+         * separately from model; LLM and STT ignore this field.
+         */
+        voice: z.ZodOptional<z.ZodString>;
+        /**
+         * Additional Inference extras forwarded as constructor options. Loose
+         * record by design — LiveKit's Inference surface evolves faster than
+         * we want to chase, and we don't gate dev productivity on schema
+         * updates here.
+         */
+        options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    }, {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"plugin">;
+        provider: z.ZodEnum<["deepgram", "elevenlabs"]>;
+        class: z.ZodEnum<["LLM", "STT", "STTv2", "TTS"]>;
+        /**
+         * Forwarded verbatim to the plugin constructor (e.g. `new deepgram.STT(options)`).
+         * Loose record because each provider's option surface is its own
+         * schema, evolving independently. The factory passes these through
+         * to the LiveKit plugin which is the source of truth for shape.
+         */
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    }, {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"realtime">;
+        provider: z.ZodEnum<["openai", "google", "xai"]>;
+        /**
+         * Forwarded verbatim to `<provider>.realtime.RealtimeModel(options)`.
+         * Each provider has its own surface (voice id, modalities, turn
+         * detection, etc.). Loose record so devs can pass any option the
+         * underlying plugin accepts without a schema chase.
+         */
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    }, {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    }>]>;
+    stt: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"inference">;
+        /** Provider-prefixed model id (e.g. `'openai/gpt-5.2-chat-latest'`). */
+        model: z.ZodString;
+        /**
+         * TTS-only — provider voice id. Inference's TTS API takes voice
+         * separately from model; LLM and STT ignore this field.
+         */
+        voice: z.ZodOptional<z.ZodString>;
+        /**
+         * Additional Inference extras forwarded as constructor options. Loose
+         * record by design — LiveKit's Inference surface evolves faster than
+         * we want to chase, and we don't gate dev productivity on schema
+         * updates here.
+         */
+        options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    }, {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"plugin">;
+        provider: z.ZodEnum<["deepgram", "elevenlabs"]>;
+        class: z.ZodEnum<["LLM", "STT", "STTv2", "TTS"]>;
+        /**
+         * Forwarded verbatim to the plugin constructor (e.g. `new deepgram.STT(options)`).
+         * Loose record because each provider's option surface is its own
+         * schema, evolving independently. The factory passes these through
+         * to the LiveKit plugin which is the source of truth for shape.
+         */
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    }, {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"realtime">;
+        provider: z.ZodEnum<["openai", "google", "xai"]>;
+        /**
+         * Forwarded verbatim to `<provider>.realtime.RealtimeModel(options)`.
+         * Each provider has its own surface (voice id, modalities, turn
+         * detection, etc.). Loose record so devs can pass any option the
+         * underlying plugin accepts without a schema chase.
+         */
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    }, {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    }>]>>;
+    tts: z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"inference">;
+        /** Provider-prefixed model id (e.g. `'openai/gpt-5.2-chat-latest'`). */
+        model: z.ZodString;
+        /**
+         * TTS-only — provider voice id. Inference's TTS API takes voice
+         * separately from model; LLM and STT ignore this field.
+         */
+        voice: z.ZodOptional<z.ZodString>;
+        /**
+         * Additional Inference extras forwarded as constructor options. Loose
+         * record by design — LiveKit's Inference surface evolves faster than
+         * we want to chase, and we don't gate dev productivity on schema
+         * updates here.
+         */
+        options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    }, {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"plugin">;
+        provider: z.ZodEnum<["deepgram", "elevenlabs"]>;
+        class: z.ZodEnum<["LLM", "STT", "STTv2", "TTS"]>;
+        /**
+         * Forwarded verbatim to the plugin constructor (e.g. `new deepgram.STT(options)`).
+         * Loose record because each provider's option surface is its own
+         * schema, evolving independently. The factory passes these through
+         * to the LiveKit plugin which is the source of truth for shape.
+         */
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    }, {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"realtime">;
+        provider: z.ZodEnum<["openai", "google", "xai"]>;
+        /**
+         * Forwarded verbatim to `<provider>.realtime.RealtimeModel(options)`.
+         * Each provider has its own surface (voice id, modalities, turn
+         * detection, etc.). Loose record so devs can pass any option the
+         * underlying plugin accepts without a schema chase.
+         */
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    }, {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    }>]>>;
+    vad: z.ZodOptional<z.ZodString>;
+    vadOptions: z.ZodOptional<z.ZodObject<{
+        minSpeechDuration: z.ZodOptional<z.ZodNumber>;
+        minSilenceDuration: z.ZodOptional<z.ZodNumber>;
+        prefixPaddingDuration: z.ZodOptional<z.ZodNumber>;
+        activationThreshold: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        minSpeechDuration?: number;
+        minSilenceDuration?: number;
+        prefixPaddingDuration?: number;
+        activationThreshold?: number;
+    }, {
+        minSpeechDuration?: number;
+        minSilenceDuration?: number;
+        prefixPaddingDuration?: number;
+        activationThreshold?: number;
+    }>>;
+    turnDetection: z.ZodOptional<z.ZodEnum<["multilingual", "english", "vad", "stt", "manual"]>>;
+    greeting: z.ZodOptional<z.ZodString>;
+    maxToolSteps: z.ZodOptional<z.ZodNumber>;
+    userAwayTimeout: z.ZodOptional<z.ZodNumber>;
+    preemptiveGeneration: z.ZodOptional<z.ZodBoolean>;
+    interruption: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        mode: z.ZodOptional<z.ZodEnum<["adaptive", "vad"]>>;
+        falseInterruptionTimeout: z.ZodOptional<z.ZodNumber>;
+        resumeFalseInterruption: z.ZodOptional<z.ZodBoolean>;
+        minDelay: z.ZodOptional<z.ZodNumber>;
+        maxDelay: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    }, {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    }>, {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    }, {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    }>>;
+    sttLanguage: z.ZodOptional<z.ZodString>;
+    krispEnabled: z.ZodOptional<z.ZodBoolean>;
+    backgroundAudio: z.ZodOptional<z.ZodObject<{
+        ambient: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["office-ambience", "keyboard-typing", "keyboard-typing-2"]>, z.ZodObject<{
+            source: z.ZodEnum<["office-ambience", "keyboard-typing", "keyboard-typing-2"]>;
+            volume: z.ZodOptional<z.ZodNumber>;
+            probability: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }>, z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<["office-ambience", "keyboard-typing", "keyboard-typing-2"]>;
+            volume: z.ZodOptional<z.ZodNumber>;
+            probability: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }>, "many">]>>;
+        thinking: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["office-ambience", "keyboard-typing", "keyboard-typing-2"]>, z.ZodObject<{
+            source: z.ZodEnum<["office-ambience", "keyboard-typing", "keyboard-typing-2"]>;
+            volume: z.ZodOptional<z.ZodNumber>;
+            probability: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }>, z.ZodArray<z.ZodObject<{
+            source: z.ZodEnum<["office-ambience", "keyboard-typing", "keyboard-typing-2"]>;
+            volume: z.ZodOptional<z.ZodNumber>;
+            probability: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }, {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }>, "many">]>>;
+    }, "strip", z.ZodTypeAny, {
+        ambient?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+        thinking?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+    }, {
+        ambient?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+        thinking?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+    }>>;
+    volume: z.ZodOptional<z.ZodNumber>;
+    pronunciations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    persistTranscript: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    vad?: string;
+    stt?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    volume?: number;
+    name?: string;
+    llm?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    tts?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    vadOptions?: {
+        minSpeechDuration?: number;
+        minSilenceDuration?: number;
+        prefixPaddingDuration?: number;
+        activationThreshold?: number;
+    };
+    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    greeting?: string;
+    maxToolSteps?: number;
+    userAwayTimeout?: number;
+    preemptiveGeneration?: boolean;
+    interruption?: {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    };
+    sttLanguage?: string;
+    krispEnabled?: boolean;
+    backgroundAudio?: {
+        ambient?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+        thinking?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+    };
+    pronunciations?: Record<string, string>;
+    persistTranscript?: boolean;
+}, {
+    vad?: string;
+    stt?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    volume?: number;
+    name?: string;
+    llm?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    tts?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    vadOptions?: {
+        minSpeechDuration?: number;
+        minSilenceDuration?: number;
+        prefixPaddingDuration?: number;
+        activationThreshold?: number;
+    };
+    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    greeting?: string;
+    maxToolSteps?: number;
+    userAwayTimeout?: number;
+    preemptiveGeneration?: boolean;
+    interruption?: {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    };
+    sttLanguage?: string;
+    krispEnabled?: boolean;
+    backgroundAudio?: {
+        ambient?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+        thinking?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+    };
+    pronunciations?: Record<string, string>;
+    persistTranscript?: boolean;
+}>, {
+    vad?: string;
+    stt?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    volume?: number;
+    name?: string;
+    llm?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    tts?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    vadOptions?: {
+        minSpeechDuration?: number;
+        minSilenceDuration?: number;
+        prefixPaddingDuration?: number;
+        activationThreshold?: number;
+    };
+    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    greeting?: string;
+    maxToolSteps?: number;
+    userAwayTimeout?: number;
+    preemptiveGeneration?: boolean;
+    interruption?: {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    };
+    sttLanguage?: string;
+    krispEnabled?: boolean;
+    backgroundAudio?: {
+        ambient?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+        thinking?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+    };
+    pronunciations?: Record<string, string>;
+    persistTranscript?: boolean;
+}, {
+    vad?: string;
+    stt?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    volume?: number;
+    name?: string;
+    llm?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    tts?: {
+        voice?: string;
+        options?: Record<string, unknown>;
+        kind?: "inference";
+        model?: string;
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "plugin";
+        provider?: "deepgram" | "elevenlabs";
+        class?: "LLM" | "STT" | "STTv2" | "TTS";
+    } | {
+        options?: Record<string, unknown>;
+        kind?: "realtime";
+        provider?: "openai" | "google" | "xai";
+    };
+    vadOptions?: {
+        minSpeechDuration?: number;
+        minSilenceDuration?: number;
+        prefixPaddingDuration?: number;
+        activationThreshold?: number;
+    };
+    turnDetection?: "multilingual" | "english" | "vad" | "stt" | "manual";
+    greeting?: string;
+    maxToolSteps?: number;
+    userAwayTimeout?: number;
+    preemptiveGeneration?: boolean;
+    interruption?: {
+        enabled?: boolean;
+        mode?: "vad" | "adaptive";
+        falseInterruptionTimeout?: number;
+        resumeFalseInterruption?: boolean;
+        minDelay?: number;
+        maxDelay?: number;
+    };
+    sttLanguage?: string;
+    krispEnabled?: boolean;
+    backgroundAudio?: {
+        ambient?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+        thinking?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2" | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        } | {
+            source?: "office-ambience" | "keyboard-typing" | "keyboard-typing-2";
+            volume?: number;
+            probability?: number;
+        }[];
+    };
+    pronunciations?: Record<string, string>;
+    persistTranscript?: boolean;
+}>;
+
+/**
+ * Context passed to LuaVoice lifecycle hooks at runtime.
+ */
+declare interface LuaVoiceHookContext {
+    sessionId: string;
+    channel: {
+        kind: string;
+        alias?: string;
+    };
+    caller?: {
+        phoneNumber?: string;
+        userId?: string;
+        isAnonymous?: boolean;
+    };
+    duration?: number;
+    session: {
+        userdata: Record<string, unknown>;
+        history: unknown[];
+        say(text: string): Promise<void>;
+        generateReply(opts?: {
+            instructions?: string;
+        }): unknown;
+    };
+}
+
+/**
+ * User-facing input type for `llm` / `stt` / `tts` on a LuaVoice. Accepts:
+ *   - a string descriptor like `'cartesia/sonic-3:9626…'` — routed through Inference.
+ *   - an instance of a LiveKit Agents plugin class such as `new deepgram.STT({...})` —
+ *     routed through the corresponding direct plugin.
+ *   - a struct `{ model, voice }` — sugar for the Inference TTS form.
+ *
+ * The compiler ASTs the source file and normalizes whichever shape it finds
+ * to the discriminated union the wire schema expects (`@lua/shared-types`).
+ * The constructor below stores the raw input as-is — the runtime classes
+ * never execute as part of the push pipeline.
+ */
+declare type LuaVoiceModelInput = string | object;
+
+declare class LuaVoiceTool<TInput extends ZodType = ZodType> implements LuaTool<TInput> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: TInput;
+    readonly execute: (input: any, ctx?: LuaVoiceToolCtx) => Promise<any>;
+    readonly condition?: () => Promise<boolean>;
+    readonly voice?: {
+        flags?: ToolFlag[];
+    };
+    constructor(config: LuaVoiceToolConfig<TInput>);
+}
+
+/**
+ * Voice-only tool — for tools that only make sense inside a call (handoffs,
+ * hold-music toggles, transfer-to-human, etc.). Skill tools are still available
+ * to voice agents; LuaVoiceTool is for the call-only ones.
+ */
+declare interface LuaVoiceToolConfig<TInput extends ZodType = ZodType> {
+    name: string;
+    description: string;
+    inputSchema: TInput;
+    execute: (input: any, ctx?: LuaVoiceToolCtx) => Promise<any>;
+    condition?: () => Promise<boolean>;
+    flags?: ToolFlag[];
+}
+
+/**
+ * Voice tool ctx — extends the base `LuaToolCtx` (from `skill.ts`) with
+ * voice-runtime-only delegates. The base ctx is what a `LuaTool` sees as
+ * its second `execute` arg whether it runs over chat or voice; this
+ * extension just adds the Phase-5 fields (currently optional + experimental).
+ *
+ * `say()` is wired today and delegates to the active LiveKit `voice.AgentSession`.
+ * `disallowInterruptions()` and `handoff()` are optional placeholders for
+ * Phase 5 (BAC-213, the LuaVoice handoffs + test framework ticket).
+ * Marked optional both because they aren't implemented yet AND so this
+ * type stays structurally compatible with `LuaToolCtx` — that
+ * compatibility is what lets a `LuaVoiceTool` (which extends `LuaTool`)
+ * present `(ctx?: LuaVoiceToolCtx)` while satisfying the parent's
+ * `(ctx?: LuaToolCtx)` signature.
+ */
+declare interface LuaVoiceToolCtx {
+    toolCallId?: string;
+    voice?: {
+        say(text: string): Promise<void>;
+        /**
+         * Transfer the live caller to a human at `msisdn`. Two mechanisms:
+         *
+         * - `'refer'` (default): SIP REFER on the caller's inbound leg.
+         *   Cheap (one billed leg) but depends on the inbound carrier
+         *   accepting REFER end-to-end — many European mobile carriers
+         *   strip it. Use when the carrier is known to support REFER.
+         *
+         * - `'bridge'`: dial the human as a second SIP participant into
+         *   the same room, keeping the caller attached. Two billed legs
+         *   but always works regardless of carrier REFER support. Use for
+         *   high-stakes transfers (sales, escalation) where reliability
+         *   matters more than per-minute cost.
+         *
+         * `announce` is spoken via `session.say(...)` before the transfer
+         * fires (e.g. "Transferring you to our sales team — one moment").
+         *
+         * @example
+         * ```typescript
+         * await ctx.voice?.transferToHuman('+32477123456', {
+         *   mode: 'bridge',
+         *   announce: 'Transferring you to our sales team — one moment.',
+         * });
+         * ```
+         */
+        transferToHuman?(msisdn: string, opts?: {
+            mode?: 'bridge' | 'refer';
+            announce?: string;
+        }): Promise<void>;
+        /**
+         * @experimental Reserved for Phase 5 (BAC-213). Optional because
+         * unimplemented — the actual "lock the assistant's current
+         * utterance against barge-in" plumbing lands with the broader
+         * turn-handling work.
+         */
+        disallowInterruptions?(): void;
+        /**
+         * @experimental Reserved for Phase 5 (BAC-213). Optional because
+         * unimplemented — handoffs require `chatCtx.copy(exclude_instructions=True)`
+         * + `update_agent` plumbing that's part of the multi-LuaVoice flow ticket.
+         */
+        handoff?(otherVoiceName: string, opts?: {
+            context?: Record<string, unknown>;
+        }): unknown;
+    };
+}
+
+/**
+ * Per-turn context passed to onUserTurnCompleted. The canonical RAG injection
+ * point — call `addMessage` to seed context, then the LLM is invoked.
+ */
+declare interface LuaVoiceTurnContext {
+    items: unknown[];
+    addMessage(message: {
+        role: 'system' | 'user' | 'assistant';
+        content: string;
+    }): void;
+}
+
+declare type RunResult = voice.testing.RunResult;
+
+export declare function runVoice(luaVoice: LuaVoice, options?: RunVoiceOptions): Promise<TestSession>;
+
+export declare interface RunVoiceOptions {
+    /**
+     * LLM mock script. Each entry is keyed by the user input text — when
+     * the agent's chat loop hits that input, the FakeLLM returns the
+     * paired content/toolCalls. Devs can pass a pre-built `llm.LLM`
+     * instance instead for full control (custom matching, multi-turn
+     * stateful responses, etc.).
+     */
+    llm?: FakeLLMResponse[] | llm.LLM;
+    /**
+     * Mock tool executions. Substitutes the dev's tool.execute for the
+     * named tool — return value flows into the LLM's next turn the same
+     * way a real execute would.
+     */
+    mockTools?: Record<string, (input: unknown, ctx?: unknown) => unknown>;
+    /** Caller info passed to onEnter / onExit hook ctx. */
+    caller?: {
+        phoneNumber?: string;
+        userId?: string;
+        isAnonymous?: boolean;
+    };
+    channel?: 'phone' | 'meeting' | 'whatsapp' | 'webchat';
+    /** Pre-seeded session.userdata. Same as the worker's initial state when onEnter hasn't run yet. */
+    initialUserdata?: Record<string, unknown>;
+    /**
+     * Other LuaVoices the agent under test can hand off to. Pass each
+     * target voice keyed by name so `ctx.voice.handoff('billing-line')`
+     * resolves; assertion happens via `expectContainsHandoff(result, 'billing-line')`.
+     */
+    handoffTargets?: Record<string, LuaVoice>;
+    /**
+     * Spy on `ctx.voice.transferToHuman(...)` calls from inside the
+     * voice's tools. Real SIP REFER / bridge dial never fires under
+     * the test harness — pass a jest.fn() (or any callback) to assert
+     * the dev's tool attempted a transfer.
+     */
+    onTransferToHuman?: TransferToHumanRecorder;
+    /**
+     * Seed `dispatchedContext` (what `Voice.call({ context })` would
+     * inject in production). Stored on session.userdata under the same
+     * key the worker uses, plus made available to the hook ctx.
+     */
+    dispatchedContext?: Record<string, unknown>;
+    sessionId?: string;
+}
+
+export declare interface TestSession {
+    /**
+     * Drive a single user turn. Returns a `RunResult` (LiveKit's
+     * built-in assertion type) — chain `.expect.nextEvent()` /
+     * `.expect.containsFunctionCall()` / etc. on the result.
+     */
+    run(userInput: string): Promise<voice.testing.RunResult>;
+    /**
+     * Drive multiple turns sequentially, returning all results in order.
+     */
+    runMany(userInputs: string[]): Promise<voice.testing.RunResult[]>;
+    /** Direct access to the underlying LiveKit AgentSession. */
+    readonly session: voice.AgentSession;
+    /** The chat history accumulated across all turns. */
+    readonly history: ReadonlyArray<unknown>;
+    /** Call the LuaVoice's onExit hook (mirror end-of-session lifecycle). */
+    close(): Promise<void>;
+}
+
+/**
+ * Lua Tool interface.
+ * Defines the structure of a tool that can be added to a LuaSkill.
+ *
+ * @template TInput - Zod schema type for input validation
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { LuaTool } from 'lua-cli';
+ *
+ * const weatherTool: LuaTool = {
+ *   name: 'get_weather',
+ *   description: 'Gets current weather for a city',
+ *   inputSchema: z.object({
+ *     city: z.string(),
+ *     units: z.enum(['metric', 'imperial']).optional()
+ *   }),
+ *   execute: async (input) => {
+ *     // Fetch weather data...
+ *     return { temperature: 72, condition: 'sunny' };
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Tool with condition - only available to premium users
+ * class PremiumSearchTool implements LuaTool {
+ *   name = "premium_search";
+ *   description = "Advanced search for premium users";
+ *   inputSchema = z.object({ query: z.string() });
+ *
+ *   // Condition runs before tool is offered to LLM
+ *   condition = async () => {
+ *     const user = await User.get();
+ *     return user.data?.isPremium === true;
+ *   };
+ *
+ *   execute = async (input) => { ... };
+ * }
+ * ```
+ */
+/**
+ * Tool-level flags mirrored from LiveKit's `ToolFlag`. Used by `LuaTool.voice.flags`
+ * to control tool availability + interruption semantics during a voice session.
+ * Defined here (not voice.ts) so LuaTool's voice metadata stays self-contained
+ * with no risk of circular imports.
+ */
+declare enum ToolFlag {
+    NONE = "none",
+    /** Tool is hidden from the LLM during the first turn after onEnter. */
+    IGNORE_ON_ENTER = "ignore_on_enter",
+    /** User speech does not interrupt the agent while this tool is executing. */
+    DISALLOW_INTERRUPTION = "disallow_interruption"
+}
+
+/**
+ * Wrap each LuaTool / LuaVoiceTool in a LiveKit `llm.tool({})` so the
+ * AgentSession can dispatch tool calls. The mockTools map overrides the
+ * dev's `execute` when provided.
+ */
+/**
+ * Optional spy on `ctx.voice.transferToHuman(msisdn, opts)` calls
+ * inside the test harness. Real SIP REFER / bridge dial doesn't fire
+ * in tests — the harness has no SipClient — so this is the only way
+ * to assert "the dev's tool tried to transfer to a human". Default is
+ * a no-op log.
+ */
+declare type TransferToHumanRecorder = (msisdn: string, opts?: {
+    mode?: 'bridge' | 'refer';
+    announce?: string;
+}) => Promise<void> | void;
+
+export { voice }
+
+export { }