twilio-agent-connect 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -104,8 +104,9 @@ declare const EnvironmentVariables: {
  * Memory retrieval mode for channels.
  *
  * - "always": Fetch memory with the message as query on every inbound message.
- * - "once": Fetch memory once at conversation start with an empty query and
- *   cache it. The cache is invalidated when the conversation becomes INACTIVE.
+ * - "once": Fetch memory once at conversation start with no query (and no
+ *   conversation id, skipping query expansion) and cache it. The cache is
+ *   invalidated when the conversation becomes INACTIVE.
  * - "never": Never automatically fetch memory (default).
  */
 declare const MemoryModeSchema: z.ZodEnum<{
@@ -1483,8 +1484,8 @@ interface InitiateConversationResult {
 /**
  * Result of initiating an outbound voice conversation.
  * Note: conversationId is not included because the conversation is created by
- * Conversation Orchestrator during passive hydration — the SDK discovers it
- * lazily on the first prompt via callSid lookup.
+ * Conversation Orchestrator during passive hydration — the SDK discovers it by
+ * callSid, in the background from WebSocket setup.
  */
 interface InitiateVoiceConversationResult {
     callSid: string;
@@ -2481,7 +2482,7 @@ declare 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)
@@ -2846,7 +2847,7 @@ interface BaseChannelOptions {
      *
      * - "never": Memory is not automatically retrieved. Use the memory TAC tool or manually call `tac.retrieveMemory()` in callbacks for conditional retrieval.
      * - "always": Memory is automatically retrieved (using the message as query) for every inbound message and available in `onMessageReady` callback.
-     * - "once": Memory is retrieved once at conversation start with an empty query and cached on the session. Subsequent messages reuse the cache until the conversation becomes INACTIVE.
+     * - "once": Memory is retrieved once at conversation start with no query (and no conversation id) and cached on the session. Subsequent messages reuse the cache until the conversation becomes INACTIVE.
      */
     memoryMode?: MemoryMode;
     /**
@@ -2984,9 +2985,9 @@ declare abstract class BaseChannel {
      *
      * 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
@@ -3137,6 +3138,10 @@ declare 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:
@@ -3147,7 +3152,7 @@ declare class TAC {
      * - observations and summaries are empty arrays
      * - communications have basic fields only (no author name/type)
      */
-    retrieveMemory(session: ConversationSession, query?: string): Promise<TACMemoryResponse>;
+    retrieveMemory(session: ConversationSession, query?: string, conversationId?: string): Promise<TACMemoryResponse>;
     /**
      * Fetch profile information with traits
      *
@@ -3549,6 +3554,10 @@ interface VoiceChannelEvents extends BaseChannelEvents {
         utteranceUntilInterrupt: string | undefined;
         durationUntilInterruptMs: number | undefined;
     }) => void;
+    /**
+     * Fired once the session and WebSocket registration exist — in orchestrated
+     * mode possibly before the first prompt, since the lookup starts at setup.
+     */
     onWebSocketConnected?: (data: {
         conversationId: ConversationId;
     }) => void;
@@ -3706,6 +3715,13 @@ declare class VoiceChannel extends BaseChannel {
      * Get active WebSocket connection for a conversation
      */
     getWebsocket(conversationId: ConversationId): WebSocket | 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.
+     */
+    private initializeOrchestratedConversation;
     /**
      * Handle WebSocket connection from ConversationRelay
      */
@@ -3860,8 +3876,8 @@ declare 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
@@ -3959,9 +3975,8 @@ declare 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
@@ -3981,11 +3996,10 @@ declare 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` /
@@ -4004,8 +4018,8 @@ declare 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: string): ConversationSession | undefined;

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;
@@ -1429,7 +1425,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 +1681,7 @@ function createLogger(options) {
 
 // package.json
 var package_default = {
-  version: "2.1.0"};
+  version: "2.2.0"};
 function buildUserAgent() {
   return `twilio-agent-connect-typescript/${package_default.version}`;
 }
@@ -1854,7 +1850,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 +3043,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 +3057,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 +3104,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 +3450,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 +3467,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 +4677,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);
@@ -4927,6 +4934,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 +4993,7 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
     let callSid = null;
     let fromNumber = null;
     let initializationFailed = false;
+    let initPromise = null;
     ws.on("message", (data) => {
       (async () => {
         try {
@@ -4957,6 +5016,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,
@@ -4990,50 +5057,21 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
                     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 (this.voiceCallbacks.onWebSocketConnected) {
+                      this.voiceCallbacks.onWebSocketConnected({ conversationId });
                     }
-                    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
-                      };
+                  } else {
+                    initPromise ??= this.initializeOrchestratedConversation(
+                      callSid,
+                      fromNumber,
+                      ws
+                    );
+                    try {
+                      conversationId = await initPromise;
+                    } finally {
+                      initPromise = null;
                     }
                   }
-                  if (this.voiceCallbacks.onWebSocketConnected) {
-                    this.voiceCallbacks.onWebSocketConnected({ conversationId });
-                  }
                   initializationFailed = false;
                   this.initializationRetries.delete(callSid);
                   this.logger.info(
@@ -5090,6 +5128,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(
@@ -5476,8 +5527,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 +5719,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 +5754,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 +5776,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) {