@kognitivedev/backend-cloud 0.2.29

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+
+$ tsc

package/.turbo/turbo-test.log

@@ -0,0 +1,14 @@
+$ vitest run
+
+ RUN  v3.2.4 /Users/vserifsaglam/work/memory-experiment/packages/backend-cloud
+
+ ✓ src/__tests__/audio-playout-tracker.test.ts (1 test) 3ms
+ ✓ src/__tests__/phone-control.test.ts (4 tests) 2ms
+ ✓ src/__tests__/cloud-voice.test.ts (21 tests) 20ms
+ ✓ src/__tests__/openai-twilio-realtime.test.ts (11 tests) 142ms
+
+ Test Files  4 passed (4)
+      Tests  37 passed (37)
+   Start at  17:30:13
+   Duration  477ms (transform 288ms, setup 0ms, collect 515ms, tests 168ms, environment 0ms, prepare 330ms)
+

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @kognitivedev/backend-cloud
+
+## 0.2.29
+
+### Patch Changes
+
+- release
+
+- Updated dependencies []:
+  - @kognitivedev/telephony@0.2.29
+  - @kognitivedev/voice-media-bridge@0.2.29

package/README.md

@@ -0,0 +1,88 @@
+# @kognitivedev/backend-cloud
+
+Reusable backend orchestration helpers for Kognitive Cloud products.
+
+This package contains provider-neutral Cloud Voice backend mechanics: session
+preparation, tool manifest generation, managed tool orchestration,
+phone session snapshots, and managed phone-control tools such as
+`hang_up_call`.
+
+It intentionally does not import Twilio, Next.js, Drizzle, Clerk, or any
+`apps/backend` aliases. Applications compose those concrete dependencies.
+
+## Boundaries
+
+- `@kognitivedev/backend-cloud` owns Cloud Voice orchestration and interfaces.
+- `@kognitivedev/telephony` owns provider mechanics such as Twilio REST,
+  TwiML, signatures, and media stream helpers.
+- `apps/backend` owns routes, auth, DB stores, trace/session persistence,
+  environment loading, and concrete adapter registration.
+
+## Prepare a Session
+
+```ts
+import {
+  createPhonePrepareSnapshot,
+  prepareCloudVoiceSessionConfig,
+} from "@kognitivedev/backend-cloud";
+
+const prepare = prepareCloudVoiceSessionConfig(agentConfig, {
+  agentName: agent.name,
+  sessionId,
+  resourceId: { userId },
+  channel: "phone",
+});
+
+const snapshot = createPhonePrepareSnapshot({
+  agent,
+  channel: "phone",
+  config: agentConfig,
+  prepare,
+});
+```
+
+Phone channels automatically receive the built-in `hang_up_call` manifest.
+Web, iframe, and script channels do not.
+
+## Execute Tools
+
+`executeCloudVoiceToolBinding` is dependency-injected. It does not persist
+events or read databases.
+
+```ts
+const { result, metadata } = await executeCloudVoiceToolBinding({
+  projectId,
+  sessionId,
+  tool,
+  args,
+  resourceId,
+  executeWebSearch,
+  executeCloudFlow,
+  executeKnowledgeBase,
+  executePlatformAction,
+});
+```
+
+The app should persist `voice.tool.started`, `voice.tool.completed`, and
+`voice.tool.failed` events around this call.
+
+## Phone Control
+
+Phone control is provider-neutral. The package defines the tool flow; provider
+packages implement the mechanics.
+
+```ts
+const result = await executeCloudVoicePhoneControlTool({
+  toolId: "hang_up_call",
+  provider: callLeg.provider,
+  providerCallId: callLeg.providerCallId,
+  args,
+  adapters: [twilioPhoneControlAdapter],
+});
+```
+
+To add another phone provider:
+
+1. Implement a provider adapter in `@kognitivedev/telephony`.
+2. Register that adapter from `apps/backend`.
+3. Keep Cloud Voice tool orchestration unchanged.

package/dist/cloud-voice-parameters.d.ts

