@vellumai/assistant 0.4.31 → 0.4.32

package/src/calls/relay-setup-router.ts

@@ -0,0 +1,307 @@
+/**
+ * Pure routing logic extracted from RelayConnection.handleSetup.
+ *
+ * Given a setup context (call session, actor trust, voice config, ACL policy),
+ * returns a discriminated union describing what the relay connection should do
+ * next — without performing any side effects itself.
+ */
+
+import { getConfig } from "../config/loader.js";
+import { findActiveVoiceInvites } from "../memory/invite-store.js";
+import {
+  type ActorTrustContext,
+  resolveActorTrust,
+} from "../runtime/actor-trust-resolver.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
+import { getPendingChallenge } from "../runtime/channel-guardian-service.js";
+import { getLogger } from "../util/logger.js";
+import type { CallSession } from "./types.js";
+
+const log = getLogger("relay-setup-router");
+
+// ── Setup context ────────────────────────────────────────────────────
+
+export interface SetupContext {
+  callSessionId: string;
+  session: CallSession | null;
+  from: string;
+  to: string;
+  customParameters?: Record<string, string>;
+}
+
+// ── Setup outcomes ───────────────────────────────────────────────────
+
+export type SetupOutcome =
+  | { action: "normal_call"; isInbound: boolean }
+  | {
+      action: "guardian_verification";
+      assistantId: string;
+      fromNumber: string;
+    }
+  | {
+      action: "outbound_guardian_verification";
+      assistantId: string;
+      sessionId: string;
+      toNumber: string;
+    }
+  | {
+      action: "callee_verification";
+      verificationConfig: { maxAttempts: number; codeLength: number };
+    }
+  | {
+      action: "invite_redemption";
+      assistantId: string;
+      fromNumber: string;
+      friendName: string | null;
+      guardianName: string | null;
+    }
+  | { action: "name_capture"; assistantId: string; fromNumber: string }
+  | { action: "deny"; message: string; logReason: string };
+
+// ── Resolved context produced alongside the outcome ──────────────────
+
+export interface SetupResolved {
+  assistantId: string;
+  isInbound: boolean;
+  otherPartyNumber: string;
+  actorTrust: ActorTrustContext;
+}
+
+// ── Router ───────────────────────────────────────────────────────────
+
+/**
+ * Determine the setup outcome for an incoming relay connection.
+ *
+ * This function is pure routing logic — it reads state but performs no
+ * side effects (no call-session mutations, no event recording, no WS
+ * messages). The caller (`RelayConnection.handleSetup`) is responsible
+ * for acting on the returned outcome.
+ */
+export function routeSetup(ctx: SetupContext): {
+  outcome: SetupOutcome;
+  resolved: SetupResolved;
+} {
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+  const isInbound = ctx.session?.initiatedFromConversationId == null;
+  const otherPartyNumber = isInbound ? ctx.from : ctx.to;
+
+  const actorTrust = resolveActorTrust({
+    assistantId,
+    sourceChannel: "voice",
+    conversationExternalId: otherPartyNumber,
+    actorExternalId: otherPartyNumber || undefined,
+  });
+
+  const resolved: SetupResolved = {
+    assistantId,
+    isInbound,
+    otherPartyNumber,
+    actorTrust,
+  };
+
+  // ── Outbound guardian verification (persisted mode) ──────────────
+  const persistedMode = ctx.session?.callMode;
+  const persistedGvSessionId = ctx.session?.guardianVerificationSessionId;
+  const customParamGvSessionId =
+    ctx.customParameters?.guardianVerificationSessionId;
+  const guardianVerificationSessionId =
+    persistedGvSessionId ?? customParamGvSessionId;
+
+  if (
+    persistedMode === "guardian_verification" &&
+    guardianVerificationSessionId
+  ) {
+    return {
+      outcome: {
+        action: "outbound_guardian_verification",
+        assistantId,
+        sessionId: guardianVerificationSessionId,
+        toNumber: ctx.to,
+      },
+      resolved,
+    };
+  }
+
+  // Secondary signal: custom parameter without persisted mode (pre-migration)
+  if (!persistedMode && customParamGvSessionId) {
+    log.warn(
+      {
+        callSessionId: ctx.callSessionId,
+        guardianVerificationSessionId: customParamGvSessionId,
+      },
+      "Guardian verification detected via setup custom parameter (no persisted call_mode) — entering verification path",
+    );
+    return {
+      outcome: {
+        action: "outbound_guardian_verification",
+        assistantId,
+        sessionId: customParamGvSessionId,
+        toNumber: ctx.to,
+      },
+      resolved,
+    };
+  }
+
+  // ── Outbound callee verification ────────────────────────────────
+  const config = getConfig();
+  const verificationConfig = config.calls.verification;
+  if (!isInbound && verificationConfig.enabled) {
+    return {
+      outcome: {
+        action: "callee_verification",
+        verificationConfig,
+      },
+      resolved,
+    };
+  }
+
+  // ── Outbound normal call ────────────────────────────────────────
+  if (!isInbound) {
+    return {
+      outcome: { action: "normal_call", isInbound: false },
+      resolved,
+    };
+  }
+
+  // ── Inbound call ACL evaluation ─────────────────────────────────
+  const pendingChallenge = getPendingChallenge(assistantId, "voice");
+
+  if (actorTrust.trustClass === "unknown" && !pendingChallenge) {
+    // Check for blocked caller
+    if (actorTrust.memberRecord?.channel.status === "blocked") {
+      log.info(
+        {
+          callSessionId: ctx.callSessionId,
+          from: ctx.from,
+          trustClass: actorTrust.trustClass,
+        },
+        "Inbound voice ACL: blocked caller denied",
+      );
+      return {
+        outcome: {
+          action: "deny",
+          message: "This number is not authorized to use this assistant.",
+          logReason: "Inbound voice ACL: caller blocked",
+        },
+        resolved,
+      };
+    }
+
+    // Check for active voice invites
+    let voiceInvites: ReturnType<typeof findActiveVoiceInvites> = [];
+    try {
+      voiceInvites = findActiveVoiceInvites({
+        assistantId,
+        expectedExternalUserId: ctx.from,
+      });
+    } catch (err) {
+      log.warn(
+        { err, callSessionId: ctx.callSessionId },
+        "Failed to check voice invites for unknown caller",
+      );
+    }
+
+    const now = Date.now();
+    const nonExpiredInvites = voiceInvites.filter(
+      (i) => !i.expiresAt || i.expiresAt > now,
+    );
+
+    if (nonExpiredInvites.length > 0) {
+      const matchedInvite = nonExpiredInvites[0];
+      log.info(
+        { callSessionId: ctx.callSessionId, from: ctx.from },
+        "Inbound voice ACL: unknown caller has active voice invite — entering redemption flow",
+      );
+      return {
+        outcome: {
+          action: "invite_redemption",
+          assistantId,
+          fromNumber: ctx.from,
+          friendName: matchedInvite.friendName,
+          guardianName: matchedInvite.guardianName,
+        },
+        resolved,
+      };
+    }
+
+    // Unknown caller — name capture flow
+    log.info(
+      {
+        callSessionId: ctx.callSessionId,
+        from: ctx.from,
+        trustClass: actorTrust.trustClass,
+      },
+      "Inbound voice ACL: unknown caller — entering name capture flow",
+    );
+    return {
+      outcome: {
+        action: "name_capture",
+        assistantId,
+        fromNumber: ctx.from,
+      },
+      resolved,
+    };
+  }
+
+  // Members with policy: 'deny'
+  if (actorTrust.memberRecord?.channel.policy === "deny") {
+    log.info(
+      {
+        callSessionId: ctx.callSessionId,
+        from: ctx.from,
+        channelId: actorTrust.memberRecord.channel.id,
+        trustClass: actorTrust.trustClass,
+      },
+      "Inbound voice ACL: member policy deny",
+    );
+    return {
+      outcome: {
+        action: "deny",
+        message: "This number is not authorized to use this assistant.",
+        logReason: "Inbound voice ACL: member policy deny",
+      },
+      resolved,
+    };
+  }
+
+  // Members with policy: 'escalate' — live calls can't wait for approval
+  if (actorTrust.memberRecord?.channel.policy === "escalate") {
+    log.info(
+      {
+        callSessionId: ctx.callSessionId,
+        from: ctx.from,
+        channelId: actorTrust.memberRecord.channel.id,
+        trustClass: actorTrust.trustClass,
+      },
+      "Inbound voice ACL: member policy escalate — cannot hold live call for guardian approval",
+    );
+    return {
+      outcome: {
+        action: "deny",
+        message:
+          "This number requires guardian approval for calls. Please have the account guardian update your permissions.",
+        logReason:
+          "Inbound voice ACL: member policy escalate — voice calls cannot await guardian approval",
+      },
+      resolved,
+    };
+  }
+
+  // Guardian verification challenge
+  if (pendingChallenge) {
+    return {
+      outcome: {
+        action: "guardian_verification",
+        assistantId,
+        fromNumber: ctx.from,
+      },
+      resolved,
+    };
+  }
+
+  // Guardian and trusted-contact callers proceed normally
+  return {
+    outcome: { action: "normal_call", isInbound: true },
+    resolved,
+  };
+}

