twilio-agent-connect 2.1.0 → 2.3.0

package/dist/index.js

@@ -17,8 +17,10 @@ var TwilioMemoryConfigSchema = z.object({
   traitGroups: z.array(z.string()).optional(),
   observationsLimit: z.number().int().min(0).max(100).default(20),
   summariesLimit: z.number().int().min(0).max(100).default(5),
-  // API default is 0 (no communications fetched). SDK defaults to 10 for a useful out-of-box experience.
-  communicationsLimit: z.number().int().min(0).max(100).default(10),
+  // 0 matches the Memory API and Python SDK. Above 0, Memory requires a
+  // conversationId on every /Recall, forcing the query expansion that
+  // `memoryMode: "once"` exists to avoid.
+  communicationsLimit: z.number().int().min(0).max(100).default(0),
   relevanceThreshold: z.number().min(0).max(1).default(0),
   /**
    * Trait group name that holds the phone identifier on newly created profiles.
@@ -49,34 +51,28 @@ var TACConfigSchema = z.object({
   memoryConfig: TwilioMemoryConfigSchema.prefault({}),
   conversationConfigurationId: z.string().regex(/^conv_configuration_[0-9a-z]{26}$/, "Invalid Conversation Configuration ID format").optional(),
   /**
-   * 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;
-        }
+   * Public domain where voice routes are reachable, optionally including a port
+   * and/or base path (e.g. "example.ngrok.app", "example.ngrok.app:8080",
+   * or "example.com/server1"). Used by VoiceChannel to construct the public
+   * WebSocket URL and ConversationRelay action URL. Required when using the Voice channel.
+   *
+   * Whitespace, schemes (https://, wss://), and trailing slashes are stripped
+   * automatically; anything else is passed through as given. Mirrors the Python
+   * SDK's `_normalize_voice_public_domain` — keep the two in step.
+   */
+  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(),
+    }
+    s = s.replace(/\/+$/, "");
+    return s.length === 0 ? void 0 : s;
+  }, z.string().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;
@@ -773,10 +769,16 @@ var InterruptMessageSchema = z.object({
   utteranceUntilInterrupt: z.string().optional(),
   durationUntilInterruptMs: z.number().int().nonnegative().optional()
 });
