@kognitivedev/backend-cloud 0.2.29

package/src/cloud-voice.ts

@@ -0,0 +1,831 @@
+import type {
+    CloudVoiceAgentConfig,
+    CloudVoiceAgentSnapshot,
+    CloudVoiceChannel,
+    CloudVoiceClientToolManifest,
+    CloudVoiceFlowEdge,
+    CloudVoiceFlowGraph,
+    CloudVoiceFlowNode,
+    CloudVoiceFlowNodeOutput,
+    CloudVoiceFunctionToolManifest,
+    CloudVoiceParameterResolutionResult,
+    CloudVoicePhonePrepareSnapshot,
+    CloudVoiceSpeechConfig,
+    CloudVoiceToolBinding,
+    CloudVoiceTransferDestination,
+    CloudVoiceTransferMode,
+    CompiledCloudVoiceFlowInstructions,
+    PreparedCloudVoiceConfig,
+} from "./types";
+import { getRecord, getString } from "./utils";
+import {
+    CLOUD_VOICE_CONFIG_VERSION,
+    CLOUD_VOICE_PROMPT_COMPILER_VERSION,
+    compileCartesiaTtsOptions,
+    getCloudVoiceProviderCapabilities,
+    normalizeCloudVoiceInputNoiseReduction,
+    normalizeCloudVoicePipelineConfig,
+    normalizeCloudVoiceTurnDetection,
+    normalizeSpeechConfig,
+    resolveCloudVoiceSpeechLanguageCode,
+    toPreparedTranscription,
+} from "./cloud-voice-runtime-service";
+import { buildPhoneControlRule, compileCloudVoiceInstructions } from "./cloud-voice-prompt-service";
+import {
+    renderCloudVoiceParameterObject,
+    renderCloudVoiceParameterTemplate,
+} from "./cloud-voice-parameters";
+
+export {
+    CLOUD_VOICE_CONFIG_VERSION,
+    CLOUD_VOICE_PROMPT_COMPILER_VERSION,
+    CLOUD_VOICE_PROVIDER_CAPABILITIES,
+    DEFAULT_CLOUD_VOICE_HUMANIZATION,
+    compileCartesiaTtsOptions,
+    getCloudVoiceProviderCapabilities,
+    normalizeCloudVoiceConversationProfile,
+    normalizeCloudVoiceHumanizationConfig,
+    normalizeCloudVoicePipelineConfig,
+    normalizeCloudVoiceTurnDetection,
+    resolveCloudVoiceSpeechLanguageCode,
+    toOpenAITurnDetection,
+    toPreparedTranscription,
+} from "./cloud-voice-runtime-service";
+export {
+    buildPhoneControlRule,
+    buildPhoneOpeningPrompt,
+    compileCloudVoiceInstructions,
+    resolveCloudVoiceProviderSystemPrompt,
+} from "./cloud-voice-prompt-service";
+
+export const CLOUD_VOICE_CHANNELS = new Set<CloudVoiceChannel>(["web", "iframe", "script", "phone", "sip", "outbound"]);
+type CloudVoiceGraphEntryMode = "incoming" | "outgoing" | "both";
+
+export const CLOUD_VOICE_PHONE_HANGUP_TOOL: CloudVoiceFunctionToolManifest = {
+    type: "function",
+    name: "hang_up_call",
+    description: "End the active phone call only after the caller clearly asks to end the call, says goodbye, or answers that they do not need anything else after you ask. Before using this tool, make sure the conversation has a natural closing: ask if there is anything else unless the caller already clearly ended, then say a brief goodbye such as \"bye\", \"see you later\", or \"take care\". Never use this when the caller asks what tools, abilities, or actions you have access to.",
+    parameters: {
+        type: "object",
+        properties: {
+            reason: {
+                type: "string",
+                description: "Short reason for ending the call.",
+            },
+        },
+        required: ["reason"],
+        additionalProperties: false,
+    },
+};
+
+export const CLOUD_VOICE_SIP_TRANSFER_TOOL: CloudVoiceFunctionToolManifest = {
+    type: "function",
+    name: "sip_transfer_call",
+    description: "Transfer the active SIP or phone call to a configured destination only when the current voice flow or agent policy allows transfer. Use this for live SIP/queue/extension/phone-number handoff, not for summarizing information.",
+    parameters: {
+        type: "object",
+        properties: {
+            providerCallId: {
+                type: "string",
+                description: "Provider call id for the active call leg. Omit when the runtime supplies it out of band.",
+            },
+            destinationId: {
+                type: "string",
+                description: "Configured transfer destination id.",
+            },
+            mode: {
+                type: "string",
+                enum: ["blind", "attended", "warm"],
+                description: "Transfer mode requested by the flow policy.",
+            },
+            reason: {
+                type: "string",
+                description: "Brief reason for the transfer.",
+            },
+        },
+        required: ["destinationId", "reason"],
+        additionalProperties: false,
+    },
+};
+
+export function resolveCloudVoiceChannel(value: unknown): CloudVoiceChannel {
+    if (value === undefined || value === null || value === "") return "web";
+    if (typeof value === "string" && CLOUD_VOICE_CHANNELS.has(value as CloudVoiceChannel)) {
+        return value as CloudVoiceChannel;
+    }
+    throw new Error(`Unsupported cloud voice channel "${String(value)}"`);
+}
+
+export function shouldInjectPhoneControlTools(channel?: CloudVoiceChannel) {
+    return channel === "phone" || channel === "sip" || channel === "outbound";
+}
+
+function getTransferDestinations(config: Pick<CloudVoiceAgentConfig, "metadata">) {
+    const destinations = getRecord(config.metadata).transferDestinations;
+    return Array.isArray(destinations)
+        ? destinations.filter((destination): destination is CloudVoiceTransferDestination => {
+            const record = getRecord(destination);
+            return typeof record.id === "string" && record.id.trim() !== "" && typeof record.destination === "object";
+        })
+        : [];
+}
+
+function entryModeForChannel(channel?: CloudVoiceChannel): CloudVoiceGraphEntryMode {
+    return channel === "outbound" ? "outgoing" : channel === "phone" ? "incoming" : "both";
+}
+
+function normalizeEntryMode(value: unknown): CloudVoiceGraphEntryMode {
+    if (value === "incoming" || value === "inbound") return "incoming";
+    if (value === "outgoing" || value === "outbound") return "outgoing";
+    return "both";
+}
+
+export function shouldInjectSipControlTools(config: Pick<CloudVoiceAgentConfig, "metadata">, channel?: CloudVoiceChannel) {
+    if (channel !== "sip" && channel !== "phone" && channel !== "outbound") return false;
+    return getTransferDestinations(config).some((destination) => destination.destination.type !== "browser_queue");
+}
+
+export function shouldPersistPhonePrepareSnapshot(channel: CloudVoiceChannel) {
+    return shouldInjectPhoneControlTools(channel);
+}
+
+export function resolveToolInputSchema(tool: CloudVoiceToolBinding) {
+    const schema = tool.inputSchema ?? getRecord(tool.config).inputSchema;
+    return schema && typeof schema === "object" && !Array.isArray(schema)
+        ? schema as Record<string, unknown>
+        : { type: "object", additionalProperties: true };
+}
+
+const MAX_FLOW_NODES = 64;
+const MAX_FLOW_EDGES = 128;
+const MAX_FLOW_TEXT_LENGTH = 900;
+export const CLOUD_VOICE_FLOW_INSTRUCTION_COMPILER_VERSION = "voice-flow-paths-v1";
+
+function getFlowArray(value: unknown): unknown[] {
+    return Array.isArray(value) ? value : [];
+}
+
+function cleanFlowText(value: unknown, maxLength = MAX_FLOW_TEXT_LENGTH) {
+    const text = getString(value, "").replace(/\s+/g, " ").trim();
+    return text.length > maxLength ? `${text.slice(0, maxLength - 3)}...` : text;
+}
+
+function normalizeFlowOutput(value: unknown): CloudVoiceFlowNodeOutput | null {
+    const record = getRecord(value);
+    const id = cleanFlowText(record.id, 96);
+    const label = cleanFlowText(record.label, 140);
+    if (!id || !label) return null;
+    return {
+        id,
+        label,
+        description: cleanFlowText(record.description, 360) || undefined,
+        desc: cleanFlowText(record.desc, 360) || undefined,
+        condition: cleanFlowText(record.condition, 360) || undefined,
+        icon: cleanFlowText(record.icon, 96) || undefined,
+        metadata: getRecord(record.metadata),
+    };
+}
+
+function normalizeFlowNode(value: unknown): CloudVoiceFlowNode | null {
+    const record = getRecord(value);
+    const id = cleanFlowText(record.id, 96);
+    const type = cleanFlowText(record.type, 64) || "case";
+    if (!id) return null;
+    const toolIds = getFlowArray(record.toolIds)
+        .map((toolId) => cleanFlowText(toolId, 96))
+        .filter(Boolean);
+    const phoneNumberIds = getFlowArray(record.phoneNumberIds)
+        .map((phoneNumberId) => cleanFlowText(phoneNumberId, 96))
+        .filter(Boolean);
+    const maxDuration = typeof record.maxDuration === "number" && Number.isFinite(record.maxDuration)
+        ? Math.round(record.maxDuration)
+        : cleanFlowText(record.maxDuration, 32) || undefined;
+    const transferMode = record.transferMode === "attended" || record.transferMode === "warm" || record.transferMode === "blind"
+        ? record.transferMode as CloudVoiceTransferMode
+        : undefined;
+    const metadata = getRecord(record.metadata);
+    const subAgentMetadata = type === "sub_agent"
+        ? {
+            ...getRecord(metadata.subAgent),
+            ...(getString(record.subAgentToolId, "") ? { toolId: getString(record.subAgentToolId, "") } : {}),
+            ...(getString(record.subAgentSlug, "") ? { agentSlug: getString(record.subAgentSlug, "") } : {}),
+        }
+        : null;
+    return {
+        id,
+        type,
+        entryMode: normalizeEntryMode(record.entryMode),
+        title: cleanFlowText(record.title, 160) || undefined,
+        prompt: cleanFlowText(record.prompt) || undefined,
+        firstMessage: cleanFlowText(record.firstMessage, 360) || undefined,
+        language: cleanFlowText(record.language, 32) || undefined,
+        maxDuration,
+        outputs: getFlowArray(record.outputs).map(normalizeFlowOutput).filter((output): output is CloudVoiceFlowNodeOutput => Boolean(output)),
+        toolId: cleanFlowText(record.toolId, 96) || undefined,
+        toolIds,
+        phoneNumberIds,
+        transferTarget: cleanFlowText(record.transferTarget, 160) || undefined,
+        transferDestinationId: cleanFlowText(record.transferDestinationId, 96) || undefined,
+        transferMode,
+        metadata: subAgentMetadata ? { ...metadata, subAgent: subAgentMetadata } : metadata,
+    };
+}
+
+function normalizeFlowEdge(value: unknown): CloudVoiceFlowEdge | null {
+    const record = getRecord(value);
+    const from = cleanFlowText(record.from, 96);
+    const to = cleanFlowText(record.to, 96);
+    if (!from || !to) return null;
+    const fromPort = record.fromPort === null ? null : cleanFlowText(record.fromPort, 96) || null;
+    return {
+        id: cleanFlowText(record.id, 96) || undefined,
+        from,
+        fromPort,
+        to,
+    };
+}
+
+function normalizeFlowGraph(value: unknown): CloudVoiceFlowGraph | null {
+    const record = getRecord(value);
+    const nodes = getFlowArray(record.nodes)
+        .slice(0, MAX_FLOW_NODES)
+        .map(normalizeFlowNode)
+        .filter((node): node is CloudVoiceFlowNode => Boolean(node));
+    const knownNodeIds = new Set(nodes.map((node) => node.id));
+    const edges = getFlowArray(record.edges)
+        .slice(0, MAX_FLOW_EDGES)
+        .map(normalizeFlowEdge)
+        .filter((edge): edge is CloudVoiceFlowEdge => Boolean(edge && knownNodeIds.has(edge.from) && knownNodeIds.has(edge.to)));
+    if (nodes.length === 0) return null;
+    const startNodeId = cleanFlowText(record.startNodeId, 96);
+    return {
+        version: record.version === 1 ? 1 : undefined,
+        startNodeId: startNodeId && knownNodeIds.has(startNodeId) ? startNodeId : undefined,
+        nodes,
+        edges,
+        metadata: getRecord(record.metadata),
+    };
+}
+
+function resolveFlowStartNode(graph: CloudVoiceFlowGraph, options: { entryMode?: CloudVoiceGraphEntryMode } = {}) {
+    const entryMode = options.entryMode ?? "both";
+    const initialNodes = graph.nodes.filter((node) => node.type === "initial");
+    const matchingStart = entryMode !== "both"
+        ? initialNodes.find((node) => normalizeEntryMode(node.entryMode) === entryMode)
+        : null;
+    const bothStart = initialNodes.find((node) => normalizeEntryMode(node.entryMode) === "both");
+    const legacyStart = graph.nodes.find((node) => node.id === graph.startNodeId)
+        ?? initialNodes[0]
+        ?? graph.nodes[0]
+        ?? null;
+    return matchingStart ?? bothStart ?? legacyStart;
+}
+
+function outputDescription(output: CloudVoiceFlowNodeOutput) {
+    return output.condition ?? output.description ?? output.desc ?? "";
+}
+
+function edgeTargetTitle(edge: CloudVoiceFlowEdge, nodesById: Map<string, CloudVoiceFlowNode>) {
+    const target = nodesById.get(edge.to);
+    return target ? `${target.title ?? target.id} (${target.type})` : edge.to;
+}
+
+function collectNodeToolIds(node: CloudVoiceFlowNode) {
+    const metadata = getRecord(node.metadata);
+    const subAgent = getRecord(metadata.subAgent);
+    return [
+        node.toolId,
+        ...(node.toolIds ?? []),
+        getString((node as unknown as Record<string, unknown>).subAgentToolId, ""),
+        getString(subAgent.toolId, ""),
+        getString(subAgent.subAgentToolId, ""),
+        getString(metadata.toolId, ""),
+        getString(metadata.toolName, ""),
+    ].map((value) => cleanFlowText(value, 96)).filter(Boolean);
+}
+
+function toolToManifest(tool: CloudVoiceToolBinding): CloudVoiceFunctionToolManifest {
+    return {
+        type: "function",
+        name: tool.id,
+        description: tool.description ?? tool.name,
+        parameters: resolveToolInputSchema(tool),
+    };
+}
+
+function stableJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const record = value as Record<string, unknown>;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+
+function hashText(value: string) {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(36);
+}
+
+function graphSignature(graph: CloudVoiceFlowGraph) {
+    return hashText(stableJson(graph));
+}
+
+function toolLabel(toolId: string, toolsById: Map<string, CloudVoiceToolBinding>) {
+    const tool = toolsById.get(toolId);
+    return tool ? `${tool.name ?? tool.id} (\`${tool.id}\`)` : `\`${toolId}\``;
+}
+
+function toolRequiredInputs(tool: CloudVoiceToolBinding | undefined) {
+    if (!tool) return "";
+    const schema = getRecord(resolveToolInputSchema(tool));
+    const required = Array.isArray(schema.required)
+        ? schema.required.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+        : [];
+    return required.length > 0 ? required.join(", ") : "";
+}
+
+function outgoingEdges(nodeId: string, edgesBySource: Map<string, CloudVoiceFlowEdge[]>) {
+    return edgesBySource.get(nodeId) ?? [];
+}
+
+function outputForEdge(node: CloudVoiceFlowNode | undefined, edge: CloudVoiceFlowEdge) {
+    return node?.outputs?.find((output) => output.id === edge.fromPort) ?? null;
+}
+
+function walkFlowPath(input: {
+    fromNodeId: string;
+    nodesById: Map<string, CloudVoiceFlowNode>;
+    edgesBySource: Map<string, CloudVoiceFlowEdge[]>;
+    toolsById: Map<string, CloudVoiceToolBinding>;
+    referencedToolIds: Set<string>;
+    visited?: Set<string>;
+}): {
+    steps: string[];
+    toolIds: string[];
+    terminal: CloudVoiceFlowNode | null;
+} {
+    const steps: string[] = [];
+    const toolIds: string[] = [];
+    const visited = new Set(input.visited ?? []);
+    let current = input.nodesById.get(input.fromNodeId) ?? null;
+
+    while (current && !visited.has(current.id)) {
+        visited.add(current.id);
+        const title = current.title ?? current.id;
+
+        if (current.type !== "initial") {
+            if (current.prompt) {
+                steps.push(`At "${title}", ${current.prompt}`);
+            } else if (current.type === "case") {
+                steps.push(`Handle "${title}" as the active case.`);
+            }
+        }
+
+        const currentToolIds = collectNodeToolIds(current);
+        if (current.type === "tool" && currentToolIds.length === 0 && current.title) {
+            const inferred = [...input.toolsById.keys()].find((toolId) => toolId === current?.title || toolId.replace(/[_-]/g, " ").toLowerCase() === current?.title?.toLowerCase());
+            if (inferred) currentToolIds.push(inferred);
+        }
+        for (const toolId of currentToolIds) {
+            input.referencedToolIds.add(toolId);
+            toolIds.push(toolId);
+            const tool = input.toolsById.get(toolId);
+            const requiredInputs = toolRequiredInputs(tool);
+            if (current.type === "sub_agent") {
+                steps.push(`Call sub-agent tool ${toolLabel(toolId, input.toolsById)}${requiredInputs ? ` after collecting: ${requiredInputs}` : ""}. Wait for its final result, read the returned \`outcome\`, and continue through the matching outcome branch.`);
+                if (current.outputs && current.outputs.length > 0) {
+                    steps.push(`Sub-agent outcome branches: ${current.outputs.map((output) => `${output.label}${outputDescription(output) ? ` (${outputDescription(output)})` : ""}`).join("; ")}.`);
+                }
+            } else {
+                steps.push(`Use ${toolLabel(toolId, input.toolsById)}${requiredInputs ? ` after collecting: ${requiredInputs}` : ""}.`);
+            }
+        }
+
+        if (current.type === "end" || current.type === "transfer") {
+            return { steps, toolIds, terminal: current };
+        }
+
+        const edges = outgoingEdges(current.id, input.edgesBySource);
+        const defaultEdge = edges.find((edge) => !edge.fromPort) ?? edges[0] ?? null;
+        if (!defaultEdge) return { steps, toolIds, terminal: current };
+
+        const output = outputForEdge(current, defaultEdge);
+        if (output) {
+            const condition = outputDescription(output);
+            steps.push(`If "${output.label}"${condition ? ` (${condition})` : ""} matches inside this step, continue.`);
+        }
+        current = input.nodesById.get(defaultEdge.to) ?? null;
+    }
+
+    return { steps: [...steps, "Stop following this route if it loops back to a node already visited."], toolIds, terminal: current };
+}
+
+function terminalInstruction(node: CloudVoiceFlowNode | null) {
+    if (!node) return "";
+    const title = node.title ?? node.id;
+    if (node.type === "end") {
+        return node.prompt ? `Then end with: ${node.prompt}` : `Then end at "${title}" with a brief polite closing.`;
+    }
+    if (node.type === "transfer") {
+        const target = node.transferTarget || node.transferDestinationId || title;
+        return node.prompt ? `Then transfer/escalate to ${target}: ${node.prompt}` : `Then transfer/escalate to ${target} with a concise handoff summary.`;
+    }
+    return "";
+}
+
+export function compileVoiceGraphToInstructions(
+    graphInput: unknown,
+    options: { tools?: CloudVoiceToolBinding[]; entryMode?: CloudVoiceGraphEntryMode; channel?: CloudVoiceChannel } = {},
+): CompiledCloudVoiceFlowInstructions | null {
+    const graph = normalizeFlowGraph(graphInput);
+    if (!graph) return null;
+
+    const entryMode = options.entryMode ?? entryModeForChannel(options.channel);
+    const start = resolveFlowStartNode(graph, { entryMode });
+    const nodesById = new Map(graph.nodes.map((node) => [node.id, node] as const));
+    const edgesBySource = new Map<string, CloudVoiceFlowEdge[]>();
+    for (const edge of graph.edges) {
+        const list = edgesBySource.get(edge.from) ?? [];
+        list.push(edge);
+        edgesBySource.set(edge.from, list);
+    }
+
+    const toolsById = new Map((options.tools ?? []).map((tool) => [tool.id, tool] as const));
+    const referencedToolIds = new Set<string>();
+    const warnings: string[] = [];
+    const signature = graphSignature(graph);
+    const lines = [
+        start?.prompt || "You are a realtime voice agent. Help the caller clearly and concisely.",
+        "",
+        "Use this conversation flow as the source of truth for routing and tool usage.",
+        "Do not reveal internal node IDs, graph structure, or implementation details to the caller.",
+        "Choose the first route that clearly matches the caller's intent. If no route clearly matches, ask one concise clarifying question.",
+    ];
+    if (start?.firstMessage) {
+        lines.push(
+            `Opening rule: if you speak first, say exactly this as your first sentence before any other greeting or introduction: ${start.firstMessage}`,
+            "Do not prepend, replace, or append an internal agent name, agent number, slug, node name, or workflow name to that first sentence.",
+        );
+    }
+    if (start?.language) lines.push(`Use this language guidance when possible: ${start.language}.`);
+    if (start?.maxDuration !== undefined) lines.push(`Keep the call within ${String(start.maxDuration)} minutes unless the caller needs a short final clarification.`);
+
+    const startEdges = start ? outgoingEdges(start.id, edgesBySource) : [];
+    const routeEdges = start && start.outputs && start.outputs.length > 0
+        ? start.outputs.flatMap((output) => startEdges.filter((edge) => edge.fromPort === output.id).map((edge) => ({ output, edge })))
+        : startEdges.map((edge) => ({ output: outputForEdge(start ?? undefined, edge), edge }));
+
+    if (routeEdges.length > 0) {
+        lines.push("", "Routes:");
+    }
+    routeEdges.forEach(({ output, edge }, index) => {
+        const condition = output ? outputDescription(output) : "";
+        const routeName = output?.label ?? edgeTargetTitle(edge, nodesById);
+        const path = walkFlowPath({
+            fromNodeId: edge.to,
+            nodesById,
+            edgesBySource,
+            toolsById,
+            referencedToolIds,
+            visited: start ? new Set([start.id]) : undefined,
+        });
+        lines.push(
+            "",
+            `${index + 1}. When ${condition || routeName}:`,
+        );
+        if (output?.label && condition) lines.push(`   Treat this as the "${output.label}" route.`);
+        if (path.steps.length === 0) {
+            lines.push(`   Continue to "${routeName}" and handle it according to its instruction.`);
+        } else {
+            path.steps.forEach((step, stepIndex) => lines.push(`   ${stepIndex + 1}. ${step}`));
+        }
+        const uniqueToolIds = [...new Set(path.toolIds)];
+        if (uniqueToolIds.length > 0) {
+            lines.push(`   Use tools in this route: ${uniqueToolIds.map((toolId) => toolLabel(toolId, toolsById)).join(", ")}.`);
+            lines.push("   Never invent tool results. If a required tool is unavailable or returns no result, explain that limitation and ask for the next best detail.");
+        }
+        const terminal = terminalInstruction(path.terminal);
+        if (terminal) lines.push(`   ${terminal}`);
+    });
+
+    if (routeEdges.length === 0 && start) {
+        lines.push("", "No explicit routes are connected. Follow the start node instructions, answer concisely, and ask one clarifying question when intent is unclear.");
+    }
+
+    lines.push(
+        "",
+        "General tool and closing rules:",
+        "- Use tools only when the matching route requires them or the caller provides enough context for that route.",
+        "- Collect required tool inputs before calling a tool.",
+        "- Summarize tool results in natural spoken language; do not read raw JSON or internal IDs unless they are useful to the caller.",
+        "- Before ending, ask whether the caller needs anything else unless the caller already clearly ended the conversation.",
+    );
+
+    const missingToolIds = [...referencedToolIds].filter((toolId) => !toolsById.has(toolId));
+    if (missingToolIds.length > 0) {
+        warnings.push(`Flow graph references tools that are not configured on this agent: ${missingToolIds.join(", ")}`);
+        lines.push("", `Unavailable graph tools: ${missingToolIds.join(", ")}. If these are needed, explain that the action is unavailable instead of inventing results.`);
+    }
+
+    const toolManifest = [...referencedToolIds]
+        .flatMap((toolId) => {
+            const tool = toolsById.get(toolId);
+            return tool ? [toolToManifest(tool)] : [];
+        });
+
+    return {
+        instructions: lines.join("\n"),
+        compilerVersion: CLOUD_VOICE_FLOW_INSTRUCTION_COMPILER_VERSION,
+        graphSignature: signature,
+        startNodeId: start?.id ?? null,
+        entryMode,
+        nodeCount: graph.nodes.length,
+        edgeCount: graph.edges.length,
+        referencedToolIds: [...referencedToolIds],
+        missingToolIds,
+        toolManifest,
+        warnings,
+    };
+}
+
+export function compileCloudVoiceGraphConfig(config: CloudVoiceAgentConfig): CloudVoiceAgentConfig {
+    const compiledFlow = compileVoiceGraphToInstructions(getRecord(config.metadata).flowGraph, { tools: config.tools });
+    if (!compiledFlow) return config;
+    const runtimeConfig = applyFlowStartRuntimeConfig(config);
+    return {
+        ...runtimeConfig,
+        instructions: compiledFlow.instructions,
+        metadata: {
+            ...getRecord(runtimeConfig.metadata),
+            flowGraphInstructionCompiler: {
+                version: compiledFlow.compilerVersion,
+                graphSignature: compiledFlow.graphSignature,
+                entryMode: compiledFlow.entryMode,
+                compiledAt: new Date().toISOString(),
+            },
+        },
+    };
+}
+
+function getFlowStartNode(config: Pick<CloudVoiceAgentConfig, "metadata">, options: { entryMode?: CloudVoiceGraphEntryMode } = {}) {
+    const flowGraph = getRecord(config.metadata).flowGraph;
+    const graph = getRecord(flowGraph);
+    const nodes = Array.isArray(graph.nodes) ? graph.nodes.map(getRecord) : [];
+    if (nodes.length === 0) return null;
+    const entryMode = options.entryMode ?? "both";
+    const initialNodes = nodes.filter((node) => getString(node.type) === "initial");
+    const matchingStart = entryMode !== "both"
+        ? initialNodes.find((node) => normalizeEntryMode(node.entryMode) === entryMode)
+        : null;
+    if (matchingStart) return matchingStart;
+    const bothStart = initialNodes.find((node) => normalizeEntryMode(node.entryMode) === "both");
+    if (bothStart) return bothStart;
+    const startNodeId = getString(graph.startNodeId);
+    return nodes.find((node) => getString(node.id) === startNodeId)
+        ?? initialNodes[0]
+        ?? nodes[0]
+        ?? null;
+}
+
+function isCloudVoiceProvider(value: string): value is CloudVoiceAgentConfig["provider"] {
+    return value === "openai-realtime"
+        || value === "gemini-live"
+        || value === "kognitive-voice"
+        || value === "xai-realtime";
+}
+
+function isCloudVoiceTransport(value: string): value is CloudVoiceAgentConfig["transport"] {
+    return value === "webrtc" || value === "websocket";
+}
+
+function applyFlowStartRuntimeConfig(config: CloudVoiceAgentConfig, options: { entryMode?: CloudVoiceGraphEntryMode } = {}): CloudVoiceAgentConfig {
+    const start = getFlowStartNode(config, options);
+    if (!start) return config;
+    const provider = getString(start.provider);
+    const transport = getString(start.transport);
+    return {
+        ...config,
+        ...(isCloudVoiceProvider(provider) ? { provider } : {}),
+        ...(getString(start.model) ? { model: getString(start.model) } : {}),
+        ...(getString(start.voice) ? { voice: getString(start.voice) } : {}),
+        ...(isCloudVoiceTransport(transport) ? { transport } : {}),
+        ...(start.providerOptions && typeof start.providerOptions === "object" && !Array.isArray(start.providerOptions)
+            ? { providerOptions: start.providerOptions as Record<string, unknown> }
+            : {}),
+        ...(start.transcription === null || (start.transcription && typeof start.transcription === "object" && !Array.isArray(start.transcription))
+            ? { transcription: start.transcription as Record<string, unknown> | null }
+            : {}),
+        ...(start.turnDetection === null || (start.turnDetection && typeof start.turnDetection === "object" && !Array.isArray(start.turnDetection))
+            ? { turnDetection: start.turnDetection as Record<string, unknown> | null }
+            : {}),
+        ...(start.inputNoiseReduction === null || (start.inputNoiseReduction && typeof start.inputNoiseReduction === "object" && !Array.isArray(start.inputNoiseReduction))
+            ? { inputNoiseReduction: start.inputNoiseReduction as Record<string, unknown> | null }
+            : {}),
+        ...(start.humanization && typeof start.humanization === "object" && !Array.isArray(start.humanization)
+            ? { humanization: start.humanization as CloudVoiceAgentConfig["humanization"] }
+            : {}),
+        metadata: {
+            ...getRecord(config.metadata),
+            ...(start.speech && typeof start.speech === "object" && !Array.isArray(start.speech)
+                ? { speech: start.speech as CloudVoiceSpeechConfig }
+                : {}),
+        },
+    };
+}
+
+export function normalizeClientToolManifests(value: unknown): CloudVoiceClientToolManifest[] {
+    if (!Array.isArray(value)) return [];
+    const tools: CloudVoiceClientToolManifest[] = [];
+    for (const item of value) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+        const record = item as Record<string, unknown>;
+        const id = getString(record.id, "");
+        if (!id || !/^[A-Za-z0-9_-]{1,64}$/.test(id)) continue;
+        const inputSchema = record.inputSchema && typeof record.inputSchema === "object" && !Array.isArray(record.inputSchema)
+            ? record.inputSchema as Record<string, unknown>
+            : { type: "object", additionalProperties: true };
+        tools.push({
+            id,
+            name: getString(record.name, id),
+            description: getString(record.description, getString(record.name, id)),
+            inputSchema,
+        });
+    }
+    return tools.slice(0, 32);
+}
+
+export function prepareCloudVoiceSessionConfig(config: CloudVoiceAgentConfig, input: {
+    agentName: string;
+    sessionId: string;
+    resourceId: Record<string, unknown>;
+    channel?: CloudVoiceChannel;
+    clientTools?: CloudVoiceClientToolManifest[];
+    parameters?: Record<string, unknown>;
+    parameterResolution?: CloudVoiceParameterResolutionResult;
+}): PreparedCloudVoiceConfig {
+    const parameters = input.parameters ?? {};
+    const channel = input.channel ?? "web";
+    const entryMode = entryModeForChannel(channel);
+    const renderedConfig = renderCloudVoiceParameterObject(applyFlowStartRuntimeConfig(config, { entryMode }), parameters);
+    const compiledFlow = compileVoiceGraphToInstructions(getRecord(renderedConfig.metadata).flowGraph, {
+        tools: renderedConfig.tools,
+        entryMode,
+    });
+    const compiledMarker = getRecord(getRecord(config.metadata).flowGraphInstructionCompiler);
+    const useCompiledFlowAsAuthoredInstructions = Boolean(compiledMarker.version) && Boolean(compiledFlow?.instructions);
+    const promptConfig = useCompiledFlowAsAuthoredInstructions
+        ? { ...renderedConfig, instructions: compiledFlow?.instructions ?? renderedConfig.instructions }
+        : renderedConfig;
+    const instructionsAlreadyIncludeCompiledFlow = Boolean(compiledFlow?.instructions)
+        && getString(promptConfig.instructions, "").includes(compiledFlow?.instructions ?? "");
+    const shouldAppendCompiledFlow = Boolean(compiledFlow)
+        && !useCompiledFlowAsAuthoredInstructions
+        && !instructionsAlreadyIncludeCompiledFlow
+        && (
+            getString(compiledMarker.version, "") !== CLOUD_VOICE_FLOW_INSTRUCTION_COMPILER_VERSION
+            || getString(compiledMarker.graphSignature, "") !== compiledFlow?.graphSignature
+            || getString(compiledMarker.entryMode, "") !== entryMode
+        );
+    const providerOptions = getRecord(renderedConfig.providerOptions);
+    const speech = normalizeSpeechConfig(renderedConfig);
+    const languageCode = resolveCloudVoiceSpeechLanguageCode(renderedConfig);
+    const turnDetection = normalizeCloudVoiceTurnDetection(renderedConfig.provider, channel, renderedConfig.turnDetection);
+    const capabilities = getCloudVoiceProviderCapabilities(renderedConfig.provider);
+    const pipeline = renderedConfig.provider === "kognitive-voice" ? normalizeCloudVoicePipelineConfig(renderedConfig) : undefined;
+    const cartesiaTtsOptions = renderedConfig.provider === "kognitive-voice" ? compileCartesiaTtsOptions(renderedConfig) : undefined;
+    const maxOutputTokens = typeof providerOptions.maxOutputTokens === "number" && Number.isFinite(providerOptions.maxOutputTokens)
+        ? Math.max(1, Math.round(providerOptions.maxOutputTokens))
+        : typeof providerOptions.maxTokens === "number" && Number.isFinite(providerOptions.maxTokens)
+            ? Math.max(1, Math.round(providerOptions.maxTokens))
+            : "inf";
+    const temperature = typeof providerOptions.temperature === "number" && Number.isFinite(providerOptions.temperature)
+        ? Math.max(0, Math.min(2, providerOptions.temperature))
+        : undefined;
+    const toolManifestByName = new Map<string, CloudVoiceFunctionToolManifest>();
+
+    for (const tool of renderedConfig.tools) {
+        toolManifestByName.set(tool.id, {
+            type: "function",
+            name: tool.id,
+            description: tool.description ?? tool.name,
+            parameters: resolveToolInputSchema(tool),
+        });
+    }
+
+    for (const tool of input.clientTools ?? []) {
+        toolManifestByName.set(tool.id, {
+            type: "function",
+            name: tool.id,
+            description: tool.description ?? tool.name ?? tool.id,
+            parameters: tool.inputSchema ?? { type: "object", additionalProperties: true },
+        });
+    }
+
+    if (shouldInjectPhoneControlTools(channel)) {
+        toolManifestByName.set(CLOUD_VOICE_PHONE_HANGUP_TOOL.name, CLOUD_VOICE_PHONE_HANGUP_TOOL);
+    }
+
+    if (shouldInjectSipControlTools(config, channel)) {
+        toolManifestByName.set(CLOUD_VOICE_SIP_TRANSFER_TOOL.name, CLOUD_VOICE_SIP_TRANSFER_TOOL);
+    }
+
+    const toolManifest = Array.from(toolManifestByName.values())
+        .sort((left, right) => {
+            if (left.name === CLOUD_VOICE_PHONE_HANGUP_TOOL.name) return 1;
+            if (right.name === CLOUD_VOICE_PHONE_HANGUP_TOOL.name) return -1;
+            return 0;
+        });
+    const phoneControlRule = buildPhoneControlRule({ config: renderedConfig, channel });
+    const system = renderCloudVoiceParameterTemplate(compileCloudVoiceInstructions({
+        config: promptConfig,
+        agentName: input.agentName,
+        channel,
+        toolCount: toolManifest.length,
+        phoneControlRule,
+        compiledFlowInstructions: shouldAppendCompiledFlow ? compiledFlow?.instructions ?? "" : "",
+    }), parameters);
+    return {
+        name: input.agentName,
+        system,
+        runtime: {
+            provider: renderedConfig.provider,
+            mode: renderedConfig.provider === "kognitive-voice" ? "pipeline" : "realtime",
+            transport: pipeline?.transport.type ?? renderedConfig.transport,
+            model: pipeline?.llm.model ?? renderedConfig.model,
+            voice: pipeline?.tts.voice ?? renderedConfig.voice,
+            providerOptions: renderedConfig.providerOptions,
+            ...(pipeline ? { pipeline } : {}),
+            capabilities,
+        },
+        voiceConfig: {
+            system,
+            model: pipeline?.llm.model ?? renderedConfig.model,
+            voice: pipeline?.tts.voice ?? renderedConfig.voice,
+            ...(speech ? { speech } : {}),
+            ...(languageCode ? { languageCode } : {}),
+            turnDetection,
+            transcription: toPreparedTranscription(renderedConfig),
+            inputNoiseReduction: normalizeCloudVoiceInputNoiseReduction(renderedConfig.provider, channel, renderedConfig.inputNoiseReduction),
+            maxOutputTokens,
+            ...(temperature !== undefined ? { temperature } : {}),
+            ...(cartesiaTtsOptions ? { tts: { provider: "cartesia" as const, options: cartesiaTtsOptions } } : {}),
+        },
+        tools: [],
+        toolManifest,
+        resourceId: input.resourceId,
+        parameters,
+        metadata: {
+            cloudVoice: true,
+            sessionId: input.sessionId,
+            cloudVoiceConfigVersion: CLOUD_VOICE_CONFIG_VERSION,
+            promptCompilerVersion: CLOUD_VOICE_PROMPT_COMPILER_VERSION,
+            clientTools: (input.clientTools ?? []).map((tool) => tool.id),
+            transferDestinations: getTransferDestinations(renderedConfig).map((destination) => destination.id),
+            parameterKeys: Object.keys(parameters),
+            missingRequiredParameters: input.parameterResolution?.missingRequired ?? [],
+            sensitiveParameterKeys: input.parameterResolution?.sensitiveKeys ?? [],
+            ...(compiledFlow
+                ? {
+                    flowGraph: {
+                        startNodeId: compiledFlow.startNodeId,
+                        entryMode: compiledFlow.entryMode,
+                        nodeCount: compiledFlow.nodeCount,
+                        edgeCount: compiledFlow.edgeCount,
+                        referencedToolIds: compiledFlow.referencedToolIds,
+                        missingToolIds: compiledFlow.missingToolIds,
+                    },
+                }
+                : {}),
+        },
+    };
+}
+
+export function createPhonePrepareSnapshot(input: {
+    agent: CloudVoiceAgentSnapshot;
+    channel: CloudVoiceChannel;
+    config: CloudVoiceAgentConfig;
+    prepare: PreparedCloudVoiceConfig;
+    now?: Date;
+}): CloudVoicePhonePrepareSnapshot {
+    return {
+        schemaVersion: 1,
+        createdAt: (input.now ?? new Date()).toISOString(),
+        channel: input.channel,
+        agent: {
+            id: input.agent.id,
+            slug: input.agent.slug,
+            name: input.agent.name,
+            version: input.agent.publishedVersion ?? input.agent.draftVersion,
+        },
+        runtime: input.prepare.runtime,
+        voiceConfig: input.prepare.voiceConfig,
+        toolManifest: input.prepare.toolManifest,
+        config: input.config,
+        parameters: input.prepare.parameters,
+    };
+}