@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

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.

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.

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.