@@ -0,0 +1,11 @@
+import type { CloudVoiceAgentConfig, CloudVoiceParameterDefinition, CloudVoiceParameterResolutionMode, CloudVoiceParameterResolutionResult, CloudVoiceParameterValueMap } from "./types";
+export declare const CLOUD_VOICE_PREDEFINED_PARAMETERS: CloudVoiceParameterDefinition[];
+export declare function normalizeCloudVoiceParameterDefinitions(value: unknown): CloudVoiceParameterDefinition[];
+export declare function resolveCloudVoiceParameters(input: {
+    config: Pick<CloudVoiceAgentConfig, "parameters">;
+    supplied?: CloudVoiceParameterValueMap | null;
+    system?: Record<string, unknown> | null;
+    mode?: CloudVoiceParameterResolutionMode;
+}): CloudVoiceParameterResolutionResult;
+export declare function renderCloudVoiceParameterTemplate(text: string, parameters: CloudVoiceParameterValueMap): string;
+export declare function renderCloudVoiceParameterObject<T>(value: T, parameters: CloudVoiceParameterValueMap): T;

package/dist/cloud-voice-parameters.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOUD_VOICE_PREDEFINED_PARAMETERS = void 0;
+exports.normalizeCloudVoiceParameterDefinitions = normalizeCloudVoiceParameterDefinitions;
+exports.resolveCloudVoiceParameters = resolveCloudVoiceParameters;
+exports.renderCloudVoiceParameterTemplate = renderCloudVoiceParameterTemplate;
+exports.renderCloudVoiceParameterObject = renderCloudVoiceParameterObject;
+const utils_1 = require("./utils");
+exports.CLOUD_VOICE_PREDEFINED_PARAMETERS = [
+    { key: "user_id", label: "User ID", type: "string", source: "system", preset: "user_id", description: "Resolved user identifier for the voice session." },
+    { key: "session_id", label: "Session ID", type: "string", source: "system", preset: "session_id", description: "Public Cloud Voice session id." },
+    { key: "agent_slug", label: "Agent slug", type: "string", source: "system", preset: "agent_slug", description: "Slug of the selected voice agent." },
+    { key: "channel", label: "Channel", type: "string", source: "system", preset: "channel", description: "Run channel such as web, script, phone, or outbound." },
+    { key: "phone", label: "Phone", type: "phone", source: "call", preset: "phone", description: "Primary phone number for the caller when available." },
+    { key: "caller_phone", label: "Caller phone", type: "phone", source: "call", preset: "caller_phone", description: "Caller phone number when available." },
+    { key: "from_phone", label: "From phone", type: "phone", source: "call", preset: "from_phone", description: "Originating phone number when available." },
+    { key: "to_phone", label: "To phone", type: "phone", source: "call", preset: "to_phone", description: "Destination phone number when available." },
+    { key: "provider", label: "Telephony provider", type: "string", source: "call", preset: "provider", description: "Phone provider when available." },
+    { key: "provider_call_id", label: "Provider call ID", type: "string", source: "call", preset: "provider_call_id", description: "Provider call id when available." },
+    { key: "call_direction", label: "Call direction", type: "string", source: "call", preset: "call_direction", description: "Inbound or outbound direction when available." },
+    { key: "phone_number_id", label: "Phone number ID", type: "string", source: "call", preset: "phone_number_id", description: "Configured Cloud Voice phone number id when available." },
+    { key: "embed_origin", label: "Embed origin", type: "string", source: "session", preset: "embed_origin", description: "Embed origin for iframe/script starts when available." },
+];
+const RESERVED_TEMPLATE_KEYS = [
+    "session_messages",
+    "tools",
+    "voice_context",
+    "project_id",
+    "workflow_run_id",
+    "workflow_name",
+    "workflow_input",
+    "workflow_output",
+];
+const RESERVED_PARAMETER_KEYS = new Set([
+    ...exports.CLOUD_VOICE_PREDEFINED_PARAMETERS.map((parameter) => parameter.key),
+    ...RESERVED_TEMPLATE_KEYS,
+]);
+const VALID_PARAMETER_TYPES = new Set(["string", "number", "boolean", "json", "phone", "email"]);
+function normalizeParameterKey(value) {
+    return (0, utils_1.getString)(value, "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function normalizeParameterType(value) {
+    return VALID_PARAMETER_TYPES.has(String(value)) ? value : "string";
+}
+function isCustomParameter(definition) {
+    return !definition.preset && !RESERVED_PARAMETER_KEYS.has(definition.key);
+}
+function normalizeEnum(value) {
+    return Array.isArray(value) ? value.filter((item) => item !== undefined) : undefined;
+}
+function normalizeCloudVoiceParameterDefinitions(value) {
+    var _a, _b, _c;
+    const rawDefinitions = Array.isArray(value) ? value : [];
+    const definitions = new Map();
+    for (const predefined of exports.CLOUD_VOICE_PREDEFINED_PARAMETERS) {
+        definitions.set(predefined.key, predefined);
+    }
+    for (const raw of rawDefinitions) {
+        const record = (0, utils_1.getRecord)(raw);
+        const key = normalizeParameterKey((_a = record.key) !== null && _a !== void 0 ? _a : record.name);
+        if (!key || RESERVED_PARAMETER_KEYS.has(key))
+            continue;
+        definitions.set(key, {
+            key,
+            label: (0, utils_1.getString)(record.label, (0, utils_1.getString)(record.name, key)),
+            type: normalizeParameterType(record.type),
+            source: "custom",
+            required: record.required === true,
+            description: (0, utils_1.getString)(record.description, "") || undefined,
+            defaultValue: record.defaultValue,
+            enum: normalizeEnum((_b = record.enum) !== null && _b !== void 0 ? _b : record.options),
+            sensitive: record.sensitive === true,
+            jsonSchema: (0, utils_1.getRecord)((_c = record.jsonSchema) !== null && _c !== void 0 ? _c : record.schema),
+        });
+    }
+    return Array.from(definitions.values());
+}
+function hasOwn(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key);
+}
+function readSystemValue(key, system) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    switch (key) {
+        case "user_id":
+            return system.userId;
+        case "session_id":
+            return system.sessionId;
+        case "agent_slug":
+            return system.agentSlug;
+        case "channel":
+            return system.channel;
+        case "phone":
+            return (_b = (_a = system.phone) !== null && _a !== void 0 ? _a : system.callerPhone) !== null && _b !== void 0 ? _b : system.fromPhone;
+        case "caller_phone":
+            return (_d = (_c = system.callerPhone) !== null && _c !== void 0 ? _c : system.phone) !== null && _d !== void 0 ? _d : system.fromPhone;
+        case "from_phone":
+            return system.fromPhone;
+        case "to_phone":
+            return (_e = system.toPhone) !== null && _e !== void 0 ? _e : system.phoneNumber;
+        case "provider":
+            return system.provider;
+        case "provider_call_id":
+            return system.providerCallId;
+        case "call_direction":
+            return (_f = system.callDirection) !== null && _f !== void 0 ? _f : system.direction;
+        case "phone_number_id":
+            return system.phoneNumberId;
+        case "embed_origin":
+            return (_g = system.embedOrigin) !== null && _g !== void 0 ? _g : system.origin;
+        default:
+            return undefined;
+    }
+}
+function coerceValue(value, definition) {
+    if (value === undefined || value === null || value === "")
+        return { ok: true, value: undefined };
+    if (definition.enum && definition.enum.length > 0 && !definition.enum.includes(value)) {
+        return { ok: false, error: `${definition.key} must be one of ${definition.enum.map(String).join(", ")}` };
+    }
+    if (definition.type === "number") {
+        const numberValue = typeof value === "number" ? value : typeof value === "string" && value.trim() ? Number(value) : NaN;
+        return Number.isFinite(numberValue) ? { ok: true, value: numberValue } : { ok: false, error: `${definition.key} must be a number` };
+    }
+    if (definition.type === "boolean") {
+        if (typeof value === "boolean")
+            return { ok: true, value };
+        if (value === "true")
+            return { ok: true, value: true };
+        if (value === "false")
+            return { ok: true, value: false };
+        return { ok: false, error: `${definition.key} must be a boolean` };
+    }
+    if (definition.type === "json") {
+        return { ok: true, value };
+    }
+    return { ok: true, value: String(value) };
+}
+function resolveCloudVoiceParameters(input) {
+    var _a, _b;
+    const mode = (_a = input.mode) !== null && _a !== void 0 ? _a : "strict";
+    const supplied = (0, utils_1.getRecord)(input.supplied);
+    const system = (0, utils_1.getRecord)(input.system);
+    const definitions = normalizeCloudVoiceParameterDefinitions(input.config.parameters);
+    const values = {};
+    const missingRequired = [];
+    const errors = [];
+    const sensitiveKeys = [];
+    for (const definition of definitions) {
+        const custom = isCustomParameter(definition);
+        const rawValue = custom && hasOwn(supplied, definition.key)
+            ? supplied[definition.key]
+            : custom && definition.defaultValue !== undefined
+                ? definition.defaultValue
+                : !custom
+                    ? readSystemValue(definition.key, system)
+                    : undefined;
+        const coerced = coerceValue(rawValue, definition);
+        if (!coerced.ok) {
+            errors.push((_b = coerced.error) !== null && _b !== void 0 ? _b : `${definition.key} is invalid`);
+            continue;
+        }
+        if (coerced.value !== undefined) {
+            values[definition.key] = coerced.value;
+            if (definition.sensitive)
+                sensitiveKeys.push(definition.key);
+            continue;
+        }
+        if (definition.required && custom) {
+            missingRequired.push(definition.key);
+        }
+    }
+    if (mode === "strict" && (missingRequired.length > 0 || errors.length > 0)) {
+        const parts = [
+            missingRequired.length ? `missing required parameters: ${missingRequired.join(", ")}` : "",
+            ...errors,
+        ].filter(Boolean);
+        throw new Error(`Cloud voice parameters are invalid: ${parts.join("; ")}`);
+    }
+    return {
+        definitions,
+        values,
+        missingRequired,
+        errors,
+        sensitiveKeys,
+    };
+}
+function stringifyTemplateValue(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+function renderCloudVoiceParameterTemplate(text, parameters) {
+    if (!text || !text.includes("{{"))
+        return text;
+    return text
+        .replace(/\{\{\s*(?:params|parameters)\.([a-zA-Z0-9_]+)\s*\}\}/g, (_match, key) => stringifyTemplateValue(parameters[key]))
+        .replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (match, key) => Object.prototype.hasOwnProperty.call(parameters, key) ? stringifyTemplateValue(parameters[key]) : match);
+}
+function renderCloudVoiceParameterObject(value, parameters) {
+    if (typeof value === "string")
+        return renderCloudVoiceParameterTemplate(value, parameters);
+    if (Array.isArray(value))
+        return value.map((item) => renderCloudVoiceParameterObject(item, parameters));
+    if (!value || typeof value !== "object")
+        return value;
+    const next = {};
+    for (const [key, child] of Object.entries(value)) {
+        next[key] = renderCloudVoiceParameterObject(child, parameters);
+    }
+    return next;
+}