+var DtmfMessageSchema = z.object({
+  type: z.literal("dtmf"),
+  /** The key pressed: `0`-`9`, `*`, `#`, or `A`-`D`. */
+  digit: z.string()
+});
 var WebSocketMessageSchema = z.union([
   SetupMessageSchema,
   PromptMessageSchema,
-  InterruptMessageSchema
+  InterruptMessageSchema,
+  DtmfMessageSchema
 ]);
 var TextTokenMessageSchema = z.object({
   type: z.literal("text"),
@@ -1429,7 +1431,7 @@ 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 routes (required for voice; domain only, without protocol/port/path, e.g., 'abc123.ngrok.app')
+   * - TWILIO_VOICE_PUBLIC_DOMAIN: Public domain for voice routes (required for voice; a port and/or base path are allowed, e.g., 'abc123.ngrok.app', 'example.ngrok.app:8080', or 'example.com/server1')
    * - 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_VOICE_CALL_EVENT_PATH: Base path for the call-event callbacks — status, async AMD, recording (default: /twilio/call-events)
@@ -1685,7 +1687,7 @@ function createLogger(options) {
 
 // package.json
 var package_default = {
-  version: "2.1.0"};
+  version: "2.3.0"};
 function buildUserAgent() {
   return `twilio-agent-connect-typescript/${package_default.version}`;
 }
@@ -1854,7 +1856,9 @@ var MemoryClient = class _MemoryClient extends BaseClient {
           profile_id: profileId,
           observation_count: observations.length,
           summary_count: summaries.length,
-          communication_count: communications.length
+          communication_count: communications.length,
+          // Server-side query time; dominates /Recall when expansion runs.
+          query_time_ms: response.meta?.queryTime
         },
         "Memory retrieval succeeded"
       );
@@ -3045,6 +3049,10 @@ var TAC = class _TAC {
    *
    * @param session - Conversation session context
    * @param query - Optional semantic search query
+   * @param conversationId - Passed through to `/Recall` as-is. Sending one
+   *   without a `query` makes Memory infer one from that conversation's history
+   *   — an expensive server-side step — so leave it unset when there is no
+   *   per-turn topic (e.g. `"once"` mode's cache-priming fetch).
    * @returns Promise containing TACMemoryResponse wrapper providing unified access to memory data.
    *
    * Attempts to retrieve from Memory API first:
@@ -3055,7 +3063,7 @@ var TAC = class _TAC {
    * - observations and summaries are empty arrays
    * - communications have basic fields only (no author name/type)
    */
-  async retrieveMemory(session, query) {
+  async retrieveMemory(session, query, conversationId) {
     if (!this.isOrchestratorEnabled()) {
       return new TACMemoryResponse([]);
     }
@@ -3102,7 +3110,7 @@ var TAC = class _TAC {
         throw new Error("Memory client is not available");
       }
       const memoryResponse = await this.memoryClient.retrieveMemories(session.profileId, {
-        conversationId: session.conversationId,
+        conversationId,
         query,
         observationsLimit: this.config.memoryConfig.observationsLimit,
         summariesLimit: this.config.memoryConfig.summariesLimit,
@@ -3448,9 +3456,9 @@ var BaseChannel = class {
    *
    * 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.
+   * - "once": Fetch once with neither a query nor a conversation id (skipping
+   *   query expansion) 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
@@ -3465,9 +3473,11 @@ var BaseChannel = class {
       return session.cachedMemory;
     }
     try {
+      const isAlways = this.memoryMode === "always";
       const memory = await this.tac.retrieveMemory(
         session,
-        this.memoryMode === "always" ? query : void 0
+        isAlways ? query : void 0,
+        isAlways ? session.conversationId : void 0
       );
       if (this.memoryMode === "once") {
         session.cachedMemory = memory;
@@ -4673,6 +4683,9 @@ function studioVoiceHandoffUrl(accountSid, flowSid) {
 
 // packages/core/src/channels/voice.ts
 var DEFAULT_WELCOME_GREETING = "Hello! How can I assist you today?";
+var POLL_ATTEMPTS = 10;
+var POLL_BASE_DELAY_MS = 250;
+var POLL_MAX_DELAY_MS = 1500;
 function stringifyParameterValue(value) {
   if (typeof value === "object") {
     return JSON.stringify(value);
@@ -4796,6 +4809,32 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
   onRecording(callback) {
     this.onRecordingHandler = callback;
   }
+  /**
+   * Register a handler for DTMF keypresses, called once per key in order.
+   *
+   * Requires `dtmfDetection: true` on the ConversationRelay config — without it
+   * Twilio sends nothing and this never fires. Digits aren't buffered, so
+   * accumulating a multi-digit entry is the handler's job.
+   *
+   * A keypress initializes the conversation just as a prompt does, since a
+   * caller can type without ever speaking; if that fails the digit still
+   * arrives, with `conversationId` and `session` undefined. Keypresses don't
+   * cancel in-flight streaming on their own — that's a separate `interrupt`
+   * message, sent when `interruptible` includes `dtmf`.
+   *
+   * @example
+   * ```typescript
+   * const digits = new Map<string, string>();
+   *
+   * voiceChannel.onDtmf(({ conversationId, digit }) => {
+   *   if (!conversationId) return;
+   *   digits.set(conversationId, (digits.get(conversationId) ?? '') + digit);
+   * });
+   * ```
+   */
+  onDtmf(callback) {
+    this.voiceCallbacks.onDtmf = callback;
+  }
   /**
    * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
    * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
@@ -4847,6 +4886,9 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
       case "interrupt":
         this.voiceCallbacks.onInterrupt = callback;
         break;
+      case "dtmf":
+        this.voiceCallbacks.onDtmf = callback;
+        break;
       case "webSocketConnected":
         this.voiceCallbacks.onWebSocketConnected = callback;
         break;
@@ -4927,6 +4969,57 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
   getWebsocket(conversationId) {
     return this.webSocketConnections.get(conversationId) || null;
   }
+  /**
+   * Poll Conversation Orchestrator for the conversation ConversationRelay
+   * created for `callSid`, then register the local session and WebSocket.
+   * Runs in the background from `setup`, so those can exist before the
+   * caller speaks.
+   */
+  async initializeOrchestratedConversation(callSid, fromNumber, ws) {
+    if (!this.conversationClient) {
+      throw new Error("Conversation client is required in orchestrated mode");
+    }
+    let conversations = [];
+    for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt++) {
+      conversations = await this.conversationClient.listConversations({
+        channelId: callSid,
+        status: ["ACTIVE"]
+      });
+      if (conversations.length === 1) break;
+      if (attempt < POLL_ATTEMPTS - 1) {
+        this.logger.debug(
+          { call_sid: callSid, attempt: attempt + 1, found: conversations.length },
+          "Conversation not ready yet, polling again"
+        );
+        const delayMs = Math.min(POLL_BASE_DELAY_MS * 2 ** attempt, POLL_MAX_DELAY_MS);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+    if (conversations.length !== 1) {
+      throw new Error(
+        `Expected exactly 1 conversation for callSid ${callSid}, but found ${conversations.length} after ${POLL_ATTEMPTS} attempts`
+      );
+    }
+    const conversation = conversations[0];
+    const conversationId = conversation.id;
+    const participants = await this.conversationClient.listParticipants(conversationId);
+    const customerParticipant = participants.find((p) => p.type === "CUSTOMER");
+    const customerAddress = customerParticipant?.addresses?.find((a) => a.channel === "VOICE")?.address ?? fromNumber ?? void 0;
+    const profileId = customerParticipant?.profileId ? customerParticipant.profileId : void 0;
+    this.webSocketConnections.set(conversationId, ws);
+    this.callSidToConversationId.set(callSid, conversationId);
+    const session = this.startConversation(conversationId, profileId);
+    session.callSid = callSid;
+    if (customerAddress) {
+      session.authorInfo = {
+        address: customerAddress
+      };
+    }
+    if (this.voiceCallbacks.onWebSocketConnected) {
+      this.voiceCallbacks.onWebSocketConnected({ conversationId });
+    }
+    return conversationId;
+  }
   /**
    * Handle WebSocket connection from ConversationRelay
    */
@@ -4935,6 +5028,65 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
     let callSid = null;
     let fromNumber = null;
     let initializationFailed = false;
+    let initPromise = null;
+    const ensureConversation = async () => {
+      if (conversationId) {
+        return conversationId;
+      }
+      const sid = callSid;
+      if (!sid) {
+        return null;
+      }
+      const retryCount = this.initializationRetries.get(sid) ?? 0;
+      if (retryCount >= this.MAX_INITIALIZATION_RETRIES) {
+        throw new Error(
+          `Cannot process message - conversation initialization failed after ${retryCount} attempts for callSid ${sid}`
+        );
+      }
+      try {
+        if (initializationFailed) {
+          this.logger.info(
+            { call_sid: sid, retry_count: retryCount },
+            "Retrying conversation initialization after previous failure"
+          );
+        }
+        if (!this.tac.isOrchestratorEnabled()) {
+          conversationId = sid;
+          this.webSocketConnections.set(conversationId, ws);
+          this.callSidToConversationId.set(sid, conversationId);
+          const session = this.startConversation(conversationId);
+          session.callSid = sid;
+          if (fromNumber) {
+            session.authorInfo = { address: fromNumber };
+          }
+          if (this.voiceCallbacks.onWebSocketConnected) {
+            this.voiceCallbacks.onWebSocketConnected({ conversationId });
+          }
+        } else {
+          initPromise ??= this.initializeOrchestratedConversation(sid, fromNumber, ws);
+          try {
+            conversationId = await initPromise;
+          } finally {
+            initPromise = null;
+          }
+        }
+        initializationFailed = false;
+        this.initializationRetries.delete(sid);
+        this.logger.info(
+          { conversation_id: conversationId, call_sid: sid },
+          "Conversation initialization succeeded"
+        );
+        return conversationId;
+      } catch (err) {
+        initializationFailed = true;
+        this.initializationRetries.set(sid, retryCount + 1);
+        this.logger.error(
+          { err, call_sid: sid, retry_count: retryCount + 1 },
+          "Conversation initialization failed"
+        );
+        throw err;
+      }
+    };
     ws.on("message", (data) => {
       (async () => {
         try {
@@ -4957,6 +5109,14 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
             case "setup":
               callSid = message.callSid;
               fromNumber = message.from;
+              if (this.tac.isOrchestratorEnabled()) {
+                this.logger.debug(
+                  { call_sid: callSid },
+                  "Starting background conversation initialization"
+                );
+                initPromise = this.initializeOrchestratedConversation(callSid, fromNumber, ws);
+                void initPromise.catch(() => void 0);
+              }
               if (this.voiceCallbacks.onSetup) {
                 this.voiceCallbacks.onSetup({
                   callSid,
@@ -4967,89 +5127,7 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
               }
               break;
             case "prompt":
-              if (!conversationId && callSid) {
-                const retryCount = this.initializationRetries.get(callSid) ?? 0;
-                if (retryCount >= this.MAX_INITIALIZATION_RETRIES) {
-                  throw new Error(
-                    `Cannot process prompt - conversation initialization failed after ${retryCount} attempts for callSid ${callSid}`
-                  );
-                }
-                try {
-                  if (initializationFailed) {
-                    this.logger.info(
-                      { call_sid: callSid, retry_count: retryCount },
-                      "Retrying conversation initialization after previous failure"
-                    );
-                  }
-                  if (!this.tac.isOrchestratorEnabled()) {
-                    conversationId = callSid;
-                    this.webSocketConnections.set(conversationId, ws);
-                    this.callSidToConversationId.set(callSid, conversationId);
-                    const session = this.startConversation(conversationId);
-                    session.callSid = callSid;
-                    if (fromNumber) {
-                      session.authorInfo = { address: fromNumber };
-                    }
-                  } else {
-                    if (!this.conversationClient) {
-                      throw new Error("Conversation client is required in orchestrated mode");
-                    }
-                    const POLL_ATTEMPTS = 5;
-                    const POLL_DELAY_MS = 500;
-                    let conversations = [];
-                    for (let attempt = 0; attempt < POLL_ATTEMPTS; attempt++) {
-                      conversations = await this.conversationClient.listConversations({
-                        channelId: callSid
-                      });
-                      if (conversations.length === 1) break;
-                      if (attempt < POLL_ATTEMPTS - 1) {
-                        this.logger.debug(
-                          { call_sid: callSid, attempt: attempt + 1, found: conversations.length },
-                          "Conversation not ready yet, polling again"
-                        );
-                        await new Promise((resolve) => setTimeout(resolve, POLL_DELAY_MS));
-                      }
-                    }
-                    if (conversations.length !== 1) {
-                      throw new Error(
-                        `Expected exactly 1 conversation for callSid ${callSid}, but found ${conversations.length} after ${POLL_ATTEMPTS} attempts`
-                      );
-                    }
-                    const conversation = conversations[0];
-                    conversationId = conversation.id;
-                    const participants = await this.conversationClient.listParticipants(conversationId);
-                    const customerParticipant = participants.find((p) => p.type === "CUSTOMER");
-                    const customerAddress = customerParticipant?.addresses?.find((a) => a.channel === "VOICE")?.address ?? fromNumber ?? void 0;
-                    const profileId = customerParticipant?.profileId ? customerParticipant.profileId : void 0;
-                    this.webSocketConnections.set(conversationId, ws);
-                    this.callSidToConversationId.set(callSid, conversationId);
-                    const session = this.startConversation(conversationId, profileId);
-                    session.callSid = callSid;
-                    if (customerAddress) {
-                      session.authorInfo = {
-                        address: customerAddress
-                      };
-                    }
-                  }
-                  if (this.voiceCallbacks.onWebSocketConnected) {
-                    this.voiceCallbacks.onWebSocketConnected({ conversationId });
-                  }
-                  initializationFailed = false;
-                  this.initializationRetries.delete(callSid);
-                  this.logger.info(
-                    { conversation_id: conversationId, call_sid: callSid },
-                    "Conversation initialization succeeded"
-                  );
-                } catch (err) {
-                  initializationFailed = true;
-                  this.initializationRetries.set(callSid, retryCount + 1);
-                  this.logger.error(
-                    { err, call_sid: callSid, retry_count: retryCount + 1 },
-                    "Conversation initialization failed"
-                  );
-                  throw err;
-                }
-              }
+              await ensureConversation();
               if (conversationId) {
                 const previousPrompt = this.promptQueues.get(conversationId) ?? Promise.resolve();
                 const currentPrompt = previousPrompt.then(() => this.handlePromptMessage(conversationId, message)).catch((err) => {
@@ -5068,6 +5146,17 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
                 this.handleInterruptMessage(conversationId, message);
               }
               break;
+            case "dtmf":
+              try {
+                await ensureConversation();
+              } catch (err) {
+                this.logger.warn(
+                  { err, call_sid: callSid },
+                  "Conversation initialization failed on DTMF keypress, delivering digit without a conversation"
+                );
+              }
+              await this.handleDtmfMessage(conversationId, callSid, message);
+              break;
             default:
               this.logger.debug(
                 {
@@ -5090,6 +5179,19 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
       });
     });
     ws.on("close", () => {
+      const pendingInit = initPromise;
+      initPromise = null;
+      if (pendingInit && !conversationId) {
+        void pendingInit.then(async (adoptedId) => {
+          await this.handleWebSocketDisconnect(adoptedId);
+          if (callSid) this.callSidToConversationId.delete(callSid);
+        }).catch((err) => {
+          this.logger.error(
+            { err, call_sid: callSid },
+            "Background conversation initialization failed after the call ended"
+          );
+        });
+      }
       if (conversationId) {
         void this.handleWebSocketDisconnect(conversationId).catch((err) => {
           this.logger.error(
@@ -5160,6 +5262,23 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
       });
     }
   }
+  /**
+   * Handle WebSocket DTMF message (caller keypress)
+   */
+  async handleDtmfMessage(conversationId, callSid, message) {
+    const { digit } = message;
+    this.logger.debug({ conversation_id: conversationId, call_sid: callSid }, "DTMF keypress");
+    if (!this.voiceCallbacks.onDtmf) {
+      return;
+    }
+    const session = conversationId ? this.getConversationSession(conversationId) : void 0;
+    await this.voiceCallbacks.onDtmf({
+      conversationId: conversationId ?? void 0,
+      callSid: callSid ?? void 0,
+      digit,
+      ...session !== void 0 && { session }
+    });
+  }
   /**
    * Handle WebSocket disconnection. In orchestrated mode the conversation stays
    * tracked until the CLOSED webhook (so a follow-up call can reuse it); in
@@ -5476,8 +5595,8 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
    *
    * Places an outbound call with inline TwiML that connects to ConversationRelay.
    * The conversationConfiguration attribute tells CO to create and manage the
-   * conversation during passive hydration. The session is initialized lazily
-   * on the first prompt when the conversation is discovered by callSid.
+   * conversation during passive hydration. The session is initialized when the
+   * background callSid lookup started at WebSocket setup finds it.
    *
    * TwiML fields are merged per-field, highest precedence first:
    *   1. `options.twimlOptions` — per-call overrides
@@ -5668,9 +5787,8 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
   /**
    * Hang up a call and clean up its ConversationRelay session.
    *
-   * Works on `callSid` alone, in any mode and before a session exists, so it's
-   * safe from a call-event handler that fires before the first prompt. Session
-   * cleanup no-ops if no tracked session matches.
+   * Works on `callSid` alone, whether or not a session exists yet. No-ops the
+   * session cleanup if none is tracked.
    *
    * Does not throw — hanging up an already-ended call is routine (the callee
    * hangs up while AMD is still resolving), and handlers shouldn't have to
@@ -5704,11 +5822,10 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
    * keyed by conversation id: the Orchestrator conversation id in orchestrator
    * mode, the CallSid only in ConversationRelay-only mode.
    *
-   * Sessions are created on the caller's first prompt, not at WebSocket setup,
-   * so this returns `undefined` for a call that connected but hasn't been spoken
-   * into. That includes `onAmd` under `machineDetection: 'Enable'`, which fires
-   * before the first prompt by design — hang up with {@link endCall}, which
-   * needs no session.
+   * Relay-only mode creates the session on the first prompt; orchestrated
+   * mode creates it when the lookup started at setup finishes, so it may
+   * exist before the caller speaks — including before `onAmd` fires. Treat it
+   * as racy and hang up with {@link endCall}, which needs no session.
    *
    * At the other end, orchestrator mode keeps the session until Conversation
    * Orchestrator's CLOSED webhook, so it outlives the call and `onCallStatus` /
@@ -5727,8 +5844,8 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
    *
    * @param callSid - Twilio Call SID, e.g. from
    *   `InitiateVoiceConversationResult.callSid` or a call event.
-   * @returns The session, or `undefined` — no first prompt yet, the call ended,
-   *   or it landed on another instance (see the horizontal-scaling note in
+   * @returns The session, or `undefined` — not created yet, the call ended, or
+   *   it landed on another instance (see the horizontal-scaling note in
    *   CLAUDE.md).
    */
   getConversationSessionByCallSid(callSid) {
@@ -6967,6 +7084,6 @@ var TACServer = class {
   }
 };
 
-export { ActionChannelSettingsSchema, ActionParticipantRefSchema, ActionResponseSchema, ActionTextContentSchema, AmdEventSchema, AnthropicToolSchema, AuthorInfoSchema, BaseChannel, BaseClient, BuiltInTools, CALL_EVENT_KINDS, CallEventKindSchema, CallOptionsSchema, CallStatusEventSchema, CaptureRuleSchema, ChannelSettingsSchema, ChannelTypeSchema, ChatChannel, CintelParticipantSchema, CommunicationContentSchema, CommunicationParticipantSchema, CommunicationSchema, ConversationAddressSchema, ConversationClient, ConversationConfigurationSchema, ConversationGroupingTypeSchema, ConversationIntelligenceConfigSchema, ConversationParticipantSchema, ConversationRelayAttributesSchema, ConversationRelayCallbackPayloadSchema, ConversationRelayConfigSchema, ConversationResponseSchema, ConversationSessionSchema, ConversationSummaryItemSchema, CreateConversationSummariesResponseSchema, CreateObservationResponseSchema, CreateObservationsRequestSchema, 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, ObservationCreateRequestSchema, ObservationInfoSchema, OpenAIToolSchema, OperatorProcessingResultSchema, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, ParticipantAddressSchema, ParticipantAddressTypeSchema, PendingHandoffDataSchema, ProfileLookupResponseSchema, ProfileResponseSchema, PromptMessageSchema, RCSChannel, RecordingEventSchema, 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, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
+export { ActionChannelSettingsSchema, ActionParticipantRefSchema, ActionResponseSchema, ActionTextContentSchema, AmdEventSchema, AnthropicToolSchema, AuthorInfoSchema, BaseChannel, BaseClient, BuiltInTools, CALL_EVENT_KINDS, CallEventKindSchema, CallOptionsSchema, CallStatusEventSchema, CaptureRuleSchema, ChannelSettingsSchema, ChannelTypeSchema, ChatChannel, CintelParticipantSchema, CommunicationContentSchema, CommunicationParticipantSchema, CommunicationSchema, ConversationAddressSchema, ConversationClient, ConversationConfigurationSchema, ConversationGroupingTypeSchema, ConversationIntelligenceConfigSchema, ConversationParticipantSchema, ConversationRelayAttributesSchema, ConversationRelayCallbackPayloadSchema, ConversationRelayConfigSchema, ConversationResponseSchema, ConversationSessionSchema, ConversationSummaryItemSchema, CreateConversationSummariesResponseSchema, CreateObservationResponseSchema, CreateObservationsRequestSchema, CustomParametersSchema, DtmfMessageSchema, 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, ObservationCreateRequestSchema, ObservationInfoSchema, OpenAIToolSchema, OperatorProcessingResultSchema, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, ParticipantAddressSchema, ParticipantAddressTypeSchema, PendingHandoffDataSchema, ProfileLookupResponseSchema, ProfileResponseSchema, PromptMessageSchema, RCSChannel, RecordingEventSchema, 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, amdEventFromForm, buildHandoffPayload, callOptionsToCreateParams, callStatusEventFromForm, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, recordingEventFromForm, redactTwimlParameters, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map