@kognitivedev/backend-cloud 0.2.29

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./cloud-voice";
+export * from "./cloud-voice-parameters";
+export * from "./cloud-voice-prompt-service";
+export * from "./cloud-voice-runtime-service";
+export * from "./phone-control";
+export * from "./phone-runtime/audio-playout-tracker";
+export * from "./phone-runtime/openai-twilio-realtime";
+export * from "./tools";
+export * from "./types";
+export * from "./utils";

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cloud-voice"), exports);
+__exportStar(require("./cloud-voice-parameters"), exports);
+__exportStar(require("./cloud-voice-prompt-service"), exports);
+__exportStar(require("./cloud-voice-runtime-service"), exports);
+__exportStar(require("./phone-control"), exports);
+__exportStar(require("./phone-runtime/audio-playout-tracker"), exports);
+__exportStar(require("./phone-runtime/openai-twilio-realtime"), exports);
+__exportStar(require("./tools"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);

package/dist/phone-control.d.ts

@@ -0,0 +1,50 @@
+import type { CloudVoiceSipControlAdapter, CloudVoicePhoneControlAdapter } from "./types";
+export interface ExecuteCloudVoicePhoneControlToolInput {
+    toolId: string;
+    args: unknown;
+    provider: string;
+    providerCallId: string;
+    adapters: CloudVoicePhoneControlAdapter[] | Record<string, CloudVoicePhoneControlAdapter>;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecuteCloudVoicePhoneControlToolResult {
+    result: {
+        ok: true;
+        provider: string;
+        providerCallId: string;
+        status: string;
+        reason: string;
+    };
+    raw?: unknown;
+}
+export interface ExecuteCloudVoiceSipTransferToolInput {
+    toolId: string;
+    args: unknown;
+    provider: string;
+    providerCallId: string;
+    adapters: CloudVoiceSipControlAdapter[] | Record<string, CloudVoiceSipControlAdapter>;
+    resolveDestination?: (destinationId: string) => {
+        destination: Parameters<CloudVoiceSipControlAdapter["transferCall"]>[0]["destination"];
+        policy?: Parameters<CloudVoiceSipControlAdapter["transferCall"]>[0]["policy"];
+    } | null | Promise<{
+        destination: Parameters<CloudVoiceSipControlAdapter["transferCall"]>[0]["destination"];
+        policy?: Parameters<CloudVoiceSipControlAdapter["transferCall"]>[0]["policy"];
+    } | null>;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecuteCloudVoiceSipTransferToolResult {
+    result: {
+        ok: true;
+        provider: string;
+        providerCallId: string;
+        status: string;
+        transferId?: string;
+        mode: string;
+        destinationId: string;
+        reason: string;
+    };
+    raw?: unknown;
+}
+export declare function getPhoneControlToolReason(args: unknown): string;
+export declare function executeCloudVoicePhoneControlTool(input: ExecuteCloudVoicePhoneControlToolInput): Promise<ExecuteCloudVoicePhoneControlToolResult>;
+export declare function executeCloudVoiceSipTransferTool(input: ExecuteCloudVoiceSipTransferToolInput): Promise<ExecuteCloudVoiceSipTransferToolResult>;

package/dist/phone-control.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPhoneControlToolReason = getPhoneControlToolReason;
+exports.executeCloudVoicePhoneControlTool = executeCloudVoicePhoneControlTool;
+exports.executeCloudVoiceSipTransferTool = executeCloudVoiceSipTransferTool;
+const cloud_voice_1 = require("./cloud-voice");
+const utils_1 = require("./utils");
+function getPhoneControlToolReason(args) {
+    return (0, utils_1.getString)((0, utils_1.getRecord)(args).reason, "agent_requested");
+}
+function resolvePhoneControlAdapter(adapters, provider) {
+    var _a, _b;
+    if (Array.isArray(adapters)) {
+        return (_a = adapters.find((adapter) => adapter.provider === provider)) !== null && _a !== void 0 ? _a : null;
+    }
+    return (_b = adapters[provider]) !== null && _b !== void 0 ? _b : null;
+}
+function resolveSipControlAdapter(adapters, provider) {
+    var _a, _b;
+    if (Array.isArray(adapters)) {
+        return (_a = adapters.find((adapter) => adapter.provider === provider)) !== null && _a !== void 0 ? _a : null;
+    }
+    return (_b = adapters[provider]) !== null && _b !== void 0 ? _b : null;
+}
+async function executeCloudVoicePhoneControlTool(input) {
+    if (input.toolId !== cloud_voice_1.CLOUD_VOICE_PHONE_HANGUP_TOOL.name) {
+        throw new Error(`Unknown Cloud Voice phone control tool "${input.toolId}"`);
+    }
+    const providerCallId = (0, utils_1.getString)(input.providerCallId, "");
+    if (!providerCallId)
+        throw new Error("Cloud Voice phone control tool is missing providerCallId");
+    const adapter = resolvePhoneControlAdapter(input.adapters, input.provider);
+    if (!adapter) {
+        throw new Error(`Phone control tool "${input.toolId}" is not supported for provider "${input.provider}"`);
+    }
+    const reason = getPhoneControlToolReason(input.args);
+    const result = await adapter.hangUpCall({
+        providerCallId,
+        reason,
+        metadata: input.metadata,
+    });
+    return {
+        result: {
+            ok: true,
+            provider: result.provider,
+            providerCallId: result.providerCallId,
+            status: result.status,
+            reason,
+        },
+        raw: result.raw,
+    };
+}
+async function executeCloudVoiceSipTransferTool(input) {
+    var _a, _b;
+    if (input.toolId !== cloud_voice_1.CLOUD_VOICE_SIP_TRANSFER_TOOL.name) {
+        throw new Error(`Unknown Cloud Voice SIP control tool "${input.toolId}"`);
+    }
+    const providerCallId = (0, utils_1.getString)(input.providerCallId, (0, utils_1.getString)((0, utils_1.getRecord)(input.args).providerCallId, ""));
+    if (!providerCallId)
+        throw new Error("Cloud Voice SIP transfer tool is missing providerCallId");
+    const adapter = resolveSipControlAdapter(input.adapters, input.provider);
+    if (!adapter) {
+        throw new Error(`SIP control tool "${input.toolId}" is not supported for provider "${input.provider}"`);
+    }
+    const args = (0, utils_1.getRecord)(input.args);
+    const destinationId = (0, utils_1.getString)(args.destinationId, "");
+    if (!destinationId)
+        throw new Error("Cloud Voice SIP transfer tool is missing destinationId");
+    const resolved = await ((_a = input.resolveDestination) === null || _a === void 0 ? void 0 : _a.call(input, destinationId));
+    if (!resolved)
+        throw new Error(`Cloud Voice SIP transfer destination "${destinationId}" was not found`);
+    const mode = args.mode === "attended" || args.mode === "warm" || args.mode === "blind"
+        ? args.mode
+        : (_b = resolved.policy) === null || _b === void 0 ? void 0 : _b.mode;
+    const reason = (0, utils_1.getString)(args.reason, "agent_requested_transfer");
+    const result = await adapter.transferCall({
+        providerCallId,
+        destination: resolved.destination,
+        mode,
+        reason,
+        policy: resolved.policy,
+        metadata: input.metadata,
+    });
+    return {
+        result: {
+            ok: true,
+            provider: result.provider,
+            providerCallId: result.providerCallId,
+            status: result.status,
+            transferId: result.transferId,
+            mode: result.mode,
+            destinationId,
+            reason,
+        },
+        raw: result.raw,
+    };
+}

package/dist/phone-runtime/audio-playout-tracker.d.ts

@@ -0,0 +1,51 @@
+export interface PhonePlayoutInterruption {
+    assistantItemId: string | null;
+    heardAudioMs: number;
+    queuedAudioMs: number;
+    pendingMarks: number;
+    interrupted: true;
+    clearedAt: string;
+    providerTruncationSupported: boolean;
+}
+export interface PhonePlayoutTrackerOptions {
+    frameDurationMs?: number;
+}
+export interface PhonePlayoutSnapshot {
+    assistantItemId: string | null;
+    queuedAudioMs: number;
+    heardAudioMs: number;
+    pendingMarks: number;
+    lastActivityAt: number;
+}
+export interface PhonePlayoutIdleResult extends PhonePlayoutSnapshot {
+    idle: boolean;
+    reason: "idle" | "timeout";
+    waitedMs: number;
+}
+export declare class PhonePlayoutTracker {
+    private readonly frameDurationMs;
+    private assistantItemId;
+    private queuedAudioMs;
+    private heardAudioMs;
+    private pendingMarks;
+    private lastActivityAt;
+    constructor(options?: PhonePlayoutTrackerOptions);
+    startAssistantItem(itemId: string | null): void;
+    recordOutboundFrame(input?: {
+        markName?: string | null;
+        durationMs?: number;
+        itemId?: string | null;
+    }): void;
+    recordCarrierMark(markName?: string | null): void;
+    interrupt(input: {
+        elapsedMs?: number;
+        providerTruncationSupported: boolean;
+    }): PhonePlayoutInterruption;
+    reset(): void;
+    snapshot(): PhonePlayoutSnapshot;
+    waitForIdle(input?: {
+        timeoutMs?: number;
+        quietMs?: number;
+        pollMs?: number;
+    }): Promise<PhonePlayoutIdleResult>;
+}

package/dist/phone-runtime/audio-playout-tracker.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhonePlayoutTracker = void 0;
+class PhonePlayoutTracker {
+    constructor(options = {}) {
+        var _a;
+        this.assistantItemId = null;
+        this.queuedAudioMs = 0;
+        this.heardAudioMs = 0;
+        this.pendingMarks = [];
+        this.lastActivityAt = Date.now();
+        this.frameDurationMs = (_a = options.frameDurationMs) !== null && _a !== void 0 ? _a : 20;
+    }
+    startAssistantItem(itemId) {
+        this.assistantItemId = itemId;
+        this.queuedAudioMs = 0;
+        this.heardAudioMs = 0;
+        this.pendingMarks = [];
+        this.lastActivityAt = Date.now();
+    }
+    recordOutboundFrame(input = {}) {
+        var _a;
+        if (input.itemId !== undefined && input.itemId !== this.assistantItemId) {
+            this.startAssistantItem(input.itemId);
+        }
+        this.queuedAudioMs += (_a = input.durationMs) !== null && _a !== void 0 ? _a : this.frameDurationMs;
+        if (input.markName)
+            this.pendingMarks.push(input.markName);
+        this.lastActivityAt = Date.now();
+    }
+    recordCarrierMark(markName) {
+        if (this.pendingMarks.length === 0)
+            return;
+        if (!markName) {
+            this.pendingMarks.shift();
+            this.heardAudioMs = Math.min(this.queuedAudioMs, this.heardAudioMs + this.frameDurationMs);
+            this.lastActivityAt = Date.now();
+            return;
+        }
+        const index = this.pendingMarks.indexOf(markName);
+        const consumed = index >= 0 ? index + 1 : 1;
+        this.pendingMarks.splice(0, consumed);
+        this.heardAudioMs = Math.min(this.queuedAudioMs, this.heardAudioMs + consumed * this.frameDurationMs);
+        this.lastActivityAt = Date.now();
+    }
+    interrupt(input) {
+        var _a;
+        const heardAudioMs = Math.max(this.heardAudioMs, Math.min((_a = input.elapsedMs) !== null && _a !== void 0 ? _a : this.queuedAudioMs, this.queuedAudioMs));
+        const event = {
+            assistantItemId: this.assistantItemId,
+            heardAudioMs,
+            queuedAudioMs: this.queuedAudioMs,
+            pendingMarks: this.pendingMarks.length,
+            interrupted: true,
+            clearedAt: new Date().toISOString(),
+            providerTruncationSupported: input.providerTruncationSupported,
+        };
+        this.reset();
+        return event;
+    }
+    reset() {
+        this.assistantItemId = null;
+        this.queuedAudioMs = 0;
+        this.heardAudioMs = 0;
+        this.pendingMarks = [];
+        this.lastActivityAt = Date.now();
+    }
+    snapshot() {
+        return {
+            assistantItemId: this.assistantItemId,
+            queuedAudioMs: this.queuedAudioMs,
+            heardAudioMs: this.heardAudioMs,
+            pendingMarks: this.pendingMarks.length,
+            lastActivityAt: this.lastActivityAt,
+        };
+    }
+    async waitForIdle(input = {}) {
+        var _a, _b, _c;
+        const startedAt = Date.now();
+        const timeoutMs = Math.max(0, (_a = input.timeoutMs) !== null && _a !== void 0 ? _a : 8000);
+        const quietMs = Math.max(0, (_b = input.quietMs) !== null && _b !== void 0 ? _b : 250);
+        const pollMs = Math.max(10, (_c = input.pollMs) !== null && _c !== void 0 ? _c : 50);
+        while (Date.now() - startedAt < timeoutMs) {
+            const snapshot = this.snapshot();
+            if (snapshot.pendingMarks === 0 && Date.now() - snapshot.lastActivityAt >= quietMs) {
+                return Object.assign(Object.assign({}, snapshot), { idle: true, reason: "idle", waitedMs: Date.now() - startedAt });
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        return Object.assign(Object.assign({}, this.snapshot()), { idle: false, reason: "timeout", waitedMs: Date.now() - startedAt });
+    }
+}
+exports.PhonePlayoutTracker = PhonePlayoutTracker;

package/dist/phone-runtime/openai-twilio-realtime.d.ts

@@ -0,0 +1,95 @@
+import { type WebSocket } from "ws";
+import type { CloudVoiceFunctionToolManifest, PreparedCloudVoiceConfig } from "../types";
+import { type PhoneAudioRoute, type PhoneMediaProfile } from "@kognitivedev/voice-media-bridge";
+export type OpenAITwilioRealtimeSnapshot = {
+    runtime?: Partial<PreparedCloudVoiceConfig["runtime"]>;
+    voiceConfig?: Partial<PreparedCloudVoiceConfig["voiceConfig"]>;
+    toolManifest?: Array<Partial<CloudVoiceFunctionToolManifest>>;
+    config?: Record<string, unknown>;
+};
+export type OpenAITwilioRealtimeCounters = {
+    inboundMediaFrames: number;
+    providerInputFrames: number;
+    providerInputDroppedBeforeReady: number;
+    outboundMediaFrames: number;
+    outboundAudioDroppedMissingStreamSid: number;
+    outboundAudioBytes: number;
+    outboundAudioPeakAbs: number;
+    outboundAudioLastRms: number;
+    clears: number;
+    truncates: number;
+    marks: number;
+    dtmf: number;
+    interruptions: number;
+    ignoredInterruptions: number;
+    toolCalls: number;
+    providerMessages: number;
+};
+type BridgeLog = (event: string, data?: Record<string, unknown>) => void;
+type BridgeError = (event: string, error: unknown, data?: Record<string, unknown>) => void;
+export type OpenAITwilioRealtimeBridgeInput = {
+    socket: WebSocket;
+    apiKey: string;
+    provider?: "openai-realtime" | "xai-realtime";
+    realtimeUrl?: string;
+    defaultModel?: string;
+    defaultVoice?: string;
+    mediaProfile?: PhoneMediaProfile;
+    audioRoute?: PhoneAudioRoute;
+    bridgeMode?: string;
+    supportsConversationItemTruncate?: boolean;
+    projectId: string;
+    sessionId: string;
+    providerCallId?: string | null;
+    snapshot: OpenAITwilioRealtimeSnapshot;
+    initialPrompt?: string | null;
+    log: BridgeLog;
+    error: BridgeError;
+    appendEvent: (eventType: string, payload?: Record<string, unknown>, message?: string) => void;
+    updateCallLegActive: (metadata: {
+        streamSid: string | null;
+    }) => void;
+    updateSessionActive: () => void;
+    onAudioFrame?: (input: {
+        source: "caller" | "assistant";
+        payload: string;
+        metadata?: Record<string, unknown>;
+    }) => void;
+    onCarrierAudioSender?: (sender: ((payload: string) => boolean) | null) => void;
+    isAiPaused?: () => boolean;
+    onAssistantTurnComplete?: () => void;
+    registerPlayoutIdleWaiter?: (waiter: (input?: {
+        timeoutMs?: number;
+        quietMs?: number;
+    }) => Promise<unknown>) => () => void;
+    executeTool: (input: {
+        toolId: string;
+        args: unknown;
+        toolCallId?: string | null;
+        providerCallId?: string | null;
+    }) => Promise<{
+        result: unknown;
+    }>;
+};
+export declare function summarizeTwilioPcmuSignal(base64Audio: string): import("@kognitivedev/voice-media-bridge").PcmSignalSummary;
+export declare function isOpenAITwilioRealtimeReady(event: unknown, mediaProfile?: PhoneMediaProfile): boolean;
+export declare function createOpenAITwilioRealtimeTools(snapshot: OpenAITwilioRealtimeSnapshot): {
+    type: string;
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}[];
+export declare function createOpenAITwilioRealtimeSessionUpdate(snapshot: OpenAITwilioRealtimeSnapshot, model: string, defaultVoice?: string, provider?: "openai-realtime" | "xai-realtime", mediaProfile?: PhoneMediaProfile, audioRoute?: PhoneAudioRoute): {
+    type: string;
+    session: Record<string, unknown>;
+};
+export declare function runOpenAITwilioRealtimeBridge(input: OpenAITwilioRealtimeBridgeInput): Promise<{
+    sendTextTurn: (text: string) => boolean;
+    close: () => void;
+}>;
+export type XAITwilioRealtimeBridgeInput = Omit<OpenAITwilioRealtimeBridgeInput, "provider" | "realtimeUrl" | "defaultModel" | "defaultVoice" | "bridgeMode" | "supportsConversationItemTruncate">;
+export declare function runXAITwilioRealtimeBridge(input: XAITwilioRealtimeBridgeInput): Promise<{
+    sendTextTurn: (text: string) => boolean;
+    close: () => void;
+}>;
+export {};