@vellumai/assistant 0.6.6 → 0.7.1

package/src/calls/twilio-routes.ts

@@ -27,7 +27,14 @@ import {
   getTwilioRelayUrl,
 } from "../inbound/public-ingress-urls.js";
 import { getProviderEntry } from "../providers/speech-to-text/provider-catalog.js";
-import { mintEdgeRelayToken } from "../runtime/auth/token-service.js";
+import {
+  BadRequestError,
+  GoneError,
+  NotFoundError,
+  RouteError,
+} from "../runtime/routes/errors.js";
+import type { RouteHandlerArgs } from "../runtime/routes/types.js";
+import { RouteResponse } from "../runtime/routes/types.js";
 import { getLogger } from "../util/logger.js";
 import { persistCallCompletionMessage } from "./call-conversation-messages.js";
 import { createInboundVoiceSession } from "./call-domain.js";
@@ -53,6 +60,13 @@ import { resolveVoiceQualityProfile } from "./voice-quality.js";
 
 const log = getLogger("twilio-routes");
 
+/**
+ * Sentinel placeholder embedded in TwiML where the relay auth token should go.
+ * The gateway replaces this with a real JWT before returning TwiML to Twilio.
+ * This keeps the signing key out of the daemon for voice webhook responses.
+ */
+const TWILIO_RELAY_TOKEN_PLACEHOLDER = "__VELLUM_RELAY_TOKEN__";
+
 // ── Speech config type ───────────────────────────────────────────────
 
 /**
@@ -240,32 +254,40 @@ function mapTwilioStatus(twilioStatus: string): CallStatus | null {
   }
 }
 
-// ── Route handlers ───────────────────────────────────────────────────
+// ── Helpers ──────────────────────────────────────────────────────────
+
+/** Wrap a TwiML string in an HTTP Response with XML content-type. */
+function twimlResponse(twiml: string): Response {
+  return new Response(twiml, {
+    status: 200,
+    headers: { "Content-Type": "text/xml" },
+  });
+}
+
+const TWIML_HEADERS = { "Content-Type": "text/xml" } as const;
+
+// ── Core voice webhook logic ─────────────────────────────────────────
 
 /**
- * Receives the initial voice webhook when Twilio connects the call.
- * Returns TwiML XML that tells Twilio to open a ConversationRelay WebSocket.
+ * Core voice webhook logic — transport-agnostic.
  *
- * Supports two flows:
- * - **Outbound** (callSessionId present in query): uses the existing session
- * - **Inbound** (callSessionId absent): creates or reuses a session keyed
- *   by the Twilio CallSid. Uses daemon internal scope for assistant identity.
+ * Accepts pre-parsed form params and an optional callSessionId (from URL
+ * query for outbound calls). Returns a TwiML string. Throws RouteError
+ * subclasses on failure.
  */
