@kognitivedev/backend-cloud 0.2.29

package/src/tools.ts

@@ -0,0 +1,227 @@
+import type {
+    CloudVoiceTelephonyDestination,
+    ExecuteCloudVoiceToolBindingInput,
+    ExecuteCloudVoiceToolBindingResult,
+} from "./types";
+import { renderCloudVoiceParameterTemplate } from "./cloud-voice-parameters";
+import { getNumber, getRecord, getString } from "./utils";
+
+function requiredHandler<T>(handler: T | undefined, toolType: string): T {
+    if (!handler) throw new Error(`Cloud Voice tool type "${toolType}" is not configured`);
+    return handler;
+}
+
+function applyParameterBindings(input: ExecuteCloudVoiceToolBindingInput) {
+    const args = { ...getRecord(input.args) };
+    const bindings = getRecord(input.tool.parameterBindings);
+    const parameters = getRecord(input.parameters);
+    for (const [field, rawBinding] of Object.entries(bindings)) {
+        const binding = getRecord(rawBinding);
+        const parameterKey = getString(binding.parameter, "");
+        if (!field || !parameterKey || !Object.prototype.hasOwnProperty.call(parameters, parameterKey)) continue;
+        if (Object.prototype.hasOwnProperty.call(args, field) && args[field] !== undefined && args[field] !== null && args[field] !== "") continue;
+        args[field] = parameters[parameterKey];
+    }
+    return args;
+}
+
+function omitReservedToolArgs(args: Record<string, unknown>) {
+    const next = { ...args };
+    delete next.to;
+    delete next.fromNumberId;
+    delete next.timeoutMs;
+    delete next.intervalMs;
+    return next;
+}
+
+function readMappedValue(value: unknown, context: Record<string, unknown>) {
+    if (typeof value === "string") return renderCloudVoiceParameterTemplate(value, context);
+    const record = getRecord(value);
+    const mode = getString(record.mode, "");
+    if (mode === "literal") return record.value;
+    if (mode === "tool_input") return context[getString(record.value ?? record.key, "")];
+    if (mode === "parent_parameter") return context[getString(record.value ?? record.parameter, "")];
+    if (Object.keys(record).length > 0 && "value" in record) return record.value;
+    return undefined;
+}
+
+function resolveCloudVoiceAgentParameters(input: ExecuteCloudVoiceToolBindingInput, args: Record<string, unknown>) {
+    const config = getRecord(input.tool.config);
+    const context = { ...(input.parameters ?? {}), ...args };
+    const parameters = omitReservedToolArgs(args);
+    const mappings = getRecord(config.parameterMappings);
+    for (const [key, mapping] of Object.entries(mappings)) {
+        const mapped = readMappedValue(mapping, context);
+        if (mapped !== undefined && mapped !== null && mapped !== "") {
+            parameters[key] = mapped;
+        }
+    }
+    return parameters;
+}
+
+function resolveTransferDestination(value: unknown): CloudVoiceTelephonyDestination {
+    const record = getRecord(value);
+    if (record.type === "phone_number" && typeof record.phoneNumber === "string" && record.phoneNumber.trim()) {
+        return {
+            type: "phone_number",
+            phoneNumber: record.phoneNumber.trim(),
+            connectionId: getString(record.connectionId, "") || undefined,
+            callerId: getString(record.callerId, "") || undefined,
+            metadata: getRecord(record.metadata),
+        };
+    }
+    if (record.type === "sip_uri" && typeof record.uri === "string" && record.uri.trim()) {
+        return {
+            type: "sip_uri",
+            uri: record.uri.trim(),
+            connectionId: getString(record.connectionId, "") || undefined,
+            transport: record.transport === "udp" || record.transport === "tcp" || record.transport === "tls" ? record.transport : undefined,
+            metadata: getRecord(record.metadata),
+        };
+    }
+    if (record.type === "extension" && typeof record.extension === "string" && record.extension.trim()) {
+        const connectionId = getString(record.connectionId, "");
+        if (!connectionId) throw new Error("SIP extension transfer destination is missing connectionId");
+        return {
+            type: "extension",
+            extension: record.extension.trim(),
+            connectionId,
+            metadata: getRecord(record.metadata),
+        };
+    }
+    if (record.type === "queue" && typeof record.queueId === "string" && record.queueId.trim()) {
+        return {
+            type: "queue",
+            queueId: record.queueId.trim(),
+            metadata: getRecord(record.metadata),
+        };
+    }
+    throw new Error("SIP transfer destination is invalid");
+}
+
+export async function executeCloudVoiceToolBinding(input: ExecuteCloudVoiceToolBindingInput): Promise<ExecuteCloudVoiceToolBindingResult> {
+    const { tool } = input;
+    const args = applyParameterBindings(input);
+
+    if (tool.type === "web_search") {
+        const query = getString(args.query, getString(tool.config.query, ""));
+        const result = await requiredHandler(input.executeWebSearch, tool.type)({
+            query,
+            parameters: getRecord(tool.config.parameters),
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "cloud_flow") {
+        const flowSlug = getString(tool.config.flowSlug, "");
+        const result = await requiredHandler(input.executeCloudFlow, tool.type)({
+            flowSlug,
+            args,
+            resourceId: input.resourceId,
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "knowledge_base") {
+        const result = await requiredHandler(input.executeKnowledgeBase, tool.type)({
+            pipelineId: getString(tool.config.pipelineId, ""),
+            query: getString(args.query, ""),
+            topK: getNumber(tool.config.topK, 5),
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "platform_action") {
+        const result = await requiredHandler(input.executePlatformAction, tool.type)({
+            actionSlug: getString(tool.config.actionSlug, ""),
+            connectionId: getString(tool.config.connectionId, ""),
+            args,
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "calendar_action") {
+        const result = await requiredHandler(input.executeCalendarAction, tool.type)({
+            action: getString(tool.config.action, getString(tool.config.actionSlug, tool.id)),
+            args,
+            config: getRecord(tool.config),
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "appointment_action") {
+        const result = await requiredHandler(input.executeAppointmentAction, tool.type)({
+            action: getString(tool.config.action, getString(tool.config.actionSlug, tool.id)),
+            args,
+            config: getRecord(tool.config),
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "cloud_voice_agent") {
+        const config = getRecord(tool.config);
+        const context = { ...(input.parameters ?? {}), ...args };
+        const toTemplate = getString(config.toTemplate, getString(config.to, ""));
+        const to = getString(args.to, toTemplate ? renderCloudVoiceParameterTemplate(toTemplate, context) : "");
+        const fromNumberId = getString(args.fromNumberId, getString(config.fromNumberId, ""));
+        const timeoutMs = getNumber(args.timeoutMs, getNumber(config.timeoutMs, 600_000));
+        const intervalMs = getNumber(args.intervalMs, getNumber(config.intervalMs, 2_000));
+        const result = await requiredHandler(input.executeCloudVoiceAgent, tool.type)({
+            agentSlug: getString(config.agentSlug, ""),
+            fromNumberId,
+            to,
+            parameters: resolveCloudVoiceAgentParameters(input, args),
+            timeoutMs,
+            intervalMs,
+            metadata: getRecord(config.metadata),
+            tool,
+            args,
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "external_webhook") {
+        const result = await requiredHandler(input.executeExternalWebhook, tool.type)({
+            tool,
+            args,
+        });
+        return { result, metadata: {} };
+    }
+
+    if (tool.type === "sip_transfer") {
+        const config = getRecord(tool.config);
+        const providerCallId = getString(args.providerCallId, getString(config.providerCallId, ""));
+        if (!providerCallId) throw new Error(`SIP transfer tool "${tool.id}" is missing providerCallId`);
+        const mode = args.mode === "attended" || args.mode === "warm" || args.mode === "blind"
+            ? args.mode
+            : config.mode === "attended" || config.mode === "warm" || config.mode === "blind"
+                ? config.mode
+                : undefined;
+        const result = await requiredHandler(input.executeSipTransfer, tool.type)({
+            providerCallId,
+            destination: resolveTransferDestination(args.destination ?? config.destination),
+            mode,
+            reason: getString(args.reason, getString(config.reason, "agent_requested_transfer")),
+            policy: getRecord(args.policy ?? config.policy),
+            metadata: {
+                projectId: input.projectId,
+                sessionId: input.sessionId,
+                toolId: tool.id,
+                ...(input.resourceId ?? {}),
+            },
+        });
+        return {
+            result,
+            metadata: {
+                transfer: {
+                    providerCallId: result.providerCallId,
+                    transferId: result.transferId,
+                    mode: result.mode,
+                    status: result.status,
+                },
+            },
+        };
+    }
+
+    throw new Error(`Unsupported Cloud Voice tool type "${String(tool.type)}"`);
+}