twilio-agent-connect 2.0.1 → 2.2.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.
@@ -33,6 +35,8 @@ var voicePathSchema = (defaultPath) => z.preprocess((v) => {
   const trimmed = v.trim();
   return trimmed.length === 0 ? void 0 : trimmed;
 }, z.string().startsWith("/", 'Path must start with "/"').default(defaultPath));
+var CallEventKindSchema = z.enum(["status", "amd", "recording"]);
+var CALL_EVENT_KINDS = CallEventKindSchema.options;
 var TACConfigSchema = z.object({
   accountSid: z.string().min(1, "Twilio Account SID is required"),
   authToken: z.string().min(1, "Twilio Auth Token is required"),
@@ -47,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;
@@ -88,8 +86,14 @@ var TACConfigSchema = z.object({
    * Must start with '/'.
    */
   voiceActionPath: voicePathSchema("/conversation-relay-callback"),
+  /**
+   * Base path for the call-event callbacks (status, async AMD, recording).
+   * TACServer registers one route per callback under it — `<base>/status`,
+   * `<base>/amd`, `<base>/recording` — so the route identifies the event. Same
+   * role as voiceActionPath. Must start with '/'.
+   */
+  voiceCallEventPath: voicePathSchema("/twilio/call-events"),
   cintelConfigurationId: z.string().optional(),
-  cintelObservationOperatorSid: z.string().optional(),
   cintelSummaryOperatorSid: z.string().optional(),
   region: z.string().max(63, "Invalid Twilio region format (must be a valid DNS label)").regex(
     /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/,
@@ -124,8 +128,8 @@ var EnvironmentVariables = {
   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_VOICE_CALL_EVENT_PATH: "TWILIO_VOICE_CALL_EVENT_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",
   TWILIO_REGION: "TWILIO_REGION",
   TWILIO_STUDIO_HANDOFF_FLOW_SID: "TWILIO_STUDIO_HANDOFF_FLOW_SID"
@@ -232,6 +236,13 @@ var AuthorInfoSchema = z.object({
 });
 var ConversationSessionSchema = z.object({
   conversationId: z.string().min(1, "Conversation ID is required"),
+  /**
+   * Twilio Call SID on the Voice channel, unset on messaging. The correlation
+   * key for call events (`VoiceChannel.onCallStatus` / `onAmd` / `onRecording`)
+   * and `endCall`. Equals `conversationId` in relay-only mode; look the session
+   * up the other way with `VoiceChannel.getConversationSessionByCallSid`.
+   */
+  callSid: z.string().optional(),
   profileId: z.string().optional(),
   serviceId: z.string().optional(),
   channel: ChannelTypeSchema,
@@ -548,7 +559,13 @@ var MemoryChannelTypeSchema = z.enum([
   "API",
   "SYSTEM"
 ]);
-var MemoryParticipantTypeSchema = z.enum(["HUMAN_AGENT", "CUSTOMER", "AI_AGENT", "AGENT"]);
+var MemoryParticipantTypeSchema = z.enum([
+  "HUMAN_AGENT",
+  "CUSTOMER",
+  "AI_AGENT",
+  "AGENT",
+  "UNKNOWN"
+]);
 var MemoryDeliveryStatusSchema = z.enum([
   "INITIATED",
   "IN_PROGRESS",
@@ -640,11 +657,17 @@ var EMPTY_MEMORY_RESPONSE = {
   summaries: [],
   communications: []
 };
-var CreateObservationResponseSchema = z.object({
+var ObservationCreateRequestSchema = z.object({
   content: z.string(),
   source: z.string(),
   occurredAt: z.string(),
-  conversationIds: z.array(z.string())
+  conversationIds: z.array(z.string()).optional()
+});
+var CreateObservationsRequestSchema = z.object({
+  observations: z.array(ObservationCreateRequestSchema)
+});
+var CreateObservationResponseSchema = z.object({
+  message: z.string()
 });
 var CreateConversationSummariesResponseSchema = z.object({
   message: z.string()
@@ -1026,10 +1049,193 @@ var ConversationRelayCallbackPayloadSchema = z.object({
   SessionStatus: z.string().optional(),
   SessionDuration: z.string().optional()
 });
+function splitCallEventForm(form, aliases) {
+  const known = {};
+  const extra = {};
+  for (const [key, value] of Object.entries(form)) {
+    const alias = aliases[key];
+    if (alias) {
+      known[alias] = value;
+    } else {
+      extra[key] = value;
+    }
+  }
+  return { known, extra };
+}
+var CallEventBaseShape = {
+  callSid: z.string().min(1, "CallSid is required"),
+  accountSid: z.string().optional(),
+  /** Any other Twilio webhook fields not surfaced above. */
+  extra: z.record(z.string(), z.string()).default({})
+};
+var CALL_EVENT_BASE_ALIASES = {
+  CallSid: "callSid",
+  AccountSid: "accountSid"
+};
+var UNREACHED_CALL_STATUSES = ["busy", "no-answer", "failed", "canceled"];
+var CallStatusEventSchema = z.object({
+  ...CallEventBaseShape,
+  callStatus: z.string().optional(),
+  callDuration: z.string().optional(),
+  sipResponseCode: z.string().optional()
+}).transform((event) => ({
+  ...event,
+  /** Call ended without reaching the callee — i.e. worth a retry. */
+  isUnreached: UNREACHED_CALL_STATUSES.includes(event.callStatus ?? "")
+}));
+var CALL_STATUS_EVENT_ALIASES = {
+  ...CALL_EVENT_BASE_ALIASES,
+  CallStatus: "callStatus",
+  CallDuration: "callDuration",
+  SipResponseCode: "sipResponseCode"
+};
+function callStatusEventFromForm(form) {
+  const { known, extra } = splitCallEventForm(form, CALL_STATUS_EVENT_ALIASES);
+  return CallStatusEventSchema.parse({ ...known, extra });
+}
+var AmdEventSchema = z.object({
+  ...CallEventBaseShape,
+  answeredBy: z.string().optional(),
+  machineDetectionDuration: z.string().optional()
+}).transform((event) => ({
+  ...event,
+  /**
+   * A machine answered — any `machine_*` value, either mode. `unknown`
+   * (detection timed out) is false, so a call is never hung up on a guess.
+   */
+  isMachine: (event.answeredBy ?? "").startsWith("machine")
+}));
+var AMD_EVENT_ALIASES = {
+  ...CALL_EVENT_BASE_ALIASES,
+  AnsweredBy: "answeredBy",
+  MachineDetectionDuration: "machineDetectionDuration"
+};
+function amdEventFromForm(form) {
+  const { known, extra } = splitCallEventForm(form, AMD_EVENT_ALIASES);
+  return AmdEventSchema.parse({ ...known, extra });
+}
+var RecordingEventSchema = z.object({
+  ...CallEventBaseShape,
+  recordingSid: z.string().optional(),
+  recordingUrl: z.string().optional(),
+  recordingStatus: z.string().optional(),
+  recordingDuration: z.string().optional()
+});
+var RECORDING_EVENT_ALIASES = {
+  ...CALL_EVENT_BASE_ALIASES,
+  RecordingSid: "recordingSid",
+  RecordingUrl: "recordingUrl",
+  RecordingStatus: "recordingStatus",
+  RecordingDuration: "recordingDuration"
+};
+function recordingEventFromForm(form) {
+  const { known, extra } = splitCallEventForm(form, RECORDING_EVENT_ALIASES);
+  return RecordingEventSchema.parse({ ...known, extra });
+}
+var CALLS_CREATE_PARAMS = [
+  "applicationSid",
+  "asyncAmd",
+  "asyncAmdStatusCallback",
+  "asyncAmdStatusCallbackMethod",
+  "byoc",
+  "callerId",
+  "callReason",
+  "callToken",
+  "clientNotificationUrl",
+  "fallbackMethod",
+  "fallbackUrl",
+  "from",
+  "machineDetection",
+  "machineDetectionSilenceTimeout",
+  "machineDetectionSpeechEndThreshold",
+  "machineDetectionSpeechThreshold",
+  "machineDetectionTimeout",
+  "method",
+  "record",
+  "recordingChannels",
+  "recordingStatusCallback",
+  "recordingStatusCallbackEvent",
+  "recordingStatusCallbackMethod",
+  "recordingTrack",
+  "sendDigits",
+  "sipAuthPassword",
+  "sipAuthUsername",
+  "statusCallback",
+  "statusCallbackEvent",
+  "statusCallbackMethod",
+  "timeLimit",
+  "timeout",
+  "to",
+  "trim",
+  "twiml",
+  "url"
+];
+var RESERVED_CALL_PARAMS = ["to", "from", "twiml", "url", "applicationSid"];
+var ACCEPTED_CALL_PARAMS = new Set(CALLS_CREATE_PARAMS);
+function isAsyncAmdEnabled(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value.trim().toLowerCase() === "true";
+  return false;
+}
+var CallOptionsObjectSchema = z.looseObject({
+  machineDetection: z.enum(["Enable", "DetectMessageEnd"]).optional(),
+  asyncAmd: z.union([z.boolean(), z.string()]).optional(),
+  asyncAmdStatusCallback: z.string().optional(),
+  asyncAmdStatusCallbackMethod: z.string().optional(),
+  machineDetectionTimeout: z.number().int().optional(),
+  machineDetectionSpeechThreshold: z.number().int().optional(),
+  machineDetectionSpeechEndThreshold: z.number().int().optional(),
+  machineDetectionSilenceTimeout: z.number().int().optional(),
+  record: z.boolean().optional(),
+  recordingStatusCallback: z.string().optional(),
+  recordingStatusCallbackEvent: z.array(z.string()).optional(),
+  recordingChannels: z.string().optional(),
+  recordingTrack: z.string().optional(),
+  statusCallback: z.string().optional(),
+  statusCallbackEvent: z.array(z.string()).optional(),
+  statusCallbackMethod: z.string().optional(),
+  timeout: z.number().int().optional()
+}).superRefine((value, ctx) => {
+  const supplied = Object.keys(value);
+  const conflict = supplied.filter(
+    (key) => RESERVED_CALL_PARAMS.includes(key)
+  );
+  if (conflict.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: `callOptions may not set TAC-owned call parameters: ${conflict.sort().join(", ")}. TAC builds the call and its TwiML.`
+    });
+  }
+  const unknown = supplied.filter((key) => !ACCEPTED_CALL_PARAMS.has(key));
+  if (unknown.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      message: `callOptions has parameters Twilio's calls.create() does not accept: ${unknown.sort().join(", ")}. Check for a typo, or upgrade the twilio package.`
+    });
+  }
+  if (Boolean(value.machineDetection) !== isAsyncAmdEnabled(value.asyncAmd)) {
+    ctx.addIssue({
+      code: "custom",
+      message: `AMD requires both machineDetection and asyncAmd; got machineDetection=${JSON.stringify(value.machineDetection)}, asyncAmd=${JSON.stringify(value.asyncAmd)}.`
+    });
+  }
+});
+var CallOptionsSchema = CallOptionsObjectSchema.transform(
+  (value) => value
+);
+function callOptionsToCreateParams(options) {
+  const params = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (value === void 0) continue;
+    params[key] = key === "asyncAmd" && typeof value === "boolean" ? String(value) : value;
+  }
+  return params;
+}
 var InitiateVoiceConversationOptionsSchema = z.object({
   to: z.string().min(1, "Recipient phone number is required"),
   websocketUrl: z.url().optional(),
-  twimlOptions: TwiMLOptionsSchema.optional()
+  twimlOptions: TwiMLOptionsSchema.optional(),
+  callOptions: CallOptionsSchema.optional()
 }).strict();
 var JSONSchemaSchema = z.object({
   type: z.enum(["object", "string", "number", "boolean", "array"]),
@@ -1047,6 +1253,11 @@ var OpenAIToolSchema = z.object({
     parameters: JSONSchemaSchema
   })
 });
+var AnthropicToolSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  input_schema: JSONSchemaSchema
+});
 var ToolExecutionResultSchema = z.object({
   success: z.boolean(),
   data: z.any().optional(),
@@ -1101,7 +1312,6 @@ var OperatorProcessingResultSchema = z.object({
 });
 var ConversationIntelligenceConfigSchema = z.object({
   configurationId: z.string(),
-  observationOperatorSid: z.string().optional(),
   summaryOperatorSid: z.string().optional()
 });
 var ConversationSummaryItemSchema = z.object({
@@ -1152,8 +1362,9 @@ var TACConfig = class _TACConfig {
   voiceWebsocketPath;
   /** Path the ConversationRelay action callback is served at (default '/conversation-relay-callback'). */
   voiceActionPath;
+  /** Base path the call-event callbacks are served under (default '/twilio/call-events'). */
+  voiceCallEventPath;
   cintelConfigurationId;
-  cintelObservationOperatorSid;
   cintelSummaryOperatorSid;
   /** Optional Twilio region subdomain for API routing (e.g. transforms base URLs to `https://{product}.{region}.twilio.com`) */
   region;
@@ -1187,12 +1398,10 @@ var TACConfig = class _TACConfig {
     }
     this.voiceWebsocketPath = validatedConfig.voiceWebsocketPath;
     this.voiceActionPath = validatedConfig.voiceActionPath;
+    this.voiceCallEventPath = validatedConfig.voiceCallEventPath;
     if (validatedConfig.cintelConfigurationId) {
       this.cintelConfigurationId = validatedConfig.cintelConfigurationId;
     }
-    if (validatedConfig.cintelObservationOperatorSid) {
-      this.cintelObservationOperatorSid = validatedConfig.cintelObservationOperatorSid;
-    }
     if (validatedConfig.cintelSummaryOperatorSid) {
       this.cintelSummaryOperatorSid = validatedConfig.cintelSummaryOperatorSid;
     }
@@ -1216,9 +1425,10 @@ 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)
    * - 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
@@ -1330,14 +1540,32 @@ var TACConfig = class _TACConfig {
       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,
+      voiceCallEventPath: process.env[EnvironmentVariables.TWILIO_VOICE_CALL_EVENT_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],
       region: process.env[EnvironmentVariables.TWILIO_REGION],
       studioHandoffFlowSid: process.env[EnvironmentVariables.TWILIO_STUDIO_HANDOFF_FLOW_SID]
     };
     return new _TACConfig(rawConfig);
   }
+  /**
+   * Path a call-event callback is served at.
+   *
+   * Single source of truth: the voice channel builds callback URLs from this
+   * and TACServer registers routes at it, so the two can't drift.
+   */
+  callEventPath(kind) {
+    return `${this.voiceCallEventPath.replace(/\/+$/, "")}/${kind}`;
+  }
+  /**
+   * Public URL for a call-event callback, or `undefined` without a public domain.
+   */
+  callEventUrl(kind) {
+    if (!this.voicePublicDomain) {
+      return void 0;
+    }
+    return `https://${this.voicePublicDomain}${this.callEventPath(kind)}`;
+  }
   /**
    * Whether Conversation Orchestrator is configured.
    * Returns false in voice-only mode (no conversationConfigurationId).
@@ -1427,6 +1655,13 @@ function maskAddress(address) {
   if (address.length <= 1) return "***";
   return `${address[0]}***`;
 }
+function redactTwimlParameters(twiml) {
+  if (!twiml) return "";
+  const parameterValueRe = /(<Parameter\b[^>]*?\bvalue=)(["'])(.*?)\2/gi;
+  return twiml.replace(parameterValueRe, (_match, prefix, quote) => {
+    return `${prefix}${quote}***${quote}`;
+  });
+}
 
 // packages/core/src/lib/logger.ts
 function piiLogMethod(args, method) {
@@ -1446,7 +1681,7 @@ function createLogger(options) {
 
 // package.json
 var package_default = {
-  version: "2.0.1"};
+  version: "2.2.0"};
 function buildUserAgent() {
   return `twilio-agent-connect-typescript/${package_default.version}`;
 }
@@ -1527,7 +1762,7 @@ var BaseClient = class {
 };
 
 // packages/core/src/clients/memory.ts
-var MemoryClient = class extends BaseClient {
+var MemoryClient = class _MemoryClient extends BaseClient {
   storeId;
   constructor(config, storeId, logger) {
     const baseUrl = config.region ? `https://memory.${config.region}.twilio.com` : "https://memory.twilio.com";
@@ -1580,28 +1815,48 @@ var MemoryClient = class extends BaseClient {
         },
         "Raw memory response received"
       );
-      const validatedResponse = MemoryRetrievalResponseSchema.safeParse(data);
-      if (!validatedResponse.success) {
+      if (data === null || typeof data !== "object") {
         this.logger.warn(
           {
             profile_id: profileId,
-            memory_store_id: this.storeId,
-            validation_errors: validatedResponse.error.issues
+            memory_store_id: this.storeId
           },
           "Invalid memory response format"
         );
         return EMPTY_MEMORY_RESPONSE;
       }
+      const response = data;
+      const observations = this.parseItems(
+        response.observations,
+        ObservationInfoSchema,
+        "observation",
+        profileId
+      );
+      const summaries = this.parseItems(
+        response.summaries,
+        SummaryInfoSchema,
+        "summary",
+        profileId
+      );
+      const communications = this.parseItems(
+        response.communications,
+        MemoryCommunicationSchema,
+        "communication",
+        profileId
+      );
       this.logger.debug(
         {
           memory_store_id: this.storeId,
           profile_id: profileId,
-          observation_count: validatedResponse.data.observations.length,
-          summary_count: validatedResponse.data.summaries.length
+          observation_count: observations.length,
+          summary_count: summaries.length,
+          communication_count: communications.length,
+          // Server-side query time; dominates /Recall when expansion runs.
+          query_time_ms: response.meta?.queryTime
         },
         "Memory retrieval succeeded"
       );
-      return validatedResponse.data;
+      return { observations, summaries, communications };
     } catch (error) {
       this.logger.warn(
         {
@@ -1614,6 +1869,67 @@ var MemoryClient = class extends BaseClient {
       return EMPTY_MEMORY_RESPONSE;
     }
   }
+  /** Cap on per-item validation warnings logged per response, to avoid flooding logs. */
+  static MAX_INVALID_ITEM_LOGS = 10;
+  /**
+   * Validate an array of memory items one at a time, dropping (and logging)
+   * any that fail validation while keeping the rest.
+   *
+   * Per-item warnings are capped at {@link MemoryClient.MAX_INVALID_ITEM_LOGS}
+   * and followed by a single summary warning with the total `invalid_count`.
+   */
+  parseItems(value, schema, itemType, profileId) {
+    if (value === void 0) {
+      return [];
+    }
+    if (!Array.isArray(value)) {
+      this.logger.warn(
+        {
+          profile_id: profileId,
+          memory_store_id: this.storeId,
+          item_type: itemType,
+          received_type: typeof value
+        },
+        "Expected an array of memory items but received a non-array value"
+      );
+      return [];
+    }
+    const parsed = [];
+    let invalidCount = 0;
+    for (const [index, item] of value.entries()) {
+      const result = schema.safeParse(item);
+      if (result.success) {
+        parsed.push(result.data);
+        continue;
+      }
+      invalidCount += 1;
+      if (invalidCount <= _MemoryClient.MAX_INVALID_ITEM_LOGS) {
+        this.logger.warn(
+          {
+            profile_id: profileId,
+            memory_store_id: this.storeId,
+            item_type: itemType,
+            item_index: index,
+            validation_errors: result.error.issues
+          },
+          "Dropping invalid memory item"
+        );
+      }
+    }
+    if (invalidCount > 0) {
+      this.logger.warn(
+        {
+          profile_id: profileId,
+          memory_store_id: this.storeId,
+          item_type: itemType,
+          invalid_count: invalidCount,
+          total_count: value.length
+        },
+        "Dropped invalid memory items"
+      );
+    }
+    return parsed;
+  }
   /**
    * Find profiles that contain a specific identifier value
    *
@@ -1701,27 +2017,30 @@ var MemoryClient = class extends BaseClient {
     }
   }
   /**
-   * Create an observation for a profile
+   * Create an observation for a profile.
+   *
+   * The Memory API Observations endpoint is a batch create: the observation is
+   * wrapped in an `observations` array and `occurredAt` is required, so it
+   * defaults to the current time (ISO 8601) when omitted or blank.
    *
    * @param profileId - The profile ID to create the observation for
    * @param content - The observation content
    * @param source - Source of the observation (default: 'conversation-intelligence')
    * @param conversationIds - Optional array of conversation IDs associated with this observation
-   * @param occurredAt - Optional timestamp when the observation occurred
-   * @returns Promise containing the created observation
+   * @param occurredAt - Timestamp when the observation occurred (ISO 8601); defaults to now when omitted or blank
+   * @returns Promise containing the API confirmation message
    */
   async createObservation(profileId, content, source = "conversation-intelligence", conversationIds, occurredAt) {
     const url = `/v1/Stores/${this.storeId}/Profiles/${profileId}/Observations`;
-    const requestBody = {
+    const observation = {
       content,
-      source
+      source,
+      occurredAt: occurredAt && occurredAt.trim() ? occurredAt : (/* @__PURE__ */ new Date()).toISOString()
     };
     if (conversationIds && conversationIds.length > 0) {
-      requestBody.conversationIds = conversationIds;
-    }
-    if (occurredAt) {
-      requestBody.occurredAt = occurredAt;
+      observation.conversationIds = conversationIds;
     }
+    const requestBody = { observations: [observation] };
     try {
       const data = await this.makeRequest(url, "POST", requestBody);
       return CreateObservationResponseSchema.parse(data);
@@ -2130,22 +2449,6 @@ function generateContent(operatorResult) {
   const jsonString = JSON.stringify(result);
   return jsonString === "{}" || jsonString === "[]" ? void 0 : jsonString;
 }
-function parseObservationsContent(jsonContent) {
-  try {
-    const parsed = JSON.parse(jsonContent);
-    if (typeof parsed === "object" && parsed !== null && "observations" in parsed) {
-      const observations = parsed.observations;
-      if (Array.isArray(observations)) {
-        return observations.filter(
-          (obs) => typeof obs === "string" && obs.trim() !== ""
-        );
-      }
-    }
-    return [];
-  } catch {
-    return [];
-  }
-}
 function parseSummariesContent(jsonContent) {
   try {
     const parsed = JSON.parse(jsonContent);
@@ -2283,13 +2586,11 @@ var OperatorResultProcessor = class {
    */
   async processOperatorResult(event, operatorResult) {
     const operatorSid = operatorResult.operator.id;
-    const isObservationOperator = this.config.observationOperatorSid === operatorSid;
     const isSummaryOperator = this.config.summaryOperatorSid === operatorSid;
-    if (!isObservationOperator && !isSummaryOperator) {
+    if (!isSummaryOperator) {
       this.logger.debug(
         {
           operator_sid: operatorSid,
-          observation_operator_sid: this.config.observationOperatorSid,
           summary_operator_sid: this.config.summaryOperatorSid
         },
         "Skipping unconfigured operator"
@@ -2327,75 +2628,7 @@ var OperatorResultProcessor = class {
         createdCount: 0
       };
     }
-    if (isObservationOperator) {
-      return this.processObservationEvent(event, operatorResult, content, profileIds);
-    } else {
-      return this.processSummaryEvent(event, operatorResult, content, profileIds);
-    }
-  }
-  /**
-   * Process an observation operator result
-   */
-  async processObservationEvent(event, operatorResult, content, profileIds) {
-    const observations = parseObservationsContent(content);
-    if (observations.length === 0) {
-      this.logger.debug(
-        { operator_sid: operatorResult.operator.id },
-        "No observations found in content"
-      );
-      return {
-        success: true,
-        eventType: "observation",
-        skipped: true,
-        skipReason: "No observations found in operator result content",
-        createdCount: 0
-      };
-    }
-    let createdCount = 0;
-    for (const profileId of profileIds) {
-      for (const observation of observations) {
-        try {
-          await this.memoryClient.createObservation(
-            profileId,
-            observation,
-            "conversation-intelligence",
-            [event.conversationId],
-            operatorResult.dateCreated
-          );
-          createdCount++;
-          this.logger.debug(
-            {
-              profile_id: profileId,
-              conversation_id: event.conversationId,
-              observation_preview: observation.substring(0, 100)
-            },
-            "Created observation"
-          );
-        } catch (error) {
-          this.logger.error(
-            {
-              err: error,
-              profile_id: profileId,
-              conversation_id: event.conversationId
-            },
-            "Failed to create observation"
-          );
-          return {
-            success: false,
-            eventType: "observation",
-            skipped: false,
-            error: `Failed to create observation: ${error instanceof Error ? error.message : String(error)}`,
-            createdCount
-          };
-        }
-      }
-    }
-    return {
-      success: true,
-      eventType: "observation",
-      skipped: false,
-      createdCount
-    };
+    return this.processSummaryEvent(event, operatorResult, content, profileIds);
   }
   /**
    * Process a summary operator result
@@ -2517,7 +2750,6 @@ var TAC = class _TAC {
           tac.memoryClient,
           {
             configurationId: tac.config.cintelConfigurationId,
-            observationOperatorSid: tac.config.cintelObservationOperatorSid,
             summaryOperatorSid: tac.config.cintelSummaryOperatorSid
           },
           tac.logger.child({ component: "cintel" })
@@ -2811,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:
@@ -2821,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([]);
     }
@@ -2868,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,
@@ -3214,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
@@ -3231,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;
@@ -3502,10 +3740,16 @@ var MessagingChannel = class extends BaseChannel {
       if (!session.aiAgentInfo) {
         const resolved = await this.reconcileParticipants(conversationId);
         if (!resolved) {
-          this.logger.warn(
-            { conversation_id: conversationId },
-            "Reconciliation failed; skipping callback for this inbound"
+          const error = new Error(
+            `Participant reconciliation failed for conversation ${conversationId}; inbound message dropped because no sendable participants could be resolved.`
           );
+          error.name = "ParticipantReconciliationError";
+          this.handleError(error, {
+            conversation_id: conversationId,
+            channel: this.channelType,
+            dropped_inbound: true,
+            error_code: "participant_reconciliation_failed"
+          });
           return;
         }
         const [agentParticipant, customerParticipant] = resolved;
@@ -4433,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);
@@ -4450,6 +4697,9 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
   twilioClient;
   voiceConfig;
   onInboundCallTwimlHandler;
+  onCallStatusHandler;
+  onAmdHandler;
+  onRecordingHandler;
   constructor(tac, options) {
     super(tac, options);
     this.voiceConfig = options ?? {};
@@ -4485,6 +4735,74 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
   onInboundCallTwiml(callback) {
     this.onInboundCallTwimlHandler = callback;
   }
+  /**
+   * Register a handler for Twilio `statusCallback` webhooks.
+   *
+   * This is the Calls-API status callback (call disposition), not the
+   * ConversationRelay session callback — see
+   * {@link handleConversationRelayCallback}.
+   *
+   * Registering does two things: it stores the handler, and it makes later
+   * outbound calls pass `statusCallback` to `calls.create`. With no handler
+   * registered TAC omits that parameter, so Twilio has nowhere to post and the
+   * event never arrives.
+   *
+   * Twilio reports only the terminal event by default, which covers every
+   * disposition; set `CallOptions.statusCallbackEvent` for ringing/answered.
+   *
+   * @example
+   * ```typescript
+   * voiceChannel.onCallStatus(async event => {
+   *   if (event.isUnreached) {
+   *     // queue a retry
+   *   }
+   * });
+   * ```
+   */
+  onCallStatus(callback) {
+    this.onCallStatusHandler = callback;
+  }
+  /**
+   * Register a handler for Twilio `asyncAmdStatusCallback` webhooks.
+   *
+   * Registering makes later outbound calls pass `asyncAmdStatusCallback` to
+   * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
+   * post the result. It does not enable detection — that's per-call, via
+   * `CallOptions.machineDetection` and `asyncAmd`, both of which are required
+   * for this to fire (at most once per call).
+   *
+   * @example
+   * ```typescript
+   * voiceChannel.onAmd(async event => {
+   *   if (event.isMachine) {
+   *     await voiceChannel.endCall(event.callSid); // voicemail → hang up
+   *   }
+   * });
+   * ```
+   */
+  onAmd(callback) {
+    this.onAmdHandler = callback;
+  }
+  /**
+   * Register a handler for Twilio `recordingStatusCallback` webhooks.
+   *
+   * Registering makes later outbound calls pass `recordingStatusCallback` to
+   * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
+   * post. It does not start recording — that's `CallOptions.record`, which is
+   * required for this to fire.
+   *
+   * @example
+   * ```typescript
+   * voiceChannel.onRecording(async event => {
+   *   if (event.recordingStatus === 'completed') {
+   *     // store event.recordingUrl
+   *   }
+   * });
+   * ```
+   */
+  onRecording(callback) {
+    this.onRecordingHandler = callback;
+  }
   /**
    * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
    * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
@@ -4616,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
    */
@@ -4624,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 {
@@ -4646,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,
@@ -4675,52 +5053,25 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
                     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`
-                      );
+                    if (this.voiceCallbacks.onWebSocketConnected) {
+                      this.voiceCallbacks.onWebSocketConnected({ conversationId });
                     }
-                    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);
-                    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(
@@ -4777,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(
@@ -5098,13 +5462,73 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
   // =========================================================================
   // Outbound Call Handling
   // =========================================================================
+  /**
+   * Overlay `perCall` onto `VoiceChannelConfig.defaultCallOptions`.
+   *
+   * Per-field via key presence, the same convention {@link overlayFields} uses
+   * for TwiML options — so a per-call `{ machineDetection: undefined }`
+   * explicitly clears the channel default rather than falling through to it.
+   *
+   * The result is always validated, for two reasons: a combination only
+   * reachable by layering — per-call clearing `machineDetection` while the
+   * default set `asyncAmd` — must still fail instead of reaching Twilio, and
+   * `VoiceChannelConfig` is a plain interface, so `defaultCallOptions` has had
+   * no runtime validation of its own.
+   */
+  mergeCallOptions(perCall) {
+    const defaults = this.voiceConfig.defaultCallOptions;
+    if (!defaults && !perCall) {
+      return void 0;
+    }
+    const merged = {};
+    for (const [key, value] of Object.entries(defaults ?? {})) {
+      if (value !== void 0) {
+        merged[key] = value;
+      }
+    }
+    for (const key of Object.keys(perCall ?? {})) {
+      merged[key] = perCall[key];
+    }
+    return CallOptionsSchema.parse(merged);
+  }
+  /**
+   * Build the extra arguments for `client.calls.create`.
+   *
+   * Layers, highest precedence first: this call's `callOptions`,
+   * `VoiceChannelConfig.defaultCallOptions`, then callback URLs derived from
+   * `voicePublicDomain` + `voiceCallEventPath`.
+   *
+   * A URL is derived only when its handler is registered. That's a deliberate
+   * deviation from `websocketUrl` / `actionUrl`, which derive unconditionally:
+   * those are load-bearing, so a wrong one fails loudly on the first call,
+   * whereas an unwanted call-event URL fails as silent 11200 alerts for a
+   * feature nobody asked for. Set the URLs in `defaultCallOptions` when TAC
+   * isn't serving the routes.
+   */
+  buildCallParams(callOptions) {
+    const merged = this.mergeCallOptions(callOptions);
+    const params = merged ? callOptionsToCreateParams(merged) : {};
+    const wiring = [
+      ["status", "statusCallback", this.onCallStatusHandler],
+      ["amd", "asyncAmdStatusCallback", this.onAmdHandler],
+      ["recording", "recordingStatusCallback", this.onRecordingHandler]
+    ];
+    for (const [kind, param, handler] of wiring) {
+      if (!handler) continue;
+      const url = this.config.callEventUrl(kind);
+      if (url !== void 0 && params[param] === void 0) {
+        params[param] = url;
+      }
+    }
+    return params;
+  }
   /**
    * Initiate an outbound voice conversation
    *
    * 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
@@ -5113,6 +5537,12 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
    *      `TACConfig`, and `actionUrl` from Studio handoff (if configured), else
    *      derived from `TACConfig.voicePublicDomain` + `voiceActionPath`.
    *
+   * Calls-API parameters merge the same way:
+   *   1. `options.callOptions` — per-call overrides
+   *   2. `VoiceChannelConfig.defaultCallOptions` — channel-wide defaults
+   *   3. Callback URLs derived from `TACConfig.voicePublicDomain` +
+   *      `voiceCallEventPath`, for handlers that are registered
+   *
    * The WebSocket URL is derived from `TACConfig.voicePublicDomain` +
    * `TACConfig.voiceWebsocketPath`, unless overridden per-call via
    * `options.websocketUrl`.
@@ -5128,11 +5558,17 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
       const merged = this.buildTwimlOptions(void 0, validated.twimlOptions);
       const websocketUrl = validated.websocketUrl ?? merged.websocketUrl ?? this.resolveWebsocketUrl("initiateOutboundConversation");
       const twiml = this.generateTwiml(websocketUrl, merged);
+      const callParams = this.buildCallParams(validated.callOptions);
+      this.logger.debug(
+        { twiml: redactTwimlParameters(twiml), to: maskAddress(validated.to) },
+        "Outbound call TwiML"
+      );
       const client = this.getTwilioClient();
       const call = await client.calls.create({
         to: validated.to,
         from: fromNumber,
-        twiml
+        twiml,
+        ...callParams
       });
       this.logger.info(
         { call_sid: call.sid, to: maskAddress(validated.to) },
@@ -5182,6 +5618,177 @@ var VoiceChannel = class _VoiceChannel extends BaseChannel {
     return { status: 200, content: "OK", contentType: "text/plain" };
   }
   // =========================================================================
+  // Call Event Handling (status callback, async AMD, recording)
+  // =========================================================================
+  /**
+   * Whether a call-webhook payload belongs to the configured account.
+   *
+   * Twilio signature validation already gates the route; this is defense in
+   * depth. A payload with no `AccountSid` is allowed through.
+   *
+   * Subaccounts: events carry the SID the call was placed on, so configure TAC
+   * with that account or its events get dropped here.
+   */
+  callEventAccountOk(form) {
+    const accountSid = form["AccountSid"];
+    if (accountSid && accountSid !== this.config.accountSid) {
+      this.logger.warn(
+        { expected: this.config.accountSid, received: accountSid },
+        "Call event AccountSid mismatch, ignoring"
+      );
+      return false;
+    }
+    return true;
+  }
+  /**
+   * Parse a call-event webhook form and dispatch it to its handler.
+   *
+   * Returns 400 when the payload can't be parsed (no `CallSid`) or the handler
+   * throws — better than handing Twilio a 200 for an event that wasn't
+   * processed. Everything else, including no handler registered and an
+   * account mismatch, is a 200 no-op.
+   */
+  async dispatchCallEvent(kind, form, handler, parse, logFields) {
+    const ok = { status: 200, content: "OK", contentType: "text/plain" };
+    if (!handler || !this.callEventAccountOk(form)) {
+      return ok;
+    }
+    try {
+      const event = parse(form);
+      this.logger.debug(logFields(event), `Call ${kind} event received`);
+      await handler(event);
+    } catch (error) {
+      this.logger.error({ err: error, kind }, "Failed to process call event callback");
+      return { status: 400, content: "Bad Request", contentType: "text/plain" };
+    }
+    return ok;
+  }
+  /**
+   * Handle a Twilio `statusCallback` webhook.
+   *
+   * The developer routes the request here (`TACServer` does this automatically
+   * for its `/status` call-event route). Parsed into a {@link CallStatusEvent}
+   * and dispatched to the {@link onCallStatus} handler. No-op if no handler is
+   * registered.
+   *
+   * @param form - Raw form data from the webhook request.
+   */
+  async handleCallStatusEvent(form) {
+    return this.dispatchCallEvent(
+      "status",
+      form,
+      this.onCallStatusHandler,
+      callStatusEventFromForm,
+      (event) => ({ call_sid: event.callSid, call_status: event.callStatus })
+    );
+  }
+  /**
+   * Handle a Twilio `asyncAmdStatusCallback` webhook.
+   *
+   * The developer routes the request here (`TACServer` does this automatically
+   * for its `/amd` call-event route). Parsed into an {@link AmdEvent} and
+   * dispatched to the {@link onAmd} handler. No-op if no handler is registered.
+   *
+   * @param form - Raw form data from the webhook request.
+   */
+  async handleAmdEvent(form) {
+    return this.dispatchCallEvent("amd", form, this.onAmdHandler, amdEventFromForm, (event) => ({
+      call_sid: event.callSid,
+      answered_by: event.answeredBy
+    }));
+  }
+  /**
+   * Handle a Twilio `recordingStatusCallback` webhook.
+   *
+   * The developer routes the request here (`TACServer` does this automatically
+   * for its `/recording` call-event route). Parsed into a
+   * {@link RecordingEvent} and dispatched to the {@link onRecording} handler.
+   * No-op if no handler is registered.
+   *
+   * @param form - Raw form data from the webhook request.
+   */
+  async handleRecordingEvent(form) {
+    return this.dispatchCallEvent(
+      "recording",
+      form,
+      this.onRecordingHandler,
+      recordingEventFromForm,
+      (event) => ({ call_sid: event.callSid, recording_status: event.recordingStatus })
+    );
+  }
+  /**
+   * Hang up a call and clean up its ConversationRelay session.
+   *
+   * 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
+   * guard against it.
+   *
+   * @param callSid - Twilio Call SID (from a call event, the outbound result, or
+   *   `ConversationSession.callSid`).
+   * @returns True if Twilio accepted the hangup, false if it failed (logged).
+   *   Session cleanup runs either way.
+   */
+  async endCall(callSid) {
+    const client = this.getTwilioClient();
+    let hungUp = true;
+    try {
+      await client.calls(callSid).update({ status: "completed" });
+    } catch (error) {
+      hungUp = false;
+      this.logger.error({ err: error, call_sid: callSid }, "Failed to hang up call");
+    }
+    const session = this.getConversationSessionByCallSid(callSid);
+    if (session) {
+      await this.endConversation(session.conversationId);
+    }
+    return hungUp;
+  }
+  /**
+   * Look up the active voice session for a Twilio Call SID.
+   *
+   * Out-of-band code holding a CallSid — a dashboard route, an operator action,
+   * a call-event handler — can't reach the session-facing methods, which are
+   * keyed by conversation id: the Orchestrator conversation id in orchestrator
+   * mode, the CallSid only in ConversationRelay-only mode.
+   *
+   * 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` /
+   * `onRecording` do resolve. Relay-only mode tears down on the
+   * ConversationRelay callback instead, which races them.
+   *
+   * @example
+   * ```typescript
+   * async function nudge(callSid: string): Promise<void> {
+   *   const session = voiceChannel.getConversationSessionByCallSid(callSid);
+   *   if (session) {
+   *     await voiceChannel.sendResponse(session.conversationId, 'Still there?');
+   *   }
+   * }
+   * ```
+   *
+   * @param callSid - Twilio Call SID, e.g. from
+   *   `InitiateVoiceConversationResult.callSid` or a call event.
+   * @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) {
+    for (const session of this.activeConversations.values()) {
+      if (session.callSid === callSid) {
+        return session;
+      }
+    }
+    return void 0;
+  }
+  // =========================================================================
   // Stream Task Management
   // =========================================================================
   /**
@@ -5971,6 +6578,9 @@ var DEFAULT_CONFIG = {
     twiml: "/twiml"
   }
 };
+function stripTrailingSlash(path) {
+  return path.replace(/\/+$/, "");
+}
 var TACServer = class {
   fastify;
   tac;
@@ -6003,6 +6613,7 @@ var TACServer = class {
         "Voice channel is configured but TACConfig.voicePublicDomain is not set. Set it directly or via the TWILIO_VOICE_PUBLIC_DOMAIN env var."
       );
     }
+    this.validateCallEventPaths();
     this.messagingChannels = config.messagingChannels ?? [
       tac.getChannel("sms"),
       tac.getChannel("rcs"),
@@ -6030,6 +6641,38 @@ var TACServer = class {
       });
     }
   }
+  /**
+   * Validate `voiceCallEventPath`, the one path that isn't literal.
+   *
+   * Every other TAC path registers as configured, so a bad value is visible.
+   * This one expands into three sub-paths, hiding a mistake the base path looks
+   * innocent for: a sub-path colliding with another route while the base looks
+   * unrelated (base `/hooks` vs `webhookPaths.twiml = '/hooks/status'`). Both
+   * would register as POST routes and requests would reach the wrong handler.
+   *
+   * The leading-slash requirement is enforced by `TACConfigSchema` at parse
+   * time, so it doesn't need re-checking here.
+   */
+  validateCallEventPaths() {
+    const cfg = this.tac.getConfig();
+    const others = {
+      [stripTrailingSlash(this.config.webhookPaths.twiml || "/twiml")]: "webhookPaths.twiml",
+      [stripTrailingSlash(cfg.voiceActionPath)]: "TACConfig.voiceActionPath",
+      [stripTrailingSlash(this.config.webhookPaths.conversation || "/webhook")]: "webhookPaths.conversation"
+    };
+    if (this.config.webhookPaths.cintel) {
+      others[stripTrailingSlash(this.config.webhookPaths.cintel)] = "webhookPaths.cintel";
+    }
+    for (const kind of CALL_EVENT_KINDS) {
+      const path = cfg.callEventPath(kind);
+      const clash = others[stripTrailingSlash(path)];
+      if (clash !== void 0) {
+        throw new Error(
+          `TACConfig.voiceCallEventPath expands to '${path}', which collides with ${clash}. Both would register as POST routes and requests would reach the wrong handler.`
+        );
+      }
+    }
+  }
   getForwardedProto(request) {
     const raw = request.headers["x-forwarded-proto"];
     return raw?.split(",")[0]?.trim() || "https";
@@ -6154,6 +6797,34 @@ var TACServer = class {
         }
       }
     );
+    const callEventHandlers = {
+      status: (channel, form) => channel.handleCallStatusEvent(form),
+      amd: (channel, form) => channel.handleAmdEvent(form),
+      recording: (channel, form) => channel.handleRecordingEvent(form)
+    };
+    for (const kind of CALL_EVENT_KINDS) {
+      const handle = callEventHandlers[kind];
+      this.fastify.post(
+        this.tac.getConfig().callEventPath(kind),
+        validateSignature,
+        async (request, reply) => {
+          try {
+            if (!this.voiceChannel) {
+              await reply.code(500).send({ error: "Voice channel not available" });
+              return;
+            }
+            const formData = request.body ?? {};
+            const result = await handle(this.voiceChannel, formData);
+            await reply.code(result.status).type(result.contentType).send(result.content);
+          } catch (error) {
+            this.fastify.log.error(
+              `Call ${kind} callback error: ` + (error instanceof Error ? error.message : String(error))
+            );
+            await reply.code(500).send({ error: "Internal server error" });
+          }
+        }
+      );
+    }
     await this.fastify.register((fastify) => {
       fastify.get(
         this.tac.getConfig().voiceWebsocketPath,
@@ -6277,6 +6948,11 @@ var TACServer = class {
           twiml_webhook: this.config.webhookPaths.twiml,
           ws_websocket: this.tac.getConfig().voiceWebsocketPath,
           conversation_relay_callback: this.tac.getConfig().voiceActionPath,
+          ...this.voiceChannel && {
+            call_event_callbacks: CALL_EVENT_KINDS.map(
+              (kind) => this.tac.getConfig().callEventPath(kind)
+            )
+          },
           ...this.config.webhookPaths.cintel && {
             cintel_webhook: this.config.webhookPaths.cintel
           }
@@ -6340,6 +7016,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, 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 };
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map