package/dist/cloud-voice-prompt-service.d.ts

@@ -0,0 +1,24 @@
+import type { CloudVoiceAgentConfig, CloudVoiceChannel } from "./types";
+export declare function compileCloudVoiceInstructions(input: {
+    config: Pick<CloudVoiceAgentConfig, "humanization" | "metadata" | "instructions">;
+    agentName?: string;
+    channel?: CloudVoiceChannel;
+    toolCount?: number;
+    phoneControlRule?: string;
+    compiledFlowInstructions?: string;
+}): string;
+export declare function buildPhoneControlRule(input: {
+    config?: Pick<CloudVoiceAgentConfig, "metadata"> | Record<string, unknown>;
+    channel?: CloudVoiceChannel;
+}): string;
+export declare function buildPhoneOpeningPrompt(input: {
+    config?: Pick<CloudVoiceAgentConfig, "humanization" | "metadata"> | Record<string, unknown>;
+    agentName?: string;
+    channel?: CloudVoiceChannel;
+}): string | null;
+export declare function resolveCloudVoiceProviderSystemPrompt(input: {
+    voiceConfig?: {
+        system?: unknown;
+    } | null;
+    config?: Pick<CloudVoiceAgentConfig, "metadata" | "instructions"> | Record<string, unknown> | null;
+}): string;