package/src/calls/relay-verification.ts

@@ -0,0 +1,280 @@
+/**
+ * Extracted verification logic for the ConversationRelay voice pipeline.
+ *
+ * These pure-ish functions encapsulate the decision-making for guardian code
+ * verification and invite code redemption without directly mutating relay
+ * connection state. They return structured result objects that the caller
+ * (RelayConnection) interprets to drive side-effects (TTS, session updates,
+ * timer scheduling, etc.).
+ */
+
+import {
+  getGuardianBinding,
+  validateAndConsumeChallenge,
+} from "../runtime/channel-guardian-service.js";
+import {
+  composeVerificationVoice,
+  GUARDIAN_VERIFY_TEMPLATE_KEYS,
+} from "../runtime/guardian-verification-templates.js";
+import { redeemVoiceInviteCode } from "../runtime/invite-service.js";
+import type { CallEventType } from "./types.js";
+
+// ── parseDigitsFromSpeech ──────────────────────────────────────────────
+
+const wordToDigit: Record<string, string> = {
+  zero: "0",
+  oh: "0",
+  o: "0",
+  one: "1",
+  won: "1",
+  two: "2",
+  too: "2",
+  to: "2",
+  three: "3",
+  four: "4",
+  for: "4",
+  fore: "4",
+  five: "5",
+  six: "6",
+  seven: "7",
+  eight: "8",
+  ate: "8",
+  nine: "9",
+};
+
+/**
+ * Extract digit characters from a speech transcript. Recognizes both
+ * raw digit characters ("1 2 3") and spoken number words ("one two three").
+ */
+export function parseDigitsFromSpeech(transcript: string): string {
+  const digits: string[] = [];
+  const lower = transcript.toLowerCase();
+
+  // Split on whitespace and non-alphanumeric boundaries
+  const tokens = lower.split(/[\s,.\-;:!?]+/);
+  for (const token of tokens) {
+    if (/^\d$/.test(token)) {
+      digits.push(token);
+    } else if (wordToDigit[token]) {
+      digits.push(wordToDigit[token]);
+    } else if (/^\d+$/.test(token)) {
+      // Multi-digit number like "123456" — split into individual digits
+      digits.push(...token.split(""));
+    }
+  }
+
+  return digits.join("");
+}
+
+// ── Guardian code verification ─────────────────────────────────────────
+
+export interface GuardianVerificationParams {
+  guardianChallengeAssistantId: string;
+  guardianVerificationFromNumber: string;
+  enteredCode: string;
+  isOutbound: boolean;
+  codeDigits: number;
+  verificationAttempts: number;
+  verificationMaxAttempts: number;
+}
+
+export type GuardianVerificationResult =
+  | {
+      outcome: "success";
+      verificationType: "guardian" | "trusted_contact";
+      /** Event name to record */
+      eventName: CallEventType;
+      /** For guardian type: whether a binding conflict was detected */
+      bindingConflict?: {
+        existingGuardian: string;
+      };
+      /** For guardian type when no conflict: the canonical principal to use */
+      canonicalPrincipal?: string;
+      /** For outbound success: the TTS text to play */
+      ttsMessage?: string;
+    }
+  | {
+      outcome: "failure";
+      eventName: CallEventType;
+      ttsMessage: string;
+      attempts: number;
+    }
+  | {
+      outcome: "retry";
+      ttsMessage: string;
+      attempt: number;
+      maxAttempts: number;
+    };
+
+/**
+ * Core logic for validating an entered code against the pending voice
+ * guardian challenge. Returns a structured result describing what happened
+ * so the caller can apply side-effects (state mutations, TTS, session
+ * updates) without this function needing access to the relay connection.
+ */
+export function attemptGuardianCodeVerification(
+  params: GuardianVerificationParams,
+): GuardianVerificationResult {
+  const {
+    guardianChallengeAssistantId,
+    guardianVerificationFromNumber,
+    enteredCode,
+    isOutbound,
+    codeDigits,
+    verificationAttempts,
+    verificationMaxAttempts,
+  } = params;
+
+  const result = validateAndConsumeChallenge(
+    guardianChallengeAssistantId,
+    "voice",
+    enteredCode,
+    guardianVerificationFromNumber,
+    guardianVerificationFromNumber,
+  );
+
+  if (result.success) {
+    const eventName = isOutbound
+      ? "outbound_guardian_voice_verification_succeeded"
+      : "guardian_voice_verification_succeeded";
+
+    // Resolve binding conflict and canonical principal for guardian type
+    let bindingConflict: { existingGuardian: string } | undefined;
+    let canonicalPrincipal: string | undefined;
+
+    if (result.verificationType === "guardian") {
+      const existingBinding = getGuardianBinding(
+        guardianChallengeAssistantId,
+        "voice",
+      );
+      if (
+        existingBinding &&
+        existingBinding.guardianExternalUserId !==
+          guardianVerificationFromNumber
+      ) {
+        bindingConflict = {
+          existingGuardian: existingBinding.guardianExternalUserId,
+        };
+      } else {
+        // Resolve canonical principal from the vellum channel binding
+        const vellumBinding = getGuardianBinding(
+          guardianChallengeAssistantId,
+          "vellum",
+        );
+        canonicalPrincipal =
+          vellumBinding?.guardianPrincipalId ?? guardianVerificationFromNumber;
+      }
+    }
+
+    let ttsMessage: string | undefined;
+    if (isOutbound) {
+      ttsMessage = composeVerificationVoice(
+        GUARDIAN_VERIFY_TEMPLATE_KEYS.VOICE_SUCCESS,
+        { codeDigits },
+      );
+    }
+
+    return {
+      outcome: "success",
+      verificationType: result.verificationType,
+      eventName,
+      bindingConflict,
+      canonicalPrincipal,
+      ttsMessage,
+    };
+  }
+
+  // Failure path
+  const newAttempts = verificationAttempts + 1;
+
+  if (newAttempts >= verificationMaxAttempts) {
+    const failEventName = isOutbound
+      ? "outbound_guardian_voice_verification_failed"
+      : "guardian_voice_verification_failed";
+
+    const failureText = isOutbound
+      ? composeVerificationVoice(GUARDIAN_VERIFY_TEMPLATE_KEYS.VOICE_FAILURE, {
+          codeDigits,
+        })
+      : "Verification failed. Goodbye.";
+
+    return {
+      outcome: "failure",
+      eventName: failEventName,
+      ttsMessage: failureText,
+      attempts: newAttempts,
+    };
+  }
+
+  const retryText = isOutbound
+    ? composeVerificationVoice(GUARDIAN_VERIFY_TEMPLATE_KEYS.VOICE_RETRY, {
+        codeDigits,
+      })
+    : "That code was incorrect. Please try again.";
+
+  return {
+    outcome: "retry",
+    ttsMessage: retryText,
+    attempt: newAttempts,
+    maxAttempts: verificationMaxAttempts,
+  };
+}
+
+// ── Invite code redemption ─────────────────────────────────────────────
+
+export interface InviteRedemptionParams {
+  inviteRedemptionAssistantId: string;
+  inviteRedemptionFromNumber: string;
+  enteredCode: string;
+  inviteRedemptionGuardianName: string | null;
+}
+
+export type InviteRedemptionResult =
+  | {
+      outcome: "success";
+      memberId: string;
+      type: "redeemed" | "already_member";
+      inviteId?: string;
+    }
+  | {
+      outcome: "failure";
+      ttsMessage: string;
+    };
+
+/**
+ * Validate an entered invite code against active voice invites for the
+ * caller. Returns a structured result so the caller can handle state
+ * mutations and session updates.
+ */
+export function attemptInviteCodeRedemption(
+  params: InviteRedemptionParams,
+): InviteRedemptionResult {
+  const {
+    inviteRedemptionAssistantId,
+    inviteRedemptionFromNumber,
+    enteredCode,
+    inviteRedemptionGuardianName,
+  } = params;
+
+  const result = redeemVoiceInviteCode({
+    assistantId: inviteRedemptionAssistantId,
+    callerExternalUserId: inviteRedemptionFromNumber,
+    sourceChannel: "voice",
+    code: enteredCode,
+  });
+
+  if (result.ok) {
+    return {
+      outcome: "success",
+      memberId: result.memberId,
+      type: result.type,
+      ...(result.type === "redeemed" ? { inviteId: result.inviteId } : {}),
+    };
+  }
+
+  const displayGuardian = inviteRedemptionGuardianName ?? "your contact";
+  return {
+    outcome: "failure",
+    ttsMessage: `Sorry, the code you provided is incorrect or has since expired. Please ask ${displayGuardian} for a new code. Goodbye.`,
+  };
+}

package/src/calls/twilio-config.ts

@@ -1,4 +1,4 @@
-import { getTwilioPhoneNumberEnv, getTwilioWssBaseUrl } from "../config/env.js";
+import { getTwilioPhoneNumberEnv } from "../config/env.js";
 import { loadConfig } from "../config/loader.js";
 import {
   getPublicBaseUrl,
@@ -43,14 +43,7 @@ export function getTwilioConfig(assistantId?: string): TwilioConfig {
   const phoneNumber = resolveTwilioPhoneNumber(config, assistantId);
   const webhookBaseUrl = getPublicBaseUrl(config);
 
-  // Always use the centralized relay URL derived from the public ingress base URL.
-  // TWILIO_WSS_BASE_URL is ignored.
   let wssBaseUrl: string;
-  if (getTwilioWssBaseUrl()) {
-    log.warn(
-      "TWILIO_WSS_BASE_URL env var is deprecated. Relay URL is derived from ingress.publicBaseUrl.",
-    );
-  }
   try {
     wssBaseUrl = getTwilioRelayUrl(config);
   } catch {