@vellumai/assistant 0.4.41 → 0.4.43

package/src/calls/twilio-config.ts

@@ -1,3 +1,4 @@
+import { getTwilioPhoneNumberEnv } from "../config/env.js";
 import { loadConfig } from "../config/loader.js";
 import {
   getPublicBaseUrl,
@@ -17,11 +18,35 @@ export interface TwilioConfig {
   wssBaseUrl: string;
 }
 
+/**
+ * Resolve the Twilio phone number using a unified fallback chain so that
+ * all callers (calls, SMS adapter, readiness checks, invite transports)
+ * agree on the same number.
+ *
+ * Resolution order:
+ *   1. TWILIO_PHONE_NUMBER env var
+ *   2. config.twilio?.phoneNumber
+ *   3. ""
+ */
+export function resolveTwilioPhoneNumber(): string {
+  const fromEnv = getTwilioPhoneNumberEnv();
+  if (fromEnv) return fromEnv;
+
+  try {
+    const config = loadConfig();
+    if (config.twilio?.phoneNumber) return config.twilio.phoneNumber;
+  } catch {
+    // Config may not be available yet during early startup
+  }
+
+  return "";
+}
+
 export function getTwilioConfig(): TwilioConfig {
   const config = loadConfig();
   const accountSid = config.twilio?.accountSid || "";
-  const authToken = getSecureKey("credential:twilio:auth_token");
-  const phoneNumber = config.twilio?.phoneNumber || "";
+  const authToken = getSecureKey("credential:twilio:auth_token") || "";
+  const phoneNumber = resolveTwilioPhoneNumber();
   const webhookBaseUrl = getPublicBaseUrl(config);
 
   let wssBaseUrl: string;
@@ -33,7 +58,7 @@ export function getTwilioConfig(): TwilioConfig {
 
   if (!accountSid || !authToken) {
     throw new ConfigError(
-      "Twilio credentials not configured. Set twilio.accountSid via config and twilio:auth_token via the credential_store tool.",
+      "Twilio credentials not configured. Set twilio.accountSid via config and store auth token via credential store.",
     );
   }
   if (!phoneNumber) {

package/src/calls/twilio-provider.ts

@@ -16,7 +16,7 @@ const log = getLogger("twilio-provider");
  * Twilio ConversationRelay voice provider.
  *
  * Uses the Twilio REST API directly via fetch() — no twilio npm package.
- * Credentials are resolved lazily from the secure key store on each call.
+ * Credentials are resolved lazily from config on each call.
  */
 export class TwilioConversationRelayProvider implements VoiceProvider {
   readonly name = "twilio";
@@ -275,12 +275,12 @@ export class TwilioConversationRelayProvider implements VoiceProvider {
   // ── Webhook signature verification ──────────────────────────────────
 
   /**
-   * Returns the Twilio auth token from the secure key store, or null if
-   * not configured. Exposed as a static method so callers (e.g. the
-   * HTTP server webhook middleware) can check availability independently.
+   * Returns the Twilio auth token from the credential store, or null if not configured.
+   * Exposed as a static method so callers (e.g. the HTTP server webhook
+   * middleware) can check availability independently.
    */
   static getAuthToken(): string | null {
-    return getSecureKey("credential:twilio:auth_token") ?? null;
+    return getSecureKey("credential:twilio:auth_token") || null;
   }
 
   /**

package/src/calls/twilio-rest.ts

@@ -2,7 +2,7 @@
  * Reusable Twilio REST API helpers.
  *
  * Provides low-level building blocks (auth header, base URL, credential
- * resolution) shared across the voice provider, SMS channel, and IPC
+ * resolution) shared across the voice provider and IPC
  * config handler. Uses fetch() directly — no twilio npm package.
  */
 
@@ -15,27 +15,29 @@ export interface TwilioCredentials {
   authToken: string;
 }
 
-/**
- * Resolve the Twilio Account SID from config.
- * Returns undefined if not found.
- */
+/** Resolve the Twilio Account SID from config. */
 function resolveAccountSid(): string | undefined {
   try {
     const config = loadConfig();
-    if (config.twilio?.accountSid) return config.twilio.accountSid;
+    return config.twilio?.accountSid || undefined;
   } catch {
     // Config may not be available during early startup
+    return undefined;
   }
-  return undefined;
 }
 
-/** Resolve Twilio credentials from config and secure key store. Throws if not configured. */
+/** Resolve the Twilio Auth Token from the credential store. */
+function resolveAuthToken(): string | undefined {
+  return getSecureKey("credential:twilio:auth_token") || undefined;
+}
+
+/** Resolve Twilio credentials from config (SID) and credential store (token). Throws if not configured. */
 export function getTwilioCredentials(): TwilioCredentials {
   const accountSid = resolveAccountSid();
-  const authToken = getSecureKey("credential:twilio:auth_token");
+  const authToken = resolveAuthToken();
   if (!accountSid || !authToken) {
     throw new ConfigError(
-      "Twilio credentials not configured. Set twilio.accountSid via config and credential:twilio:auth_token via the credential_store tool.",
+      "Twilio credentials not configured. Set twilio.accountSid via config and store auth token via credential store.",
     );
   }
   return { accountSid, authToken };
@@ -43,9 +45,11 @@ export function getTwilioCredentials(): TwilioCredentials {
 
 /** Check whether Twilio credentials are present (non-throwing). */
 export function hasTwilioCredentials(): boolean {
-  return (
-    !!resolveAccountSid() && !!getSecureKey("credential:twilio:auth_token")
-  );
+  try {
+    return !!resolveAccountSid() && !!resolveAuthToken();
+  } catch {
+    return false;
+  }
 }
 
 /** Build the HTTP Basic auth header for Twilio API requests. */
@@ -66,7 +70,7 @@ export function twilioBaseUrl(accountSid: string): string {
 export interface TwilioPhoneNumber {
   phoneNumber: string;
   friendlyName: string;
-  capabilities: { voice: boolean; sms: boolean };
+  capabilities: { voice: boolean };
 }
 
 /** List incoming phone numbers owned by the account. */
@@ -95,21 +99,21 @@ export async function listIncomingPhoneNumbers(
     incoming_phone_numbers: Array<{
       phone_number: string;
       friendly_name: string;
-      capabilities: { voice: boolean; sms: boolean };
+      capabilities: { voice: boolean };
     }>;
   };
 
   return data.incoming_phone_numbers.map((n) => ({
     phoneNumber: n.phone_number,
     friendlyName: n.friendly_name,
-    capabilities: { voice: n.capabilities.voice, sms: n.capabilities.sms },
+    capabilities: { voice: n.capabilities.voice },
   }));
 }
 
 export interface AvailablePhoneNumber {
   phoneNumber: string;
   friendlyName: string;
-  capabilities: { voice: boolean; sms: boolean };
+  capabilities: { voice: boolean };
 }
 
 /** Search for available phone numbers to purchase. */
@@ -148,14 +152,14 @@ export async function searchAvailableNumbers(
     available_phone_numbers: Array<{
       phone_number: string;
       friendly_name: string;
-      capabilities: { voice: boolean; sms: boolean };
+      capabilities: { voice: boolean };
     }>;
   };
 
   return data.available_phone_numbers.map((n) => ({
     phoneNumber: n.phone_number,
     friendlyName: n.friendly_name,
-    capabilities: { voice: n.capabilities.voice, sms: n.capabilities.sms },
+    capabilities: { voice: n.capabilities.voice },
   }));
 }
 
@@ -191,7 +195,7 @@ export async function provisionPhoneNumber(
   const data = (await res.json()) as {
     phone_number: string;
     friendly_name: string;
-    capabilities: { voice: boolean; sms: boolean };
+    capabilities: { voice: boolean };
   };
 
   return {
@@ -199,7 +203,6 @@ export async function provisionPhoneNumber(
     friendlyName: data.friendly_name,
     capabilities: {
       voice: data.capabilities.voice,
-      sms: data.capabilities.sms,
     },
   };
 }
@@ -245,15 +248,13 @@ export async function fetchMessageStatus(
 export interface WebhookUrls {
   voiceUrl: string;
   statusCallbackUrl: string;
-  smsUrl: string;
 }
 
 /**
  * Update the webhook URLs on a Twilio IncomingPhoneNumber.
  *
- * Configures voice webhook, voice status callback, and SMS webhook so
- * that Twilio routes inbound calls and messages to the assistant's
- * gateway endpoints.
+ * Configures voice webhook and voice status callback so that Twilio
+ * routes inbound calls to the assistant's gateway endpoints.
  */
 export async function updatePhoneNumberWebhooks(
   accountSid: string,
@@ -303,8 +304,6 @@ export async function updatePhoneNumberWebhooks(
     VoiceMethod: "POST",
     StatusCallback: webhooks.statusCallbackUrl,
     StatusCallbackMethod: "POST",
-    SmsUrl: webhooks.smsUrl,
-    SmsMethod: "POST",
   });
 
   const updateRes = await fetch(

package/src/calls/twilio-routes.ts

@@ -27,7 +27,6 @@ import {
   releaseCallbackClaim,
   updateCallSession,
 } from "./call-store.js";
-import { getTwilioConfig } from "./twilio-config.js";
 import type { CallStatus } from "./types.js";
 import { resolveVoiceQualityProfile } from "./voice-quality.js";
 
@@ -115,22 +114,6 @@ export function buildWelcomeGreeting(
   return "";
 }
 
-/**
- * Resolve the WebSocket relay URL from Twilio config.
- *
- * Treats wssBaseUrl as present only when it is non-empty after trimming.
- * Falls back to webhookBaseUrl, normalizing the scheme from http(s) to ws(s)
- * and stripping any trailing slash.
- */
-export function resolveRelayUrl(
-  wssBaseUrl: string,
-  webhookBaseUrl: string,
-): string {
-  const base = wssBaseUrl.trim() || webhookBaseUrl;
-  const normalized = base.replace(/\/$/, "").replace(/^http(s?)/, "ws$1");
-  return `${normalized}/v1/calls/relay`;
-}
-
 /**
  * Map Twilio call status strings to our internal CallStatus.
  */
@@ -198,7 +181,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
     return buildVoiceWebhookTwiml(
       session.id,
       session.task,
-      session.guardianVerificationSessionId,
+      session.verificationSessionId,
     );
   }
 
@@ -226,7 +209,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
   return buildVoiceWebhookTwiml(
     callSessionId,
     session.task,
-    session.guardianVerificationSessionId,
+    session.verificationSessionId,
   );
 }
 
@@ -235,7 +218,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
  * Resolves voice quality profile, relay URL, and welcome greeting,
  * then returns a Response with the generated TwiML.
  *
- * When `guardianVerificationSessionId` is provided, it is included as a
+ * When `verificationSessionId` is provided, it is included as a
  * `<Parameter>` in the TwiML for observability and compatibility with
  * the Twilio setup payload. The persisted call session mode is the
  * primary signal for deterministic flow selection in the relay server.
@@ -243,7 +226,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
 function buildVoiceWebhookTwiml(
   callSessionId: string,
   task: string | null,
-  guardianVerificationSessionId?: string | null,
+  verificationSessionId?: string | null,
 ): Response {
   const profile = resolveVoiceQualityProfile(loadConfig());
 
@@ -252,28 +235,16 @@ function buildVoiceWebhookTwiml(
     "Voice quality profile resolved",
   );
 
-  const twilioConfig = getTwilioConfig();
-  let relayUrl: string;
-  try {
-    relayUrl = getTwilioRelayUrl(loadConfig());
-  } catch {
-    // Fallback to legacy resolution when ingress is not configured
-    relayUrl = resolveRelayUrl(
-      twilioConfig.wssBaseUrl,
-      twilioConfig.webhookBaseUrl,
-    );
-  }
+  const relayUrl = getTwilioRelayUrl(loadConfig());
   const welcomeGreeting = buildWelcomeGreeting(task, getCallWelcomeGreeting());
 
   const relayToken = mintEdgeRelayToken();
 
-  // Propagate guardianVerificationSessionId as a TwiML <Parameter> for
+  // 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 =
-    guardianVerificationSessionId
-      ? { guardianVerificationSessionId }
-      : undefined;
+    verificationSessionId ? { verificationSessionId } : undefined;
 
   const twiml = generateTwiML(
     callSessionId,
@@ -348,6 +319,7 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
     return new Response(null, { status: 200 });
   }
 
+  let eventPersisted = false;
   try {
     const wasTerminal = isTerminalState(session.status);
 
@@ -366,9 +338,6 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       updates.endedAt = Date.now();
     }
 
-    updateCallSession(session.id, updates);
-
-    // Record event
     const eventType = isTerminal
       ? mappedStatus === "completed"
         ? "call_ended"
@@ -377,18 +346,32 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
         ? "call_connected"
         : "call_started";
 
-    recordCallEvent(session.id, eventType, {
-      twilioStatus: callStatus,
-      callSid,
+    // 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, {
+          twilioStatus: callStatus,
+          callSid,
+        });
+        eventPersisted = true;
+      },
     });
 
-    // Expire pending questions on terminal status
-    if (isTerminal) {
-      expirePendingQuestions(session.id);
-
-      if (!wasTerminal) {
-        persistCallCompletionMessage(session.conversationId, session.id).catch(
-          (err) => {
+    // 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);
+
+        if (!wasTerminal) {
+          persistCallCompletionMessage(
+            session.conversationId,
+            session.id,
+          ).catch((err) => {
             log.error(
               {
                 err,
@@ -397,10 +380,15 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
               },
               "Failed to persist call completion message",
             );
-          },
-        );
-        fireCallCompletionNotifier(session.conversationId, session.id);
+          });
+          fireCallCompletionNotifier(session.conversationId, session.id);
+        }
       }
+    } catch (postErr) {
+      log.error(
+        { err: postErr, callSid, callStatus, callSessionId: session.id },
+        "Post-persistence processing failed — event and claim are intact, but side effects may be incomplete",
+      );
     }
 
     // Mark the claim as permanently processed so it never expires.
@@ -416,8 +404,33 @@ export async function handleStatusCallback(req: Request): Promise<Response> {
       );
     }
   } catch (err) {
-    // Release claim so Twilio retries can reprocess
-    releaseCallbackClaim(dedupeKey, claimId);
+    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(
+          { dedupeKey, claimId, callSid, callStatus, err },
+          "Post-persistence error — claim finalized to prevent duplicate events on retry",
+        );
+      } catch (finalizeErr) {
+        log.error(
+          { dedupeKey, claimId, callSid, callStatus, finalizeErr },
+          "Failed to finalize claim after event persistence — original error will still be re-thrown",
+        );
+      }
+    } else {
+      // Nothing persisted yet — safe to release so retries can reprocess
+      try {
+        releaseCallbackClaim(dedupeKey, claimId);
+      } catch (releaseErr) {
+        log.error(
+          { dedupeKey, claimId, callSid, callStatus, releaseErr },
+          "Failed to release claim — original error will still be re-thrown",
+        );
+      }
+    }
     throw err;
   }
 

package/src/calls/types.ts

@@ -19,12 +19,12 @@ export type CallEventType =
   | "callee_verification_started"
   | "callee_verification_succeeded"
   | "callee_verification_failed"
-  | "guardian_voice_verification_started"
-  | "guardian_voice_verification_succeeded"
-  | "guardian_voice_verification_failed"
-  | "outbound_guardian_voice_verification_started"
-  | "outbound_guardian_voice_verification_succeeded"
-  | "outbound_guardian_voice_verification_failed"
+  | "voice_verification_started"
+  | "voice_verification_succeeded"
+  | "voice_verification_failed"
+  | "outbound_voice_verification_started"
+  | "outbound_voice_verification_succeeded"
+  | "outbound_voice_verification_failed"
   | "guardian_consultation_timed_out"
   | "guardian_unavailable_skipped"
   | "guardian_consult_deferred"
@@ -58,7 +58,7 @@ export type PendingQuestionStatus =
  * uses this as the primary signal for deterministic flow selection,
  * with Twilio setup custom parameters as a secondary/observability signal.
  */
-export type CallMode = "normal" | "guardian_verification";
+export type CallMode = "normal" | "verification";
 
 export interface CallSession {
   id: string;
@@ -70,7 +70,7 @@ export interface CallSession {
   task: string | null;
   status: CallStatus;
   callMode: CallMode | null;
-  guardianVerificationSessionId: string | null;
+  verificationSessionId: string | null;
   callerIdentityMode: string | null;
   callerIdentitySource: string | null;
   initiatedFromConversationId?: string | null;

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

@@ -0,0 +1,110 @@
+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;
+
+export interface VoiceIngressPreflightSuccess {
+  ok: true;
+  ingressConfig: AssistantConfig;
+  publicBaseUrl: string;
+}
+
+export interface VoiceIngressPreflightFailure {
+  ok: false;
+  error: string;
+  status: typeof SERVICE_UNAVAILABLE_STATUS;
+}
+
+export type VoiceIngressPreflightResult =
+  | VoiceIngressPreflightSuccess
+  | VoiceIngressPreflightFailure;
+
+function fail(error: string): VoiceIngressPreflightFailure {
+  return {
+    ok: false,
+    error,
+    status: SERVICE_UNAVAILABLE_STATUS,
+  };
+}
+
+function buildGatewayUnhealthyMessage(
+  target: string,
+  error: string | undefined,
+  afterRecoveryAttempt: boolean,
+): string {
+  const detail = error ?? "Unknown gateway health check failure";
+  if (afterRecoveryAttempt) {
+    return `Voice callback gateway is still unhealthy at ${target} after a local recovery attempt: ${detail}`;
+  }
+  return `Voice callback gateway is unhealthy at ${target}: ${detail}`;
+}
+
+export async function preflightVoiceIngress(): Promise<VoiceIngressPreflightResult> {
+  const ingressConfig = loadConfig();
+
+  // Platform-callback deployments register routes with the platform and receive
+  // stable callback URLs. No public ingress URL or local gateway is involved.
+  if (shouldUsePlatformCallbacks()) {
+    return {
+      ok: true,
+      ingressConfig,
+      publicBaseUrl: "",
+    };
+  }
+
+  let publicBaseUrl: string;
+  try {
+    publicBaseUrl = getPublicBaseUrl(ingressConfig);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail(
+      msg ||
+        "Outbound voice calls require public ingress to be enabled and a public base URL (ingress.publicBaseUrl or INGRESS_PUBLIC_BASE_URL).",
+    );
+  }
+
+  const { ensureLocalGatewayReady, probeLocalGatewayHealth } =
+    await import("../runtime/local-gateway-health.js");
+
+  const initialHealth = await probeLocalGatewayHealth();
+  if (!initialHealth.healthy && !initialHealth.localDeployment) {
+    return fail(
+      buildGatewayUnhealthyMessage(
+        initialHealth.target,
+        initialHealth.error,
+        false,
+      ),
+    );
+  }
+
+  if (initialHealth.localDeployment) {
+    const recovery = await ensureLocalGatewayReady();
+    // Re-probe after the wake flow so the dial path only continues when the
+    // current gateway process is demonstrably serving the callback stack.
+    const confirmedHealth = await probeLocalGatewayHealth();
+    if (!confirmedHealth.healthy) {
+      return fail(
+        buildGatewayUnhealthyMessage(
+          confirmedHealth.target,
+          confirmedHealth.error ?? recovery.error,
+          recovery.recoveryAttempted,
+        ),
+      );
+    }
+  }
+
+  return {
+    ok: true,
+    ingressConfig: {
+      ...ingressConfig,
+      ingress: {
+        ...(ingressConfig.ingress ?? {}),
+        enabled: true,
+        publicBaseUrl,
+      },
+    },
+    publicBaseUrl,
+  };
+}

package/src/calls/voice-session-bridge.ts

@@ -13,7 +13,7 @@
 import { consumeGrantForInvocation } from "../approvals/approval-primitive.js";
 import type { ChannelId } from "../channels/types.js";
 import { getConfig } from "../config/loader.js";
-import type { ServerMessage } from "../daemon/ipc-protocol.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
 import type { Session } from "../daemon/session.js";
 import type { TrustContext } from "../daemon/session-runtime-assembly.js";
 import { resolveChannelCapabilities } from "../daemon/session-runtime-assembly.js";
@@ -219,7 +219,7 @@ function buildVoiceCallControlPrompt(opts: {
  * Execute a single voice turn through the daemon session pipeline.
  *
  * Manages the session directly with voice-specific defaults:
- *   - sourceChannel: 'voice'
+ *   - sourceChannel: 'phone'
  *   - event sink wired to the provided callbacks
  *   - abort propagated from the returned handle
  *
@@ -283,7 +283,7 @@ export async function startVoiceTurn(
 
   // Get or create the session
   const transport = {
-    channelId: "voice" as ChannelId,
+    channelId: "phone" as ChannelId,
   };
   const session = await deps.getOrCreateSession(opts.conversationId, transport);
 
@@ -321,11 +321,11 @@ export async function startVoiceTurn(
   session.setTrustContext(opts.trustContext ?? null);
   session.setCommandIntent(null);
   session.setTurnChannelContext({
-    userMessageChannel: "voice",
-    assistantMessageChannel: "voice",
+    userMessageChannel: "phone",
+    assistantMessageChannel: "phone",
   });
   session.setChannelCapabilities(
-    resolveChannelCapabilities("voice", undefined),
+    resolveChannelCapabilities("phone", undefined),
   );
   session.setVoiceCallControlPrompt(voiceCallControlPrompt);
 
@@ -392,7 +392,7 @@ export async function startVoiceTurn(
               toolName: msg.toolName,
               inputDigest,
               consumingRequestId: msg.requestId,
-              executionChannel: "voice",
+              executionChannel: "phone",
               conversationId: opts.conversationId,
               callSessionId: opts.callSessionId,
               requesterExternalUserId:

package/src/channels/config.ts

@@ -45,15 +45,6 @@ const CHANNEL_POLICIES = {
       codeRedemptionEnabled: true,
     },
   },
-  sms: {
-    notification: {
-      deliveryEnabled: true,
-      conversationStrategy: "continue_existing_conversation",
-    },
-    invite: {
-      codeRedemptionEnabled: true,
-    },
-  },
   whatsapp: {
     notification: {
       deliveryEnabled: false,
@@ -81,7 +72,7 @@ const CHANNEL_POLICIES = {
       codeRedemptionEnabled: true,
     },
   },
-  voice: {
+  phone: {
     notification: {
       deliveryEnabled: false,
       conversationStrategy: "not_deliverable",

package/src/{config/channel-permission-profiles.ts → channels/permission-profiles.ts}

@@ -11,7 +11,7 @@
  * Each entry maps a channel ID to a ChannelPermissionProfile.
  */
 
-import { getConfig, saveConfig } from "./loader.js";
+import { getConfig, saveConfig } from "../config/loader.js";
 
 // ── Types ───────────────────────────────────────────────────────────