twilio-agent-connect 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -4,6 +4,7 @@ import pino from 'pino';
4
4
  import { AxiosInstance } from 'axios';
5
5
  import { WebSocket } from 'ws';
6
6
  import VoiceResponse from 'twilio/lib/twiml/VoiceResponse.js';
7
+ import { CallListInstanceCreateOptions } from 'twilio/lib/rest/api/v2010/account/call.js';
7
8
  import { FastifyInstance, FastifyServerOptions } from 'fastify';
8
9
 
9
10
  /**
@@ -30,6 +31,15 @@ declare const TwilioMemoryConfigSchema: z.ZodObject<{
30
31
  phoneTraitField: z.ZodDefault<z.ZodString>;
31
32
  }, z.core.$strip>;
32
33
  type TwilioMemoryConfig = z.infer<typeof TwilioMemoryConfigSchema>;
34
+ /** The three Twilio call callbacks TAC serves, one route per kind. */
35
+ declare const CallEventKindSchema: z.ZodEnum<{
36
+ status: "status";
37
+ amd: "amd";
38
+ recording: "recording";
39
+ }>;
40
+ type CallEventKind = z.infer<typeof CallEventKindSchema>;
41
+ /** Iterable form of {@link CallEventKind}, for registering every route. */
42
+ declare const CALL_EVENT_KINDS: readonly CallEventKind[];
33
43
  /**
34
44
  * TAC configuration schema
35
45
  */
