@kognitivedev/backend-cloud 0.2.29

package/src/index.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/src/phone-control.ts

@@ -0,0 +1,156 @@
+import { CLOUD_VOICE_PHONE_HANGUP_TOOL, CLOUD_VOICE_SIP_TRANSFER_TOOL } from "./cloud-voice";
+import type { CloudVoiceSipControlAdapter, CloudVoicePhoneControlAdapter } from "./types";
+import { getRecord, getString } from "./utils";
+
+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 function getPhoneControlToolReason(args: unknown) {
+    return getString(getRecord(args).reason, "agent_requested");
+}
+
+function resolvePhoneControlAdapter(
+    adapters: CloudVoicePhoneControlAdapter[] | Record<string, CloudVoicePhoneControlAdapter>,
+    provider: string,
+) {
+    if (Array.isArray(adapters)) {
+        return adapters.find((adapter) => adapter.provider === provider) ?? null;
+    }
+    return adapters[provider] ?? null;
+}
+
+function resolveSipControlAdapter(
+    adapters: CloudVoiceSipControlAdapter[] | Record<string, CloudVoiceSipControlAdapter>,
+    provider: string,
+) {
+    if (Array.isArray(adapters)) {
+        return adapters.find((adapter) => adapter.provider === provider) ?? null;
+    }
+    return adapters[provider] ?? null;
+}
+
+export async function executeCloudVoicePhoneControlTool(
+    input: ExecuteCloudVoicePhoneControlToolInput,
+): Promise<ExecuteCloudVoicePhoneControlToolResult> {
+    if (input.toolId !== CLOUD_VOICE_PHONE_HANGUP_TOOL.name) {
+        throw new Error(`Unknown Cloud Voice phone control tool "${input.toolId}"`);
+    }
+    const providerCallId = 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,
+    };
+}
+
+export async function executeCloudVoiceSipTransferTool(
+    input: ExecuteCloudVoiceSipTransferToolInput,
+): Promise<ExecuteCloudVoiceSipTransferToolResult> {
+    if (input.toolId !== CLOUD_VOICE_SIP_TRANSFER_TOOL.name) {
+        throw new Error(`Unknown Cloud Voice SIP control tool "${input.toolId}"`);
+    }
+    const providerCallId = getString(input.providerCallId, getString(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 = getRecord(input.args);
+    const destinationId = getString(args.destinationId, "");
+    if (!destinationId) throw new Error("Cloud Voice SIP transfer tool is missing destinationId");
+    const resolved = await input.resolveDestination?.(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
+        : resolved.policy?.mode;
+    const reason = 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/src/phone-runtime/audio-playout-tracker.ts

@@ -0,0 +1,132 @@
+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 class PhonePlayoutTracker {
+    private readonly frameDurationMs: number;
+    private assistantItemId: string | null = null;
+    private queuedAudioMs = 0;
+    private heardAudioMs = 0;
+    private pendingMarks: string[] = [];
+    private lastActivityAt = Date.now();
+
+    constructor(options: PhonePlayoutTrackerOptions = {}) {
+        this.frameDurationMs = options.frameDurationMs ?? 20;
+    }
+
+    startAssistantItem(itemId: string | null) {
+        this.assistantItemId = itemId;
+        this.queuedAudioMs = 0;
+        this.heardAudioMs = 0;
+        this.pendingMarks = [];
+        this.lastActivityAt = Date.now();
+    }
+
+    recordOutboundFrame(input: { markName?: string | null; durationMs?: number; itemId?: string | null } = {}) {
+        if (input.itemId !== undefined && input.itemId !== this.assistantItemId) {
+            this.startAssistantItem(input.itemId);
+        }
+        this.queuedAudioMs += input.durationMs ?? this.frameDurationMs;
+        if (input.markName) this.pendingMarks.push(input.markName);
+        this.lastActivityAt = Date.now();
+    }
+
+    recordCarrierMark(markName?: string | null) {
+        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: { elapsedMs?: number; providerTruncationSupported: boolean }): PhonePlayoutInterruption {
+        const heardAudioMs = Math.max(this.heardAudioMs, Math.min(input.elapsedMs ?? this.queuedAudioMs, this.queuedAudioMs));
+        const event: PhonePlayoutInterruption = {
+            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(): PhonePlayoutSnapshot {
+        return {
+            assistantItemId: this.assistantItemId,
+            queuedAudioMs: this.queuedAudioMs,
+            heardAudioMs: this.heardAudioMs,
+            pendingMarks: this.pendingMarks.length,
+            lastActivityAt: this.lastActivityAt,
+        };
+    }
+
+    async waitForIdle(input: { timeoutMs?: number; quietMs?: number; pollMs?: number } = {}): Promise<PhonePlayoutIdleResult> {
+        const startedAt = Date.now();
+        const timeoutMs = Math.max(0, input.timeoutMs ?? 8_000);
+        const quietMs = Math.max(0, input.quietMs ?? 250);
+        const pollMs = Math.max(10, input.pollMs ?? 50);
+
+        while (Date.now() - startedAt < timeoutMs) {
+            const snapshot = this.snapshot();
+            if (snapshot.pendingMarks === 0 && Date.now() - snapshot.lastActivityAt >= quietMs) {
+                return {
+                    ...snapshot,
+                    idle: true,
+                    reason: "idle",
+                    waitedMs: Date.now() - startedAt,
+                };
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+
+        return {
+            ...this.snapshot(),
+            idle: false,
+            reason: "timeout",
+            waitedMs: Date.now() - startedAt,
+        };
+    }
+}