twilio-agent-connect 1.0.2 → 2.0.0

package/dist/index.js

@@ -28,6 +28,11 @@ var TwilioMemoryConfigSchema = z.object({
   /** Trait field name within `phoneTraitGroup` that holds the phone identifier. */
   phoneTraitField: z.string().default("phone")
 });
+var voicePathSchema = (defaultPath) => z.preprocess((v) => {
+  if (typeof v !== "string") return v;
+  const trimmed = v.trim();
+  return trimmed.length === 0 ? void 0 : trimmed;
+}, z.string().startsWith("/", 'Path must start with "/"').default(defaultPath));
 var TACConfigSchema = z.object({
   accountSid: z.string().min(1, "Twilio Account SID is required"),
   authToken: z.string().min(1, "Twilio Auth Token is required"),
@@ -41,10 +46,48 @@ var TACConfigSchema = z.object({
   whatsappNumber: z.string().regex(/^whatsapp:\+\d+$/, "WhatsApp number must be in format: whatsapp:+1234567890").optional(),
   memoryConfig: TwilioMemoryConfigSchema.prefault({}),
   conversationConfigurationId: z.string().regex(/^conv_configuration_[0-9a-z]{26}$/, "Invalid Conversation Configuration ID format").optional(),
-  voicePublicDomain: z.string().max(253, "Hostname too long (max 253 characters)").regex(
-    /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/,
-    'Invalid hostname format. Must be a hostname without protocol, port, or path (e.g., "abc123.ngrok.app", "localhost", or "192.168.1.100")'
+  /**
+   * Public domain where voice routes are reachable (e.g. "abc123.ngrok.app").
+   * Used by VoiceChannel to construct the public WebSocket URL and
+   * ConversationRelay action URL. Required when using the Voice channel.
+   *
+   * Schemes (https://, wss://), surrounding whitespace, and trailing slashes
+   * are stripped automatically before validation — a naive copy-paste from a
+   * browser address bar like "https://example.ngrok.app/" is normalized to
+   * "example.ngrok.app" rather than rejected.
+   */
+  voicePublicDomain: z.preprocess(
+    (v) => {
+      if (typeof v !== "string") return v;
+      let s = v.trim();
+      if (s.length === 0) return void 0;
+      for (const scheme of ["https://", "http://", "wss://", "ws://"]) {
+        if (s.toLowerCase().startsWith(scheme)) {
+          s = s.slice(scheme.length);
+          break;
+        }
+      }
+      s = s.replace(/\/+$/, "");
+      return s.length === 0 ? void 0 : s;
+    },
+    z.string().max(253, "Hostname too long (max 253 characters)").regex(
+      /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/,
+      'Invalid hostname format. Must be a hostname without protocol, port, or path (e.g., "abc123.ngrok.app", "localhost", or "192.168.1.100")'
+    ).optional()
   ).optional(),
+  /**
+   * Path the voice WebSocket is served at. Combined with voicePublicDomain to
+   * build the public WebSocket URL the voice channel hands to Twilio in TwiML;
+   * TACServer also registers its WebSocket route at this path. Override only if
+   * you mount the route at a non-default path. Must start with '/'.
+   */
+  voiceWebsocketPath: voicePathSchema("/ws"),
+  /**
+   * Path the ConversationRelay action callback is served at. Same role as
+   * voiceWebsocketPath but for the `<Connect action=...>` cleanup callback.
+   * Must start with '/'.
+   */
+  voiceActionPath: voicePathSchema("/conversation-relay-callback"),
   cintelConfigurationId: z.string().optional(),
   cintelObservationOperatorSid: z.string().optional(),
   cintelSummaryOperatorSid: z.string().optional(),
@@ -79,6 +122,8 @@ var EnvironmentVariables = {
   TWILIO_MEMORY_PHONE_TRAIT_FIELD: "TWILIO_MEMORY_PHONE_TRAIT_FIELD",
   TWILIO_CONVERSATION_CONFIGURATION_ID: "TWILIO_CONVERSATION_CONFIGURATION_ID",
   TWILIO_VOICE_PUBLIC_DOMAIN: "TWILIO_VOICE_PUBLIC_DOMAIN",
+  TWILIO_VOICE_WEBSOCKET_PATH: "TWILIO_VOICE_WEBSOCKET_PATH",
+  TWILIO_VOICE_ACTION_PATH: "TWILIO_VOICE_ACTION_PATH",
   TWILIO_TAC_CI_CONFIGURATION_ID: "TWILIO_TAC_CI_CONFIGURATION_ID",
   TWILIO_TAC_CI_OBSERVATION_OPERATOR_SID: "TWILIO_TAC_CI_OBSERVATION_OPERATOR_SID",
   TWILIO_TAC_CI_SUMMARY_OPERATOR_SID: "TWILIO_TAC_CI_SUMMARY_OPERATOR_SID",
@@ -204,7 +249,12 @@ var ConversationSessionSchema = z.object({
    * Pending handoff payload set by the handoff tool. Voice channel sends
    * this as a WS "end" message after the LLM's final response.
    */
-  pendingHandoffData: PendingHandoffDataSchema.optional()
+  pendingHandoffData: PendingHandoffDataSchema.optional(),
+  /**
+   * Cached memory for "once" mode. Set on the first retrieval, cleared when
+   * the conversation becomes INACTIVE. Not persisted/serialized.
+   */
+  cachedMemory: z.custom().optional()
 });
 function isConversationId(value) {
   return value.length > 0;
@@ -486,7 +536,7 @@ var TACMemoryResponse = class {
     return lines.length > 2 ? lines.join("\n") : null;
   }
 };
-var MemoryModeSchema = z.enum(["always", "never"]);
+var MemoryModeSchema = z.enum(["always", "never", "once"]);
 var MessageDirectionSchema = z.enum(["inbound", "outbound"]);
 var MemoryChannelTypeSchema = z.enum([
   "VOICE",
@@ -710,6 +760,240 @@ var ConversationRelayConfigSchema = ConversationRelayAttributesSchema.extend({
   /** Optional language configurations as child <Language> elements */
   languages: z.array(LanguageAttributesSchema).optional()
 });
+var InterruptModeSchema = z.enum(["none", "dtmf", "speech", "any"]);
+var LanguageConfigSchema = z.object({
+  /**
+   * Language code, e.g. 'es-MX'. Can be 'multi' for automatic language
+   * detection (requires ElevenLabs TTS and Deepgram STT).
+   */
+  code: z.string(),
+  /** TTS voice name for this language */
+  voice: z.string().optional(),
+  /** TTS provider, e.g. 'google' */
+  ttsProvider: z.string().optional(),
+  /** Transcription provider, e.g. 'deepgram' */
+  transcriptionProvider: z.string().optional(),
+  /** Speech model for STT. Choices vary by transcriptionProvider. */
+  speechModel: z.string().optional()
+});
+var TwiMLOptionsSchema = z.object({
+  /** Custom parameters to pass to ConversationRelay as `<Parameter>` children */
+  customParameters: CustomParametersSchema.optional(),
+  /** Initial greeting message for the caller */
+  welcomeGreeting: z.string().optional(),
+  /**
+   * What caller input can interrupt the welcome greeting.
+   * Defaults to 'any' on Twilio.
+   */
+  welcomeGreetingInterruptible: InterruptModeSchema.optional(),
+  /**
+   * URL for Twilio to request when the call ends (`<Connect action>`). Set to
+   * a non-empty URL, or leave unset. An explicit `undefined` suppresses the
+   * action entirely (see `VoiceChannel`'s actionUrl resolution); an empty
+   * string is rejected so it can't silently drop the action.
+   */
+  actionUrl: z.string().min(1, "actionUrl must not be empty").optional(),
+  /**
+   * Conversation Service SID. When set, ConversationRelay will manage
+   * conversation creation and participants.
+   */
+  conversationConfiguration: z.string().optional(),
+  /**
+   * ConversationRelay WebSocket URL (the `<ConversationRelay url=...>`
+   * attribute). Leave unset (the default) to use the URL the channel derives
+   * from `TACConfig.voicePublicDomain` + `voiceWebsocketPath`. Set it only for
+   * a per-call URL — e.g. an affinity-routed host that appends a token to the
+   * upgrade URL — typically from an `onInboundCallTwiml` customizer. Layers
+   * per-field like every other field. Must be non-empty when set.
+   */
+  websocketUrl: z.string().min(1, "websocketUrl must not be empty").optional(),
+  // Language, TTS, STT
+  /**
+   * Language for both STT and TTS, e.g. 'en-US'. Equivalent to setting both
+   * ttsLanguage and transcriptionLanguage.
+   */
+  language: z.string().optional(),
+  /** TTS language code; overrides `language` for TTS. */
+  ttsLanguage: z.string().optional(),
+  /**
+   * STT language code; overrides `language` for transcription. Can be
+   * 'multi' for automatic language detection (Deepgram only).
+   */
+  transcriptionLanguage: z.string().optional(),
+  /** TTS voice name (choices vary by ttsProvider) */
+  voice: z.string().optional(),
+  /** TTS provider: 'Google', 'Amazon', or 'ElevenLabs'. Defaults to 'ElevenLabs'. */
+  ttsProvider: z.string().optional(),
+  /**
+   * STT provider: 'Google' or 'Deepgram'. Defaults to 'Deepgram' (or 'Google'
+   * for accounts that used ConversationRelay before 2025-09-12).
+   */
+  transcriptionProvider: z.string().optional(),
+  /** Speech model for STT. Choices vary by transcriptionProvider. */
+  speechModel: z.string().optional(),
+  /**
+   * Text normalization for ElevenLabs TTS. Defaults to 'off'. 'auto' behaves
+   * like 'off' for ConversationRelay calls.
+   */
+  elevenlabsTextNormalization: z.enum(["on", "auto", "off"]).optional(),
+  // Turn detection / interruption
+  /**
+   * Confidence required to finish a turn. Only applies with Deepgram + flux
+   * speech model. Twilio enforces the accepted range — see ConversationRelay docs.
+   */
+  eotThreshold: z.number().optional(),
+  /**
+   * Send unfinalized prompts and eager end-of-turn events (last=false). Only
+   * applies with Deepgram + flux speech model.
+   */
+  partialPrompts: z.boolean().optional(),
+  /**
+   * Use Deepgram Smart Format for transcription output. Defaults to true when
+   * transcriptionProvider='Deepgram'.
+   */
+  deepgramSmartFormat: z.boolean().optional(),
+  /**
+   * Silence (ms) after speech before finalizing the prompt. Integer
+   * milliseconds or the literal 'auto' (the platform default). Twilio enforces
+   * the accepted range — see ConversationRelay docs.
+   */
+  speechTimeout: z.union([z.number().int(), z.literal("auto")]).optional(),
+  /**
+   * What caller input interrupts TTS playback. Boolean accepted for backward
+   * compat: true='any', false='none'. Defaults to 'any'.
+   */
+  interruptible: z.union([InterruptModeSchema, z.boolean()]).optional(),
+  /** How easily caller speech triggers an interrupt. Defaults to 'high'. */
+  interruptSensitivity: z.enum(["high", "medium", "low"]).optional(),
+  /**
+   * What caller input gets reported while the agent is speaking (independent
+   * of whether playback is interrupted). Defaults to 'none' since May 2025.
+   */
+  reportInputDuringAgentSpeech: InterruptModeSchema.optional(),
+  /**
+   * Filter short conversational feedback ('yeah', 'uh-huh', …) so it doesn't
+   * interrupt the agent. Defaults to false.
+   */
+  ignoreBackchannel: z.boolean().optional(),
+  /**
+   * Allow text tokens from the next talk cycle to interrupt the current one.
+   * Defaults to false.
+   */
+  preemptible: z.boolean().optional(),
+  /** Emit DTMF keypress events over the WebSocket. */
+  dtmfDetection: z.boolean().optional(),
+  // Recognition hints / events / debug / intelligence
+  /**
+   * Comma-separated words/phrases likely to appear in speech. Capitalize
+   * proper nouns.
+   */
+  hints: z.string().optional(),
+  /** Space-separated event subscriptions, e.g. 'speaker-events tokens-played'. */
+  events: z.string().optional(),
+  /**
+   * Debug subscription, e.g. 'debugging'. Note: 'speaker-events' and
+   * 'tokens-played' have moved to the `events` attribute — only use them here
+   * for backward compatibility.
+   */
+  debug: z.string().optional(),
+  /**
+   * Conversation Intelligence (classic) Service SID or unique name for
+   * persisting transcripts and running Language Operators.
+   */
+  intelligenceService: z.string().optional(),
+  // Nested <Language> children
+  /** Additional `<Language>` children for multi-language support */
+  languages: z.array(LanguageConfigSchema).optional(),
+  /**
+   * Escape hatch for ConversationRelay attributes not yet typed on this model.
+   * Keys are emitted as-is on `<ConversationRelay>`; Twilio's SDK converts
+   * snake_case to camelCase, lowercases bools to 'true'/'false', and
+   * stringifies numbers. Prefer a typed field when one exists — use `extra`
+   * only for newly-added Twilio attributes not yet in this SDK.
+   */
+  extra: z.record(z.string(), z.union([z.string(), z.boolean(), z.number()])).optional()
+}).strict().superRefine((value, ctx) => {
+  if (!value.extra) return;
+  const typed = new Set(Object.keys(TwiMLOptionsShape).filter((k) => k !== "extra"));
+  const shadowed = Object.keys(value.extra).filter((k) => typed.has(k)).sort();
+  if (shadowed.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["extra"],
+      message: `TwiMLOptions.extra keys [${shadowed.join(", ")}] shadow typed fields. Set the typed field directly instead of using \`extra\`.`
+    });
+  }
+});
+var TwiMLOptionsShape = {
+  customParameters: true,
+  welcomeGreeting: true,
+  welcomeGreetingInterruptible: true,
+  actionUrl: true,
+  conversationConfiguration: true,
+  websocketUrl: true,
+  language: true,
+  ttsLanguage: true,
+  transcriptionLanguage: true,
+  voice: true,
+  ttsProvider: true,
+  transcriptionProvider: true,
+  speechModel: true,
+  elevenlabsTextNormalization: true,
+  eotThreshold: true,
+  partialPrompts: true,
+  deepgramSmartFormat: true,
+  speechTimeout: true,
+  interruptible: true,
+  interruptSensitivity: true,
+  reportInputDuringAgentSpeech: true,
+  ignoreBackchannel: true,
+  preemptible: true,
+  dtmfDetection: true,
+  hints: true,
+  events: true,
+  debug: true,
+  intelligenceService: true,
+  languages: true,
+  extra: true
+};
+var TwiMLRequestSchema = z.object({
+  from: z.string().optional(),
+  to: z.string().optional(),
+  callSid: z.string().optional(),
+  callerCountry: z.string().optional(),
+  callerState: z.string().optional(),
+  callerCity: z.string().optional(),
+  direction: z.string().optional(),
+  /**
+   * Any other fields from the Twilio webhook not captured above. Values are
+   * always strings here (webhook form fields are url-encoded), unlike
+   * TwiMLOptions.extra which accepts string | boolean | number for emitted
+   * TwiML attributes.
+   */
+  extra: z.record(z.string(), z.string()).default({})
+});
+var TWIML_REQUEST_FORM_ALIASES = {
+  From: "from",
+  To: "to",
+  CallSid: "callSid",
+  CallerCountry: "callerCountry",
+  CallerState: "callerState",
+  CallerCity: "callerCity",
+  Direction: "direction"
+};
+function twiMLRequestFromForm(form) {
+  const known = {};
+  const extra = {};
+  for (const [key, value] of Object.entries(form)) {
+    const alias = TWIML_REQUEST_FORM_ALIASES[key];
+    if (alias) {
+      known[alias] = value;
+    } else {
+      extra[key] = value;
+    }
+  }
+  return TwiMLRequestSchema.parse({ ...known, extra });
+}
 var ConversationRelayCallbackPayloadSchema = z.object({
   // Core Twilio identifiers (required)
   AccountSid: z.string(),
@@ -744,9 +1028,9 @@ var ConversationRelayCallbackPayloadSchema = z.object({
 });
 var InitiateVoiceConversationOptionsSchema = z.object({
   to: z.string().min(1, "Recipient phone number is required"),
-  conversationRelayConfig: ConversationRelayConfigSchema,
-  actionUrl: z.url().optional()
-});
+  websocketUrl: z.url().optional(),
+  twimlOptions: TwiMLOptionsSchema.optional()
+}).strict();
 var JSONSchemaSchema = z.object({
   type: z.enum(["object", "string", "number", "boolean", "array"]),
   properties: z.record(z.string(), z.any()).optional(),
@@ -864,6 +1148,10 @@ var TACConfig = class _TACConfig {
   memoryConfig;
   conversationConfigurationId;
   voicePublicDomain;
+  /** Path the voice WebSocket is served at (default '/ws'). */
+  voiceWebsocketPath;
+  /** Path the ConversationRelay action callback is served at (default '/conversation-relay-callback'). */
+  voiceActionPath;
   cintelConfigurationId;
   cintelObservationOperatorSid;
   cintelSummaryOperatorSid;
@@ -897,6 +1185,8 @@ var TACConfig = class _TACConfig {
     if (validatedConfig.voicePublicDomain) {
       this.voicePublicDomain = validatedConfig.voicePublicDomain;
     }
+    this.voiceWebsocketPath = validatedConfig.voiceWebsocketPath;
+    this.voiceActionPath = validatedConfig.voiceActionPath;
     if (validatedConfig.cintelConfigurationId) {
       this.cintelConfigurationId = validatedConfig.cintelConfigurationId;
     }
@@ -926,7 +1216,9 @@ var TACConfig = class _TACConfig {
    * Optional environment variables:
    * - TWILIO_WHATSAPP_NUMBER: WhatsApp number for WhatsApp channel (e.g., 'whatsapp:+1234567890')
    * - TWILIO_CONVERSATION_CONFIGURATION_ID: Conversation Orchestrator configuration ID (enables orchestrated mode)
-   * - TWILIO_VOICE_PUBLIC_DOMAIN: Public domain for voice WebSocket connections (domain only, without protocol/port/path, e.g., 'abc123.ngrok.app')
+   * - TWILIO_VOICE_PUBLIC_DOMAIN: Public domain for voice routes (required for voice; domain only, without protocol/port/path, e.g., 'abc123.ngrok.app')
+   * - TWILIO_VOICE_WEBSOCKET_PATH: Path for the voice WebSocket (default: /ws)
+   * - TWILIO_VOICE_ACTION_PATH: Path for the ConversationRelay action callback (default: /conversation-relay-callback)
    * - TWILIO_REGION: Twilio region subdomain for API routing (e.g. transforms base URLs to `https://{product}.{region}.twilio.com`)
    * - TWILIO_STUDIO_HANDOFF_FLOW_SID: Studio Flow SID used by createStudioHandoffTool for human handoff
    * - TWILIO_RCS_SENDER_ID: RCS Sender ID for the RCS channel
@@ -1036,6 +1328,8 @@ var TACConfig = class _TACConfig {
       },
       conversationConfigurationId: process.env[EnvironmentVariables.TWILIO_CONVERSATION_CONFIGURATION_ID] || void 0,
       voicePublicDomain: process.env[EnvironmentVariables.TWILIO_VOICE_PUBLIC_DOMAIN],
+      voiceWebsocketPath: process.env[EnvironmentVariables.TWILIO_VOICE_WEBSOCKET_PATH] || void 0,
+      voiceActionPath: process.env[EnvironmentVariables.TWILIO_VOICE_ACTION_PATH] || void 0,
       cintelConfigurationId: process.env[EnvironmentVariables.TWILIO_TAC_CI_CONFIGURATION_ID],
       cintelObservationOperatorSid: process.env[EnvironmentVariables.TWILIO_TAC_CI_OBSERVATION_OPERATOR_SID],
       cintelSummaryOperatorSid: process.env[EnvironmentVariables.TWILIO_TAC_CI_SUMMARY_OPERATOR_SID],
@@ -1150,7 +1444,7 @@ function createLogger(options) {
 
 // package.json
 var package_default = {
-  version: "1.0.2"};
+  version: "2.0.0"};
 function buildUserAgent() {
   return `twilio-agent-connect-typescript/${package_default.version}`;
 }
@@ -2643,6 +2937,8 @@ var BaseChannel = class {
   activeConversations;
   callbacks;
   memoryMode;
+  processedWebhookTokens;
+  maxTrackedTokens;
   constructor(tac, options) {
     this.tac = tac;
     this.config = tac.getConfig();
@@ -2654,9 +2950,17 @@ var BaseChannel = class {
     const modeToValidate = providedMode === void 0 ? "never" : providedMode;
     const parseResult = MemoryModeSchema.safeParse(modeToValidate);
     if (!parseResult.success) {
-      throw new Error(`Invalid memoryMode: "${modeToValidate}". Must be "always" or "never".`);
+      throw new Error(
+        `Invalid memoryMode: "${modeToValidate}". Must be "always", "once", or "never".`
+      );
     }
     this.memoryMode = parseResult.data;
+    const capacity = options?.dedupCapacity ?? 1e4;
+    if (capacity < 1 || !Number.isInteger(capacity)) {
+      throw new Error("dedupCapacity must be a positive integer");
+    }
+    this.maxTrackedTokens = capacity;
+    this.processedWebhookTokens = /* @__PURE__ */ new Set();
   }
   /**
    * Register event callbacks
@@ -2774,6 +3078,55 @@ var BaseChannel = class {
       }
     }
   }
+  /**
+   * Check if a webhook has already been processed using Twilio's idempotency token.
+   * Uses a sliding window with fixed capacity to track tokens (FIFO eviction).
+   *
+   * This is intentionally a single synchronous check-and-record to prevent race conditions
+   * where a duplicate arrives while the first request is still awaiting async work.
+   */
+  isDuplicateWebhook(idempotencyToken) {
+    if (this.processedWebhookTokens.has(idempotencyToken)) {
+      return true;
+    }
+    if (this.processedWebhookTokens.size >= this.maxTrackedTokens) {
+      const oldest = this.processedWebhookTokens.values().next().value;
+      this.processedWebhookTokens.delete(oldest);
+    }
+    this.processedWebhookTokens.add(idempotencyToken);
+    return false;
+  }
+  /**
+   * Remove an idempotency token from the deduplication cache.
+   * Used when webhook processing fails and retries should not be blocked.
+   */
+  removeWebhookToken(idempotencyToken) {
+    this.processedWebhookTokens.delete(idempotencyToken);
+  }
+  /**
+   * Self-filtering: check if webhook event belongs to this channel.
+   *
+   * - COMMUNICATION_CREATED: require author.channel matches this channel type
+   * - CONVERSATION_UPDATED: only process if conversation is tracked locally
+   * - Other events: pass through
+   */
+  isEventForThisChannel(webhookData) {
+    const eventType = webhookData.eventType;
+    const authorChannel = webhookData.data?.author?.channel;
+    if (eventType === "COMMUNICATION_CREATED") {
+      if (!authorChannel) {
+        return false;
+      }
+      return authorChannel === this.channelType.toUpperCase();
+    }
+    if (eventType === "CONVERSATION_UPDATED") {
+      const conversationId = this.extractConversationId(webhookData);
+      if (conversationId && !this.activeConversations.has(conversationId)) {
+        return false;
+      }
+    }
+    return true;
+  }
   /**
    * Validate webhook payload (override in subclasses for specific validation)
    */
@@ -2781,21 +3134,109 @@ var BaseChannel = class {
     return payload !== null && payload !== void 0;
   }
   /**
-   * Retrieve memory only when memoryMode === 'always'.
+   * Preprocess webhook before handling event-specific logic.
+   * Handles deduplication, validation, filtering, and data extraction.
+   *
+   * @param payload - Raw webhook payload from Twilio
+   * @param idempotencyToken - Optional idempotency token for deduplication
+   * @returns Preprocessed webhook data, or null if webhook should be skipped
+   */
+  preprocessWebhook(payload, idempotencyToken) {
+    this.logger.debug({ operation: "webhook_processing" }, "Processing webhook");
+    if (idempotencyToken && this.isDuplicateWebhook(idempotencyToken)) {
+      this.logger.debug({ idempotency_token: idempotencyToken }, "Skipping duplicate webhook");
+      return null;
+    }
+    if (!this.validateWebhookPayload(payload)) {
+      throw new Error("Invalid webhook payload");
+    }
+    const webhookData = payload;
+    const eventType = webhookData.eventType;
+    const conversationId = webhookData.data?.conversationId || webhookData.data?.id;
+    if (!this.isEventForThisChannel(webhookData)) {
+      this.logger.debug(
+        { event_type: eventType, channel: this.channelType, conversation_id: conversationId },
+        "Ignoring event for different channel type"
+      );
+      return null;
+    }
+    return { webhookData, eventType, conversationId };
+  }
+  /**
+   * Extract conversation ID from webhook payload with type validation.
+   *
+   * Extracts conversationId from webhookData.data?.conversationId || webhookData.data?.id,
+   * validates the value is a non-empty string, and ensures it passes isConversationId check.
+   *
+   * This prevents invalid IDs from causing downstream issues like incorrect Map key
+   * matching in CONVERSATION_UPDATED self-filtering or propagating malformed IDs.
+   */
+  extractConversationId(payload) {
+    if (!payload || typeof payload !== "object") {
+      return null;
+    }
+    const webhookData = payload;
+    const conversationId = webhookData.data?.conversationId || webhookData.data?.id;
+    if (conversationId && typeof conversationId === "string" && isConversationId(conversationId)) {
+      return conversationId;
+    }
+    return null;
+  }
+  /**
+   * Extract profile ID from webhook payload with type validation.
+   *
+   * Extracts profileId from webhookData.data?.profileId,
+   * validates the value is a non-empty string, and ensures it passes isProfileId check.
+   *
+   * This prevents invalid IDs from propagating downstream and ensures consistent
+   * validation across all channel types.
+   */
+  extractProfileId(payload) {
+    if (!payload || typeof payload !== "object") {
+      return null;
+    }
+    const webhookData = payload;
+    const profileId = webhookData.data?.profileId;
+    if (profileId && typeof profileId === "string" && isProfileId(profileId)) {
+      return profileId;
+    }
+    return null;
+  }
+  /**
+   * Retrieve memory according to the channel's memoryMode.
    *
    * This method handles the common logic for memory retrieval across all channels,
-   * including error handling and debug logging. If memoryMode is 'never',
-   * automatic memory retrieval is skipped.
+   * including error handling and debug logging.
+   *
+   * Modes:
+   * - "always": Fetch with the provided query on every message.
+   * - "once": Fetch once with an empty query and cache the result on the
+   *   session. Subsequent calls reuse the cache until it is invalidated on the
+   *   INACTIVE transition.
+   * - "never": Skip retrieval.
+   *
+   * Memory retrieval failures are logged and swallowed so message processing
+   * continues without memory context.
    */
   async retrieveMemoryIfEnabled(session, query) {
-    if (this.memoryMode !== "always") {
+    if (this.memoryMode !== "always" && this.memoryMode !== "once") {
       return void 0;
     }
+    if (this.memoryMode === "once" && session.cachedMemory !== void 0) {
+      this.logger.debug({ conversation_id: session.conversationId }, "Reusing cached memory");
+      return session.cachedMemory;
+    }
     try {
-      const memory = await this.tac.retrieveMemory(session, query);
+      const memory = await this.tac.retrieveMemory(
+        session,
+        this.memoryMode === "always" ? query : void 0
+      );
+      if (this.memoryMode === "once") {
+        session.cachedMemory = memory;
+      }
       this.logger.debug(
-        { conversation_id: session.conversationId },
-        "Memory retrieved successfully"
+        { conversation_id: session.conversationId, memory_mode: this.memoryMode },
+        "Memory retrieved"
       );
       return memory;
     } catch (error) {
@@ -2806,6 +3247,25 @@ var BaseChannel = class {
       return void 0;
     }
   }
+  /**
+   * Invalidate cached memory for "once" mode when a conversation becomes
+   * INACTIVE. Conversation Orchestrator updates memory on the INACTIVE
+   * transition, so the next message re-fetches fresh memory. No-op for other
+   * memory modes.
+   */
+  invalidateCachedMemory(conversationId) {
+    if (this.memoryMode !== "once") {
+      return;
+    }
+    const session = this.activeConversations.get(conversationId);
+    if (session?.cachedMemory !== void 0) {
+      session.cachedMemory = void 0;
+      this.logger.debug(
+        { conversation_id: conversationId },
+        "Invalidated cached memory on INACTIVE status"
+      );
+    }
+  }
   /**
    * Cleanup resources when shutting down
    */
@@ -2823,12 +3283,9 @@ var CHANNEL_IDENTITY_TYPES = {
   RCS: "rcs",
   WHATSAPP: "whatsapp"
 };
-var DEFAULT_DEDUP_CAPACITY = 1e4;
 var MessagingChannel = class extends BaseChannel {
   conversationClient;
   messagingCallbacks;
-  processedTokens = /* @__PURE__ */ new Set();
-  maxTrackedTokens;
   /**
    * Controls whether reconciliation promotes an UNKNOWN customer-side
    * participant to CUSTOMER. Subclasses override to opt out (e.g. chat).
@@ -2843,28 +3300,6 @@ var MessagingChannel = class extends BaseChannel {
     }
     this.conversationClient = tac.getConversationClient();
     this.messagingCallbacks = {};
-    const capacity = config?.dedupCapacity ?? DEFAULT_DEDUP_CAPACITY;
-    if (capacity < 1 || !Number.isInteger(capacity)) {
-      throw new Error("dedupCapacity must be a positive integer");
-    }
-    this.maxTrackedTokens = capacity;
-  }
-  /**
-   * Check if a webhook has already been processed, and if not, record the token immediately.
-   * This is intentionally a single synchronous check-and-record to prevent race conditions
-   * where a duplicate arrives while the first request is still awaiting async work.
-   * Uses a sliding window with FIFO eviction at capacity.
-   */
-  isDuplicateWebhook(idempotencyToken) {
-    if (this.processedTokens.has(idempotencyToken)) {
-      return true;
-    }
-    if (this.processedTokens.size >= this.maxTrackedTokens) {
-      const oldest = this.processedTokens.values().next().value;
-      this.processedTokens.delete(oldest);
-    }
-    this.processedTokens.add(idempotencyToken);
-    return false;
   }
   /**
    * Check if a message is from the bot itself (2-tier).
@@ -2910,57 +3345,15 @@ var MessagingChannel = class extends BaseChannel {
     }
   }
   /**
-   * Check if this webhook event belongs to this channel.
-   * Returns false if the event is clearly for a different channel type.
-   */
-  isEventForThisChannel(webhookData) {
-    const eventType = webhookData.eventType;
-    const authorChannel = webhookData.data?.author?.channel;
-    if (eventType === "COMMUNICATION_CREATED") {
-      if (!authorChannel) {
-        return false;
-      }
-      return authorChannel === this.channelType.toUpperCase();
-    }
-    if (eventType === "CONVERSATION_UPDATED") {
-      const conversationId = this.extractConversationId(webhookData);
-      if (conversationId && !this.isConversationActive(conversationId)) {
-        return false;
-      }
-    }
-    return true;
-  }
-  /**
-   * Process messaging channel webhook from Twilio Conversations Service
+   * Process messaging channel webhook from Conversation Orchestrator
    */
   async processWebhook(payload, idempotencyToken) {
-    this.logger.debug({ operation: "webhook_processing" }, "Processing webhook");
     try {
-      if (idempotencyToken && this.isDuplicateWebhook(idempotencyToken)) {
-        this.logger.debug({ idempotency_token: idempotencyToken }, "Skipping duplicate webhook");
-        return;
-      }
-      if (!this.validateWebhookPayload(payload)) {
-        throw new Error("Invalid webhook payload");
-      }
-      const webhookData = payload;
-      const eventType = webhookData.eventType;
-      const conversationId = webhookData.data?.conversationId || webhookData.data?.id;
-      if (!this.isEventForThisChannel(webhookData)) {
-        this.logger.debug(
-          { event_type: eventType, channel: this.channelType, conversation_id: conversationId },
-          "Ignoring event for different channel type"
-        );
+      const result = this.preprocessWebhook(payload, idempotencyToken);
+      if (!result) {
         return;
       }
-      this.logger.info(
-        {
-          event_type: eventType,
-          raw_event_type: webhookData.eventType,
-          conversation_id: conversationId
-        },
-        "Processing webhook event"
-      );
+      const { webhookData, eventType, conversationId } = result;
       switch (eventType) {
         case "CONVERSATION_CREATED":
           this.logger.debug(
@@ -2993,12 +3386,8 @@ var MessagingChannel = class extends BaseChannel {
       this.logger.debug({ event_type: eventType }, "Webhook processing completed");
     } catch (error) {
       if (idempotencyToken) {
-        this.processedTokens.delete(idempotencyToken);
+        this.removeWebhookToken(idempotencyToken);
       }
-      this.logger.error(
-        { err: error, operation: "webhook_processing" },
-        "Webhook processing error"
-      );
       this.handleError(error instanceof Error ? error : new Error(String(error)), { payload });
     }
   }
@@ -3150,43 +3539,15 @@ var MessagingChannel = class extends BaseChannel {
       throw new Error("Missing conversation ID in conversation.updated event");
     }
     if (payload.data?.status === "CLOSED") {
-      this.logger.info(
+      this.logger.debug(
         { conversation_id: conversationId, status: payload.data.status },
         "Conversation closed, cleaning up"
       );
       await this.endConversation(conversationId);
+    } else if (payload.data?.status === "INACTIVE") {
+      this.invalidateCachedMemory(conversationId);
     }
   }
-  /**
-   * Extract conversation ID from webhook payload
-   */
-  extractConversationId(payload) {
-    const webhookData = payload;
-    const conversationId = webhookData.data?.conversationId || webhookData.data?.id;
-    if (conversationId && isConversationId(conversationId)) {
-      return conversationId;
-    }
-    return null;
-  }
-  /**
-   * Extract profile ID from webhook payload
-   */
-  extractProfileId(payload) {
-    const webhookData = payload;
-    const profileId = webhookData.data?.profileId;
-    if (profileId && isProfileId(profileId)) {
-      this.logger.debug(
-        { profile_id: profileId, conversation_id: webhookData.data?.conversationId },
-        "Extracted profile ID from webhook payload"
-      );
-      return profileId;
-    }
-    this.logger.debug(
-      { conversation_id: webhookData.data?.conversationId },
-      "Profile ID missing or invalid in webhook payload"
-    );
-    return null;
-  }
   /**
    * Validate messaging channel webhook payload structure
    */
@@ -4057,7 +4418,24 @@ var ChatChannel = class extends MessagingChannel {
     });
   }
 };
-var VoiceChannel = class extends BaseChannel {
+
+// packages/core/src/util/handoff-urls.ts
+function studioExecutionsUrl(flowSid) {
+  return `https://studio.twilio.com/v2/Flows/${flowSid}/Executions`;
+}
+function studioVoiceHandoffUrl(accountSid, flowSid) {
+  return `https://webhooks.twilio.com/v1/Accounts/${accountSid}/Flows/${flowSid}?Trigger=incomingCall`;
+}
+
+// packages/core/src/channels/voice.ts
+var DEFAULT_WELCOME_GREETING = "Hello! How can I assist you today?";
+function stringifyParameterValue(value) {
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+var VoiceChannel = class _VoiceChannel extends BaseChannel {
   webSocketConnections;
   voiceCallbacks;
   streamTasks;
@@ -4066,8 +4444,11 @@ var VoiceChannel = class extends BaseChannel {
   callSidToConversationId;
   MAX_INITIALIZATION_RETRIES = 3;
   twilioClient;
+  voiceConfig;
+  onInboundCallTwimlHandler;
   constructor(tac, options) {
     super(tac, options);
+    this.voiceConfig = options ?? {};
     this.webSocketConnections = /* @__PURE__ */ new Map();
     this.voiceCallbacks = {};
     this.streamTasks = /* @__PURE__ */ new Map();
@@ -4075,6 +4456,56 @@ var VoiceChannel = class extends BaseChannel {
     this.initializationRetries = /* @__PURE__ */ new Map();
     this.callSidToConversationId = /* @__PURE__ */ new Map();
   }
+  /**
+   * Register a callback that produces per-call overrides for the TwiML inside
+   * `<ConversationRelay>` on inbound calls.
+   *
+   * The callback receives a framework-neutral {@link TwiMLRequest} (parsed from
+   * the Twilio webhook form) and returns {@link TwiMLOptions}. Fields the
+   * callback explicitly sets override `defaultTwimlOptions` and TAC defaults;
+   * unset fields fall through.
+   *
+   * @example
+   * ```typescript
+   * voiceChannel.onInboundCallTwiml(async req => {
+   *   if (req.callerCountry === 'MX') {
+   *     return { language: 'es-MX', welcomeGreeting: '¡Hola!' };
+   *   }
+   *   return {};
+   * });
+   * ```
+   *
+   * Outbound calls don't use this — pass per-call TwiML via
+   * `InitiateVoiceConversationOptions.twimlOptions` directly.
+   */
+  onInboundCallTwiml(callback) {
+    this.onInboundCallTwimlHandler = callback;
+  }
+  /**
+   * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
+   * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
+   */
+  resolveWebsocketUrl(action) {
+    if (this.config.voicePublicDomain) {
+      return `wss://${this.config.voicePublicDomain}${this.config.voiceWebsocketPath}`;
+    }
+    throw new Error(
+      `${action} needs a WebSocket URL. Set TWILIO_VOICE_PUBLIC_DOMAIN (or TACConfig.voicePublicDomain).`
+    );
+  }
+  /**
+   * Resolve the default `<Connect action=...>` cleanup URL.
+   *
+   * Returns undefined if `voicePublicDomain` isn't set; that's fine because
+   * actionUrl has higher-priority layers (customizer, twimlOptions, Studio
+   * handoff) above this fallback.
+   */
+  resolveDefaultActionUrl() {
+    if (this.config.voicePublicDomain) {
+      return `https://${this.config.voicePublicDomain}${this.config.voiceActionPath}`;
+    }
+    return void 0;
+  }
   getTwilioClient() {
     if (!this.twilioClient) {
       this.twilioClient = twilio(this.config.apiKey, this.config.apiSecret, {
@@ -4113,12 +4544,67 @@ var VoiceChannel = class extends BaseChannel {
     }
   }
   /**
-   * Process webhook - Voice channel doesn't use traditional webhooks,
-   * but this method is required by the base class
+   * Process conversation webhooks for cleanup.
+   *
+   * Voice channel processes CONVERSATION_UPDATED events:
+   * - CLOSED status: Clean up local session state
+   *
+   * Note: Conversation tracking uses instance-local memory. In multi-instance
+   * deployments, webhooks may route to a different instance, preventing cleanup.
+   *
+   * @param payload - Raw webhook event data from Twilio
+   * @param idempotencyToken - Optional Twilio idempotency token from request headers
    */
-  processWebhook(_payload) {
-    this.logger.warn("processWebhook called but Voice channel uses WebSocket connections");
-    return Promise.resolve();
+  async processWebhook(payload, idempotencyToken) {
+    try {
+      const result = this.preprocessWebhook(payload, idempotencyToken);
+      if (!result) {
+        return;
+      }
+      const { webhookData, eventType, conversationId } = result;
+      switch (eventType) {
+        case "CONVERSATION_UPDATED":
+          this.logger.debug(
+            { conversation_id: conversationId, status: webhookData.data?.status },
+            "Handling CONVERSATION_UPDATED"
+          );
+          await this.handleConversationUpdated(webhookData);
+          break;
+        default:
+          this.logger.debug(
+            {
+              event_type: eventType,
+              raw_event_type: webhookData.eventType,
+              conversation_id: conversationId
+            },
+            "Unhandled event type - this event will be ignored"
+          );
+      }
+      this.logger.debug({ event_type: eventType }, "Webhook processing completed");
+    } catch (error) {
+      if (idempotencyToken) {
+        this.removeWebhookToken(idempotencyToken);
+      }
+      this.handleError(error instanceof Error ? error : new Error(String(error)), { payload });
+    }
+  }
+  /**
+   * Handle conversation updated event
+   */
+  async handleConversationUpdated(payload) {
+    const conversationId = this.extractConversationId(payload);
+    if (!conversationId) {
+      throw new Error("Missing conversation ID in conversation.updated event");
+    }
+    if (payload.data?.status === "CLOSED") {
+      this.logger.debug(
+        { conversation_id: conversationId, status: payload.data.status },
+        "Conversation closed, cleaning up"
+      );
+      await this.endConversation(conversationId);
+    } else if (payload.data?.status === "INACTIVE") {
+      this.invalidateCachedMemory(conversationId);
+    }
   }
   /**
    * Get active WebSocket connection for a conversation
@@ -4358,7 +4844,9 @@ var VoiceChannel = class extends BaseChannel {
     }
   }
   /**
-   * Handle WebSocket disconnection
+   * Handle WebSocket disconnection. In orchestrated mode the conversation stays
+   * tracked until the CLOSED webhook (so a follow-up call can reuse it); in
+   * voice-only mode there is no such webhook, so it ends here.
    */
   async handleWebSocketDisconnect(conversationId) {
     this.cancelStreamTask(conversationId);
@@ -4367,7 +4855,9 @@ var VoiceChannel = class extends BaseChannel {
     if (this.voiceCallbacks.onWebSocketDisconnected) {
       this.voiceCallbacks.onWebSocketDisconnected({ conversationId });
     }
-    await this.endConversation(conversationId);
+    if (!this.tac.isOrchestratorEnabled()) {
+      await this.endConversation(conversationId);
+    }
   }
   /**
    * Send voice response via WebSocket
@@ -4472,24 +4962,134 @@ var VoiceChannel = class extends BaseChannel {
   // Incoming Call Handling
   // =========================================================================
   /**
-   * Handle incoming voice call - generate TwiML to connect to ConversationRelay
+   * Generate the TwiML response for an incoming voice call.
+   *
+   * ConversationRelay automatically handles conversation creation and
+   * participant management via the `conversationConfiguration` parameter.
+   *
+   * The WebSocket URL and default session-cleanup action URL are derived from
+   * `TACConfig.voicePublicDomain` + `TACConfig.voiceWebsocketPath` /
+   * `voiceActionPath`.
+   *
+   * TwiML fields are merged per-field, highest precedence first:
+   *   1. Output of the customizer registered via
+   *      `VoiceChannel.onInboundCallTwiml(...)` if configured and `twimlRequest`
+   *      is given. (Application-owned.)
+   *   2. `VoiceChannelConfig.defaultTwimlOptions` — per-channel defaults.
+   *   3. `hostTwimlOptions` — per-call transport facts supplied by the host (the
+   *      code owning the route), e.g. a per-call `websocketUrl` with an affinity
+   *      token.
+   *   4. TAC defaults: a fixed default welcomeGreeting, `conversationConfiguration`
+   *      from `TACConfig`, `actionUrl` resolved via Studio handoff (when
+   *      `studioHandoffFlowSid` is configured), else derived from
+   *      `TACConfig.voicePublicDomain` + `voiceActionPath`, and the `websocketUrl`
+   *      derived from `TACConfig.voicePublicDomain` + `voiceWebsocketPath`.
    *
-   * ConversationRelay will create the conversation automatically. The conversation
-   * will be initialized on the first prompt using the callSid.
+   * Fields not set at a layer fall through to lower layers. Arrays (`languages`)
+   * and nested objects (`customParameters`) replace wholesale when set at a
+   * higher-priority layer. `websocketUrl` falls back to the `TACConfig`-derived
+   * URL if unset at every layer.
    *
-   * @param options - Options for handling the incoming call
-   * @returns TwiML XML string with ConversationRelay configuration
+   * @param twimlRequest - Parsed Twilio webhook fields. Passed to the customizer
+   *   if one is configured on the channel.
+   * @param options - Additional per-call inputs.
+   * @param options.hostTwimlOptions - Per-call TwiML supplied by a custom
+   *   in-process host (e.g. an affinity-routed deployment injecting a per-call
+   *   `websocketUrl`), layered below `defaultTwimlOptions` and the application
+   *   customizer but above the TAC defaults.
+   * @returns TwiML XML string for call connection.
    */
-  handleIncomingCall(options) {
-    const { actionUrl, conversationRelayConfig } = options;
-    const conversationConfiguration = this.tac.isOrchestratorEnabled() ? conversationRelayConfig.conversationConfiguration ?? this.config.conversationConfigurationId : void 0;
-    return this.connectConversationRelay(
-      {
-        ...conversationRelayConfig,
-        ...conversationConfiguration !== void 0 && { conversationConfiguration }
-      },
-      actionUrl ? { actionUrl } : void 0
-    );
+  async handleIncomingCall(twimlRequest, options) {
+    let customized;
+    if (this.onInboundCallTwimlHandler && twimlRequest) {
+      customized = await this.onInboundCallTwimlHandler(twimlRequest);
+    }
+    const merged = this.buildTwimlOptions(options?.hostTwimlOptions, customized);
+    const websocketUrl = merged.websocketUrl ?? this.resolveWebsocketUrl("handleIncomingCall");
+    return this.generateTwiml(websocketUrl, merged);
+  }
+  /**
+   * Layer TwiML options, lowest precedence first: TAC defaults → `host`
+   * (calling host's per-call values) → channel `defaultTwimlOptions` → `perCall`
+   * (application customizer output for inbound, or
+   * `InitiateVoiceConversationOptions.twimlOptions` for outbound).
+   */
+  buildTwimlOptions(host, perCall) {
+    const merged = {
+      welcomeGreeting: DEFAULT_WELCOME_GREETING,
+      ...this.tac.isOrchestratorEnabled() && this.config.conversationConfigurationId !== void 0 ? { conversationConfiguration: this.config.conversationConfigurationId } : {}
+    };
+    const resolvedActionUrl = this.resolveActionUrl(host, perCall);
+    if (resolvedActionUrl !== void 0) {
+      merged.actionUrl = resolvedActionUrl;
+    }
+    if (host) {
+      this.overlayFields(merged, host);
+    }
+    if (this.voiceConfig.defaultTwimlOptions) {
+      this.overlayFields(merged, this.voiceConfig.defaultTwimlOptions);
+    }
+    if (perCall) {
+      this.overlayFields(merged, perCall);
+    }
+    return merged;
+  }
+  /**
+   * Apply fields explicitly present on `source` onto `target`.
+   *
+   * Nested objects (`customParameters`), arrays (`languages`), and dicts
+   * (`extra`) replace wholesale — there's no per-key merging.
+   *
+   * `actionUrl` is skipped here on purpose — it's resolved once via
+   * `resolveActionUrl` looking at every layer at once, and that resolved value
+   * is written into `target` before this overlay runs. Letting it through here
+   * would let a higher-priority layer that didn't set actionUrl silently clobber
+   * a lower layer that did.
+   *
+   * "Explicitly present" is detected via key presence (`key in source`), which
+   * mirrors Python's `model_fields_set`: a key set to `undefined` is still
+   * "present" and overrides lower layers, while an absent key falls through.
+   */
+  overlayFields(target, source) {
+    for (const key of Object.keys(source)) {
+      if (key === "actionUrl") {
+        continue;
+      }
+      target[key] = source[key];
+    }
+  }
+  /**
+   * Resolve the TwiML `<Connect action=...>` URL.
+   *
+   * Precedence (highest to lowest):
+   *   1. application customizer
+   *   2. channel `defaultTwimlOptions`
+   *   3. `host` (calling host's per-call options)
+   *   4. Studio handoff (when `studioHandoffFlowSid` is configured)
+   *   5. Channel default — derived from `TACConfig.voicePublicDomain` +
+   *      `TACConfig.voiceActionPath`.
+   *
+   * User-expressed intent (Studio handoff is configured explicitly on
+   * `TACConfig`) beats the SDK's generated cleanup default.
+   *
+   * Explicit `actionUrl: undefined` on a layer (key present, value undefined)
+   * suppresses `<Connect action=...>` entirely — all lower layers are skipped.
+   * `actionUrl` left absent (key not present) falls through to the next layer.
+   */
+  resolveActionUrl(host, customized) {
+    if (customized && "actionUrl" in customized) {
+      return customized.actionUrl;
+    }
+    if (this.voiceConfig.defaultTwimlOptions && "actionUrl" in this.voiceConfig.defaultTwimlOptions) {
+      return this.voiceConfig.defaultTwimlOptions.actionUrl;
+    }
+    if (host && "actionUrl" in host) {
+      return host.actionUrl;
+    }
+    if (this.config.studioHandoffFlowSid) {
+      return studioVoiceHandoffUrl(this.config.accountSid, this.config.studioHandoffFlowSid);
+    }
+    return this.resolveDefaultActionUrl();
   }
   // =========================================================================
   // Outbound Call Handling
@@ -4502,10 +5102,16 @@ var VoiceChannel = class extends BaseChannel {
    * conversation during passive hydration. The session is initialized lazily
    * on the first prompt when the conversation is discovered by callSid.
    *
-   * `conversationRelayConfig.url` must be the publicly accessible WebSocket
-   * endpoint (e.g., `wss://your-domain.ngrok.app/ws`). Unlike inbound calls
-   * where TACServer sets this automatically, outbound calls require it
-   * explicitly since there is no incoming HTTP request to derive the host from.
+   * TwiML fields are merged per-field, highest precedence first:
+   *   1. `options.twimlOptions` — per-call overrides
+   *   2. `VoiceChannelConfig.defaultTwimlOptions` — channel-wide defaults
+   *   3. TAC defaults: welcome greeting, `conversationConfiguration` from
+   *      `TACConfig`, and `actionUrl` from Studio handoff (if configured), else
+   *      derived from `TACConfig.voicePublicDomain` + `voiceActionPath`.
+   *
+   * The WebSocket URL is derived from `TACConfig.voicePublicDomain` +
+   * `TACConfig.voiceWebsocketPath`, unless overridden per-call via
+   * `options.websocketUrl`.
    */
   async initiateOutboundConversation(options) {
     const validated = InitiateVoiceConversationOptionsSchema.parse(options);
@@ -4515,16 +5121,9 @@ var VoiceChannel = class extends BaseChannel {
       "Initiating outbound voice conversation"
     );
     try {
-      const conversationConfiguration = this.tac.isOrchestratorEnabled() ? validated.conversationRelayConfig.conversationConfiguration ?? this.config.conversationConfigurationId : void 0;
-      const twiml = this.connectConversationRelay(
-        {
-          ...validated.conversationRelayConfig,
-          ...conversationConfiguration !== void 0 && { conversationConfiguration }
-        },
-        {
-          ...validated.actionUrl ? { actionUrl: validated.actionUrl } : {}
-        }
-      );
+      const merged = this.buildTwimlOptions(void 0, validated.twimlOptions);
+      const websocketUrl = validated.websocketUrl ?? merged.websocketUrl ?? this.resolveWebsocketUrl("initiateOutboundConversation");
+      const twiml = this.generateTwiml(websocketUrl, merged);
       const client = this.getTwilioClient();
       const call = await client.calls.create({
         to: validated.to,
@@ -4551,7 +5150,8 @@ var VoiceChannel = class extends BaseChannel {
   // ConversationRelay Callback Handling
   // =========================================================================
   /**
-   * Handle ConversationRelay callback from Twilio
+   * Handle ConversationRelay callback from Twilio. Cleans up on call completion
+   * in voice-only mode; in orchestrated mode the CO webhook owns cleanup.
    *
    * @param payload - Callback payload from Twilio
    * @returns Response with status, content, and content type
@@ -4568,7 +5168,7 @@ var VoiceChannel = class extends BaseChannel {
       );
       return { status: 403, content: "Forbidden", contentType: "text/plain" };
     }
-    if (payload.CallStatus === "completed") {
+    if (payload.CallStatus === "completed" && !this.tac.isOrchestratorEnabled()) {
       const conversationId = this.callSidToConversationId.get(payload.CallSid);
       if (conversationId) {
         this.callSidToConversationId.delete(payload.CallSid);
@@ -4631,6 +5231,103 @@ var VoiceChannel = class extends BaseChannel {
   // =========================================================================
   // ConversationRelay TwiML Generation
   // =========================================================================
+  /**
+   * Field names on {@link TwiMLOptions} that map directly to `<ConversationRelay>`
+   * attributes (camelCase, emitted as-is). Excludes the fields handled specially
+   * by {@link generateTwiml}: websocketUrl (resolved through the layered merge and
+   * emitted as the `url` attribute), actionUrl, languages, customParameters, extra.
+   */
+  static RELAY_ATTR_FIELDS = [
+    "welcomeGreeting",
+    "welcomeGreetingInterruptible",
+    "conversationConfiguration",
+    "language",
+    "ttsLanguage",
+    "transcriptionLanguage",
+    "voice",
+    "ttsProvider",
+    "transcriptionProvider",
+    "speechModel",
+    "elevenlabsTextNormalization",
+    "eotThreshold",
+    "partialPrompts",
+    "deepgramSmartFormat",
+    "speechTimeout",
+    "interruptible",
+    "interruptSensitivity",
+    "reportInputDuringAgentSpeech",
+    "ignoreBackchannel",
+    "preemptible",
+    "dtmfDetection",
+    "hints",
+    "events",
+    "debug",
+    "intelligenceService"
+  ];
+  /**
+   * Generate TwiML XML for ConversationRelay from a merged {@link TwiMLOptions}.
+   *
+   * This is the low-level emitter used by `handleIncomingCall` and
+   * `initiateOutboundConversation` after layering. It mirrors the Python SDK's
+   * `generate_twiml`. The WebSocket URL may be passed as `websocketUrl` or via
+   * `options.websocketUrl` (the explicit argument wins when both are given), so a
+   * channel-less caller can pass everything in one object.
+   *
+   * @param websocketUrl - Public WebSocket URL (e.g. 'wss://example.ngrok.app/ws').
+   *   Optional if `options.websocketUrl` is set.
+   * @param options - Merged TwiMLOptions to emit.
+   * @returns TwiML XML string ready to return to Twilio.
+   * @throws {Error} if no WebSocket URL is provided via either source.
+   */
+  generateTwiml(websocketUrl, options) {
+    const resolvedWebsocketUrl = websocketUrl || options.websocketUrl;
+    if (!resolvedWebsocketUrl) {
+      throw new Error(
+        "generateTwiml requires a WebSocket URL \u2014 pass it explicitly or set options.websocketUrl."
+      );
+    }
+    const response = new VoiceResponse();
+    const connect = response.connect(options.actionUrl ? { action: options.actionUrl } : {});
+    const relayAttrs = { url: resolvedWebsocketUrl };
+    for (const field of _VoiceChannel.RELAY_ATTR_FIELDS) {
+      let value = options[field];
+      if (value === void 0) {
+        continue;
+      }
+      if (field === "interruptible" && typeof value === "boolean") {
+        value = value ? "any" : "none";
+      }
+      relayAttrs[field] = value;
+    }
+    if (options.extra) {
+      for (const [key, value] of Object.entries(options.extra)) {
+        if (key === "url") {
+          this.logger.warn(
+            "Ignoring `url` in TwiMLOptions.extra; set `websocketUrl` to override the ConversationRelay URL."
+          );
+          continue;
+        }
+        relayAttrs[key] = value;
+      }
+    }
+    const relay = connect.conversationRelay(
+      relayAttrs
+    );
+    if (options.languages && options.languages.length > 0) {
+      for (const lang of options.languages) {
+        const langAttrs = this.filterUnsetValues(lang);
+        relay.language(langAttrs);
+      }
+    }
+    if (options.customParameters) {
+      for (const [name, value] of Object.entries(options.customParameters)) {
+        if (value !== null && value !== void 0) {
+          relay.parameter({ name, value: stringifyParameterValue(value) });
+        }
+      }
+    }
+    return response.toString();
+  }
   /**
    * Generate TwiML to connect a call to ConversationRelay.
    * Validates configuration with Zod before generating TwiML.
@@ -4678,18 +5375,6 @@ var VoiceChannel = class extends BaseChannel {
     }
     return filtered;
   }
-  /**
-   * Extract conversation ID - Not applicable for Voice channel
-   */
-  extractConversationId(_payload) {
-    return null;
-  }
-  /**
-   * Extract profile ID - Not applicable for Voice channel
-   */
-  extractProfileId(_payload) {
-    return null;
-  }
   /**
    * Cleanup channel state on shutdown
    *
@@ -4706,14 +5391,6 @@ var VoiceChannel = class extends BaseChannel {
   }
 };
 
-// packages/core/src/util/handoff-urls.ts
-function studioExecutionsUrl(flowSid) {
-  return `https://studio.twilio.com/v2/Flows/${flowSid}/Executions`;
-}
-function studioVoiceHandoffUrl(accountSid, flowSid) {
-  return `https://webhooks.twilio.com/v1/Accounts/${accountSid}/Flows/${flowSid}?Trigger=incomingCall`;
-}
-
 // packages/core/src/lib/conversation-session-helpers.ts
 function formatTraitValue(value) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
@@ -5286,49 +5963,56 @@ var DEFAULT_CONFIG = {
   host: "0.0.0.0",
   port: 8e3,
   webhookPaths: {
-    messaging: "/webhook",
-    twiml: "/twiml",
-    ws: "/ws",
-    conversationRelayCallback: "/conversation-relay-callback"
-  },
-  conversationRelayConfig: {
-    welcomeGreeting: "Hello! How can I assist you today?"
+    conversation: "/webhook",
+    twiml: "/twiml"
   }
 };
 var TACServer = class {
   fastify;
   tac;
   config;
-  /** All enabled messaging channels — webhooks are fanned out to each one */
+  /** All enabled messaging channels */
   messagingChannels;
   /** Voice channel instance */
   voiceChannel;
+  /** All channels that need webhook processing (voice + messaging) */
+  webhookChannels;
   constructor(tac, config = {}) {
     this.tac = tac;
+    const webhookPaths = { ...DEFAULT_CONFIG.webhookPaths, ...config.webhookPaths };
+    if (config.webhookPaths?.messaging) {
+      console.warn(
+        'TACServer: The "webhookPaths.messaging" field is deprecated and will be removed in a future version. Please update your configuration to use "webhookPaths.conversation" instead.'
+      );
+      if (!config.webhookPaths.conversation) {
+        webhookPaths.conversation = config.webhookPaths.messaging;
+      }
+    }
     this.config = {
       ...DEFAULT_CONFIG,
       ...config,
-      // Deep merge webhookPaths to preserve defaults while allowing overrides
-      webhookPaths: {
-        ...DEFAULT_CONFIG.webhookPaths,
-        ...config.webhookPaths
-      },
-      // Deep merge conversationRelayConfig to preserve defaults while allowing overrides
-      conversationRelayConfig: {
-        ...DEFAULT_CONFIG.conversationRelayConfig,
-        ...config.conversationRelayConfig
-      }
+      webhookPaths
     };
     this.voiceChannel = config.voiceChannel ?? tac.getChannel("voice");
+    if (this.voiceChannel && !tac.getConfig().voicePublicDomain) {
+      throw new Error(
+        "Voice channel is configured but TACConfig.voicePublicDomain is not set. Set it directly or via the TWILIO_VOICE_PUBLIC_DOMAIN env var."
+      );
+    }
     this.messagingChannels = config.messagingChannels ?? [
       tac.getChannel("sms"),
       tac.getChannel("rcs"),
       tac.getChannel("chat"),
       tac.getChannel("whatsapp")
     ].filter((ch) => ch != null);
-    if (this.messagingChannels.length === 0) {
+    this.webhookChannels = [];
+    if (this.voiceChannel) {
+      this.webhookChannels.push(this.voiceChannel);
+    }
+    this.webhookChannels.push(...this.messagingChannels);
+    if (this.webhookChannels.length === 0) {
       console.warn(
-        'TACServer: No messaging channels configured. Messaging webhooks will be disabled. Register a MessagingChannel (e.g., "sms", "rcs", "chat", or "whatsapp") with TAC to enable messaging.'
+        "TACServer: No channels configured for webhook processing. Register channels with TAC to enable webhooks."
       );
     }
     if (config.fastifyInstance) {
@@ -5392,18 +6076,18 @@ var TACServer = class {
         await this.validateRequestSignature(request, reply);
       }
     };
-    if (this.messagingChannels.length > 0) {
+    if (this.webhookChannels.length > 0) {
       this.fastify.post(
-        this.config.webhookPaths.messaging || "/webhook",
+        this.config.webhookPaths.conversation || "/webhook",
         validateSignature,
         async (request, reply) => {
           const rawHeader = request.headers["i-twilio-idempotency-token"];
           const idempotencyToken = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
-          for (const channel of this.messagingChannels) {
+          for (const channel of this.webhookChannels) {
             channel.processWebhook(request.body, idempotencyToken).catch((err) => {
               this.fastify.log.error(
                 { err, channel: channel.channelType },
-                "Messaging webhook processing error"
+                "Webhook processing error"
               );
             });
           }
@@ -5421,18 +6105,9 @@ var TACServer = class {
             return;
           }
           const voiceChannel = this.voiceChannel;
-          const protocol = this.getForwardedProto(request);
-          const host = this.getForwardedHost(request);
-          const websocketUrl = `${protocol === "https" ? "wss" : "ws"}://${host}${this.config.webhookPaths.ws || "/ws"}`;
-          const tacConfig = this.tac.getConfig();
-          const actionUrl = tacConfig.studioHandoffFlowSid ? studioVoiceHandoffUrl(tacConfig.accountSid, tacConfig.studioHandoffFlowSid) : `${protocol}://${host}${this.config.webhookPaths.conversationRelayCallback || "/conversation-relay-callback"}`;
-          const twiml = voiceChannel.handleIncomingCall({
-            actionUrl,
-            conversationRelayConfig: {
-              url: websocketUrl,
-              ...this.config.conversationRelayConfig
-            }
-          });
+          const formDict = request.body ?? {};
+          const twimlRequest = twiMLRequestFromForm(formDict);
+          const twiml = await voiceChannel.handleIncomingCall(twimlRequest);
           await reply.type("application/xml").send(twiml);
         } catch (error) {
           this.fastify.log.error(
@@ -5446,7 +6121,7 @@ var TACServer = class {
       }
     );
     this.fastify.post(
-      this.config.webhookPaths.conversationRelayCallback || "/conversation-relay-callback",
+      this.tac.getConfig().voiceActionPath,
       validateSignature,
       async (request, reply) => {
         try {
@@ -5477,7 +6152,7 @@ var TACServer = class {
     );
     await this.fastify.register((fastify) => {
       fastify.get(
-        this.config.webhookPaths.ws || "/ws",
+        this.tac.getConfig().voiceWebsocketPath,
         { websocket: true },
         (socket, request) => {
           const signature = request.headers["x-twilio-signature"];
@@ -5594,10 +6269,10 @@ var TACServer = class {
         {
           host: this.config.host,
           port: this.config.port,
-          messaging_webhook: this.config.webhookPaths.messaging,
+          conversation_webhook: this.config.webhookPaths.conversation,
           twiml_webhook: this.config.webhookPaths.twiml,
-          ws_websocket: this.config.webhookPaths.ws,
-          conversation_relay_callback: this.config.webhookPaths.conversationRelayCallback,
+          ws_websocket: this.tac.getConfig().voiceWebsocketPath,
+          conversation_relay_callback: this.tac.getConfig().voiceActionPath,
           ...this.config.webhookPaths.cintel && {
             cintel_webhook: this.config.webhookPaths.cintel
           }
@@ -5661,6 +6336,6 @@ var TACServer = class {
   }
 };
 
-export { ActionChannelSettingsSchema, ActionParticipantRefSchema, ActionResponseSchema, ActionTextContentSchema, AuthorInfoSchema, BaseChannel, BaseClient, BuiltInTools, CaptureRuleSchema, ChannelSettingsSchema, ChannelTypeSchema, ChatChannel, CintelParticipantSchema, CommunicationContentSchema, CommunicationParticipantSchema, CommunicationSchema, ConversationAddressSchema, ConversationClient, ConversationConfigurationSchema, ConversationGroupingTypeSchema, ConversationIntelligenceConfigSchema, ConversationParticipantSchema, ConversationRelayAttributesSchema, ConversationRelayCallbackPayloadSchema, ConversationRelayConfigSchema, ConversationResponseSchema, ConversationSessionSchema, ConversationSummaryItemSchema, CreateConversationSummariesResponseSchema, CreateObservationResponseSchema, CustomParametersSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, ExecutionDetailsSchema, HandoffPayloadSchema, InitiateMessagingConversationOptionsSchema, InitiateVoiceConversationOptionsSchema, IntelligenceConfigurationSchema, InterruptMessageSchema, JSONSchemaSchema, KnowledgeBaseSchema, KnowledgeBaseStatusSchema, KnowledgeChunkResultSchema, KnowledgeClient, KnowledgeSearchResponseSchema, LanguageAttributesSchema, ListCommunicationsResponseSchema, ListConversationsResponseSchema, ListParticipantsResponseSchema, MemoryChannelTypeSchema, MemoryClient, MemoryCommunicationContentSchema, MemoryCommunicationSchema, MemoryDeliveryStatusSchema, MemoryModeSchema, MemoryParticipantSchema, MemoryParticipantTypeSchema, MemoryPromptBuilder, MemoryRetrievalRequestSchema, MemoryRetrievalResponseSchema, MessageDirectionSchema, MessagingChannel, ObservationInfoSchema, OpenAIToolSchema, OperatorProcessingResultSchema, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, ParticipantAddressSchema, ParticipantAddressTypeSchema, PendingHandoffDataSchema, ProfileLookupResponseSchema, ProfileResponseSchema, PromptMessageSchema, RCSChannel, SMSChannel, SendMessageActionPayloadSchema, SendMessageActionRequestSchema, SessionInfoSchema, SessionMessageSchema, SetupMessageSchema, StatusCallbackSchema, StatusTimeoutsSchema, SummaryInfoSchema, TAC, TACChannelTypeSchema, TACCommunicationAuthorSchema, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, TACConfigSchema, TACDeliveryStatusSchema, TACMemoryResponse, TACParticipantTypeSchema, TACServer, TACTool, TextTokenMessageSchema, ToolExecutionResultSchema, TranscriptionSchema, TranscriptionWordSchema, TwilioMemoryConfigSchema, VoiceChannel, WebSocketMessageSchema, WhatsAppChannel, buildHandoffPayload, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl };
+export { ActionChannelSettingsSchema, ActionParticipantRefSchema, ActionResponseSchema, ActionTextContentSchema, AuthorInfoSchema, BaseChannel, BaseClient, BuiltInTools, CaptureRuleSchema, ChannelSettingsSchema, ChannelTypeSchema, ChatChannel, CintelParticipantSchema, CommunicationContentSchema, CommunicationParticipantSchema, CommunicationSchema, ConversationAddressSchema, ConversationClient, ConversationConfigurationSchema, ConversationGroupingTypeSchema, ConversationIntelligenceConfigSchema, ConversationParticipantSchema, ConversationRelayAttributesSchema, ConversationRelayCallbackPayloadSchema, ConversationRelayConfigSchema, ConversationResponseSchema, ConversationSessionSchema, ConversationSummaryItemSchema, CreateConversationSummariesResponseSchema, CreateObservationResponseSchema, CustomParametersSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, ExecutionDetailsSchema, HandoffPayloadSchema, InitiateMessagingConversationOptionsSchema, InitiateVoiceConversationOptionsSchema, IntelligenceConfigurationSchema, InterruptMessageSchema, InterruptModeSchema, JSONSchemaSchema, KnowledgeBaseSchema, KnowledgeBaseStatusSchema, KnowledgeChunkResultSchema, KnowledgeClient, KnowledgeSearchResponseSchema, LanguageAttributesSchema, LanguageConfigSchema, ListCommunicationsResponseSchema, ListConversationsResponseSchema, ListParticipantsResponseSchema, MemoryChannelTypeSchema, MemoryClient, MemoryCommunicationContentSchema, MemoryCommunicationSchema, MemoryDeliveryStatusSchema, MemoryModeSchema, MemoryParticipantSchema, MemoryParticipantTypeSchema, MemoryPromptBuilder, MemoryRetrievalRequestSchema, MemoryRetrievalResponseSchema, MessageDirectionSchema, MessagingChannel, ObservationInfoSchema, OpenAIToolSchema, OperatorProcessingResultSchema, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, ParticipantAddressSchema, ParticipantAddressTypeSchema, PendingHandoffDataSchema, ProfileLookupResponseSchema, ProfileResponseSchema, PromptMessageSchema, RCSChannel, SMSChannel, SendMessageActionPayloadSchema, SendMessageActionRequestSchema, SessionInfoSchema, SessionMessageSchema, SetupMessageSchema, StatusCallbackSchema, StatusTimeoutsSchema, SummaryInfoSchema, TAC, TACChannelTypeSchema, TACCommunicationAuthorSchema, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, TACConfigSchema, TACDeliveryStatusSchema, TACMemoryResponse, TACParticipantTypeSchema, TACServer, TACTool, TextTokenMessageSchema, ToolExecutionResultSchema, TranscriptionSchema, TranscriptionWordSchema, TwiMLOptionsSchema, TwiMLRequestSchema, TwilioMemoryConfigSchema, VoiceChannel, WebSocketMessageSchema, WhatsAppChannel, buildHandoffPayload, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map