@@ -54,8 +64,8 @@ declare const TACConfigSchema: z.ZodObject<{
54
64
  voicePublicDomain: z.ZodOptional<z.ZodPreprocess<z.ZodOptional<z.ZodString>>>;
55
65
  voiceWebsocketPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
56
66
  voiceActionPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
67
+ voiceCallEventPath: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
57
68
  cintelConfigurationId: z.ZodOptional<z.ZodString>;
58
- cintelObservationOperatorSid: z.ZodOptional<z.ZodString>;
59
69
  cintelSummaryOperatorSid: z.ZodOptional<z.ZodString>;
60
70
  region: z.ZodOptional<z.ZodString>;
61
71
  studioHandoffFlowSid: z.ZodOptional<z.ZodString>;
@@ -83,8 +93,8 @@ declare const EnvironmentVariables: {
83
93
  readonly TWILIO_VOICE_PUBLIC_DOMAIN: "TWILIO_VOICE_PUBLIC_DOMAIN";
84
94
  readonly TWILIO_VOICE_WEBSOCKET_PATH: "TWILIO_VOICE_WEBSOCKET_PATH";
85
95
  readonly TWILIO_VOICE_ACTION_PATH: "TWILIO_VOICE_ACTION_PATH";
96
+ readonly TWILIO_VOICE_CALL_EVENT_PATH: "TWILIO_VOICE_CALL_EVENT_PATH";
86
97
  readonly TWILIO_TAC_CI_CONFIGURATION_ID: "TWILIO_TAC_CI_CONFIGURATION_ID";
87
- readonly TWILIO_TAC_CI_OBSERVATION_OPERATOR_SID: "TWILIO_TAC_CI_OBSERVATION_OPERATOR_SID";
88
98
  readonly TWILIO_TAC_CI_SUMMARY_OPERATOR_SID: "TWILIO_TAC_CI_SUMMARY_OPERATOR_SID";
89
99
  readonly TWILIO_REGION: "TWILIO_REGION";
90
100
  readonly TWILIO_STUDIO_HANDOFF_FLOW_SID: "TWILIO_STUDIO_HANDOFF_FLOW_SID";
@@ -134,6 +144,7 @@ declare const MemoryParticipantTypeSchema: z.ZodEnum<{
134
144
  CUSTOMER: "CUSTOMER";
135
145
  AI_AGENT: "AI_AGENT";
136
146
  AGENT: "AGENT";
147
+ UNKNOWN: "UNKNOWN";
137
148
  }>;
138
149
  type MemoryParticipantType = z.infer<typeof MemoryParticipantTypeSchema>;
139
150
  /**
@@ -173,6 +184,7 @@ declare const MemoryParticipantSchema: z.ZodObject<{
173
184
  CUSTOMER: "CUSTOMER";
174
185
  AI_AGENT: "AI_AGENT";
175
186
  AGENT: "AGENT";
187
+ UNKNOWN: "UNKNOWN";
176
188
  }>>;
177
189
  profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
178
190
  deliveryStatus: z.ZodOptional<z.ZodEnum<{
@@ -222,6 +234,7 @@ declare const MemoryCommunicationSchema: z.ZodObject<{
222
234
  CUSTOMER: "CUSTOMER";
223
235
  AI_AGENT: "AI_AGENT";
224
236
  AGENT: "AGENT";
237
+ UNKNOWN: "UNKNOWN";
225
238
  }>>;
226
239
  profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
227
240
  deliveryStatus: z.ZodOptional<z.ZodEnum<{
@@ -254,6 +267,7 @@ declare const MemoryCommunicationSchema: z.ZodObject<{
254
267
  CUSTOMER: "CUSTOMER";
255
268
  AI_AGENT: "AI_AGENT";
256
269
  AGENT: "AGENT";
270
+ UNKNOWN: "UNKNOWN";
257
271
  }>>;
258
272
  profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
259
273
  deliveryStatus: z.ZodOptional<z.ZodEnum<{
@@ -390,6 +404,7 @@ declare const MemoryRetrievalResponseSchema: z.ZodObject<{
390
404
  CUSTOMER: "CUSTOMER";
391
405
  AI_AGENT: "AI_AGENT";
392
406
  AGENT: "AGENT";
407
+ UNKNOWN: "UNKNOWN";
393
408
  }>>;
394
409
  profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
395
410
  deliveryStatus: z.ZodOptional<z.ZodEnum<{
@@ -422,6 +437,7 @@ declare const MemoryRetrievalResponseSchema: z.ZodObject<{
422
437
  CUSTOMER: "CUSTOMER";
423
438
  AI_AGENT: "AI_AGENT";
424
439
  AGENT: "AGENT";
440
+ UNKNOWN: "UNKNOWN";
425
441
  }>>;
426
442
  profileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
427
443
  deliveryStatus: z.ZodOptional<z.ZodEnum<{
@@ -463,13 +479,39 @@ type ProfileResponse = z.infer<typeof ProfileResponseSchema>;
463
479
  */
464
480
  declare const EMPTY_MEMORY_RESPONSE: MemoryRetrievalResponse;
465
481
  /**
466
- * Response from creating an observation
482
+ * A single observation in a create request.
483
+ *
484
+ * `occurredAt` is required by the Memory API and formatted as ISO 8601.
467
485
  */
468
- declare const CreateObservationResponseSchema: z.ZodObject<{
486
+ declare const ObservationCreateRequestSchema: z.ZodObject<{
469
487
  content: z.ZodString;
470
488
  source: z.ZodString;
471
489
  occurredAt: z.ZodString;
472
- conversationIds: z.ZodArray<z.ZodString>;
490
+ conversationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
491
+ }, z.core.$strip>;
492
+ type ObservationCreateRequest = z.infer<typeof ObservationCreateRequestSchema>;
493
+ /**
494
+ * Request body for the Memory API Observations endpoint.
495
+ *
496
+ * The endpoint is a batch create that wraps observations in an array.
497
+ */
498
+ declare const CreateObservationsRequestSchema: z.ZodObject<{
499
+ observations: z.ZodArray<z.ZodObject<{
500
+ content: z.ZodString;
501
+ source: z.ZodString;
502
+ occurredAt: z.ZodString;
503
+ conversationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
504
+ }, z.core.$strip>>;
505
+ }, z.core.$strip>;
506
+ type CreateObservationsRequest = z.infer<typeof CreateObservationsRequestSchema>;
507
+ /**
508
+ * Response from creating an observation.
509
+ *
510
+ * The Memory API Observations endpoint is a batch create that returns a
511
+ * confirmation message rather than the persisted observation.
512
+ */
513
+ declare const CreateObservationResponseSchema: z.ZodObject<{
514
+ message: z.ZodString;
473
515
  }, z.core.$strip>;
474
516
  type CreateObservationResponse = z.infer<typeof CreateObservationResponseSchema>;
475
517
  /**
@@ -1152,6 +1194,7 @@ interface Profile {
1152
1194
  */
1153
1195
  declare const ConversationSessionSchema: z.ZodObject<{
1154
1196
  conversationId: z.ZodString;
1197
+ callSid: z.ZodOptional<z.ZodString>;
1155
1198
  profileId: z.ZodOptional<z.ZodString>;
1156
1199
  serviceId: z.ZodOptional<z.ZodString>;
1157
1200
  channel: z.ZodEnum<{
@@ -1827,6 +1870,213 @@ declare const ConversationRelayCallbackPayloadSchema: z.ZodObject<{
1827
1870
  SessionDuration: z.ZodOptional<z.ZodString>;
1828
1871
  }, z.core.$strip>;
1829
1872
  type ConversationRelayCallbackPayload = z.infer<typeof ConversationRelayCallbackPayloadSchema>;
1873
+ /**
1874
+ * A Twilio `statusCallback` webhook — call progress and disposition.
1875
+ *
1876
+ * By default Twilio sends only the terminal event, which covers every
1877
+ * disposition (`completed` / `busy` / `no-answer` / `failed` / `canceled`); set
1878
+ * `CallOptions.statusCallbackEvent` for the intermediate ones. Register a
1879
+ * handler via `VoiceChannel.onCallStatus`.
1880
+ *
1881
+ * `isUnreached` is computed at parse time so application code doesn't have to
1882
+ * match disposition strings itself.
1883
+ */
1884
+ declare const CallStatusEventSchema: z.ZodPipe<z.ZodObject<{
1885
+ callStatus: z.ZodOptional<z.ZodString>;
1886
+ callDuration: z.ZodOptional<z.ZodString>;
1887
+ sipResponseCode: z.ZodOptional<z.ZodString>;
1888
+ callSid: z.ZodString;
1889
+ accountSid: z.ZodOptional<z.ZodString>;
1890
+ extra: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
1891
+ }, z.core.$strip>, z.ZodTransform<{
1892
+ /** Call ended without reaching the callee — i.e. worth a retry. */
1893
+ isUnreached: boolean;
1894
+ callSid: string;
1895
+ extra: Record<string, string>;
1896
+ callStatus?: string | undefined;
1897
+ callDuration?: string | undefined;
1898
+ sipResponseCode?: string | undefined;
1899
+ accountSid?: string | undefined;
1900
+ }, {
1901
+ callSid: string;
1902
+ extra: Record<string, string>;
1903
+ callStatus?: string | undefined;
1904
+ callDuration?: string | undefined;
1905
+ sipResponseCode?: string | undefined;
1906
+ accountSid?: string | undefined;
1907
+ }>>;
1908
+ type CallStatusEvent = z.infer<typeof CallStatusEventSchema>;
1909
+ /** Build a {@link CallStatusEvent} from a raw Twilio webhook form. */
1910
+ declare function callStatusEventFromForm(form: Record<string, string>): CallStatusEvent;
1911
+ /**
1912
+ * A Twilio `asyncAmdStatusCallback` webhook — answering machine detection.
1913
+ *
1914
+ * Fires at most once per call, and only when the call set both
1915
+ * `CallOptions.machineDetection` and `asyncAmd`.
1916
+ *
1917
+ * `answeredBy` is mode-dependent — `machine_start` under `'Enable'`,
1918
+ * `machine_end_beep` / `machine_end_silence` / `machine_end_other` under
1919
+ * `'DetectMessageEnd'`, plus `human` / `fax` / `unknown` in both. Use
1920
+ * `isMachine` rather than matching those yourself. Register a handler via
1921
+ * `VoiceChannel.onAmd`.
1922
+ */
1923
+ declare const AmdEventSchema: z.ZodPipe<z.ZodObject<{
1924
+ answeredBy: z.ZodOptional<z.ZodString>;
1925
+ machineDetectionDuration: z.ZodOptional<z.ZodString>;
1926
+ callSid: z.ZodString;
1927
+ accountSid: z.ZodOptional<z.ZodString>;
1928
+ extra: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
1929
+ }, z.core.$strip>, z.ZodTransform<{
1930
+ /**
1931
+ * A machine answered — any `machine_*` value, either mode. `unknown`
1932
+ * (detection timed out) is false, so a call is never hung up on a guess.
1933
+ */
1934
+ isMachine: boolean;
1935
+ callSid: string;
1936
+ extra: Record<string, string>;
1937
+ answeredBy?: string | undefined;
1938
+ machineDetectionDuration?: string | undefined;
1939
+ accountSid?: string | undefined;
1940
+ }, {
1941
+ callSid: string;
1942
+ extra: Record<string, string>;
1943
+ answeredBy?: string | undefined;
1944
+ machineDetectionDuration?: string | undefined;
1945
+ accountSid?: string | undefined;
1946
+ }>>;
1947
+ type AmdEvent = z.infer<typeof AmdEventSchema>;
1948
+ /** Build an {@link AmdEvent} from a raw Twilio webhook form. */
1949
+ declare function amdEventFromForm(form: Record<string, string>): AmdEvent;
1950
+ /**
1951
+ * A Twilio `recordingStatusCallback` webhook — a recording became available.
1952
+ *
1953
+ * Fires when the recording is ready (`recordingUrl` accessible), only when
1954
+ * recording is enabled. Register a handler via `VoiceChannel.onRecording`.
1955
+ */
1956
+ declare const RecordingEventSchema: z.ZodObject<{
1957
+ recordingSid: z.ZodOptional<z.ZodString>;
1958
+ recordingUrl: z.ZodOptional<z.ZodString>;
1959
+ recordingStatus: z.ZodOptional<z.ZodString>;
1960
+ recordingDuration: z.ZodOptional<z.ZodString>;
1961
+ callSid: z.ZodString;
1962
+ accountSid: z.ZodOptional<z.ZodString>;
1963
+ extra: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
1964
+ }, z.core.$strip>;
1965
+ type RecordingEvent = z.infer<typeof RecordingEventSchema>;
1966
+ /** Build a {@link RecordingEvent} from a raw Twilio webhook form. */
1967
+ declare function recordingEventFromForm(form: Record<string, string>): RecordingEvent;
1968
+ /**
1969
+ * Every parameter `client.calls.create()` accepts, as of the pinned Twilio SDK.
1970
+ *
1971
+ * Unlike Python's `inspect.signature`, TypeScript has no runtime view of a
1972
+ * function's accepted keys, so the set is listed here and pinned to the SDK by
1973
+ * {@link _CallsCreateDriftGuards} at typecheck time. It's needed at runtime
1974
+ * because the Node SDK builds its request body from an explicit whitelist —
1975
+ * an unrecognized key is **silently dropped**, not an error, so without this a
1976
+ * typo would look like it worked.
1977
+ */
1978
+ declare const CALLS_CREATE_PARAMS: readonly ["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"];
1979
+ /**
1980
+ * `calls.create` parameters TAC owns — it builds the call and its TwiML, so a
1981
+ * caller setting these would either be overwritten or break the call.
1982
+ */
1983
+ declare const RESERVED_CALL_PARAMS: readonly ["to", "from", "twiml", "url", "applicationSid"];
1984
+ type ReservedCallParam = (typeof RESERVED_CALL_PARAMS)[number];
1985
+ /**
1986
+ * The `calls.create` parameters TAC types explicitly — the ones outbound
1987
+ * ConversationRelay reaches for. Everything else the SDK accepts is still
1988
+ * forwarded, typed by the SDK itself via {@link CallOptions}.
1989
+ */
1990
+ interface TypedCallOptions {
1991
+ /**
1992
+ * Enables AMD. `'Enable'` reports as soon as it can tell human from machine
1993
+ * (to hang up on voicemail); `'DetectMessageEnd'` waits out the greeting (to
1994
+ * leave a message). Required, together with `asyncAmd`, for `onAmd` to fire.
1995
+ */
1996
+ machineDetection?: 'Enable' | 'DetectMessageEnd' | undefined;
1997
+ /**
1998
+ * Detect in the background. Required for `onAmd`: with it off, `AnsweredBy`
1999
+ * comes back on the TwiML request, which inline TwiML can't receive.
2000
+ *
2001
+ * Twilio's API types this as a string; a boolean is serialized for you.
2002
+ */
2003
+ asyncAmd?: boolean | string | undefined;
2004
+ asyncAmdStatusCallback?: string | undefined;
2005
+ asyncAmdStatusCallbackMethod?: string | undefined;
2006
+ machineDetectionTimeout?: number | undefined;
2007
+ machineDetectionSpeechThreshold?: number | undefined;
2008
+ machineDetectionSpeechEndThreshold?: number | undefined;
2009
+ machineDetectionSilenceTimeout?: number | undefined;
2010
+ /** Required for `onRecording`. */
2011
+ record?: boolean | undefined;
2012
+ recordingStatusCallback?: string | undefined;
2013
+ recordingStatusCallbackEvent?: string[] | undefined;
2014
+ recordingChannels?: string | undefined;
2015
+ recordingTrack?: string | undefined;
2016
+ statusCallback?: string | undefined;
2017
+ /**
2018
+ * Lifecycle events to report. Omitted, Twilio sends only `'completed'` —
2019
+ * which covers busy/canceled/failed/no-answer. Set it for ringing/answered.
2020
+ */
2021
+ statusCallbackEvent?: string[] | undefined;
2022
+ statusCallbackMethod?: string | undefined;
2023
+ /** Seconds to ring before giving up. Twilio defaults to 60. */
2024
+ timeout?: number | undefined;
2025
+ }
2026
+ /**
2027
+ * Parameters for Twilio's `client.calls.create()`.
2028
+ *
2029
+ * {@link TypedCallOptions} covers the ones outbound ConversationRelay reaches
2030
+ * for; any other parameter `calls.create()` accepts is forwarded too, typed by
2031
+ * the Twilio SDK. TAC-owned parameters (`to`, `from`, `twiml`, `url`,
2032
+ * `applicationSid`) are excluded — TAC builds the call and its TwiML.
2033
+ *
2034
+ * Unknown keys are rejected at validation, so a typo fails at
2035
+ * `initiateOutboundConversation` rather than being silently dropped by the SDK.
2036
+ *
2037
+ * @example
2038
+ * ```typescript
2039
+ * const callOptions: CallOptions = {
2040
+ * machineDetection: 'Enable',
2041
+ * asyncAmd: true,
2042
+ * record: true,
2043
+ * };
2044
+ * ```
2045
+ */
2046
+ type CallOptions = TypedCallOptions & Omit<CallListInstanceCreateOptions, ReservedCallParam | keyof TypedCallOptions>;
2047
+ /**
2048
+ * @internal Fails typecheck unless instantiated with `true`. A conditional type
2049
+ * that merely resolves to `never` is not an error on its own, so the assertion
2050
+ * has to be a constraint violation to be load-bearing.
2051
+ */
2052
+ type _AssertTrue<T extends true> = T;
2053
+ /**
2054
+ * @internal Compile-time SDK drift guards — do not use directly.
2055
+ * If the Twilio SDK adds, removes, or renames a `calls.create` parameter these
2056
+ * checks fail during `npm run typecheck`, signaling that
2057
+ * {@link CALLS_CREATE_PARAMS} needs updating. Without the `complete` direction a
2058
+ * newly added SDK parameter would be rejected at runtime as unknown.
2059
+ */
2060
+ type _CallsCreateDriftGuards = {
2061
+ known: _AssertTrue<(typeof CALLS_CREATE_PARAMS)[number] extends keyof CallListInstanceCreateOptions ? true : false>;
2062
+ complete: _AssertTrue<keyof CallListInstanceCreateOptions extends (typeof CALLS_CREATE_PARAMS)[number] ? true : false>;
2063
+ typedAreRealParams: _AssertTrue<keyof TypedCallOptions extends keyof CallListInstanceCreateOptions ? true : false>;
2064
+ reservedAreRealParams: _AssertTrue<ReservedCallParam extends keyof CallListInstanceCreateOptions ? true : false>;
2065
+ };
2066
+ /**
2067
+ * Validates {@link CallOptions}. The parsed value is re-widened to `CallOptions`
2068
+ * because the loose object's inferred index signature would otherwise erase the
2069
+ * SDK-derived parameter types.
2070
+ */
2071
+ declare const CallOptionsSchema: z.ZodType<CallOptions, unknown>;
2072
+ /**
2073
+ * Serialize {@link CallOptions} into the argument object for
2074
+ * `client.calls.create()`, dropping unset keys.
2075
+ *
2076
+ * `asyncAmd` is coerced to a string because Twilio's SDK types it as one,
2077
+ * unlike `record`.
2078
+ */
2079
+ declare function callOptionsToCreateParams(options: CallOptions): Record<string, unknown>;
1830
2080
  /**
1831
2081
  * Options for initiating an outbound voice conversation.
1832
2082
  *
@@ -1858,6 +2108,12 @@ interface InitiateVoiceConversationOptions {
1858
2108
  * `VoiceChannelConfig.defaultTwimlOptions` and TAC defaults.
1859
2109
  */
1860
2110
  twimlOptions?: TwiMLOptions | undefined;
2111
+ /**
2112
+ * Parameters for Twilio's `calls.create()` — AMD, recording, status
2113
+ * callbacks, timeout (see {@link CallOptions}). Callback URLs auto-wire when
2114
+ * the matching handler is registered; an explicit URL wins.
2115
+ */
2116
+ callOptions?: CallOptions | undefined;
1861
2117
  }
1862
2118
  declare const InitiateVoiceConversationOptionsSchema: z.ZodType<InitiateVoiceConversationOptions>;
1863
2119
 
@@ -1910,7 +2166,7 @@ type JSONSchema = z.infer<typeof JSONSchemaSchema>;
1910
2166
  /**
1911
2167
  * Tool function signature
1912
2168
  */
1913
- type ToolFunction<TParams = any, TResult = any> = (params: TParams) => Promise<TResult> | TResult;
2169
+ type ToolFunction<TParams = unknown, TResult = unknown> = (params: TParams) => Promise<TResult> | TResult;
1914
2170
  /**
1915
2171
  * OpenAI tool format
1916
2172
  */
@@ -1936,6 +2192,28 @@ declare const OpenAIToolSchema: z.ZodObject<{
1936
2192
  }, z.core.$strip>;
1937
2193
  }, z.core.$strip>;
1938
2194
  type OpenAITool = z.infer<typeof OpenAIToolSchema>;
2195
+ /**
2196
+ * Anthropic tool format
2197
+ */
2198
+ declare const AnthropicToolSchema: z.ZodObject<{
2199
+ name: z.ZodString;
2200
+ description: z.ZodString;
2201
+ input_schema: z.ZodObject<{
2202
+ type: z.ZodEnum<{
2203
+ string: "string";
2204
+ number: "number";
2205
+ boolean: "boolean";
2206
+ object: "object";
2207
+ array: "array";
2208
+ }>;
2209
+ properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
2210
+ required: z.ZodOptional<z.ZodArray<z.ZodString>>;
2211
+ items: z.ZodOptional<z.ZodAny>;
2212
+ enum: z.ZodOptional<z.ZodArray<z.ZodAny>>;
2213
+ description: z.ZodOptional<z.ZodString>;
2214
+ }, z.core.$strip>;
2215
+ }, z.core.$strip>;
2216
+ type AnthropicTool = z.infer<typeof AnthropicToolSchema>;
1939
2217
  /**
1940
2218
  * Tool execution context
1941
2219
  */
@@ -2078,7 +2356,6 @@ type OperatorProcessingResult = z.infer<typeof OperatorProcessingResultSchema>;
2078
2356
  */
2079
2357
  declare const ConversationIntelligenceConfigSchema: z.ZodObject<{
2080
2358
  configurationId: z.ZodString;
2081
- observationOperatorSid: z.ZodOptional<z.ZodString>;
2082
2359
  summaryOperatorSid: z.ZodOptional<z.ZodString>;
2083
2360
  }, z.core.$strip>;
2084
2361
  type ConversationIntelligenceConfig = z.infer<typeof ConversationIntelligenceConfigSchema>;
@@ -2176,8 +2453,9 @@ declare class TACConfig {
2176
2453
  readonly voiceWebsocketPath: string;
2177
2454
  /** Path the ConversationRelay action callback is served at (default '/conversation-relay-callback'). */
2178
2455
  readonly voiceActionPath: string;
2456
+ /** Base path the call-event callbacks are served under (default '/twilio/call-events'). */
2457
+ readonly voiceCallEventPath: string;
2179
2458
  readonly cintelConfigurationId?: string;
2180
- readonly cintelObservationOperatorSid?: string;
2181
2459
  readonly cintelSummaryOperatorSid?: string;
2182
2460
  /** Optional Twilio region subdomain for API routing (e.g. transforms base URLs to `https://{product}.{region}.twilio.com`) */
2183
2461
  readonly region?: string;
@@ -2206,6 +2484,7 @@ declare class TACConfig {
2206
2484
  * - TWILIO_VOICE_PUBLIC_DOMAIN: Public domain for voice routes (required for voice; domain only, without protocol/port/path, e.g., 'abc123.ngrok.app')
2207
2485
  * - TWILIO_VOICE_WEBSOCKET_PATH: Path for the voice WebSocket (default: /ws)
2208
2486
  * - TWILIO_VOICE_ACTION_PATH: Path for the ConversationRelay action callback (default: /conversation-relay-callback)
2487
+ * - TWILIO_VOICE_CALL_EVENT_PATH: Base path for the call-event callbacks — status, async AMD, recording (default: /twilio/call-events)
2209
2488
  * - TWILIO_REGION: Twilio region subdomain for API routing (e.g. transforms base URLs to `https://{product}.{region}.twilio.com`)
2210
2489
  * - TWILIO_STUDIO_HANDOFF_FLOW_SID: Studio Flow SID used by createStudioHandoffTool for human handoff
2211
2490
  * - TWILIO_RCS_SENDER_ID: RCS Sender ID for the RCS channel
@@ -2231,9 +2510,22 @@ declare class TACConfig {
2231
2510
  * ```
2232
2511
  */
2233
2512
  static fromEnv(): TACConfig;
2513
+ /**
2514
+ * Path a call-event callback is served at.
2515
+ *
2516
+ * Single source of truth: the voice channel builds callback URLs from this
2517
+ * and TACServer registers routes at it, so the two can't drift.
2518
+ */
2519
+ callEventPath(kind: CallEventKind): string;
2520
+ /**
2521
+ * Public URL for a call-event callback, or `undefined` without a public domain.
2522
+ */
2523
+ callEventUrl(kind: CallEventKind): string | undefined;
2234
2524
  /**
2235
2525
  * Whether Conversation Orchestrator is configured.
2236
2526
  * Returns false in voice-only mode (no conversationConfigurationId).
2527
+ *
2528
+ * @internal
2237
2529
  */
2238
2530
  isOrchestratorEnabled(): boolean;
2239
2531
  /**
@@ -2302,6 +2594,16 @@ declare class MemoryClient extends BaseClient {
2302
2594
  * @returns Promise containing memory retrieval response
2303
2595
  */
2304
2596
  retrieveMemories(profileId: string, request?: Partial<MemoryRetrievalRequest>): Promise<MemoryRetrievalResponse>;
2597
+ /** Cap on per-item validation warnings logged per response, to avoid flooding logs. */
2598
+ private static readonly MAX_INVALID_ITEM_LOGS;
2599
+ /**
2600
+ * Validate an array of memory items one at a time, dropping (and logging)
2601
+ * any that fail validation while keeping the rest.
2602
+ *
2603
+ * Per-item warnings are capped at {@link MemoryClient.MAX_INVALID_ITEM_LOGS}
2604
+ * and followed by a single summary warning with the total `invalid_count`.
2605
+ */
2606
+ private parseItems;
2305
2607
  /**
2306
2608
  * Find profiles that contain a specific identifier value
2307
2609
  *
@@ -2337,14 +2639,18 @@ declare class MemoryClient extends BaseClient {
2337
2639
  */
2338
2640
  getProfile(profileId: string, traitGroups?: string[]): Promise<ProfileResponse>;
2339
2641
  /**
2340
- * Create an observation for a profile
2642
+ * Create an observation for a profile.
2643
+ *
2644
+ * The Memory API Observations endpoint is a batch create: the observation is
2645
+ * wrapped in an `observations` array and `occurredAt` is required, so it
2646
+ * defaults to the current time (ISO 8601) when omitted or blank.
2341
2647
  *
2342
2648
  * @param profileId - The profile ID to create the observation for
2343
2649
  * @param content - The observation content
2344
2650
  * @param source - Source of the observation (default: 'conversation-intelligence')
2345
2651
  * @param conversationIds - Optional array of conversation IDs associated with this observation
2346
- * @param occurredAt - Optional timestamp when the observation occurred
2347
- * @returns Promise containing the created observation
2652
+ * @param occurredAt - Timestamp when the observation occurred (ISO 8601); defaults to now when omitted or blank
2653
+ * @returns Promise containing the API confirmation message
2348
2654
  */
2349
2655
  createObservation(profileId: string, content: string, source?: string, conversationIds?: string[], occurredAt?: string): Promise<CreateObservationResponse>;
2350
2656
  /**
@@ -2780,6 +3086,8 @@ declare class TAC {
2780
3086
  /**
2781
3087
  * Whether Conversation Orchestrator is configured.
2782
3088
  * Returns false in voice-only mode.
3089
+ *
3090
+ * @internal
2783
3091
  */
2784
3092
  isOrchestratorEnabled(): boolean;
2785
3093
  /**
@@ -3198,6 +3506,14 @@ interface VoiceChannelConfig extends BaseChannelOptions {
3198
3506
  * higher-priority layer sets them.
3199
3507
  */
3200
3508
  defaultTwimlOptions?: TwiMLOptions;
3509
+ /**
3510
+ * Static {@link CallOptions} applied to every outbound call — the
3511
+ * `calls.create` parameters, including the call-event callback URLs. This is
3512
+ * the layer to use for a custom server or non-default routes: URLs set here
3513
+ * override the ones TAC would derive from `voicePublicDomain` +
3514
+ * `voiceCallEventPath`.
3515
+ */
3516
+ defaultCallOptions?: CallOptions;
3201
3517
  }
3202
3518
  /**
3203
3519
  * Callback that produces per-call overrides for the TwiML inside
@@ -3205,6 +3521,12 @@ interface VoiceChannelConfig extends BaseChannelOptions {
3205
3521
  * {@link TwiMLRequest} and returns {@link TwiMLOptions}.
3206
3522
  */
3207
3523
  type InboundCallTwimlHandler = (req: TwiMLRequest) => Promise<TwiMLOptions>;
3524
+ /** Handler for Twilio `statusCallback` webhooks. */
3525
+ type CallStatusHandler = (event: CallStatusEvent) => Promise<void> | void;
3526
+ /** Handler for Twilio `asyncAmdStatusCallback` webhooks. */
3527
+ type AmdHandler = (event: AmdEvent) => Promise<void> | void;
3528
+ /** Handler for Twilio `recordingStatusCallback` webhooks. */
3529
+ type RecordingHandler = (event: RecordingEvent) => Promise<void> | void;
3208
3530
  /**
3209
3531
  * Voice channel event callbacks extending base callbacks
3210
3532
  */
@@ -3255,6 +3577,9 @@ declare class VoiceChannel extends BaseChannel {
3255
3577
  private twilioClient;
3256
3578
  private readonly voiceConfig;
3257
3579
  private onInboundCallTwimlHandler;
3580
+ private onCallStatusHandler;
3581
+ private onAmdHandler;
3582
+ private onRecordingHandler;
3258
3583
  constructor(tac: TAC, options?: VoiceChannelConfig);
3259
3584
  /**
3260
3585
  * Register a callback that produces per-call overrides for the TwiML inside
@@ -3279,6 +3604,68 @@ declare class VoiceChannel extends BaseChannel {
3279
3604
  * `InitiateVoiceConversationOptions.twimlOptions` directly.
3280
3605
  */
3281
3606
  onInboundCallTwiml(callback: InboundCallTwimlHandler): void;
3607
+ /**
3608
+ * Register a handler for Twilio `statusCallback` webhooks.
3609
+ *
3610
+ * This is the Calls-API status callback (call disposition), not the
3611
+ * ConversationRelay session callback — see
3612
+ * {@link handleConversationRelayCallback}.
3613
+ *
3614
+ * Registering does two things: it stores the handler, and it makes later
3615
+ * outbound calls pass `statusCallback` to `calls.create`. With no handler
3616
+ * registered TAC omits that parameter, so Twilio has nowhere to post and the
3617
+ * event never arrives.
3618
+ *
3619
+ * Twilio reports only the terminal event by default, which covers every
3620
+ * disposition; set `CallOptions.statusCallbackEvent` for ringing/answered.
3621
+ *
3622
+ * @example
3623
+ * ```typescript
3624
+ * voiceChannel.onCallStatus(async event => {
3625
+ * if (event.isUnreached) {
3626
+ * // queue a retry
3627
+ * }
3628
+ * });
3629
+ * ```
3630
+ */
3631
+ onCallStatus(callback: CallStatusHandler): void;
3632
+ /**
3633
+ * Register a handler for Twilio `asyncAmdStatusCallback` webhooks.
3634
+ *
3635
+ * Registering makes later outbound calls pass `asyncAmdStatusCallback` to
3636
+ * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
3637
+ * post the result. It does not enable detection — that's per-call, via
3638
+ * `CallOptions.machineDetection` and `asyncAmd`, both of which are required
3639
+ * for this to fire (at most once per call).
3640
+ *
3641
+ * @example
3642
+ * ```typescript
3643
+ * voiceChannel.onAmd(async event => {
3644
+ * if (event.isMachine) {
3645
+ * await voiceChannel.endCall(event.callSid); // voicemail → hang up
3646
+ * }
3647
+ * });
3648
+ * ```
3649
+ */
3650
+ onAmd(callback: AmdHandler): void;
3651
+ /**
3652
+ * Register a handler for Twilio `recordingStatusCallback` webhooks.
3653
+ *
3654
+ * Registering makes later outbound calls pass `recordingStatusCallback` to
3655
+ * `calls.create`; without a handler TAC omits it and Twilio has nowhere to
3656
+ * post. It does not start recording — that's `CallOptions.record`, which is
3657
+ * required for this to fire.
3658
+ *
3659
+ * @example
3660
+ * ```typescript
3661
+ * voiceChannel.onRecording(async event => {
3662
+ * if (event.recordingStatus === 'completed') {
3663
+ * // store event.recordingUrl
3664
+ * }
3665
+ * });
3666
+ * ```
3667
+ */
3668
+ onRecording(callback: RecordingHandler): void;
3282
3669
  /**
3283
3670
  * Resolve the public WebSocket URL from `TACConfig.voicePublicDomain` +
3284
3671
  * `TACConfig.voiceWebsocketPath`. Throws if `voicePublicDomain` isn't set.
@@ -3439,6 +3826,35 @@ declare class VoiceChannel extends BaseChannel {
3439
3826
  * `actionUrl` left absent (key not present) falls through to the next layer.
3440
3827
  */
3441
3828
  private resolveActionUrl;
3829
+ /**
3830
+ * Overlay `perCall` onto `VoiceChannelConfig.defaultCallOptions`.
3831
+ *
3832
+ * Per-field via key presence, the same convention {@link overlayFields} uses
3833
+ * for TwiML options — so a per-call `{ machineDetection: undefined }`
3834
+ * explicitly clears the channel default rather than falling through to it.
3835
+ *
3836
+ * The result is always validated, for two reasons: a combination only
3837
+ * reachable by layering — per-call clearing `machineDetection` while the
3838
+ * default set `asyncAmd` — must still fail instead of reaching Twilio, and
3839
+ * `VoiceChannelConfig` is a plain interface, so `defaultCallOptions` has had
3840
+ * no runtime validation of its own.
3841
+ */
3842
+ private mergeCallOptions;
3843
+ /**
3844
+ * Build the extra arguments for `client.calls.create`.
3845
+ *
3846
+ * Layers, highest precedence first: this call's `callOptions`,
3847
+ * `VoiceChannelConfig.defaultCallOptions`, then callback URLs derived from
3848
+ * `voicePublicDomain` + `voiceCallEventPath`.
3849
+ *
3850
+ * A URL is derived only when its handler is registered. That's a deliberate
3851
+ * deviation from `websocketUrl` / `actionUrl`, which derive unconditionally:
3852
+ * those are load-bearing, so a wrong one fails loudly on the first call,
3853
+ * whereas an unwanted call-event URL fails as silent 11200 alerts for a
3854
+ * feature nobody asked for. Set the URLs in `defaultCallOptions` when TAC
3855
+ * isn't serving the routes.
3856
+ */
3857
+ private buildCallParams;
3442
3858
  /**
3443
3859
  * Initiate an outbound voice conversation
3444
3860
  *
@@ -3454,6 +3870,12 @@ declare class VoiceChannel extends BaseChannel {
3454
3870
  * `TACConfig`, and `actionUrl` from Studio handoff (if configured), else
3455
3871
  * derived from `TACConfig.voicePublicDomain` + `voiceActionPath`.
3456
3872
  *
3873
+ * Calls-API parameters merge the same way:
3874
+ * 1. `options.callOptions` — per-call overrides
3875
+ * 2. `VoiceChannelConfig.defaultCallOptions` — channel-wide defaults
3876
+ * 3. Callback URLs derived from `TACConfig.voicePublicDomain` +
3877
+ * `voiceCallEventPath`, for handlers that are registered
3878
+ *
3457
3879
  * The WebSocket URL is derived from `TACConfig.voicePublicDomain` +
3458
3880
  * `TACConfig.voiceWebsocketPath`, unless overridden per-call via
3459
3881
  * `options.websocketUrl`.
@@ -3471,6 +3893,122 @@ declare class VoiceChannel extends BaseChannel {
3471
3893
  content: string;
3472
3894
  contentType: string;
3473
3895
  }>;
3896
+ /**
3897
+ * Whether a call-webhook payload belongs to the configured account.
3898
+ *
3899
+ * Twilio signature validation already gates the route; this is defense in
3900
+ * depth. A payload with no `AccountSid` is allowed through.
3901
+ *
3902
+ * Subaccounts: events carry the SID the call was placed on, so configure TAC
3903
+ * with that account or its events get dropped here.
3904
+ */
3905
+ private callEventAccountOk;
3906
+ /**
3907
+ * Parse a call-event webhook form and dispatch it to its handler.
3908
+ *
3909
+ * Returns 400 when the payload can't be parsed (no `CallSid`) or the handler
3910
+ * throws — better than handing Twilio a 200 for an event that wasn't
3911
+ * processed. Everything else, including no handler registered and an
3912
+ * account mismatch, is a 200 no-op.
3913
+ */
3914
+ private dispatchCallEvent;
3915
+ /**
3916
+ * Handle a Twilio `statusCallback` webhook.
3917
+ *
3918
+ * The developer routes the request here (`TACServer` does this automatically
3919
+ * for its `/status` call-event route). Parsed into a {@link CallStatusEvent}
3920
+ * and dispatched to the {@link onCallStatus} handler. No-op if no handler is
3921
+ * registered.
3922
+ *
3923
+ * @param form - Raw form data from the webhook request.
3924
+ */
3925
+ handleCallStatusEvent(form: Record<string, string>): Promise<{
3926
+ status: number;
3927
+ content: string;
3928
+ contentType: string;
3929
+ }>;
3930
+ /**
3931
+ * Handle a Twilio `asyncAmdStatusCallback` webhook.
3932
+ *
3933
+ * The developer routes the request here (`TACServer` does this automatically
3934
+ * for its `/amd` call-event route). Parsed into an {@link AmdEvent} and
3935
+ * dispatched to the {@link onAmd} handler. No-op if no handler is registered.
3936
+ *
3937
+ * @param form - Raw form data from the webhook request.
3938
+ */
3939
+ handleAmdEvent(form: Record<string, string>): Promise<{
3940
+ status: number;
3941
+ content: string;
3942
+ contentType: string;
3943
+ }>;
3944
+ /**
3945
+ * Handle a Twilio `recordingStatusCallback` webhook.
3946
+ *
3947
+ * The developer routes the request here (`TACServer` does this automatically
3948
+ * for its `/recording` call-event route). Parsed into a
3949
+ * {@link RecordingEvent} and dispatched to the {@link onRecording} handler.
3950
+ * No-op if no handler is registered.
3951
+ *
3952
+ * @param form - Raw form data from the webhook request.
3953
+ */
3954
+ handleRecordingEvent(form: Record<string, string>): Promise<{
3955
+ status: number;
3956
+ content: string;
3957
+ contentType: string;
3958
+ }>;
3959
+ /**
3960
+ * Hang up a call and clean up its ConversationRelay session.
3961
+ *
3962
+ * Works on `callSid` alone, in any mode and before a session exists, so it's
3963
+ * safe from a call-event handler that fires before the first prompt. Session
3964
+ * cleanup no-ops if no tracked session matches.
3965
+ *
3966
+ * Does not throw — hanging up an already-ended call is routine (the callee
3967
+ * hangs up while AMD is still resolving), and handlers shouldn't have to
3968
+ * guard against it.
3969
+ *
3970
+ * @param callSid - Twilio Call SID (from a call event, the outbound result, or
3971
+ * `ConversationSession.callSid`).
3972
+ * @returns True if Twilio accepted the hangup, false if it failed (logged).
3973
+ * Session cleanup runs either way.
3974
+ */
3975
+ endCall(callSid: string): Promise<boolean>;
3976
+ /**
3977
+ * Look up the active voice session for a Twilio Call SID.
3978
+ *
3979
+ * Out-of-band code holding a CallSid — a dashboard route, an operator action,
3980
+ * a call-event handler — can't reach the session-facing methods, which are
3981
+ * keyed by conversation id: the Orchestrator conversation id in orchestrator
3982
+ * mode, the CallSid only in ConversationRelay-only mode.
3983
+ *
3984
+ * Sessions are created on the caller's first prompt, not at WebSocket setup,
3985
+ * so this returns `undefined` for a call that connected but hasn't been spoken
3986
+ * into. That includes `onAmd` under `machineDetection: 'Enable'`, which fires
3987
+ * before the first prompt by design — hang up with {@link endCall}, which
3988
+ * needs no session.
3989
+ *
3990
+ * At the other end, orchestrator mode keeps the session until Conversation
3991
+ * Orchestrator's CLOSED webhook, so it outlives the call and `onCallStatus` /
3992
+ * `onRecording` do resolve. Relay-only mode tears down on the
3993
+ * ConversationRelay callback instead, which races them.
3994
+ *
3995
+ * @example
3996
+ * ```typescript
3997
+ * async function nudge(callSid: string): Promise<void> {
3998
+ * const session = voiceChannel.getConversationSessionByCallSid(callSid);
3999
+ * if (session) {
4000
+ * await voiceChannel.sendResponse(session.conversationId, 'Still there?');
4001
+ * }
4002
+ * }
4003
+ * ```
4004
+ *
4005
+ * @param callSid - Twilio Call SID, e.g. from
4006
+ * `InitiateVoiceConversationResult.callSid` or a call event.
4007
+ * @returns The session, or `undefined` — no first prompt yet, the call ended,
4008
+ * or it landed on another instance (see the horizontal-scaling note in
4009
+ * CLAUDE.md).
4010
+ */
4011
+ getConversationSessionByCallSid(callSid: string): ConversationSession | undefined;
3474
4012
  /**
3475
4013
  * Start tracking a streaming task for a conversation
3476
4014
  *
@@ -3553,6 +4091,18 @@ declare function scrubObject(obj: unknown, seen?: WeakSet<object>): unknown;
3553
4091
  declare function maskPhone(phone: string): string;
3554
4092
  declare function maskEmail(email: string): string;
3555
4093
  declare function maskAddress(address: string): string;
4094
+ /**
4095
+ * Mask `<Parameter value="...">` contents in TwiML, keeping the names.
4096
+ *
4097
+ * `<Parameter>` children carry whatever the developer put in
4098
+ * `customParameters` — profile IDs, caller names. Names stay because knowing
4099
+ * which parameters were sent is the point of logging the TwiML.
4100
+ *
4101
+ * Handles either quote style. TAC's own TwiML comes from the Twilio SDK, which
4102
+ * always double-quotes, but this takes a plain string and shouldn't depend on
4103
+ * that to stay safe.
4104
+ */
4105
+ declare function redactTwimlParameters(twiml: string | undefined | null): string;
3556
4106
 
3557
4107
  /**
3558
4108
  * URL builders for Twilio Studio handoff.
@@ -3579,8 +4129,8 @@ declare function studioVoiceHandoffUrl(accountSid: string, flowSid: string): str
3579
4129
  /**
3580
4130
  * Processor for Conversation Intelligence operator result webhooks
3581
4131
  *
3582
- * Processes operator results from CI and creates observations or summaries
3583
- * in the Memory service based on the operator configuration.
4132
+ * Processes operator results from CI and creates conversation summaries in the
4133
+ * Memory service based on the operator configuration.
3584
4134
  */
3585
4135
  declare class OperatorResultProcessor {
3586
4136
  private readonly memoryClient;
@@ -3598,10 +4148,6 @@ declare class OperatorResultProcessor {
3598
4148
  * Process an individual operator result
3599
4149
  */
3600
4150
  private processOperatorResult;
3601
- /**
3602
- * Process an observation operator result
3603
- */
3604
- private processObservationEvent;
3605
4151
  /**
3606
4152
  * Process a summary operator result
3607
4153
  */
@@ -3737,7 +4283,7 @@ declare class MemoryPromptBuilder {
3737
4283
  *
3738
4284
  * Matches Python's TACTool dataclass with conversion methods.
3739
4285
  */
3740
- declare class TACTool<TParams = any, TResult = any> {
4286
+ declare class TACTool<TParams = unknown, TResult = unknown> {
3741
4287
  readonly name: string;
3742
4288
  readonly description: string;
3743
4289
  readonly parameters: JSONSchema;
@@ -3746,11 +4292,11 @@ declare class TACTool<TParams = any, TResult = any> {
3746
4292
  /**
3747
4293
  * Convert to OpenAI function calling format
3748
4294
  */
3749
- toOpenAIFormat(): Record<string, any>;
4295
+ toOpenAIFormat(): OpenAITool;
3750
4296
  /**
3751
4297
  * Convert to Anthropic tool calling format
3752
4298
  */
3753
- toAnthropicFormat(): Record<string, any>;
4299
+ toAnthropicFormat(): AnthropicTool;
3754
4300
  /**
3755
4301
  * Convert to JSON string (OpenAI format by default)
3756
4302
  */
@@ -3777,7 +4323,7 @@ declare class TACTool<TParams = any, TResult = any> {
3777
4323
  * Simplified approach matching Python's create_tool function.
3778
4324
  * No builder pattern - just a simple function call.
3779
4325
  */
3780
- declare function defineTool<TParams = any, TResult = any>(name: string, description: string, parameters: JSONSchema, implementation: ToolFunction<TParams, TResult>): TACTool<TParams, TResult>;
4326
+ declare function defineTool<TParams = unknown, TResult = unknown>(name: string, description: string, parameters: JSONSchema, implementation: ToolFunction<TParams, TResult>): TACTool<TParams, TResult>;
3781
4327
 
3782
4328
  /**
3783
4329
  * Parameters for memory retrieval tool
@@ -3839,9 +4385,6 @@ declare function createSendMessageTool(channel: BaseChannel, conversationId: Con
3839
4385
  * Create factory function for messaging tools
3840
4386
  */
3841
4387
  declare function createMessagingTools(): {
3842
- /**
3843
- * Create send message tool for specific channel and conversation
3844
- */
3845
4388
  forConversation: (channel: BaseChannel, conversationId: ConversationId) => TACTool<SendMessageParams, SendMessageResult>;
3846
4389
  };
3847
4390
 
@@ -4047,6 +4590,19 @@ declare class TACServer {
4047
4590
  /** All channels that need webhook processing (voice + messaging) */
4048
4591
  private readonly webhookChannels;
4049
4592
  constructor(tac: TAC, config?: TACServerConfig);
4593
+ /**
4594
+ * Validate `voiceCallEventPath`, the one path that isn't literal.
4595
+ *
4596
+ * Every other TAC path registers as configured, so a bad value is visible.
4597
+ * This one expands into three sub-paths, hiding a mistake the base path looks
4598
+ * innocent for: a sub-path colliding with another route while the base looks
4599
+ * unrelated (base `/hooks` vs `webhookPaths.twiml = '/hooks/status'`). Both
4600
+ * would register as POST routes and requests would reach the wrong handler.
4601
+ *
4602
+ * The leading-slash requirement is enforced by `TACConfigSchema` at parse
4603
+ * time, so it doesn't need re-checking here.
4604
+ */
4605
+ private validateCallEventPaths;
4050
4606
  private getForwardedProto;
4051
4607
  private getForwardedHost;
4052
4608
  /**
@@ -4080,4 +4636,4 @@ declare class TACServer {
4080
4636
  stop(): Promise<void>;
4081
4637
  }
4082
4638
 
4083
- export { type ActionChannelSettings, ActionChannelSettingsSchema, type ActionParticipantRef, ActionParticipantRefSchema, type ActionResponse, ActionResponseSchema, type ActionTextContent, ActionTextContentSchema, type AdapterOptions, type AuthorInfo, AuthorInfoSchema, BaseChannel, type BaseChannelEvents, type BaseChannelOptions, BaseClient, type BuiltInToolName, BuiltInTools, type CaptureRule, CaptureRuleSchema, type ChannelSettings, ChannelSettingsSchema, type ChannelType, ChannelTypeSchema, ChatChannel, type ChatChannelConfig, type CintelParticipant, CintelParticipantSchema, type Communication, type CommunicationContent, CommunicationContentSchema, type CommunicationParticipant, CommunicationParticipantSchema, CommunicationSchema, type ConversationAddress, ConversationAddressSchema, ConversationClient, type ConversationConfiguration, ConversationConfigurationSchema, type ConversationEndedCallback, type ConversationGroupingType, ConversationGroupingTypeSchema, type ConversationId, type ConversationIntelligenceConfig, ConversationIntelligenceConfigSchema, type ConversationParticipant, ConversationParticipantSchema, type ConversationRelayAttributes, ConversationRelayAttributesSchema, type ConversationRelayCallbackPayload, ConversationRelayCallbackPayloadSchema, type ConversationRelayConfig, ConversationRelayConfigSchema, type ConversationResponse, ConversationResponseSchema, type ConversationSession, ConversationSessionSchema, type ConversationSummaryItem, ConversationSummaryItemSchema, type ConversationWebhookPayload, type CreateConversationSummariesResponse, CreateConversationSummariesResponseSchema, type CreateObservationResponse, CreateObservationResponseSchema, type CustomParameters, CustomParametersSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, type ExecutionDetails, ExecutionDetailsSchema, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InboundCallTwimlHandler, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, InitiateVoiceConversationOptionsSchema, type InitiateVoiceConversationResult, type IntelligenceConfiguration, IntelligenceConfigurationSchema, type InterruptCallback, type InterruptMessage, InterruptMessageSchema, type InterruptMode, InterruptModeSchema, type JSONSchema, JSONSchemaSchema, type KnowledgeBase, KnowledgeBaseSchema, type KnowledgeBaseStatus, KnowledgeBaseStatusSchema, type KnowledgeChunkResult, KnowledgeChunkResultSchema, KnowledgeClient, type KnowledgeSearchResponse, KnowledgeSearchResponseSchema, type LanguageAttributes, LanguageAttributesSchema, type LanguageConfig, LanguageConfigSchema, type ListCommunicationsResponse, ListCommunicationsResponseSchema, type ListConversationsResponse, ListConversationsResponseSchema, type ListParticipantsResponse, ListParticipantsResponseSchema, type Logger, type MemoryChannelType, MemoryChannelTypeSchema, MemoryClient, type MemoryCommunication, type MemoryCommunicationContent, MemoryCommunicationContentSchema, MemoryCommunicationSchema, type MemoryDeliveryStatus, MemoryDeliveryStatusSchema, type MemoryMode, MemoryModeSchema, type MemoryParticipant, MemoryParticipantSchema, type MemoryParticipantType, MemoryParticipantTypeSchema, MemoryPromptBuilder, type MemoryRetrievalRequest, MemoryRetrievalRequestSchema, type MemoryRetrievalResponse, MemoryRetrievalResponseSchema, type MessageDirection, MessageDirectionSchema, type MessageReadyCallback, MessagingChannel, type MessagingChannelConfig, type MessagingChannelEvents, type ObservationInfo, ObservationInfoSchema, type OpenAITool, OpenAIToolSchema, type Operator, type OperatorProcessingResult, OperatorProcessingResultSchema, type OperatorResult, type OperatorResultEvent, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, type ParticipantAddress, ParticipantAddressSchema, type ParticipantAddressType, ParticipantAddressTypeSchema, type ParticipantId, type PendingHandoffData, PendingHandoffDataSchema, type Profile, type ProfileId, type ProfileLookupResponse, ProfileLookupResponseSchema, type ProfileResponse, ProfileResponseSchema, type PromptMessage, PromptMessageSchema, RCSChannel, SMSChannel, type SendMessageActionPayload, SendMessageActionPayloadSchema, type SendMessageActionRequest, SendMessageActionRequestSchema, type SessionInfo, SessionInfoSchema, type SessionMessage, SessionMessageSchema, type SetupMessage, SetupMessageSchema, type StatusCallback, StatusCallbackSchema, type StatusTimeouts, StatusTimeoutsSchema, type StreamTask, type SummaryInfo, SummaryInfoSchema, TAC, type TACChannelType, TACChannelTypeSchema, type TACCommunication, type TACCommunicationAuthor, TACCommunicationAuthorSchema, type TACCommunicationContent, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, type TACConfigData, TACConfigSchema, type TACDeliveryStatus, TACDeliveryStatusSchema, TACMemoryResponse, type TACOptions, type TACParticipantType, TACParticipantTypeSchema, TACServer, type TACServerConfig, TACTool, type TextTokenMessage, TextTokenMessageSchema, type ToolContext, type ToolExecutionResult, ToolExecutionResultSchema, type ToolFunction, type Transcription, TranscriptionSchema, type TranscriptionWord, TranscriptionWordSchema, type TwiMLOptions, TwiMLOptionsSchema, type TwiMLRequest, TwiMLRequestSchema, type TwilioMemoryConfig, TwilioMemoryConfigSchema, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _SDKDriftGuards, buildHandoffPayload, createKnowledgeSearchTool, createKnowledgeSearchToolAsync, createKnowledgeTools, createLogger, createMemoryRetrievalTool, createMemoryTools, createMessagingTools, createSendMessageTool, createStudioHandoffTool, defineTool, isConversationId, isParticipantId, isProfileId, maskAddress, maskEmail, maskPhone, postStudioHandoff, scrubObject, scrubPii, studioExecutionsUrl, studioVoiceHandoffUrl, twiMLRequestFromForm };
4639
+ export { type ActionChannelSettings, ActionChannelSettingsSchema, type ActionParticipantRef, ActionParticipantRefSchema, type ActionResponse, ActionResponseSchema, type ActionTextContent, ActionTextContentSchema, type AdapterOptions, type AmdEvent, AmdEventSchema, type AmdHandler, type AnthropicTool, AnthropicToolSchema, type AuthorInfo, AuthorInfoSchema, BaseChannel, type BaseChannelEvents, type BaseChannelOptions, BaseClient, type BuiltInToolName, BuiltInTools, CALL_EVENT_KINDS, type CallEventKind, CallEventKindSchema, type CallOptions, CallOptionsSchema, type CallStatusEvent, CallStatusEventSchema, type CallStatusHandler, type CaptureRule, CaptureRuleSchema, type ChannelSettings, ChannelSettingsSchema, type ChannelType, ChannelTypeSchema, ChatChannel, type ChatChannelConfig, type CintelParticipant, CintelParticipantSchema, type Communication, type CommunicationContent, CommunicationContentSchema, type CommunicationParticipant, CommunicationParticipantSchema, CommunicationSchema, type ConversationAddress, ConversationAddressSchema, ConversationClient, type ConversationConfiguration, ConversationConfigurationSchema, type ConversationEndedCallback, type ConversationGroupingType, ConversationGroupingTypeSchema, type ConversationId, type ConversationIntelligenceConfig, ConversationIntelligenceConfigSchema, type ConversationParticipant, ConversationParticipantSchema, type ConversationRelayAttributes, ConversationRelayAttributesSchema, type ConversationRelayCallbackPayload, ConversationRelayCallbackPayloadSchema, type ConversationRelayConfig, ConversationRelayConfigSchema, type ConversationResponse, ConversationResponseSchema, type ConversationSession, ConversationSessionSchema, type ConversationSummaryItem, ConversationSummaryItemSchema, type ConversationWebhookPayload, type CreateConversationSummariesResponse, CreateConversationSummariesResponseSchema, type CreateObservationResponse, CreateObservationResponseSchema, type CreateObservationsRequest, CreateObservationsRequestSchema, type CustomParameters, CustomParametersSchema, EMPTY_MEMORY_RESPONSE, EnvironmentVariables, type ExecutionDetails, ExecutionDetailsSchema, type HandoffPayload, HandoffPayloadSchema, type HandoffResult, type InboundCallTwimlHandler, type InitiateChatConversationOptions, type InitiateConversationResult, type InitiateMessagingConversationOptions, InitiateMessagingConversationOptionsSchema, type InitiateVoiceConversationOptions, InitiateVoiceConversationOptionsSchema, type InitiateVoiceConversationResult, type IntelligenceConfiguration, IntelligenceConfigurationSchema, type InterruptCallback, type InterruptMessage, InterruptMessageSchema, type InterruptMode, InterruptModeSchema, type JSONSchema, JSONSchemaSchema, type KnowledgeBase, KnowledgeBaseSchema, type KnowledgeBaseStatus, KnowledgeBaseStatusSchema, type KnowledgeChunkResult, KnowledgeChunkResultSchema, KnowledgeClient, type KnowledgeSearchResponse, KnowledgeSearchResponseSchema, type LanguageAttributes, LanguageAttributesSchema, type LanguageConfig, LanguageConfigSchema, type ListCommunicationsResponse, ListCommunicationsResponseSchema, type ListConversationsResponse, ListConversationsResponseSchema, type ListParticipantsResponse, ListParticipantsResponseSchema, type Logger, type MemoryChannelType, MemoryChannelTypeSchema, MemoryClient, type MemoryCommunication, type MemoryCommunicationContent, MemoryCommunicationContentSchema, MemoryCommunicationSchema, type MemoryDeliveryStatus, MemoryDeliveryStatusSchema, type MemoryMode, MemoryModeSchema, type MemoryParticipant, MemoryParticipantSchema, type MemoryParticipantType, MemoryParticipantTypeSchema, MemoryPromptBuilder, type MemoryRetrievalRequest, MemoryRetrievalRequestSchema, type MemoryRetrievalResponse, MemoryRetrievalResponseSchema, type MessageDirection, MessageDirectionSchema, type MessageReadyCallback, MessagingChannel, type MessagingChannelConfig, type MessagingChannelEvents, type ObservationCreateRequest, ObservationCreateRequestSchema, type ObservationInfo, ObservationInfoSchema, type OpenAITool, OpenAIToolSchema, type Operator, type OperatorProcessingResult, OperatorProcessingResultSchema, type OperatorResult, type OperatorResultEvent, OperatorResultEventSchema, OperatorResultProcessor, OperatorResultSchema, OperatorSchema, type ParticipantAddress, ParticipantAddressSchema, type ParticipantAddressType, ParticipantAddressTypeSchema, type ParticipantId, type PendingHandoffData, PendingHandoffDataSchema, type Profile, type ProfileId, type ProfileLookupResponse, ProfileLookupResponseSchema, type ProfileResponse, ProfileResponseSchema, type PromptMessage, PromptMessageSchema, RCSChannel, type RecordingEvent, RecordingEventSchema, type RecordingHandler, SMSChannel, type SendMessageActionPayload, SendMessageActionPayloadSchema, type SendMessageActionRequest, SendMessageActionRequestSchema, type SessionInfo, SessionInfoSchema, type SessionMessage, SessionMessageSchema, type SetupMessage, SetupMessageSchema, type StatusCallback, StatusCallbackSchema, type StatusTimeouts, StatusTimeoutsSchema, type StreamTask, type SummaryInfo, SummaryInfoSchema, TAC, type TACChannelType, TACChannelTypeSchema, type TACCommunication, type TACCommunicationAuthor, TACCommunicationAuthorSchema, type TACCommunicationContent, TACCommunicationContentSchema, TACCommunicationSchema, TACConfig, type TACConfigData, TACConfigSchema, type TACDeliveryStatus, TACDeliveryStatusSchema, TACMemoryResponse, type TACOptions, type TACParticipantType, TACParticipantTypeSchema, TACServer, type TACServerConfig, TACTool, type TextTokenMessage, TextTokenMessageSchema, type ToolContext, type ToolExecutionResult, ToolExecutionResultSchema, type ToolFunction, type Transcription, TranscriptionSchema, type TranscriptionWord, TranscriptionWordSchema, type TwiMLOptions, TwiMLOptionsSchema, type TwiMLRequest, TwiMLRequestSchema, type TwilioMemoryConfig, TwilioMemoryConfigSchema, type TypedCallOptions, VoiceChannel, type VoiceChannelConfig, type VoiceChannelEvents, type WebSocketMessage, WebSocketMessageSchema, WhatsAppChannel, type _CallsCreateDriftGuards, type _SDKDriftGuards, 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 };