-export async function handleVoiceWebhook(req: Request): Promise<Response> {
-  const url = new URL(req.url);
-  const callSessionId = url.searchParams.get("callSessionId");
-
-  // Parse the Twilio POST body to capture CallSid and caller metadata.
-  const formBody = new URLSearchParams(await req.text());
-  const callSid = formBody.get("CallSid");
-  const callerFrom = formBody.get("From") ?? "";
-  const callerTo = formBody.get("To") ?? "";
+function processVoiceWebhook(
+  params: Record<string, string>,
+  callSessionId: string | null,
+): string {
+  const callSid = params.CallSid ?? null;
+  const callerFrom = params.From ?? "";
+  const callerTo = params.To ?? "";
 
-  // ── Inbound mode: no callSessionId in query ─────────────────────
+  // ── Inbound mode: no callSessionId ──────────────────────────────
   if (!callSessionId) {
     if (!callSid) {
       log.warn("Inbound voice webhook called without CallSid");
-      return new Response("Missing CallSid", { status: 400 });
+      throw new BadRequestError("Missing CallSid");
     }
 
     log.info(
@@ -297,7 +319,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
   const session = getCallSession(callSessionId);
   if (!session) {
     log.warn({ callSessionId }, "Voice webhook: call session not found");
-    return new Response("Call session not found", { status: 404 });
+    throw new NotFoundError("Call session not found");
   }
 
   if (isTerminalState(session.status)) {
@@ -305,7 +327,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
       { callSessionId, status: session.status },
       "Voice webhook: call session is in terminal state",
     );
-    return new Response("Call session is no longer active", { status: 410 });
+    throw new GoneError("Call session is no longer active");
   }
 
   // Capture CallSid immediately so status callbacks can locate this session
@@ -328,6 +350,34 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
   );
 }
 
+// ── Route handlers ───────────────────────────────────────────────────
+
+/**
+ * Receives the initial voice webhook when Twilio connects the call.
+ * Returns TwiML XML that tells Twilio to open a ConversationRelay WebSocket.
+ *
+ * Supports two flows:
+ * - **Outbound** (callSessionId present in query): uses the existing session
+ * - **Inbound** (callSessionId absent): creates or reuses a session keyed
+ *   by the Twilio CallSid. Uses daemon internal scope for assistant identity.
+ */
+export async function handleVoiceWebhook(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const callSessionId = url.searchParams.get("callSessionId");
+
+  const formBody = new URLSearchParams(await req.text());
+  const params = Object.fromEntries(formBody.entries());
+
+  try {
+    return twimlResponse(processVoiceWebhook(params, callSessionId));
+  } catch (err) {
+    if (err instanceof RouteError) {
+      return new Response(err.message, { status: err.statusCode });
+    }
+    throw err;
+  }
+}
+
 /**
  * Shared TwiML generation for both inbound and outbound voice webhooks.
  *
@@ -358,7 +408,7 @@ function buildVoiceWebhookTwiml(
     inviteGuardianName: string | null;
   } | null,
   verificationSessionId?: string | null,
-): Response {
+): string {
   const cfg = loadConfig();
   const profile = resolveVoiceQualityProfile(cfg);
 
@@ -392,7 +442,7 @@ function buildVoiceWebhookTwiml(
     );
     // Graceful degradation: fall back to Deepgram ConversationRelay so
     // calls don't fail entirely on a misconfigured provider.
-    return buildConversationRelayResponse(
+    return buildConversationRelayTwiml(
       callSessionId,
       cfg,
       profile,
@@ -405,7 +455,7 @@ function buildVoiceWebhookTwiml(
   const { strategy } = routingResult;
 
   if (strategy.strategy === "conversation-relay-native") {
-    return buildConversationRelayResponse(
+    return buildConversationRelayTwiml(
       callSessionId,
       cfg,
       profile,
@@ -448,7 +498,7 @@ function buildVoiceWebhookTwiml(
     );
     // Fall back to ConversationRelay so the interactive flow can proceed
     // through the relay server which supports it natively.
-    return buildConversationRelayResponse(
+    return buildConversationRelayTwiml(
       callSessionId,
       cfg,
       profile,
@@ -458,13 +508,13 @@ function buildVoiceWebhookTwiml(
     );
   }
 
-  return buildMediaStreamResponse(callSessionId, cfg, verificationSessionId);
+  return buildMediaStreamTwiml(callSessionId, cfg, verificationSessionId);
 }
 
 /**
- * Build a ConversationRelay TwiML response for Twilio-native STT providers.
+ * Build ConversationRelay TwiML for Twilio-native STT providers.
  */
-function buildConversationRelayResponse(
+function buildConversationRelayTwiml(
   callSessionId: string,
   cfg: ReturnType<typeof loadConfig>,
   profile: ReturnType<typeof resolveVoiceQualityProfile>,
@@ -478,7 +528,7 @@ function buildConversationRelayResponse(
   } | null,
   verificationSessionId: string | null | undefined,
   sttAttrs: { transcriptionProvider: string; speechModel: string | undefined },
-): Response {
+): string {
   const rawHints = resolveCallHints(sessionContext, profile.hints);
 
   const speechConfig: TwilioRelaySpeechConfig = {
@@ -490,11 +540,8 @@ function buildConversationRelayResponse(
 
   const relayUrl = getTwilioRelayUrl(cfg);
   const welcomeGreeting = buildWelcomeGreeting(sessionContext?.task ?? null);
-  const relayToken = mintEdgeRelayToken();
+  const relayToken = TWILIO_RELAY_TOKEN_PLACEHOLDER;
 
-  // Propagate verificationSessionId as a TwiML <Parameter> for
-  // observability. This is not the sole source of truth; the relay
-  // server reads the persisted call_mode from the call session first.
   const customParameters: Record<string, string> | undefined =
     verificationSessionId ? { verificationSessionId } : undefined;
 
@@ -517,22 +564,19 @@ function buildConversationRelayResponse(
     "Returning ConversationRelay TwiML",
   );
 
-  return new Response(twiml, {
-    status: 200,
-    headers: { "Content-Type": "text/xml" },
-  });
+  return twiml;
 }
 
 /**
- * Build a Stream TwiML response for custom media-stream STT providers.
+ * Build Stream TwiML for custom media-stream STT providers.
  */
-function buildMediaStreamResponse(
+function buildMediaStreamTwiml(
   callSessionId: string,
   cfg: ReturnType<typeof loadConfig>,
   verificationSessionId: string | null | undefined,
-): Response {
+): string {
   const streamUrl = getTwilioMediaStreamUrl(cfg);
-  const relayToken = mintEdgeRelayToken();
+  const relayToken = TWILIO_RELAY_TOKEN_PLACEHOLDER;
 
   const customParameters: Record<string, string> | undefined =
     verificationSessionId ? { verificationSessionId } : undefined;
@@ -549,29 +593,26 @@ function buildMediaStreamResponse(
     "Returning Stream TwiML",
   );
 
-  return new Response(twiml, {
-    status: 200,
-    headers: { "Content-Type": "text/xml" },
-  });
+  return twiml;
 }
 
 /**
- * Receives call status updates from Twilio (POST with form-urlencoded body).
- * Updates the call session status and records events.
+ * Core status callback logic — transport-agnostic.
+ *
+ * Accepts pre-parsed form params. Returns void (always 200 to Twilio
+ * regardless of internal state — errors are logged, not surfaced).
  */
-export async function handleStatusCallback(req: Request): Promise<Response> {
-  const formBody = new URLSearchParams(await req.text());
-  const callSid = formBody.get("CallSid");
-  const callStatus = formBody.get("CallStatus");
+function processStatusCallback(params: Record<string, string>): void {
+  const callSid = params.CallSid ?? null;
+  const callStatus = params.CallStatus ?? null;
 
   if (!callSid || !callStatus) {
-    const rawPayload = Object.fromEntries(formBody.entries());
     logDeadLetterEvent(
       "Status callback missing CallSid or CallStatus",
-      rawPayload,
+      params,
       log,
     );
-    return new Response(null, { status: 200 });
+    return;
   }
 
   log.info({ callSid, callStatus }, "Twilio status callback received");
@@ -582,19 +623,18 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       { callSid, callStatus },
       "Status callback: no call session found for CallSid",
     );
-    return new Response(null, { status: 200 });
+    return;
   }
 
   const mappedStatus = mapTwilioStatus(callStatus);
   if (!mappedStatus) {
-    const rawPayload = Object.fromEntries(formBody.entries());
-    logDeadLetterEvent(`Unknown Twilio status: ${callStatus}`, rawPayload, log);
-    return new Response(null, { status: 200 });
+    logDeadLetterEvent(`Unknown Twilio status: ${callStatus}`, params, log);
+    return;
   }
 
   // ── Atomic idempotency claim ────────────────────────────────────
-  const timestamp = formBody.get("Timestamp");
-  const sequenceNumber = formBody.get("SequenceNumber");
+  const timestamp = params.Timestamp ?? null;
+  const sequenceNumber = params.SequenceNumber ?? null;
   const dedupeKey = buildCallbackDedupeKey(
     callSid,
     callStatus,
@@ -608,14 +648,13 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       { callSid, callStatus, dedupeKey },
       "Duplicate status callback — skipping",
     );
-    return new Response(null, { status: 200 });
+    return;
   }
 
   let eventPersisted = false;
   try {
     const wasTerminal = isTerminalState(session.status);
 
-    // Build updates
     const updates: Parameters<typeof updateCallSession>[1] = {
       status: mappedStatus,
     };
@@ -638,10 +677,6 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
         ? "call_connected"
         : "call_started";
 
-    // Record event after DB update but before lease sync: avoids duplicate
-    // events on retry (if update fails we never record), while ensuring the
-    // lease is only released after persistence so vellum sleep doesn't proceed
-    // before the call is fully recorded.
     updateCallSession(session.id, updates, {
       beforeLeaseSync: () => {
         recordCallEvent(session.id, eventType, {
@@ -652,9 +687,6 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       },
     });
 
-    // Post-persistence processing is best-effort — failures must not
-    // propagate to the outer catch block, which would incorrectly treat
-    // them as lease-sync failures and finalize the dedupe claim.
     try {
       if (isTerminal) {
         expirePendingQuestions(session.id);
@@ -683,11 +715,6 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       );
     }
 
-    // Mark the claim as permanently processed so it never expires.
-    // If finalization returns false, another handler reclaimed this key
-    // after our claim expired — our business writes already landed but
-    // the dedupe row now belongs to the other handler, risking duplicate
-    // processing on later retries.
     const finalized = finalizeCallbackClaim(dedupeKey, claimId);
     if (!finalized) {
       log.warn(
@@ -697,9 +724,6 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
     }
   } catch (err) {
     if (eventPersisted) {
-      // Event already written — releasing the claim would let Twilio
-      // retries insert a duplicate event. Finalize instead so the
-      // dedupe guard blocks subsequent attempts.
       try {
         finalizeCallbackClaim(dedupeKey, claimId);
         log.warn(
@@ -713,7 +737,6 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
         );
       }
     } else {
-      // Nothing persisted yet — safe to release so retries can reprocess
       try {
         releaseCallbackClaim(dedupeKey, claimId);
       } catch (releaseErr) {
@@ -725,7 +748,16 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
     }
     throw err;
   }
+}
 
+/**
+ * Receives call status updates from Twilio (POST with form-urlencoded body).
+ * Updates the call session status and records events.
+ */
+export async function handleStatusCallback(req: Request): Promise<Response> {
+  const formBody = new URLSearchParams(await req.text());
+  const params = Object.fromEntries(formBody.entries());
+  processStatusCallback(params);
   return new Response(null, { status: 200 });
 }
 
@@ -740,3 +772,53 @@ export async function handleConnectAction(_req: Request): Promise<Response> {
     headers: { "Content-Type": "text/xml" },
   });
 }
+
+// ── Transport-agnostic internal route handlers ───────────────────────
+
+const EMPTY_TWIML = '<?xml version="1.0" encoding="UTF-8"?><Response/>';
+
+/**
+ * Internal voice-webhook handler for gateway→runtime forwarding.
+ * Accepts JSON body `{ params, originalUrl? }` from the gateway.
+ */
+export function handleInternalVoiceWebhook({
+  body = {},
+}: RouteHandlerArgs): RouteResponse {
+  const { params = {}, originalUrl } = body as {
+    params?: Record<string, string>;
+    originalUrl?: string;
+  };
+
+  // Extract callSessionId from the original URL query string
+  let callSessionId: string | null = null;
+  if (originalUrl) {
+    try {
+      callSessionId = new URL(originalUrl).searchParams.get("callSessionId");
+    } catch {
+      // malformed URL — treat as no callSessionId
+    }
+  }
+
+  const twiml = processVoiceWebhook(params, callSessionId);
+  return new RouteResponse(twiml, TWIML_HEADERS);
+}
+
+/**
+ * Internal status-callback handler for gateway→runtime forwarding.
+ * Accepts JSON body `{ params }` from the gateway.
+ */
+export function handleInternalStatusCallback({
+  body = {},
+}: RouteHandlerArgs): RouteResponse {
+  const { params = {} } = body as { params?: Record<string, string> };
+  processStatusCallback(params);
+  return new RouteResponse(null, {});
+}
+
+/**
+ * Internal connect-action handler for gateway→runtime forwarding.
+ */
+export function handleInternalConnectAction(): RouteResponse {
+  log.info("ConversationRelay connect-action callback received");
+  return new RouteResponse(EMPTY_TWIML, TWIML_HEADERS);
+}

package/src/calls/voice-control-protocol.ts

@@ -19,20 +19,20 @@ export const END_CALL_MARKER = "[END_CALL]";
 // ---------------------------------------------------------------------------
 
 export const ASK_GUARDIAN_CAPTURE_REGEX = /\[ASK_GUARDIAN:\s*(.+?)\]/;
-export const ASK_GUARDIAN_MARKER_REGEX = /\[ASK_GUARDIAN:\s*.+?\]/g;
+const ASK_GUARDIAN_MARKER_REGEX = /\[ASK_GUARDIAN:\s*.+?\]/g;
 
 // Flexible prefix for ASK_GUARDIAN_APPROVAL — tolerates variable whitespace
 // after the colon so the marker is recognized even if the model omits the
 // space or inserts a newline.
-export const ASK_GUARDIAN_APPROVAL_PREFIX_RE = /\[ASK_GUARDIAN_APPROVAL:\s*/;
+const ASK_GUARDIAN_APPROVAL_PREFIX_RE = /\[ASK_GUARDIAN_APPROVAL:\s*/;
 
-export const USER_ANSWERED_MARKER_REGEX = /\[USER_ANSWERED:\s*.+?\]/g;
-export const USER_INSTRUCTION_MARKER_REGEX = /\[USER_INSTRUCTION:\s*.+?\]/g;
-export const CALL_OPENING_MARKER_REGEX = /\[CALL_OPENING\]/g;
-export const CALL_OPENING_ACK_MARKER_REGEX = /\[CALL_OPENING_ACK\]/g;
-export const END_CALL_MARKER_REGEX = /\[END_CALL\]/g;
-export const GUARDIAN_TIMEOUT_MARKER_REGEX = /\[GUARDIAN_TIMEOUT\]/g;
-export const GUARDIAN_UNAVAILABLE_MARKER_REGEX = /\[GUARDIAN_UNAVAILABLE\]/g;
+const USER_ANSWERED_MARKER_REGEX = /\[USER_ANSWERED:\s*.+?\]/g;
+const USER_INSTRUCTION_MARKER_REGEX = /\[USER_INSTRUCTION:\s*.+?\]/g;
+const CALL_OPENING_MARKER_REGEX = /\[CALL_OPENING\]/g;
+const CALL_OPENING_ACK_MARKER_REGEX = /\[CALL_OPENING_ACK\]/g;
+const END_CALL_MARKER_REGEX = /\[END_CALL\]/g;
+const GUARDIAN_TIMEOUT_MARKER_REGEX = /\[GUARDIAN_TIMEOUT\]/g;
+const GUARDIAN_UNAVAILABLE_MARKER_REGEX = /\[GUARDIAN_UNAVAILABLE\]/g;
 
 // ---------------------------------------------------------------------------
 // Balanced JSON extraction (used by stripGuardianApprovalMarkers)
@@ -124,7 +124,7 @@ export function extractBalancedJson(
  * nested braces, string literals, and flexible whitespace correctly.
  * Only strips complete markers (prefix + balanced JSON + closing `]`).
  */
-export function stripGuardianApprovalMarkers(text: string): string {
+function stripGuardianApprovalMarkers(text: string): string {
   let result = text;
   for (;;) {
     const match = extractBalancedJson(result);

package/src/calls/voice-ingress-preflight.ts

@@ -1,6 +1,6 @@
+import { getIsPlatform } from "../config/env-registry.js";
 import { loadConfig } from "../config/loader.js";
 import type { AssistantConfig } from "../config/types.js";
-import { shouldUsePlatformCallbacks } from "../inbound/platform-callback-registration.js";
 import { getPublicBaseUrl } from "../inbound/public-ingress-urls.js";
 
 const SERVICE_UNAVAILABLE_STATUS = 503 as const;
@@ -34,7 +34,7 @@ export async function preflightVoiceIngress(): Promise<VoiceIngressPreflightResu
 
   // Platform-callback deployments register routes with the platform and receive
   // stable callback URLs. No public ingress URL or local gateway is involved.
-  if (shouldUsePlatformCallbacks()) {
+  if (getIsPlatform()) {
     return {
       ok: true,
       ingressConfig,