@kognitivedev/backend-cloud 0.2.29

package/src/cloud-voice-prompt-service.ts

@@ -0,0 +1,493 @@
+import type {
+    CloudVoiceAgentConfig,
+    CloudVoiceChannel,
+} from "./types";
+import {
+    normalizeCloudVoiceHumanizationConfig,
+    normalizeSpeechConfig,
+    toLanguageInstruction,
+} from "./cloud-voice-runtime-service";
+import { getRecord, getString } from "./utils";
+
+function isPhoneChannel(channel?: CloudVoiceChannel) {
+    return channel === "phone" || channel === "sip" || channel === "outbound";
+}
+
+type PromptLanguageId = "en" | "tr";
+
+type PromptLanguagePack = {
+    fallbackSystem: string;
+    headings: {
+        identity: string;
+        authoredInstructions: string;
+        personality: string;
+        speechDirection: string;
+        unclearAudio: string;
+        confirmation: string;
+        toolSpeech: string;
+        escalation: string;
+        phoneRules: string;
+        flowInstructions: string;
+    };
+    labels: {
+        language: string;
+        style: string;
+        accent: string;
+        pace: string;
+        emotion: string;
+    };
+    identity: {
+        realtime: string;
+        phone: string;
+        noInternalNames: string;
+        publicIdentityOnly: string;
+        selectedLanguage: (language: string) => string;
+    };
+    naturalness: {
+        liveConversation: string;
+        shortSentences: string;
+        acknowledge: string;
+        noMarkdown: string;
+        lightFillers: string;
+        naturalFillers: string;
+        lowBackchannels: string;
+        mediumBackchannels: string;
+        rareDisfluency: string;
+    };
+    profile: {
+        personality: (value: string) => string;
+        tone: (value: string) => string;
+        pacing: (value: string) => string;
+        unclearConfirmBestGuess: string;
+        unclearAskRepeat: string;
+        confirmAllActions: string;
+        confirmMinimal: string;
+        confirmCritical: string;
+        escalateOnRequest: string;
+        escalateNever: string;
+        escalateWhenBlocked: string;
+        readbackEnabled: string;
+        readbackBrief: string;
+    };
+    tools: {
+        beforeTool: string;
+        afterTool: string;
+        toolFails: string;
+    };
+    phone: {
+        doNotEndAfterTask: string;
+        askClosingQuestion: string;
+        callHangupOnlyAfterClose: string;
+        sayGoodbyeBeforeHangup: string;
+        doNotRevealTools: string;
+    };
+    opening: {
+        exactFirstMessage: (firstMessage: string) => string;
+        continueFlow: string;
+        noInternalNames: string;
+        startGreeting: (style: string, language: string) => string;
+        publicIdentityOnly: string;
+        outboundRightPerson: string;
+        askHowCanHelp: string;
+        oneShortSentence: string;
+        styles: {
+            warm: string;
+            professional: string;
+            brief: string;
+        };
+    };
+};
+
+const PROMPT_LANGUAGE_PACKS: Record<PromptLanguageId, PromptLanguagePack> = {
+    en: {
+        fallbackSystem: "You are a helpful phone voice agent. Keep responses concise and natural.",
+        headings: {
+            identity: "Identity",
+            authoredInstructions: "Authored Instructions",
+            personality: "Personality, Tone, and Pacing",
+            speechDirection: "Speech Direction",
+            unclearAudio: "Unclear Audio",
+            confirmation: "Confirmation and Readback",
+            toolSpeech: "Tool Speech",
+            escalation: "Escalation and Handoff",
+            phoneRules: "Phone Rules",
+            flowInstructions: "Flow Instructions",
+        },
+        labels: {
+            language: "Language",
+            style: "Style",
+            accent: "Accent",
+            pace: "Pace",
+            emotion: "Emotion",
+        },
+        identity: {
+            realtime: "You are a realtime voice agent.",
+            phone: "You are a realtime phone voice agent.",
+            noInternalNames: "Never tell the caller your internal agent name, agent number, slug, node name, workflow name, or implementation details.",
+            publicIdentityOnly: "If you need to identify yourself, use only the public identity explicitly written in the authored instructions or first-message text.",
+            selectedLanguage: (language) => `Use ${language} for caller-facing speech. If authored instructions are written in another language, follow their meaning but speak ${language}.`,
+        },
+        naturalness: {
+            liveConversation: "- Speak like a natural live conversation, not written chat.",
+            shortSentences: "- Use short spoken sentences and contractions.",
+            acknowledge: "- Acknowledge the caller before answering when it fits.",
+            noMarkdown: "- Do not use markdown, bullet points, or long lists unless the caller asks for them.",
+            lightFillers: '- Use light fillers only when useful, such as "okay", "one sec", or "let me check".',
+            naturalFillers: '- Use natural, brief fillers when useful, such as "hm", "okay", "right", "one sec", or "let me check".',
+            lowBackchannels: '- Use occasional short acknowledgements such as "got it" or "sure" without interrupting the caller.',
+            mediumBackchannels: "- Use short acknowledgements naturally when the caller gives details, but keep them brief.",
+            rareDisfluency: '- Rarely use "uh" or "um"; never repeat fillers or sound uncertain on purpose.',
+        },
+        profile: {
+            personality: (value) => `- Personality: ${value}.`,
+            tone: (value) => `- Tone: ${value}.`,
+            pacing: (value) => `- Pacing: ${value}.`,
+            unclearConfirmBestGuess: "- If audio is unclear, briefly state what you think you heard and ask the caller to confirm.",
+            unclearAskRepeat: "- If audio is unclear, ask the caller to repeat that part instead of guessing.",
+            confirmAllActions: "- Confirm before every external action, transfer, booking, cancellation, or account change.",
+            confirmMinimal: "- Confirm only when the caller asks for a change or when ambiguity could cause harm.",
+            confirmCritical: "- Confirm critical fields before acting, including names, phone numbers, emails, order ids, dates, times, addresses, prices, and account changes.",
+            escalateOnRequest: "- Escalate or hand off when the caller asks for a person.",
+            escalateNever: "- Do not escalate unless a configured flow explicitly routes to a transfer.",
+            escalateWhenBlocked: "- Escalate or hand off when blocked, when the caller is frustrated, or when policy/tool limits prevent a reliable answer.",
+            readbackEnabled: "- Read back numbers, dates, times, and identifiers in small chunks before using them.",
+            readbackBrief: "- Keep readbacks brief and only use them when the caller asks or the value is ambiguous.",
+        },
+        tools: {
+            beforeTool: '- Before calling a tool while the caller is waiting, say a short acknowledgement such as "Let me check that" or "One sec".',
+            afterTool: "- After a tool returns, summarize the result in plain spoken language.",
+            toolFails: "- If a tool fails, apologize briefly and explain what can still be done.",
+        },
+        phone: {
+            doNotEndAfterTask: "For phone calls, do not end the call just because you answered a question or completed one task.",
+            askClosingQuestion: 'Before ending, ask a short closing question such as "Is there anything else I can help with?" unless the caller already clearly said goodbye.',
+            callHangupOnlyAfterClose: 'Call hang_up_call only after the caller explicitly asks to end the call, says goodbye, or answers "no" or equivalent after your closing question.',
+            sayGoodbyeBeforeHangup: 'Immediately before calling hang_up_call, say a brief natural goodbye such as "bye", "see you later", or "take care".',
+            doNotRevealTools: "If the caller asks what tools, functions, abilities, or actions you have access to, answer in plain language and do not call hang_up_call.",
+        },
+        opening: {
+            exactFirstMessage: (firstMessage) => `Start the phone call now: say exactly this first sentence, without adding any agent name, number, or extra introduction: ${firstMessage}`,
+            continueFlow: "After that, continue naturally and follow the configured conversation flow.",
+            noInternalNames: "Do not mention internal agent names, agent numbers, slugs, node names, or workflow names.",
+            startGreeting: (style, language) => `Start the phone call now with a ${style} greeting in ${language}.`,
+            publicIdentityOnly: "Only use a public human or company identity if it is explicitly present in the authored instructions; otherwise do not state a name.",
+            outboundRightPerson: "If this is an outbound call, confirm you are speaking with the right person before continuing.",
+            askHowCanHelp: "Ask how you can help.",
+            oneShortSentence: "Keep the opening to one short sentence.",
+            styles: {
+                warm: "warm and friendly",
+                professional: "professional and concise",
+                brief: "brief and natural",
+            },
+        },
+    },
+    tr: {
+        fallbackSystem: "Yardımcı bir telefon sesli asistanısın. Yanıtlarını kısa, doğal ve konuşma diline uygun tut.",
+        headings: {
+            identity: "Kimlik",
+            authoredInstructions: "Yazılmış Talimatlar",
+            personality: "Kişilik, Ton ve Tempo",
+            speechDirection: "Konuşma Yönlendirmesi",
+            unclearAudio: "Anlaşılmayan Ses",
+            confirmation: "Onay ve Geri Okuma",
+            toolSpeech: "Araç Konuşması",
+            escalation: "Aktarma ve İnsana Devretme",
+            phoneRules: "Telefon Kuralları",
+            flowInstructions: "Akış Talimatları",
+        },
+        labels: {
+            language: "Dil",
+            style: "Stil",
+            accent: "Aksan",
+            pace: "Tempo",
+            emotion: "Duygu",
+        },
+        identity: {
+            realtime: "Gerçek zamanlı bir sesli asistansın.",
+            phone: "Gerçek zamanlı bir telefon sesli asistansın.",
+            noInternalNames: "Arayana hiçbir zaman dahili agent adını, agent numarasını, slug'ı, düğüm adını, workflow adını veya uygulama detaylarını söyleme.",
+            publicIdentityOnly: "Kendini tanıtman gerekiyorsa yalnızca yazılmış talimatlarda veya ilk mesaj metninde açıkça verilen kamusal kimliği kullan.",
+            selectedLanguage: (language) => `Arayana dönük tüm konuşmalarda ${language} kullan. Yazılmış talimatlar başka dildeyse anlamını takip et ama ${language} konuş.`,
+        },
+        naturalness: {
+            liveConversation: "- Yazılı sohbet gibi değil, doğal bir canlı konuşma gibi konuş.",
+            shortSentences: "- Kısa, konuşma diline uygun cümleler kullan.",
+            acknowledge: "- Uygun olduğunda cevaplamadan önce arayanı kısaca onayla.",
+            noMarkdown: "- Arayan istemedikçe markdown, madde listesi veya uzun listeler kullanma.",
+            lightFillers: '- Sadece gerekli olduğunda "tamam", "bir saniye" veya "hemen bakıyorum" gibi hafif geçiş ifadeleri kullan.',
+            naturalFillers: '- Gerekli olduğunda "hmm", "tamam", "peki", "bir saniye" veya "hemen bakıyorum" gibi kısa ve doğal geçiş ifadeleri kullan.',
+            lowBackchannels: '- Arayanı bölmeden ara sıra "anladım" veya "tabii" gibi kısa onaylar kullan.',
+            mediumBackchannels: "- Arayan detay verirken doğal şekilde kısa onaylar kullan, ama bunları kısa tut.",
+            rareDisfluency: '- "ee" veya "ıı" gibi dolgu seslerini nadiren kullan; dolgu ifadelerini tekrar etme ve bilerek kararsız duyulma.',
+        },
+        profile: {
+            personality: (value) => `- Kişilik: ${value}.`,
+            tone: (value) => `- Ton: ${value}.`,
+            pacing: (value) => `- Tempo: ${value}.`,
+            unclearConfirmBestGuess: "- Ses net değilse, ne duyduğunu kısaca söyle ve arayandan onay iste.",
+            unclearAskRepeat: "- Ses net değilse tahmin etmek yerine arayandan o kısmı tekrar etmesini iste.",
+            confirmAllActions: "- Her harici işlem, aktarma, randevu, iptal veya hesap değişikliğinden önce onay al.",
+            confirmMinimal: "- Yalnızca arayan değişiklik istediğinde veya belirsizlik zarar verebilecekse onay al.",
+            confirmCritical: "- İşlem yapmadan önce ad, telefon numarası, e-posta, sipariş numarası, tarih, saat, adres, fiyat ve hesap değişikliği gibi kritik alanları onayla.",
+            escalateOnRequest: "- Arayan bir kişiyle görüşmek isterse aktar veya insana devret.",
+            escalateNever: "- Yapılandırılmış akış açıkça aktarmaya yönlendirmedikçe insana devretme.",
+            escalateWhenBlocked: "- Tıkanırsan, arayan gerilirse veya politika/araç sınırları güvenilir cevap vermeni engellerse aktar veya insana devret.",
+            readbackEnabled: "- Numara, tarih, saat ve tanımlayıcıları kullanmadan önce küçük parçalar halinde geri oku.",
+            readbackBrief: "- Geri okumaları kısa tut ve yalnızca arayan isterse veya değer belirsizse kullan.",
+        },
+        tools: {
+            beforeTool: '- Arayan beklerken araç çağırmadan önce "hemen bakıyorum" veya "bir saniye" gibi kısa bir onay söyle.',
+            afterTool: "- Araç sonucu döndüğünde sonucu sade konuşma diliyle özetle.",
+            toolFails: "- Araç hata verirse kısaca özür dile ve hâlâ ne yapılabileceğini açıkla.",
+        },
+        phone: {
+            doNotEndAfterTask: "Telefon görüşmelerinde yalnızca bir soruyu cevapladın veya bir işi tamamladın diye çağrıyı bitirme.",
+            askClosingQuestion: 'Bitirmeden önce, arayan açıkça vedalaşmadıysa "Yardımcı olabileceğim başka bir konu var mı?" gibi kısa bir kapanış sorusu sor.',
+            callHangupOnlyAfterClose: 'hang_up_call aracını yalnızca arayan açıkça çağrıyı bitirmek isterse, vedalaşırsa veya kapanış sorundan sonra "hayır" ya da eşdeğer bir yanıt verirse çağır.',
+            sayGoodbyeBeforeHangup: 'hang_up_call aracını çağırmadan hemen önce "görüşmek üzere", "iyi günler" veya "hoşça kalın" gibi kısa ve doğal bir veda söyle.',
+            doNotRevealTools: "Arayan hangi araçlara, fonksiyonlara, yeteneklere veya işlemlere erişebildiğini sorarsa sade dille cevap ver ve hang_up_call aracını çağırma.",
+        },
+        opening: {
+            exactFirstMessage: (firstMessage) => `Telefon görüşmesini şimdi başlat: başka agent adı, numarası veya ek tanıtım eklemeden ilk cümle olarak aynen şunu söyle: ${firstMessage}`,
+            continueFlow: "Sonrasında doğal şekilde devam et ve yapılandırılmış konuşma akışını takip et.",
+            noInternalNames: "Dahili agent adlarını, agent numaralarını, slug'ları, düğüm adlarını veya workflow adlarını söyleme.",
+            startGreeting: (style, language) => `Telefon görüşmesini şimdi ${language} dilinde ${style} bir selamlamayla başlat.`,
+            publicIdentityOnly: "Yalnızca yazılmış talimatlarda açıkça geçiyorsa kamusal bir kişi veya şirket kimliği kullan; aksi halde isim belirtme.",
+            outboundRightPerson: "Bu dış aramaysa, devam etmeden önce doğru kişiyle konuştuğunu teyit et.",
+            askHowCanHelp: "Nasıl yardımcı olabileceğini sor.",
+            oneShortSentence: "Açılışı tek kısa cümleyle sınırla.",
+            styles: {
+                warm: "sıcak ve samimi",
+                professional: "profesyonel ve kısa",
+                brief: "kısa ve doğal",
+            },
+        },
+    },
+};
+
+const LANGUAGE_ALIASES: Record<string, PromptLanguageId> = {
+    en: "en",
+    "en-us": "en",
+    "en-gb": "en",
+    tr: "tr",
+    "tr-tr": "tr",
+};
+
+function resolvePromptLanguage(config?: Pick<CloudVoiceAgentConfig, "metadata"> | Record<string, unknown>): PromptLanguageId {
+    const speech = normalizeSpeechConfig(getRecord(config) as Pick<CloudVoiceAgentConfig, "metadata">) ?? {};
+    const language = getString(speech.language, "").toLowerCase();
+    return LANGUAGE_ALIASES[language] ?? "en";
+}
+
+function getPromptLanguagePack(config?: Pick<CloudVoiceAgentConfig, "metadata"> | Record<string, unknown>) {
+    return PROMPT_LANGUAGE_PACKS[resolvePromptLanguage(config)];
+}
+
+function buildSpeechDirectives(config: Pick<CloudVoiceAgentConfig, "metadata">) {
+    const pack = getPromptLanguagePack(config);
+    const speech = normalizeSpeechConfig(config) ?? {};
+    const language = toLanguageInstruction(speech.language);
+    return [
+        [pack.labels.language, language],
+        [pack.labels.style, speech.style],
+        [pack.labels.accent, speech.accent],
+        [pack.labels.pace, speech.pace],
+        [pack.labels.emotion, speech.emotion],
+    ]
+        .filter(([, value]) => typeof value === "string" && value.trim())
+        .map(([label, value]) => `- ${label}: ${String(value).trim()}`);
+}
+
+function buildNaturalnessDirectives(config: Pick<CloudVoiceAgentConfig, "humanization" | "metadata">) {
+    const pack = getPromptLanguagePack(config);
+    const humanization = normalizeCloudVoiceHumanizationConfig(config.humanization);
+    if (!humanization.enabled) return [];
+
+    const directives = [
+        pack.naturalness.liveConversation,
+        pack.naturalness.shortSentences,
+        pack.naturalness.acknowledge,
+        pack.naturalness.noMarkdown,
+    ];
+    if (humanization.fillerStyle === "light") {
+        directives.push(pack.naturalness.lightFillers);
+    } else if (humanization.fillerStyle === "natural") {
+        directives.push(pack.naturalness.naturalFillers);
+    }
+    if (humanization.backchannelFrequency === "low") {
+        directives.push(pack.naturalness.lowBackchannels);
+    } else if (humanization.backchannelFrequency === "medium") {
+        directives.push(pack.naturalness.mediumBackchannels);
+    }
+    if (humanization.disfluency === "rare") {
+        directives.push(pack.naturalness.rareDisfluency);
+    }
+
+    return directives;
+}
+
+function buildToolSpeechDirectives(toolCount: number, pack: PromptLanguagePack) {
+    if (toolCount <= 0) return [];
+    return [
+        pack.tools.beforeTool,
+        pack.tools.afterTool,
+        pack.tools.toolFails,
+    ];
+}
+
+function section(title: string, lines: Array<string | undefined | null>) {
+    const filtered = lines.filter((line): line is string => typeof line === "string" && line.trim().length > 0);
+    return filtered.length > 0 ? [`## ${title}`, ...filtered].join("\n") : "";
+}
+
+function entryModeForChannel(channel?: CloudVoiceChannel) {
+    return channel === "outbound" ? "outgoing" : channel === "phone" ? "incoming" : "both";
+}
+
+function normalizeEntryMode(value: unknown) {
+    if (value === "incoming" || value === "inbound") return "incoming";
+    if (value === "outgoing" || value === "outbound") return "outgoing";
+    return "both";
+}
+
+function getConfiguredFirstMessage(config?: Pick<CloudVoiceAgentConfig, "metadata"> | Record<string, unknown>, channel?: CloudVoiceChannel) {
+    const metadata = getRecord(config?.metadata);
+    const flowGraph = getRecord(metadata.flowGraph);
+    const nodes = Array.isArray(flowGraph.nodes) ? flowGraph.nodes : [];
+    const startNodeId = getString(flowGraph.startNodeId);
+    const normalizedNodes = nodes.map(getRecord);
+    const initialNodes = normalizedNodes.filter((node) => getString(node.type) === "initial");
+    const entryMode = entryModeForChannel(channel);
+    const startNode = (entryMode !== "both"
+        ? initialNodes.find((node) => normalizeEntryMode(node.entryMode) === entryMode)
+        : null)
+        ?? initialNodes.find((node) => normalizeEntryMode(node.entryMode) === "both")
+        ?? normalizedNodes.find((node) => getString(node.id) === startNodeId)
+        ?? initialNodes[0];
+    return getString(startNode?.firstMessage);
+}
+
+export function compileCloudVoiceInstructions(input: {
+    config: Pick<CloudVoiceAgentConfig, "humanization" | "metadata" | "instructions">;
+    agentName?: string;
+    channel?: CloudVoiceChannel;
+    toolCount?: number;
+    phoneControlRule?: string;
+    compiledFlowInstructions?: string;
+}) {
+    const pack = getPromptLanguagePack(input.config);
+    const humanization = normalizeCloudVoiceHumanizationConfig(input.config.humanization);
+    const profile = humanization.conversationProfile;
+    const isPhone = isPhoneChannel(input.channel);
+    const identity = isPhone ? pack.identity.phone : pack.identity.realtime;
+    const authoredInstructions = getString(input.config.instructions, "").trim();
+    const speech = normalizeSpeechConfig(input.config) ?? {};
+    const selectedLanguage = toLanguageInstruction(speech.language);
+    const personalityLines = [
+        pack.profile.personality(profile.personality),
+        pack.profile.tone(profile.tone),
+        pack.profile.pacing(profile.pacing),
+        ...buildNaturalnessDirectives(input.config),
+    ];
+    const unclearAudio = profile.unclearAudio === "confirm_best_guess"
+        ? pack.profile.unclearConfirmBestGuess
+        : pack.profile.unclearAskRepeat;
+    const confirmation = profile.confirmation === "all_actions"
+        ? pack.profile.confirmAllActions
+        : profile.confirmation === "minimal"
+            ? pack.profile.confirmMinimal
+            : pack.profile.confirmCritical;
+    const escalation = profile.escalation === "on_request"
+        ? pack.profile.escalateOnRequest
+        : profile.escalation === "never"
+            ? pack.profile.escalateNever
+            : pack.profile.escalateWhenBlocked;
+    const readback = profile.numberReadback
+        ? pack.profile.readbackEnabled
+        : pack.profile.readbackBrief;
+    return [
+        section(pack.headings.identity, [
+            identity,
+            selectedLanguage ? pack.identity.selectedLanguage(selectedLanguage) : undefined,
+            pack.identity.noInternalNames,
+            pack.identity.publicIdentityOnly,
+        ]),
+        section(pack.headings.authoredInstructions, [authoredInstructions]),
+        section(pack.headings.personality, personalityLines),
+        section(pack.headings.speechDirection, buildSpeechDirectives(input.config)),
+        section(pack.headings.unclearAudio, [unclearAudio]),
+        section(pack.headings.confirmation, [confirmation, readback]),
+        section(pack.headings.toolSpeech, buildToolSpeechDirectives(input.toolCount ?? 0, pack)),
+        section(pack.headings.escalation, [escalation]),
+        section(pack.headings.phoneRules, [input.phoneControlRule]),
+        section(pack.headings.flowInstructions, [input.compiledFlowInstructions]),
+    ].filter((block) => block.trim()).join("\n\n");
+}
+
+export function buildPhoneControlRule(input: {
+    config?: Pick<CloudVoiceAgentConfig, "metadata"> | Record<string, unknown>;
+    channel?: CloudVoiceChannel;
+}) {
+    if (!isPhoneChannel(input.channel)) return "";
+    const pack = getPromptLanguagePack(input.config);
+    return [
+        pack.phone.doNotEndAfterTask,
+        pack.phone.askClosingQuestion,
+        pack.phone.callHangupOnlyAfterClose,
+        pack.phone.sayGoodbyeBeforeHangup,
+        pack.phone.doNotRevealTools,
+    ].join("\n");
+}
+
+export function buildPhoneOpeningPrompt(input: {
+    config?: Pick<CloudVoiceAgentConfig, "humanization" | "metadata"> | Record<string, unknown>;
+    agentName?: string;
+    channel?: CloudVoiceChannel;
+}) {
+    const config = getRecord(input.config);
+    const pack = getPromptLanguagePack(config);
+    const humanization = normalizeCloudVoiceHumanizationConfig(config.humanization);
+    if (humanization.openingMode === "wait") return null;
+    const firstMessage = getConfiguredFirstMessage(config, input.channel);
+    if (firstMessage) {
+        return [
+            pack.opening.exactFirstMessage(firstMessage),
+            pack.opening.continueFlow,
+            pack.opening.noInternalNames,
+        ].join(" ");
+    }
+
+    const profile = humanization.conversationProfile;
+    const speech = getRecord(getRecord(config.metadata).speech);
+    const language = typeof speech.language === "string" && speech.language
+        ? toLanguageInstruction(speech.language) ?? speech.language
+        : "the selected language";
+    const style = profile.tone === "empathetic" || humanization.openingStyle === "warm"
+        ? pack.opening.styles.warm
+        : profile.tone === "professional" || profile.tone === "polished" || humanization.openingStyle === "professional"
+            ? pack.opening.styles.professional
+            : pack.opening.styles.brief;
+    const channelHint = input.channel === "outbound"
+        ? pack.opening.outboundRightPerson
+        : pack.opening.askHowCanHelp;
+
+    return [
+        pack.opening.startGreeting(style, language),
+        pack.opening.noInternalNames,
+        pack.opening.publicIdentityOnly,
+        channelHint,
+        pack.opening.oneShortSentence,
+    ].join(" ");
+}
+
+export function resolveCloudVoiceProviderSystemPrompt(input: {
+    voiceConfig?: { system?: unknown } | null;
+    config?: Pick<CloudVoiceAgentConfig, "metadata" | "instructions"> | Record<string, unknown> | null;
+}) {
+    const voiceSystem = getString(input.voiceConfig?.system, "");
+    if (voiceSystem) return voiceSystem;
+    const config = getRecord(input.config);
+    const authoredInstructions = getString(config.instructions, "");
+    if (authoredInstructions) return authoredInstructions;
+    return getPromptLanguagePack(config).fallbackSystem;
+}