@kognitivedev/backend-cloud 0.2.29

package/src/__tests__/cloud-voice.test.ts

@@ -0,0 +1,1006 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+    CLOUD_VOICE_PHONE_HANGUP_TOOL,
+    CLOUD_VOICE_SIP_TRANSFER_TOOL,
+    buildPhoneOpeningPrompt,
+    compileCloudVoiceGraphConfig,
+    compileVoiceGraphToInstructions,
+    createPhonePrepareSnapshot,
+    executeCloudVoiceToolBinding,
+    normalizeCloudVoiceHumanizationConfig,
+    normalizeCloudVoicePipelineConfig,
+    prepareCloudVoiceSessionConfig,
+    resolveCloudVoiceChannel,
+    resolveCloudVoiceParameters,
+    toOpenAITurnDetection,
+} from "../index";
+import type { CloudVoiceAgentConfig } from "../types";
+
+const baseConfig: CloudVoiceAgentConfig = {
+    instructions: "Help customers.",
+    provider: "openai-realtime",
+    model: "gpt-4o-realtime-preview",
+    voice: "alloy",
+    transport: "websocket",
+    transcription: {},
+    turnDetection: { type: "server_vad" },
+    inputNoiseReduction: null,
+    tools: [{
+        id: "lookup_order",
+        type: "external_webhook",
+        name: "Lookup order",
+        description: "Look up an order",
+        inputSchema: {
+            type: "object",
+            properties: { orderNumber: { type: "string" } },
+        },
+        config: {
+            url: "https://example.test/tools/lookup-order",
+        },
+    }],
+    knowledgeBases: [],
+    widget: { title: "Talk" },
+    channels: { web: true, iframe: true, script: true, phone: true, sip: false, outbound: true },
+    metadata: {
+        speech: {
+            language: "tr",
+            accent: "standard Istanbul Turkish",
+            style: "warm",
+        },
+    },
+};
+
+describe("@kognitivedev/backend-cloud voice preparation", () => {
+    it("resolves supported channels and rejects unknown channels", () => {
+        expect(resolveCloudVoiceChannel(undefined)).toBe("web");
+        expect(resolveCloudVoiceChannel("outbound")).toBe("outbound");
+        expect(() => resolveCloudVoiceChannel("fax")).toThrow("Unsupported cloud voice channel");
+    });
+
+    it("prepares web sessions without phone control tools", () => {
+        const prepare = prepareCloudVoiceSessionConfig(baseConfig, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "web",
+        });
+
+        expect(prepare.toolManifest.map((tool) => tool.name)).toEqual(["lookup_order"]);
+        expect(prepare.system).toContain("## Konuşma Yönlendirmesi");
+        expect(prepare.system).toContain("Dil: Turkish");
+        expect(prepare.system).toContain("Aksan: standard Istanbul Turkish");
+        expect(prepare.system).toContain("## Kişilik, Ton ve Tempo");
+        expect(prepare.system).toContain("## Araç Konuşması");
+        expect(prepare.voiceConfig.system).toBe(prepare.system);
+        expect(prepare.voiceConfig.transcription).toEqual({ language: "tr" });
+        expect(prepare.voiceConfig.speech).toEqual({
+            language: "tr",
+            accent: "standard Istanbul Turkish",
+            style: "warm",
+        });
+        expect(prepare.voiceConfig.languageCode).toBe("tr-TR");
+    });
+
+    it("passes model temperature and max output tokens into prepared voice config", () => {
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            providerOptions: {
+                temperature: 0.7,
+                maxOutputTokens: 640,
+            },
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "web",
+        });
+
+        expect(prepare.voiceConfig.temperature).toBe(0.7);
+        expect(prepare.voiceConfig.maxOutputTokens).toBe(640);
+    });
+
+    it("defaults OpenAI phone sessions to near-field input noise reduction when unset", () => {
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            inputNoiseReduction: undefined,
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "phone",
+        });
+
+        expect(prepare.voiceConfig.inputNoiseReduction).toEqual({ type: "near_field" });
+    });
+
+    it("preserves explicit disabled noise reduction for OpenAI phone sessions", () => {
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            inputNoiseReduction: null,
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "phone",
+        });
+
+        expect(prepare.voiceConfig.inputNoiseReduction).toBeNull();
+    });
+
+    it("renders resolved parameters into instructions, graph nodes, and prepared metadata", () => {
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            instructions: "User calling: {{phone}} with name: {{params.name}}.",
+            metadata: {
+                flowGraph: {
+                    version: 1,
+                    startNodeId: "n_start",
+                    nodes: [{
+                        id: "n_start",
+                        type: "initial",
+                        title: "Greeting",
+                        prompt: "Greet {{name}} at {{parameters.phone}}.",
+                    }],
+                    edges: [],
+                },
+            },
+            parameters: [
+                { key: "name", type: "string", source: "custom", required: true },
+                { key: "phone", type: "string", source: "system", preset: "phone" },
+            ],
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "web",
+            parameters: { name: "Ada", phone: "+15551234567" },
+        });
+
+        expect(prepare.system).toContain("User calling: +15551234567 with name: Ada.");
+        expect(prepare.system).toContain("Greet Ada at +15551234567.");
+        expect(prepare.parameters).toEqual({ name: "Ada", phone: "+15551234567" });
+        expect(prepare.metadata.parameterKeys).toEqual(["name", "phone"]);
+    });
+
+    it("enforces required custom parameters in strict mode and records misses in permissive mode", () => {
+        const config: CloudVoiceAgentConfig = {
+            ...baseConfig,
+            parameters: [{ key: "name", type: "string", source: "custom", required: true }],
+        };
+
+        expect(() => resolveCloudVoiceParameters({ config, supplied: {}, system: {}, mode: "strict" })).toThrow("Cloud voice parameters are invalid");
+        expect(resolveCloudVoiceParameters({ config, supplied: {}, system: {}, mode: "permissive" })).toMatchObject({
+            values: {},
+            missingRequired: ["name"],
+        });
+    });
+
+    it("normalizes kognitive voice pipeline config and exposes it on prepared runtime", () => {
+        const config: CloudVoiceAgentConfig = {
+            ...baseConfig,
+            provider: "kognitive-voice",
+            model: "unused-realtime-model",
+            voice: "alloy",
+            transport: "websocket",
+            pipeline: {
+                transport: { type: "webrtc", provider: "daily" },
+                stt: { provider: "deepgram", model: "nova-3", language: "en" },
+                llm: { provider: "openai", model: "gpt-4o-mini" },
+                tts: { provider: "cartesia", model: "sonic-3", voice: "voice_123" },
+                turn: { interruptResponse: true, silenceDurationMs: 650 },
+            },
+        };
+
+        expect(normalizeCloudVoicePipelineConfig(config)).toMatchObject({
+            transport: { type: "webrtc", provider: "daily" },
+            stt: { provider: "deepgram", model: "nova-3", language: "en" },
+            llm: { provider: "openai", model: "gpt-4o-mini" },
+            tts: { provider: "cartesia", model: "sonic-3", voice: "voice_123" },
+        });
+
+        const prepare = prepareCloudVoiceSessionConfig(config, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "web",
+        });
+
+        expect(prepare.runtime).toMatchObject({
+            provider: "kognitive-voice",
+            mode: "pipeline",
+            transport: "webrtc",
+            model: "gpt-4o-mini",
+            voice: "voice_123",
+            pipeline: {
+                transport: { type: "webrtc", provider: "daily" },
+            },
+        });
+        expect(prepare.voiceConfig).toMatchObject({
+            model: "gpt-4o-mini",
+            voice: "voice_123",
+        });
+    });
+
+    it("compiles flow graphs into routing instructions and matched tool manifests", () => {
+        const compiled = compileVoiceGraphToInstructions({
+            startNodeId: "n_start",
+            nodes: [{
+                id: "n_start",
+                type: "initial",
+                title: "Welcome and intent",
+                prompt: "Greet the caller and classify intent.",
+                firstMessage: "Hi, how can I help?",
+                outputs: [{
+                    id: "o_order",
+                    label: "Order status",
+                    desc: "Caller asks about an order, tracking, or shipment.",
+                }],
+            }, {
+                id: "n_lookup",
+                type: "tool",
+                title: "Lookup order",
+                prompt: "Collect the order number before calling the tool.",
+                toolId: "lookup_order",
+            }, {
+                id: "n_end",
+                type: "end",
+                title: "Close call",
+                prompt: "Close politely.",
+            }],
+            edges: [
+                { from: "n_start", fromPort: "o_order", to: "n_lookup" },
+                { from: "n_lookup", fromPort: null, to: "n_end" },
+            ],
+        }, { tools: baseConfig.tools });
+
+        expect(compiled).toMatchObject({
+            startNodeId: "n_start",
+            nodeCount: 3,
+            edgeCount: 2,
+            referencedToolIds: ["lookup_order"],
+            missingToolIds: [],
+        });
+        expect(compiled?.toolManifest).toEqual([expect.objectContaining({
+            name: "lookup_order",
+            parameters: baseConfig.tools[0].inputSchema,
+        })]);
+        expect(compiled?.instructions).toContain("Greet the caller and classify intent.");
+        expect(compiled?.instructions).toContain("say exactly this as your first sentence");
+        expect(compiled?.instructions).toContain("Hi, how can I help?");
+        expect(compiled?.instructions).toContain("Do not prepend, replace, or append an internal agent name");
+        expect(compiled?.instructions).toContain("When Caller asks about an order, tracking, or shipment.");
+        expect(compiled?.instructions).toContain("Use Lookup order (`lookup_order`)");
+        expect(compiled?.instructions).toContain("Then end with: Close politely.");
+        expect(compiled?.compilerVersion).toBe("voice-flow-paths-v1");
+        expect(compiled?.graphSignature).toEqual(expect.any(String));
+    });
+
+    it("selects the matching initial flow node for each call direction", () => {
+        const graph = {
+            startNodeId: "n_incoming",
+            nodes: [{
+                id: "n_incoming",
+                type: "initial",
+                entryMode: "incoming",
+                title: "Incoming start",
+                prompt: "Handle incoming conversations.",
+                firstMessage: "Thanks for calling.",
+            }, {
+                id: "n_outgoing",
+                type: "initial",
+                entryMode: "outgoing",
+                title: "Outgoing start",
+                prompt: "Handle outbound conversations.",
+                firstMessage: "Hi, I am calling about your appointment.",
+            }],
+            edges: [],
+        };
+
+        const incoming = compileVoiceGraphToInstructions(graph, { channel: "phone" });
+        const outgoing = compileVoiceGraphToInstructions(graph, { channel: "outbound" });
+
+        expect(incoming).toMatchObject({ startNodeId: "n_incoming", entryMode: "incoming" });
+        expect(incoming?.instructions).toContain("Handle incoming conversations.");
+        expect(incoming?.instructions).toContain("Thanks for calling.");
+        expect(incoming?.instructions).not.toContain("Handle outbound conversations.");
+        expect(outgoing).toMatchObject({ startNodeId: "n_outgoing", entryMode: "outgoing" });
+        expect(outgoing?.instructions).toContain("Handle outbound conversations.");
+        expect(outgoing?.instructions).toContain("Hi, I am calling about your appointment.");
+        expect(outgoing?.instructions).not.toContain("Handle incoming conversations.");
+    });
+
+    it("compiles sub-agent nodes as blocking tool calls with outcome routing", () => {
+        const subAgentTool = {
+            id: "voice_agent_boss_approval",
+            type: "cloud_voice_agent" as const,
+            name: "Voice Agent: Boss approval",
+            description: "Call the boss and wait for a decision.",
+            inputSchema: {
+                type: "object",
+                required: ["discount"],
+                properties: { discount: { type: "number" } },
+            },
+        };
+        const compiled = compileVoiceGraphToInstructions({
+            startNodeId: "n_start",
+            nodes: [{
+                id: "n_start",
+                type: "initial",
+                title: "Welcome",
+                prompt: "Negotiate the price.",
+                outputs: [{ id: "o_discount", label: "Discount", desc: "Broker asks for a discount." }],
+            }, {
+                id: "n_ask_boss",
+                type: "sub_agent",
+                title: "Ask boss",
+                prompt: "Ask if the requested discount can be accepted.",
+                subAgentToolId: "voice_agent_boss_approval",
+                outputs: [
+                    { id: "outcome_accept", label: "accept", desc: "Boss accepts." },
+                    { id: "outcome_decline", label: "decline", desc: "Boss declines." },
+                ],
+            }],
+            edges: [{ from: "n_start", fromPort: "o_discount", to: "n_ask_boss" }],
+        }, { tools: [subAgentTool] });
+
+        expect(compiled).toMatchObject({
+            referencedToolIds: ["voice_agent_boss_approval"],
+            missingToolIds: [],
+        });
+        expect(compiled?.toolManifest).toEqual([expect.objectContaining({
+            name: "voice_agent_boss_approval",
+            parameters: subAgentTool.inputSchema,
+        })]);
+        expect(compiled?.instructions).toContain("Call sub-agent tool Voice Agent: Boss approval (`voice_agent_boss_approval`) after collecting: discount. Wait for its final result, read the returned `outcome`, and continue through the matching outcome branch.");
+        expect(compiled?.instructions).toContain("Sub-agent outcome branches: accept (Boss accepts.); decline (Boss declines.).");
+    });
+
+    it("appends metadata flow graphs to prepared system instructions for legacy uncompiled configs", () => {
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            metadata: {
+                ...baseConfig.metadata,
+                flowGraph: {
+                    nodes: [{
+                        id: "n_start",
+                        type: "initial",
+                        title: "Welcome",
+                        prompt: "Greet and route.",
+                        outputs: [{ id: "o_order", label: "Order status", desc: "Order questions." }],
+                    }, {
+                        id: "n_lookup",
+                        type: "tool",
+                        title: "Lookup order",
+                        toolId: "lookup_order",
+                    }],
+                    edges: [{ from: "n_start", fromPort: "o_order", to: "n_lookup" }],
+                },
+            },
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "web",
+        });
+
+        expect(prepare.system).toContain("Greet and route.");
+        expect(prepare.system).toContain("When Order questions.");
+        expect(prepare.metadata.flowGraph).toEqual({
+            startNodeId: "n_start",
+            entryMode: "both",
+            nodeCount: 2,
+            edgeCount: 1,
+            referencedToolIds: ["lookup_order"],
+            missingToolIds: [],
+        });
+    });
+
+    it("compiles flow graph instructions into config and does not append them twice at runtime", () => {
+        const compiledConfig = compileCloudVoiceGraphConfig({
+            ...baseConfig,
+            instructions: "Old dashboard prompt.",
+            metadata: {
+                ...baseConfig.metadata,
+                flowGraph: {
+                    nodes: [{
+                        id: "n_start",
+                        type: "initial",
+                        title: "Welcome",
+                        prompt: "You are Aria. Route callers by intent.",
+                        outputs: [{ id: "o_refund", label: "Refund request", desc: "Caller asks for a refund." }],
+                    }, {
+                        id: "n_lookup",
+                        type: "tool",
+                        title: "Lookup order",
+                        prompt: "Confirm the order before checking refund policy.",
+                        toolId: "lookup_order",
+                    }, {
+                        id: "n_end",
+                        type: "end",
+                        title: "Close",
+                        prompt: "Explain the result and close politely.",
+                    }],
+                    edges: [
+                        { from: "n_start", fromPort: "o_refund", to: "n_lookup" },
+                        { from: "n_lookup", fromPort: null, to: "n_end" },
+                    ],
+                },
+            },
+        });
+
+        expect(compiledConfig.instructions).not.toContain("Old dashboard prompt.");
+        expect(compiledConfig.instructions).toContain("When Caller asks for a refund.");
+        expect(compiledConfig.instructions).toContain("Use Lookup order (`lookup_order`)");
+        expect(compiledConfig.metadata?.flowGraphInstructionCompiler).toMatchObject({
+            version: "voice-flow-paths-v1",
+            graphSignature: expect.any(String),
+        });
+
+        const prepare = prepareCloudVoiceSessionConfig(compiledConfig, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "web",
+        });
+        expect(prepare.system.match(/When Caller asks for a refund\./g)).toHaveLength(1);
+    });
+
+    it("uses initial flow node runtime settings when preparing and publishing graph configs", () => {
+        const graphConfig = {
+            ...baseConfig,
+            provider: "openai-realtime" as const,
+            model: "gpt-realtime-2",
+            voice: "marin",
+            transport: "webrtc" as const,
+            providerOptions: { reasoning: { effort: "low" } },
+            metadata: {
+                ...baseConfig.metadata,
+                flowGraph: {
+                    nodes: [{
+                        id: "n_start",
+                        type: "initial",
+                        title: "Welcome",
+                        prompt: "Route callers.",
+                        provider: "xai-realtime" as const,
+                        model: "grok-voice-think-fast-1.0",
+                        voice: "eve",
+                        transport: "websocket" as const,
+                        providerOptions: {},
+                        transcription: null,
+                        inputNoiseReduction: null,
+                    }],
+                    edges: [],
+                },
+            },
+        };
+
+        const compiledConfig = compileCloudVoiceGraphConfig(graphConfig);
+        expect(compiledConfig).toMatchObject({
+            provider: "xai-realtime",
+            model: "grok-voice-think-fast-1.0",
+            voice: "eve",
+            transport: "websocket",
+            providerOptions: {},
+            transcription: null,
+            inputNoiseReduction: null,
+        });
+
+        const prepare = prepareCloudVoiceSessionConfig(graphConfig, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "caller-1" },
+            channel: "outbound",
+        });
+        expect(prepare.runtime).toMatchObject({
+            provider: "xai-realtime",
+            model: "grok-voice-think-fast-1.0",
+            voice: "eve",
+            transport: "websocket",
+        });
+    });
+
+    it("prepares direction-specific prompts and runtime settings from separate initial nodes", () => {
+        const graphConfig: CloudVoiceAgentConfig = {
+            ...baseConfig,
+            provider: "openai-realtime",
+            model: "gpt-realtime-2",
+            voice: "marin",
+            transport: "webrtc",
+            metadata: {
+                ...baseConfig.metadata,
+                flowGraph: {
+                    startNodeId: "n_incoming",
+                    nodes: [{
+                        id: "n_incoming",
+                        type: "initial",
+                        entryMode: "incoming",
+                        title: "Incoming start",
+                        prompt: "Use the inbound service flow.",
+                        provider: "openai-realtime",
+                        model: "gpt-realtime-2",
+                        voice: "marin",
+                        transport: "webrtc",
+                    }, {
+                        id: "n_outgoing",
+                        type: "initial",
+                        entryMode: "outgoing",
+                        title: "Outgoing start",
+                        prompt: "Use the outbound reminder flow.",
+                        provider: "xai-realtime",
+                        model: "grok-voice-think-fast-1.0",
+                        voice: "eve",
+                        transport: "websocket",
+                        transcription: null,
+                        inputNoiseReduction: null,
+                    }],
+                    edges: [],
+                },
+            },
+        };
+
+        const incoming = prepareCloudVoiceSessionConfig(graphConfig, {
+            agentName: "Support",
+            sessionId: "voice_session_in",
+            resourceId: { userId: "caller-1" },
+            channel: "phone",
+        });
+        const outgoing = prepareCloudVoiceSessionConfig(graphConfig, {
+            agentName: "Support",
+            sessionId: "voice_session_out",
+            resourceId: { userId: "caller-1" },
+            channel: "outbound",
+        });
+
+        expect(incoming.runtime).toMatchObject({
+            provider: "openai-realtime",
+            model: "gpt-realtime-2",
+            voice: "marin",
+            transport: "webrtc",
+        });
+        expect(incoming.system).toContain("Use the inbound service flow.");
+        expect(incoming.system).not.toContain("Use the outbound reminder flow.");
+        expect(incoming.metadata.flowGraph).toMatchObject({
+            startNodeId: "n_incoming",
+            entryMode: "incoming",
+        });
+
+        expect(outgoing.runtime).toMatchObject({
+            provider: "xai-realtime",
+            model: "grok-voice-think-fast-1.0",
+            voice: "eve",
+            transport: "websocket",
+        });
+        expect(outgoing.voiceConfig.transcription).toBeNull();
+        expect(outgoing.voiceConfig.inputNoiseReduction).toBeNull();
+        expect(outgoing.system).toContain("Use the outbound reminder flow.");
+        expect(outgoing.system).not.toContain("Use the inbound service flow.");
+        expect(outgoing.metadata.flowGraph).toMatchObject({
+            startNodeId: "n_outgoing",
+            entryMode: "outgoing",
+        });
+    });
+
+    it("injects SIP transfer control when transfer destinations are configured", () => {
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            metadata: {
+                ...baseConfig.metadata,
+                transferDestinations: [{
+                    id: "support_queue",
+                    name: "Support queue",
+                    provider: "telnyx",
+                    destination: { type: "sip_uri", uri: "sip:support@example.com" },
+                    policy: { mode: "warm", timeoutSeconds: 25, fallback: "return_to_ai" },
+                }],
+            },
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "caller-1" },
+            channel: "sip",
+        });
+
+        expect(prepare.toolManifest).toEqual(expect.arrayContaining([
+            CLOUD_VOICE_SIP_TRANSFER_TOOL,
+        ]));
+        expect(prepare.metadata.transferDestinations).toEqual(["support_queue"]);
+    });
+
+    it("preserves xAI realtime provider defaults in prepared sessions", () => {
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            provider: "xai-realtime",
+            model: "grok-voice-think-fast-1.0",
+            voice: "eve",
+            transport: "websocket",
+            transcription: null,
+            inputNoiseReduction: null,
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "user-1" },
+            channel: "web",
+        });
+
+        expect(prepare.runtime).toEqual(expect.objectContaining({
+            provider: "xai-realtime",
+            mode: "realtime",
+            model: "grok-voice-think-fast-1.0",
+            voice: "eve",
+            transport: "websocket",
+        }));
+        expect(prepare.voiceConfig.transcription).toBeNull();
+        expect(prepare.voiceConfig.inputNoiseReduction).toBeNull();
+    });
+
+    it("normalizes humanization and can omit naturalness rules", () => {
+        expect(normalizeCloudVoiceHumanizationConfig(undefined)).toEqual({
+            enabled: true,
+            openingMode: "auto",
+            openingStyle: "brief",
+            fillerStyle: "light",
+            backchannelFrequency: "low",
+            disfluency: "rare",
+            toolLatencyFillerMs: 700,
+            conversationProfile: {
+                personality: "warm",
+                tone: "professional",
+                pacing: "concise",
+                unclearAudio: "ask_repeat",
+                confirmation: "critical_fields",
+                escalation: "when_blocked",
+                numberReadback: true,
+            },
+        });
+
+        const prepare = prepareCloudVoiceSessionConfig({
+            ...baseConfig,
+            humanization: { enabled: false },
+        }, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: {},
+            channel: "phone",
+        });
+
+        expect(prepare.system).not.toContain("Conversation naturalness:");
+        expect(prepare.system).toContain("yalnızca bir soruyu cevapladın veya bir işi tamamladın diye çağrıyı bitirme");
+        expect(prepare.system).toContain("hang_up_call aracını yalnızca arayan açıkça çağrıyı bitirmek isterse");
+        expect(prepare.system).toContain("hang_up_call aracını çağırmadan hemen önce");
+        expect(prepare.system).toContain("Arayan hangi araçlara, fonksiyonlara, yeteneklere veya işlemlere erişebildiğini sorarsa");
+        expect(prepare.system).toContain("dahili agent adını");
+        expect(prepare.system).not.toContain("You may introduce yourself as Support");
+    });
+
+    it("builds phone opening prompts from humanization and speech config", () => {
+        expect(buildPhoneOpeningPrompt({
+            config: {
+                humanization: { openingMode: "auto", openingStyle: "warm" },
+                metadata: { speech: { language: "tr" } },
+            },
+            agentName: "Support",
+            channel: "outbound",
+        })).toContain("Turkish dilinde sıcak ve samimi bir selamlamayla başlat");
+        expect(buildPhoneOpeningPrompt({
+            config: {
+                humanization: { openingMode: "auto", openingStyle: "warm" },
+                metadata: {
+                    flowGraph: {
+                        startNodeId: "n_start",
+                        nodes: [{
+                            id: "n_start",
+                            type: "initial",
+                            firstMessage: "Merhaba, ben Evital'dan Vahit, sizi yaklaşan randevunuzu hatırlatmak için arıyorum.",
+                        }],
+                        edges: [],
+                    },
+                },
+            },
+            agentName: "Voice agent 11",
+            channel: "outbound",
+        })).toContain("say exactly this first sentence");
+        expect(buildPhoneOpeningPrompt({
+            config: {
+                humanization: { openingMode: "auto", openingStyle: "warm" },
+                metadata: {
+                    flowGraph: {
+                        startNodeId: "n_start",
+                        nodes: [{
+                            id: "n_start",
+                            type: "initial",
+                            firstMessage: "Merhaba, ben Evital'dan Vahit, sizi yaklaşan randevunuzu hatırlatmak için arıyorum.",
+                        }],
+                        edges: [],
+                    },
+                },
+            },
+            agentName: "Voice agent 11",
+            channel: "outbound",
+        })).not.toContain("Voice agent 11");
+
+        expect(buildPhoneOpeningPrompt({
+            config: {
+                humanization: { openingMode: "auto", openingStyle: "warm" },
+                metadata: {
+                    flowGraph: {
+                        startNodeId: "n_incoming",
+                        nodes: [{
+                            id: "n_incoming",
+                            type: "initial",
+                            entryMode: "incoming",
+                            firstMessage: "Thanks for calling Acme.",
+                        }, {
+                            id: "n_outgoing",
+                            type: "initial",
+                            entryMode: "outgoing",
+                            firstMessage: "Hi, I am calling from Acme.",
+                        }],
+                        edges: [],
+                    },
+                },
+            },
+            agentName: "Voice agent 11",
+            channel: "outbound",
+        })).toContain("Hi, I am calling from Acme.");
+
+        expect(buildPhoneOpeningPrompt({
+            config: {
+                humanization: { openingMode: "wait" },
+                metadata: { speech: { language: "en" } },
+            },
+            agentName: "Support",
+            channel: "phone",
+        })).toBeNull();
+    });
+
+    it("injects hangup for phone sessions and dedupes client tool manifests", () => {
+        const prepare = prepareCloudVoiceSessionConfig(baseConfig, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "caller-1" },
+            channel: "phone",
+            clientTools: [{
+                id: "lookup_order",
+                name: "Client lookup",
+                description: "Client side lookup",
+                inputSchema: { type: "object", properties: { id: { type: "string" } } },
+            }],
+        });
+
+        expect(prepare.toolManifest).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                name: "lookup_order",
+                description: "Client side lookup",
+            }),
+            CLOUD_VOICE_PHONE_HANGUP_TOOL,
+        ]));
+        expect(prepare.toolManifest.at(-1)?.name).toBe("hang_up_call");
+        expect(prepare.metadata.clientTools).toEqual(["lookup_order"]);
+    });
+
+    it("normalizes OpenAI turn detection", () => {
+        expect(toOpenAITurnDetection({
+            type: "server_vad",
+            createResponse: true,
+            interruptResponse: false,
+            prefixPaddingMs: 250,
+            silenceDurationMs: 600,
+            threshold: 0.5,
+            eagerness: "medium",
+        })).toEqual({
+            type: "server_vad",
+            create_response: true,
+            interrupt_response: false,
+            prefix_padding_ms: 250,
+            silence_duration_ms: 600,
+            threshold: 0.5,
+            eagerness: "medium",
+        });
+    });
+
+    it("creates stable phone prepare snapshots", () => {
+        const prepare = prepareCloudVoiceSessionConfig(baseConfig, {
+            agentName: "Support",
+            sessionId: "voice_session_1",
+            resourceId: { userId: "caller-1" },
+            channel: "phone",
+        });
+        const snapshot = createPhonePrepareSnapshot({
+            agent: {
+                id: "agent-1",
+                slug: "support",
+                name: "Support",
+                draftVersion: 3,
+                publishedVersion: 2,
+            },
+            channel: "phone",
+            config: baseConfig,
+            prepare,
+            now: new Date("2026-04-28T00:00:00.000Z"),
+        });
+
+        expect(snapshot).toMatchObject({
+            schemaVersion: 1,
+            createdAt: "2026-04-28T00:00:00.000Z",
+            channel: "phone",
+            agent: {
+                id: "agent-1",
+                slug: "support",
+                version: 2,
+            },
+            runtime: prepare.runtime,
+            voiceConfig: prepare.voiceConfig,
+            toolManifest: prepare.toolManifest,
+        });
+        expect(snapshot.config).toBe(baseConfig);
+    });
+});
+
+describe("@kognitivedev/backend-cloud tool execution", () => {
+    it("dispatches managed tools to supplied handlers", async () => {
+        await expect(executeCloudVoiceToolBinding({
+            projectId: "project-1",
+            sessionId: "session-1",
+            tool: {
+                id: "search",
+                type: "web_search",
+                name: "Search",
+                config: { parameters: { maxResults: 3 } },
+            },
+            args: { query: "status page" },
+            executeWebSearch: async (input) => ({ query: input.query, parameters: input.parameters }),
+        })).resolves.toEqual({
+            result: { query: "status page", parameters: { maxResults: 3 } },
+            metadata: {},
+        });
+    });
+
+    it("dispatches calendar action tools to supplied handlers", async () => {
+        await expect(executeCloudVoiceToolBinding({
+            projectId: "project-1",
+            sessionId: "session-1",
+            tool: {
+                id: "calendar_hold_slot",
+                type: "calendar_action",
+                name: "Hold calendar slot",
+                config: { action: "calendar_hold_slot", resourceId: "resource-1" },
+            },
+            args: { serviceId: "service-1", startAt: "2026-05-20T17:00:00.000Z" },
+            executeCalendarAction: async (input) => input,
+        })).resolves.toEqual({
+            result: {
+                action: "calendar_hold_slot",
+                args: { serviceId: "service-1", startAt: "2026-05-20T17:00:00.000Z" },
+                config: { action: "calendar_hold_slot", resourceId: "resource-1" },
+            },
+            metadata: {},
+        });
+    });
+
+    it("injects configured parameter bindings into managed tool arguments", async () => {
+        await expect(executeCloudVoiceToolBinding({
+            projectId: "project-1",
+            sessionId: "session-1",
+            tool: {
+                id: "lookup_order",
+                type: "external_webhook",
+                name: "Lookup order",
+                config: { url: "https://example.test/tools/lookup" },
+                parameterBindings: {
+                    userId: { parameter: "user_id" },
+                    phone: { parameter: "phone" },
+                },
+            },
+            args: { orderNumber: "KV-1042" },
+            parameters: { user_id: "user-1", phone: "+15551234567" },
+            executeExternalWebhook: async (input) => ({ args: input.args }),
+        })).resolves.toEqual({
+            result: { args: { orderNumber: "KV-1042", userId: "user-1", phone: "+15551234567" } },
+            metadata: {},
+        });
+    });
+
+    it("dispatches SIP transfer tools to supplied handlers", async () => {
+        await expect(executeCloudVoiceToolBinding({
+            projectId: "project-1",
+            sessionId: "session-1",
+            tool: {
+                id: "transfer_to_support",
+                type: "sip_transfer",
+                name: "Transfer to support",
+                config: {
+                    destination: { type: "sip_uri", uri: "sip:support@example.com" },
+                    mode: "warm",
+                },
+            },
+            args: {
+                providerCallId: "call_1",
+                reason: "caller needs live support",
+            },
+            executeSipTransfer: async (input) => ({
+                provider: "telnyx",
+                providerCallId: input.providerCallId,
+                status: "active",
+                destination: input.destination,
+                mode: input.mode ?? "blind",
+                transferId: "transfer_1",
+            }),
+        })).resolves.toMatchObject({
+            result: {
+                provider: "telnyx",
+                providerCallId: "call_1",
+                status: "active",
+                transferId: "transfer_1",
+                mode: "warm",
+            },
+            metadata: {
+                transfer: {
+                    providerCallId: "call_1",
+                    transferId: "transfer_1",
+                    mode: "warm",
+                    status: "active",
+                },
+            },
+        });
+    });
+
+    it("dispatches cloud voice agent tools with mapped parameters", async () => {
+        const executeCloudVoiceAgent = vi.fn(async (input) => ({
+            childSessionId: "child-session-1",
+            status: "completed",
+            outcome: "accept",
+            input,
+        }));
+
+        await expect(executeCloudVoiceToolBinding({
+            projectId: "project-1",
+            sessionId: "session-1",
+            tool: {
+                id: "voice_agent_boss_approval",
+                type: "cloud_voice_agent",
+                name: "Voice Agent: Boss approval",
+                config: {
+                    agentSlug: "boss-approval",
+                    fromNumberId: "pn_1",
+                    toTemplate: "{{params.boss_phone}}",
+                    timeoutMs: 600_000,
+                    parameterMappings: {
+                        discount: { mode: "parent_parameter", value: "requested_discount" },
+                        reason: { mode: "literal", value: "broker requested a discount" },
+                    },
+                },
+                parameterBindings: {
+                    dealId: { parameter: "deal_id" },
+                },
+            },
+            args: { notes: "urgent" },
+            parameters: {
+                boss_phone: "+15550001111",
+                requested_discount: 12,
+                deal_id: "deal_1",
+            },
+            executeCloudVoiceAgent,
+        })).resolves.toMatchObject({
+            result: {
+                childSessionId: "child-session-1",
+                status: "completed",
+                outcome: "accept",
+            },
+            metadata: {},
+        });
+
+        expect(executeCloudVoiceAgent).toHaveBeenCalledWith(expect.objectContaining({
+            agentSlug: "boss-approval",
+            fromNumberId: "pn_1",
+            to: "+15550001111",
+            timeoutMs: 600_000,
+            intervalMs: 2_000,
+            parameters: {
+                notes: "urgent",
+                dealId: "deal_1",
+                discount: 12,
+                reason: "broker requested a discount",
+            },
+        }));
+    });
+});