@voicelayer/sdk 0.1.11 → 0.3.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.
Files changed (9) hide show
  1. package/README.md +8 -0
  2. package/dist/brain/index.d.ts +283 -0
  3. package/dist/brain/index.js +3550 -0
  4. package/dist/index.d.ts +1472 -1588
  5. package/dist/index.js +9129 -6719
  6. package/dist/runtime/text-session.d.ts +2 -1
  7. package/dist/runtime/text-session.js +1969 -98
  8. package/dist/{text-session-D1j8nQac.d.ts → text-session-B7oyrhwQ.d.ts} +403 -308
  9. package/package.json +11 -6
package/dist/index.d.ts CHANGED
@@ -1,8 +1,130 @@
1
- import { A as AgentDTO, a as AgentStatus, b as AgentEnvironment, P as ProcessSchemaDTO, c as AgentContext, d as Participant, C as CallInfo } from './text-session-D1j8nQac.js';
2
- export { e as AgentTurnEvent, f as AudioProfile, g as AudioSurface, h as ChannelKind, D as DtmfEvent, i as DtmfHandler, E as EndCallControllerHandle, j as EndCallOutcome, F as FakeSessionAdapter, k as FloorControlConfig, I as InboundOptions, L as LK_AGENT_STATE_MAP, M as MemoryHandle, l as MetricsEvent, N as NON_BUSY_STATES, m as ParticipantId, n as ParticipantKind, o as ParticipantSet, p as ProcessSnapshot, R as RespondOptions, q as Room, r as RouteEntry, s as RoutingRule, t as RoutingSnapshot, u as RunTextSessionOptions, v as RunTextTranscriptOptions, S as SayOptions, w as SendDtmfOptions, x as SessionAdapter, y as SessionCapabilities, z as SessionErrorEvent, B as SessionEvent, G as SessionEventMap, H as SessionFactory, J as SessionFactoryInput, K as SessionOutbound, O as SessionState, Q as SpeechResult, T as SpeechTarget, U as StateChangeEvent, V as TextSession, W as TextTranscriptResult, X as TtsVoiceConfig, Y as TurnEvent, Z as Unsubscribe, _ as UserInputEvent, $ as UserTurn, a0 as applySpeechTurnHandling, a1 as dtmfCodeToDigit, a2 as dtmfDigitToCode, a3 as duck, a4 as mute, a5 as normalizeState, m as participantId, a6 as passthrough, a7 as runTextSession, a8 as runTextTranscript, a9 as transform } from './text-session-D1j8nQac.js';
1
+ import { A as AgentDTO, a as AgentStatus, b as AgentEnvironment, c as AgentContext, P as Participant, C as CallInfo, d as ProcessSchemaDTO } from './text-session-B7oyrhwQ.js';
2
+ export { e as AgentTurnEvent, f as AudioProfile, g as AudioSurface, h as ChannelKind, D as DtmfEvent, i as DtmfHandler, E as EndCallControllerHandle, j as EndCallOutcome, F as FakeSessionAdapter, k as FloorControlConfig, I as InboundOptions, L as LK_AGENT_STATE_MAP, M as MemoryHandle, l as MetricsEvent, N as NON_BUSY_STATES, m as ParticipantId, n as ParticipantKind, o as ParticipantSet, p as ProcessSnapshot, R as RespondOptions, q as Room, r as RouteEntry, s as RoutingRule, t as RoutingSnapshot, u as RunTextSessionOptions, v as RunTextTranscriptOptions, S as SayOptions, w as SendDtmfOptions, x as SessionAdapter, y as SessionCapabilities, z as SessionErrorEvent, B as SessionEvent, G as SessionEventMap, H as SessionFactory, J as SessionFactoryInput, K as SessionOutbound, O as SessionState, Q as SpeechResult, T as SpeechTarget, U as StateChangeEvent, V as TextSession, W as TextTranscriptResult, X as TtsVoiceConfig, Y as TurnEvent, Z as Unsubscribe, _ as UserInputEvent, $ as UserStateEvent, a0 as UserTurn, a1 as applySpeechTurnHandling, a2 as dtmfCodeToDigit, a3 as dtmfDigitToCode, a4 as duck, a5 as mute, a6 as normalizeState, m as participantId, a7 as passthrough, a8 as runTextSession, a9 as runTextTranscript, aa as transform } from './text-session-B7oyrhwQ.js';
3
3
  import { z, ZodType } from 'zod';
4
- import { llm } from '@livekit/agents';
5
- import { Redis } from 'ioredis';
4
+ import { OnQuery, BrainTransport } from './brain/index.js';
5
+ export { BrainCallMetadata, BrainCapabilities, BrainChunk, BrainConfigError, BrainEndpointConfig, BrainMessage, BrainPubSub, BrainRequest, BrainRequestError, ConnectorChatModel, ConnectorChatModelOptions, ConnectorLLMOptions, IncomingBrainRequest, OnQueryContext, OnQueryResult, RedisBrainPubSub, SseDelta, TunnelBrainTransportOptions, assertPublicHttpsUrl, buildRedisBrainPubSub, callbackTransport, createConnectorLLM, httpBrainTransport, parseChatCompletionSse, runBrainRequest, tunnelBrainTransport } from './brain/index.js';
6
+ import '@livekit/agents';
7
+ import 'openai';
8
+ import 'ioredis';
9
+
10
+ /** What the worker fetches: the message, the conversation before it, and who sent it. */
11
+ declare const TextTurn: z.ZodObject<{
12
+ turnId: z.ZodString;
13
+ agentId: z.ZodString;
14
+ /** The Line the message came in on (`sms`, `discord`, `web`, `playground`, …). */
15
+ channel: z.ZodString;
16
+ /** The sender on that Line (phone number, Discord user, widget visitor) — the agent's caller-scoped memory key. */
17
+ from: z.ZodString;
18
+ /** The conversation this turn belongs to (stable across turns) — the tool context's call id. */
19
+ conversationKey: z.ZodString;
20
+ history: z.ZodArray<z.ZodObject<{
21
+ role: z.ZodEnum<["user", "assistant"]>;
22
+ content: z.ZodString;
23
+ }, "strip", z.ZodTypeAny, {
24
+ role: "user" | "assistant";
25
+ content: string;
26
+ }, {
27
+ role: "user" | "assistant";
28
+ content: string;
29
+ }>, "many">;
30
+ text: z.ZodString;
31
+ /** When the API stops waiting; the worker stops the run before it. */
32
+ deadlineAt: z.ZodString;
33
+ }, "strip", z.ZodTypeAny, {
34
+ text: string;
35
+ from: string;
36
+ agentId: string;
37
+ turnId: string;
38
+ channel: string;
39
+ conversationKey: string;
40
+ history: {
41
+ role: "user" | "assistant";
42
+ content: string;
43
+ }[];
44
+ deadlineAt: string;
45
+ }, {
46
+ text: string;
47
+ from: string;
48
+ agentId: string;
49
+ turnId: string;
50
+ channel: string;
51
+ conversationKey: string;
52
+ history: {
53
+ role: "user" | "assistant";
54
+ content: string;
55
+ }[];
56
+ deadlineAt: string;
57
+ }>;
58
+ type TextTurn = z.infer<typeof TextTurn>;
59
+ declare const TextTurnReply: z.ZodUnion<[z.ZodObject<{
60
+ agentId: z.ZodString;
61
+ replies: z.ZodArray<z.ZodString, "many">;
62
+ usage: z.ZodDefault<z.ZodArray<z.ZodObject<{
63
+ provider: z.ZodString;
64
+ model: z.ZodString;
65
+ inputTokens: z.ZodNumber;
66
+ outputTokens: z.ZodNumber;
67
+ /** Only a first-party worker's label is used; a customer's worker runs on its own key (the API decides). */
68
+ byok: z.ZodBoolean;
69
+ }, "strip", z.ZodTypeAny, {
70
+ provider: string;
71
+ model: string;
72
+ inputTokens: number;
73
+ outputTokens: number;
74
+ byok: boolean;
75
+ }, {
76
+ provider: string;
77
+ model: string;
78
+ inputTokens: number;
79
+ outputTokens: number;
80
+ byok: boolean;
81
+ }>, "many">>;
82
+ }, "strip", z.ZodTypeAny, {
83
+ replies: string[];
84
+ agentId: string;
85
+ usage: {
86
+ provider: string;
87
+ model: string;
88
+ inputTokens: number;
89
+ outputTokens: number;
90
+ byok: boolean;
91
+ }[];
92
+ }, {
93
+ replies: string[];
94
+ agentId: string;
95
+ usage?: {
96
+ provider: string;
97
+ model: string;
98
+ inputTokens: number;
99
+ outputTokens: number;
100
+ byok: boolean;
101
+ }[] | undefined;
102
+ }>, z.ZodObject<{
103
+ agentId: z.ZodString;
104
+ error: z.ZodObject<{
105
+ code: z.ZodEnum<["agent_unavailable", "agent_timeout"]>;
106
+ detail: z.ZodOptional<z.ZodString>;
107
+ }, "strip", z.ZodTypeAny, {
108
+ code: "agent_unavailable" | "agent_timeout";
109
+ detail?: string | undefined;
110
+ }, {
111
+ code: "agent_unavailable" | "agent_timeout";
112
+ detail?: string | undefined;
113
+ }>;
114
+ }, "strip", z.ZodTypeAny, {
115
+ error: {
116
+ code: "agent_unavailable" | "agent_timeout";
117
+ detail?: string | undefined;
118
+ };
119
+ agentId: string;
120
+ }, {
121
+ error: {
122
+ code: "agent_unavailable" | "agent_timeout";
123
+ detail?: string | undefined;
124
+ };
125
+ agentId: string;
126
+ }>]>;
127
+ type TextTurnReply = z.infer<typeof TextTurnReply>;
6
128
 
7
129
  /**
8
130
  * The plan itself. Everything the agent needs to run the call without the
@@ -27,7 +149,6 @@ declare const CallPlan: z.ZodObject<{
27
149
  displayName?: string | undefined;
28
150
  }>;
29
151
  draftConfig: z.ZodDefault<z.ZodObject<{
30
- source: z.ZodOptional<z.ZodOptional<z.ZodEnum<["sdk", "flow", "playbook", "connector"]>>>;
31
152
  name: z.ZodOptional<z.ZodString>;
32
153
  triggers: z.ZodOptional<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
33
154
  on: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
@@ -35,22 +156,22 @@ declare const CallPlan: z.ZodObject<{
35
156
  pattern: z.ZodString;
36
157
  flags: z.ZodOptional<z.ZodString>;
37
158
  }, "strip", z.ZodTypeAny, {
38
- kind: "regex";
39
159
  pattern: string;
160
+ kind: "regex";
40
161
  flags?: string | undefined;
41
162
  }, {
42
- kind: "regex";
43
163
  pattern: string;
164
+ kind: "regex";
44
165
  flags?: string | undefined;
45
166
  }>, z.ZodObject<{
46
167
  kind: z.ZodLiteral<"signal">;
47
168
  name: z.ZodString;
48
169
  }, "strip", z.ZodTypeAny, {
49
- kind: "signal";
50
170
  name: string;
51
- }, {
52
171
  kind: "signal";
172
+ }, {
53
173
  name: string;
174
+ kind: "signal";
54
175
  }>]>;
55
176
  then: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
56
177
  kind: z.ZodLiteral<"handoff">;
@@ -68,11 +189,11 @@ declare const CallPlan: z.ZodObject<{
68
189
  kind: z.ZodLiteral<"say">;
69
190
  text: z.ZodString;
70
191
  }, "strip", z.ZodTypeAny, {
71
- kind: "say";
72
192
  text: string;
73
- }, {
74
193
  kind: "say";
194
+ }, {
75
195
  text: string;
196
+ kind: "say";
76
197
  }>]>;
77
198
  onlyWhile: z.ZodOptional<z.ZodString>;
78
199
  }, "strip", z.ZodTypeAny, {
@@ -81,16 +202,16 @@ declare const CallPlan: z.ZodObject<{
81
202
  } | {
82
203
  kind: "endCall";
83
204
  } | {
84
- kind: "say";
85
205
  text: string;
206
+ kind: "say";
86
207
  };
87
208
  on: {
88
- kind: "regex";
89
209
  pattern: string;
210
+ kind: "regex";
90
211
  flags?: string | undefined;
91
212
  } | {
92
- kind: "signal";
93
213
  name: string;
214
+ kind: "signal";
94
215
  };
95
216
  onlyWhile?: string | undefined;
96
217
  }, {
@@ -99,16 +220,16 @@ declare const CallPlan: z.ZodObject<{
99
220
  } | {
100
221
  kind: "endCall";
101
222
  } | {
102
- kind: "say";
103
223
  text: string;
224
+ kind: "say";
104
225
  };
105
226
  on: {
106
- kind: "regex";
107
227
  pattern: string;
228
+ kind: "regex";
108
229
  flags?: string | undefined;
109
230
  } | {
110
- kind: "signal";
111
231
  name: string;
232
+ kind: "signal";
112
233
  };
113
234
  onlyWhile?: string | undefined;
114
235
  }>>>>;
@@ -122,27 +243,44 @@ declare const CallPlan: z.ZodObject<{
122
243
  toolName: string;
123
244
  defaultArgs?: Record<string, unknown> | undefined;
124
245
  }>, "many">>>;
125
- mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["cascade", "realtime"]>>>;
126
- model: z.ZodOptional<z.ZodObject<{
127
- provider: z.ZodEnum<["openai", "anthropic", "gemini"]>;
246
+ stt: z.ZodOptional<z.ZodOptional<z.ZodObject<{
247
+ provider: z.ZodEnum<["deepgram", "cartesia", "assemblyai"]>;
248
+ model: z.ZodOptional<z.ZodString>;
249
+ language: z.ZodOptional<z.ZodString>;
250
+ endOfTurnConfidence: z.ZodOptional<z.ZodNumber>;
251
+ endOfTurnTimeoutMs: z.ZodOptional<z.ZodNumber>;
252
+ keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
253
+ }, "strip", z.ZodTypeAny, {
254
+ provider: "deepgram" | "cartesia" | "assemblyai";
255
+ model?: string | undefined;
256
+ language?: string | undefined;
257
+ endOfTurnConfidence?: number | undefined;
258
+ endOfTurnTimeoutMs?: number | undefined;
259
+ keywords?: string[] | undefined;
260
+ }, {
261
+ provider: "deepgram" | "cartesia" | "assemblyai";
262
+ model?: string | undefined;
263
+ language?: string | undefined;
264
+ endOfTurnConfidence?: number | undefined;
265
+ endOfTurnTimeoutMs?: number | undefined;
266
+ keywords?: string[] | undefined;
267
+ }>>>;
268
+ realtime: z.ZodOptional<z.ZodOptional<z.ZodObject<{
269
+ provider: z.ZodEnum<["openai", "google"]>;
128
270
  model: z.ZodString;
271
+ voice: z.ZodOptional<z.ZodString>;
129
272
  temperature: z.ZodOptional<z.ZodNumber>;
130
- maxOutputTokens: z.ZodOptional<z.ZodNumber>;
131
- topP: z.ZodOptional<z.ZodNumber>;
132
273
  }, "strip", z.ZodTypeAny, {
133
- provider: "openai" | "anthropic" | "gemini";
274
+ provider: "openai" | "google";
134
275
  model: string;
276
+ voice?: string | undefined;
135
277
  temperature?: number | undefined;
136
- maxOutputTokens?: number | undefined;
137
- topP?: number | undefined;
138
278
  }, {
139
- provider: "openai" | "anthropic" | "gemini";
279
+ provider: "openai" | "google";
140
280
  model: string;
281
+ voice?: string | undefined;
141
282
  temperature?: number | undefined;
142
- maxOutputTokens?: number | undefined;
143
- topP?: number | undefined;
144
- }>>;
145
- language: z.ZodOptional<z.ZodDefault<z.ZodString>>;
283
+ }>>>;
146
284
  voice: z.ZodOptional<z.ZodObject<{
147
285
  provider: z.ZodEnum<["deepgram", "elevenlabs", "openai", "cartesia"]>;
148
286
  voiceId: z.ZodString;
@@ -159,46 +297,30 @@ declare const CallPlan: z.ZodObject<{
159
297
  model?: string | undefined;
160
298
  rate?: number | undefined;
161
299
  }>>;
162
- realtime: z.ZodOptional<z.ZodOptional<z.ZodObject<{
163
- provider: z.ZodEnum<["openai", "google"]>;
300
+ source: z.ZodOptional<z.ZodOptional<z.ZodEnum<["sdk", "flow", "playbook", "connector"]>>>;
301
+ mode: z.ZodOptional<z.ZodDefault<z.ZodEnum<["cascade", "realtime"]>>>;
302
+ model: z.ZodOptional<z.ZodObject<{
303
+ provider: z.ZodEnum<["openai", "anthropic", "gemini"]>;
164
304
  model: z.ZodString;
165
- voice: z.ZodOptional<z.ZodString>;
166
305
  temperature: z.ZodOptional<z.ZodNumber>;
306
+ maxOutputTokens: z.ZodOptional<z.ZodNumber>;
307
+ topP: z.ZodOptional<z.ZodNumber>;
167
308
  }, "strip", z.ZodTypeAny, {
168
- provider: "openai" | "google";
309
+ provider: "openai" | "anthropic" | "gemini";
169
310
  model: string;
170
311
  temperature?: number | undefined;
171
- voice?: string | undefined;
312
+ maxOutputTokens?: number | undefined;
313
+ topP?: number | undefined;
172
314
  }, {
173
- provider: "openai" | "google";
315
+ provider: "openai" | "anthropic" | "gemini";
174
316
  model: string;
175
317
  temperature?: number | undefined;
176
- voice?: string | undefined;
177
- }>>>;
318
+ maxOutputTokens?: number | undefined;
319
+ topP?: number | undefined;
320
+ }>>;
321
+ language: z.ZodOptional<z.ZodDefault<z.ZodString>>;
178
322
  systemPrompt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
179
323
  routingInstructions: z.ZodOptional<z.ZodOptional<z.ZodString>>;
180
- stt: z.ZodOptional<z.ZodOptional<z.ZodObject<{
181
- provider: z.ZodEnum<["deepgram", "cartesia", "assemblyai"]>;
182
- model: z.ZodOptional<z.ZodString>;
183
- language: z.ZodOptional<z.ZodString>;
184
- endOfTurnConfidence: z.ZodOptional<z.ZodNumber>;
185
- endOfTurnTimeoutMs: z.ZodOptional<z.ZodNumber>;
186
- keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
187
- }, "strip", z.ZodTypeAny, {
188
- provider: "deepgram" | "cartesia" | "assemblyai";
189
- model?: string | undefined;
190
- language?: string | undefined;
191
- endOfTurnConfidence?: number | undefined;
192
- endOfTurnTimeoutMs?: number | undefined;
193
- keywords?: string[] | undefined;
194
- }, {
195
- provider: "deepgram" | "cartesia" | "assemblyai";
196
- model?: string | undefined;
197
- language?: string | undefined;
198
- endOfTurnConfidence?: number | undefined;
199
- endOfTurnTimeoutMs?: number | undefined;
200
- keywords?: string[] | undefined;
201
- }>>>;
202
324
  consultation: z.ZodOptional<z.ZodObject<{
203
325
  enabled: z.ZodDefault<z.ZodBoolean>;
204
326
  defaultTimeoutMs: z.ZodDefault<z.ZodNumber>;
@@ -283,12 +405,12 @@ declare const CallPlan: z.ZodObject<{
283
405
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
284
406
  }, "strip", z.ZodTypeAny, {
285
407
  url: string;
286
- headers?: Record<string, string> | undefined;
287
408
  timeoutMs?: number | undefined;
409
+ headers?: Record<string, string> | undefined;
288
410
  }, {
289
411
  url: string;
290
- headers?: Record<string, string> | undefined;
291
412
  timeoutMs?: number | undefined;
413
+ headers?: Record<string, string> | undefined;
292
414
  }>>;
293
415
  }, "strip", z.ZodTypeAny, {
294
416
  collect: Record<string, {
@@ -304,14 +426,14 @@ declare const CallPlan: z.ZodObject<{
304
426
  completeWhen: "all-required-captured" | "all-captured";
305
427
  backendAck?: {
306
428
  url: string;
307
- headers?: Record<string, string> | undefined;
308
429
  timeoutMs?: number | undefined;
430
+ headers?: Record<string, string> | undefined;
309
431
  } | undefined;
310
432
  }, {
311
433
  backendAck?: {
312
434
  url: string;
313
- headers?: Record<string, string> | undefined;
314
435
  timeoutMs?: number | undefined;
436
+ headers?: Record<string, string> | undefined;
315
437
  } | undefined;
316
438
  collect?: Record<string, {
317
439
  type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
@@ -348,7 +470,6 @@ declare const CallPlan: z.ZodObject<{
348
470
  description?: string | undefined;
349
471
  }>, "many">>>;
350
472
  }, "strip", z.ZodTypeAny, {
351
- source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
352
473
  name?: string | undefined;
353
474
  triggers?: Record<string, {
354
475
  then: {
@@ -356,16 +477,16 @@ declare const CallPlan: z.ZodObject<{
356
477
  } | {
357
478
  kind: "endCall";
358
479
  } | {
359
- kind: "say";
360
480
  text: string;
481
+ kind: "say";
361
482
  };
362
483
  on: {
363
- kind: "regex";
364
484
  pattern: string;
485
+ kind: "regex";
365
486
  flags?: string | undefined;
366
487
  } | {
367
- kind: "signal";
368
488
  name: string;
489
+ kind: "signal";
369
490
  };
370
491
  onlyWhile?: string | undefined;
371
492
  }> | undefined;
@@ -373,37 +494,38 @@ declare const CallPlan: z.ZodObject<{
373
494
  toolName: string;
374
495
  defaultArgs?: Record<string, unknown> | undefined;
375
496
  }[] | undefined;
376
- mode?: "cascade" | "realtime" | undefined;
377
- model?: {
378
- provider: "openai" | "anthropic" | "gemini";
497
+ stt?: {
498
+ provider: "deepgram" | "cartesia" | "assemblyai";
499
+ model?: string | undefined;
500
+ language?: string | undefined;
501
+ endOfTurnConfidence?: number | undefined;
502
+ endOfTurnTimeoutMs?: number | undefined;
503
+ keywords?: string[] | undefined;
504
+ } | undefined;
505
+ realtime?: {
506
+ provider: "openai" | "google";
379
507
  model: string;
508
+ voice?: string | undefined;
380
509
  temperature?: number | undefined;
381
- maxOutputTokens?: number | undefined;
382
- topP?: number | undefined;
383
510
  } | undefined;
384
- language?: string | undefined;
385
511
  voice?: {
386
512
  provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
387
513
  voiceId: string;
388
514
  model?: string | undefined;
389
515
  rate?: number | undefined;
390
516
  } | undefined;
391
- realtime?: {
392
- provider: "openai" | "google";
517
+ source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
518
+ mode?: "realtime" | "cascade" | undefined;
519
+ model?: {
520
+ provider: "openai" | "anthropic" | "gemini";
393
521
  model: string;
394
522
  temperature?: number | undefined;
395
- voice?: string | undefined;
523
+ maxOutputTokens?: number | undefined;
524
+ topP?: number | undefined;
396
525
  } | undefined;
526
+ language?: string | undefined;
397
527
  systemPrompt?: string | undefined;
398
528
  routingInstructions?: string | undefined;
399
- stt?: {
400
- provider: "deepgram" | "cartesia" | "assemblyai";
401
- model?: string | undefined;
402
- language?: string | undefined;
403
- endOfTurnConfidence?: number | undefined;
404
- endOfTurnTimeoutMs?: number | undefined;
405
- keywords?: string[] | undefined;
406
- } | undefined;
407
529
  consultation?: {
408
530
  enabled: boolean;
409
531
  defaultTimeoutMs: number;
@@ -432,8 +554,8 @@ declare const CallPlan: z.ZodObject<{
432
554
  completeWhen: "all-required-captured" | "all-captured";
433
555
  backendAck?: {
434
556
  url: string;
435
- headers?: Record<string, string> | undefined;
436
557
  timeoutMs?: number | undefined;
558
+ headers?: Record<string, string> | undefined;
437
559
  } | undefined;
438
560
  } | undefined;
439
561
  tags?: string[] | undefined;
@@ -447,7 +569,6 @@ declare const CallPlan: z.ZodObject<{
447
569
  description?: string | undefined;
448
570
  }[] | undefined;
449
571
  }, {
450
- source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
451
572
  name?: string | undefined;
452
573
  triggers?: Record<string, {
453
574
  then: {
@@ -455,16 +576,16 @@ declare const CallPlan: z.ZodObject<{
455
576
  } | {
456
577
  kind: "endCall";
457
578
  } | {
458
- kind: "say";
459
579
  text: string;
580
+ kind: "say";
460
581
  };
461
582
  on: {
462
- kind: "regex";
463
583
  pattern: string;
584
+ kind: "regex";
464
585
  flags?: string | undefined;
465
586
  } | {
466
- kind: "signal";
467
587
  name: string;
588
+ kind: "signal";
468
589
  };
469
590
  onlyWhile?: string | undefined;
470
591
  }> | undefined;
@@ -472,37 +593,38 @@ declare const CallPlan: z.ZodObject<{
472
593
  toolName: string;
473
594
  defaultArgs?: Record<string, unknown> | undefined;
474
595
  }[] | undefined;
475
- mode?: "cascade" | "realtime" | undefined;
476
- model?: {
477
- provider: "openai" | "anthropic" | "gemini";
596
+ stt?: {
597
+ provider: "deepgram" | "cartesia" | "assemblyai";
598
+ model?: string | undefined;
599
+ language?: string | undefined;
600
+ endOfTurnConfidence?: number | undefined;
601
+ endOfTurnTimeoutMs?: number | undefined;
602
+ keywords?: string[] | undefined;
603
+ } | undefined;
604
+ realtime?: {
605
+ provider: "openai" | "google";
478
606
  model: string;
607
+ voice?: string | undefined;
479
608
  temperature?: number | undefined;
480
- maxOutputTokens?: number | undefined;
481
- topP?: number | undefined;
482
609
  } | undefined;
483
- language?: string | undefined;
484
610
  voice?: {
485
611
  provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
486
612
  voiceId: string;
487
613
  model?: string | undefined;
488
614
  rate?: number | undefined;
489
615
  } | undefined;
490
- realtime?: {
491
- provider: "openai" | "google";
616
+ source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
617
+ mode?: "realtime" | "cascade" | undefined;
618
+ model?: {
619
+ provider: "openai" | "anthropic" | "gemini";
492
620
  model: string;
493
621
  temperature?: number | undefined;
494
- voice?: string | undefined;
622
+ maxOutputTokens?: number | undefined;
623
+ topP?: number | undefined;
495
624
  } | undefined;
625
+ language?: string | undefined;
496
626
  systemPrompt?: string | undefined;
497
627
  routingInstructions?: string | undefined;
498
- stt?: {
499
- provider: "deepgram" | "cartesia" | "assemblyai";
500
- model?: string | undefined;
501
- language?: string | undefined;
502
- endOfTurnConfidence?: number | undefined;
503
- endOfTurnTimeoutMs?: number | undefined;
504
- keywords?: string[] | undefined;
505
- } | undefined;
506
628
  consultation?: {
507
629
  enabled?: boolean | undefined;
508
630
  defaultTimeoutMs?: number | undefined;
@@ -520,8 +642,8 @@ declare const CallPlan: z.ZodObject<{
520
642
  process?: {
521
643
  backendAck?: {
522
644
  url: string;
523
- headers?: Record<string, string> | undefined;
524
645
  timeoutMs?: number | undefined;
646
+ headers?: Record<string, string> | undefined;
525
647
  } | undefined;
526
648
  collect?: Record<string, {
527
649
  type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
@@ -553,14 +675,14 @@ declare const CallPlan: z.ZodObject<{
553
675
  options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
554
676
  deferrableToCallee: z.ZodDefault<z.ZodBoolean>;
555
677
  }, "strip", z.ZodTypeAny, {
556
- kind: "decision" | "auth" | "fact";
557
678
  id: string;
679
+ kind: "decision" | "auth" | "fact";
558
680
  prompt: string;
559
681
  deferrableToCallee: boolean;
560
682
  options?: string[] | undefined;
561
683
  }, {
562
- kind: "decision" | "auth" | "fact";
563
684
  id: string;
685
+ kind: "decision" | "auth" | "fact";
564
686
  prompt: string;
565
687
  options?: string[] | undefined;
566
688
  deferrableToCallee?: boolean | undefined;
@@ -572,14 +694,14 @@ declare const CallPlan: z.ZodObject<{
572
694
  options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
573
695
  deferrableToCallee: z.ZodDefault<z.ZodBoolean>;
574
696
  }, "strip", z.ZodTypeAny, {
575
- kind: "decision" | "auth" | "fact";
576
697
  id: string;
698
+ kind: "decision" | "auth" | "fact";
577
699
  prompt: string;
578
700
  deferrableToCallee: boolean;
579
701
  options?: string[] | undefined;
580
702
  }, {
581
- kind: "decision" | "auth" | "fact";
582
703
  id: string;
704
+ kind: "decision" | "auth" | "fact";
583
705
  prompt: string;
584
706
  options?: string[] | undefined;
585
707
  deferrableToCallee?: boolean | undefined;
@@ -617,7 +739,6 @@ declare const CallPlan: z.ZodObject<{
617
739
  displayName?: string | undefined;
618
740
  };
619
741
  draftConfig: {
620
- source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
621
742
  name?: string | undefined;
622
743
  triggers?: Record<string, {
623
744
  then: {
@@ -625,16 +746,16 @@ declare const CallPlan: z.ZodObject<{
625
746
  } | {
626
747
  kind: "endCall";
627
748
  } | {
628
- kind: "say";
629
749
  text: string;
750
+ kind: "say";
630
751
  };
631
752
  on: {
632
- kind: "regex";
633
753
  pattern: string;
754
+ kind: "regex";
634
755
  flags?: string | undefined;
635
756
  } | {
636
- kind: "signal";
637
757
  name: string;
758
+ kind: "signal";
638
759
  };
639
760
  onlyWhile?: string | undefined;
640
761
  }> | undefined;
@@ -642,37 +763,38 @@ declare const CallPlan: z.ZodObject<{
642
763
  toolName: string;
643
764
  defaultArgs?: Record<string, unknown> | undefined;
644
765
  }[] | undefined;
645
- mode?: "cascade" | "realtime" | undefined;
646
- model?: {
647
- provider: "openai" | "anthropic" | "gemini";
648
- model: string;
649
- temperature?: number | undefined;
650
- maxOutputTokens?: number | undefined;
651
- topP?: number | undefined;
766
+ stt?: {
767
+ provider: "deepgram" | "cartesia" | "assemblyai";
768
+ model?: string | undefined;
769
+ language?: string | undefined;
770
+ endOfTurnConfidence?: number | undefined;
771
+ endOfTurnTimeoutMs?: number | undefined;
772
+ keywords?: string[] | undefined;
773
+ } | undefined;
774
+ realtime?: {
775
+ provider: "openai" | "google";
776
+ model: string;
777
+ voice?: string | undefined;
778
+ temperature?: number | undefined;
652
779
  } | undefined;
653
- language?: string | undefined;
654
780
  voice?: {
655
781
  provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
656
782
  voiceId: string;
657
783
  model?: string | undefined;
658
784
  rate?: number | undefined;
659
785
  } | undefined;
660
- realtime?: {
661
- provider: "openai" | "google";
786
+ source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
787
+ mode?: "realtime" | "cascade" | undefined;
788
+ model?: {
789
+ provider: "openai" | "anthropic" | "gemini";
662
790
  model: string;
663
791
  temperature?: number | undefined;
664
- voice?: string | undefined;
792
+ maxOutputTokens?: number | undefined;
793
+ topP?: number | undefined;
665
794
  } | undefined;
795
+ language?: string | undefined;
666
796
  systemPrompt?: string | undefined;
667
797
  routingInstructions?: string | undefined;
668
- stt?: {
669
- provider: "deepgram" | "cartesia" | "assemblyai";
670
- model?: string | undefined;
671
- language?: string | undefined;
672
- endOfTurnConfidence?: number | undefined;
673
- endOfTurnTimeoutMs?: number | undefined;
674
- keywords?: string[] | undefined;
675
- } | undefined;
676
798
  consultation?: {
677
799
  enabled: boolean;
678
800
  defaultTimeoutMs: number;
@@ -701,8 +823,8 @@ declare const CallPlan: z.ZodObject<{
701
823
  completeWhen: "all-required-captured" | "all-captured";
702
824
  backendAck?: {
703
825
  url: string;
704
- headers?: Record<string, string> | undefined;
705
826
  timeoutMs?: number | undefined;
827
+ headers?: Record<string, string> | undefined;
706
828
  } | undefined;
707
829
  } | undefined;
708
830
  tags?: string[] | undefined;
@@ -717,15 +839,15 @@ declare const CallPlan: z.ZodObject<{
717
839
  }[] | undefined;
718
840
  };
719
841
  openQuestions: {
720
- kind: "decision" | "auth" | "fact";
721
842
  id: string;
843
+ kind: "decision" | "auth" | "fact";
722
844
  prompt: string;
723
845
  deferrableToCallee: boolean;
724
846
  options?: string[] | undefined;
725
847
  }[];
726
848
  unresolvedQuestions: {
727
- kind: "decision" | "auth" | "fact";
728
849
  id: string;
850
+ kind: "decision" | "auth" | "fact";
729
851
  prompt: string;
730
852
  deferrableToCallee: boolean;
731
853
  options?: string[] | undefined;
@@ -757,7 +879,6 @@ declare const CallPlan: z.ZodObject<{
757
879
  secondary?: "ask_callee" | "fallback_phrase" | undefined;
758
880
  };
759
881
  draftConfig?: {
760
- source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
761
882
  name?: string | undefined;
762
883
  triggers?: Record<string, {
763
884
  then: {
@@ -765,16 +886,16 @@ declare const CallPlan: z.ZodObject<{
765
886
  } | {
766
887
  kind: "endCall";
767
888
  } | {
768
- kind: "say";
769
889
  text: string;
890
+ kind: "say";
770
891
  };
771
892
  on: {
772
- kind: "regex";
773
893
  pattern: string;
894
+ kind: "regex";
774
895
  flags?: string | undefined;
775
896
  } | {
776
- kind: "signal";
777
897
  name: string;
898
+ kind: "signal";
778
899
  };
779
900
  onlyWhile?: string | undefined;
780
901
  }> | undefined;
@@ -782,37 +903,38 @@ declare const CallPlan: z.ZodObject<{
782
903
  toolName: string;
783
904
  defaultArgs?: Record<string, unknown> | undefined;
784
905
  }[] | undefined;
785
- mode?: "cascade" | "realtime" | undefined;
786
- model?: {
787
- provider: "openai" | "anthropic" | "gemini";
906
+ stt?: {
907
+ provider: "deepgram" | "cartesia" | "assemblyai";
908
+ model?: string | undefined;
909
+ language?: string | undefined;
910
+ endOfTurnConfidence?: number | undefined;
911
+ endOfTurnTimeoutMs?: number | undefined;
912
+ keywords?: string[] | undefined;
913
+ } | undefined;
914
+ realtime?: {
915
+ provider: "openai" | "google";
788
916
  model: string;
917
+ voice?: string | undefined;
789
918
  temperature?: number | undefined;
790
- maxOutputTokens?: number | undefined;
791
- topP?: number | undefined;
792
919
  } | undefined;
793
- language?: string | undefined;
794
920
  voice?: {
795
921
  provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
796
922
  voiceId: string;
797
923
  model?: string | undefined;
798
924
  rate?: number | undefined;
799
925
  } | undefined;
800
- realtime?: {
801
- provider: "openai" | "google";
926
+ source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
927
+ mode?: "realtime" | "cascade" | undefined;
928
+ model?: {
929
+ provider: "openai" | "anthropic" | "gemini";
802
930
  model: string;
803
931
  temperature?: number | undefined;
804
- voice?: string | undefined;
932
+ maxOutputTokens?: number | undefined;
933
+ topP?: number | undefined;
805
934
  } | undefined;
935
+ language?: string | undefined;
806
936
  systemPrompt?: string | undefined;
807
937
  routingInstructions?: string | undefined;
808
- stt?: {
809
- provider: "deepgram" | "cartesia" | "assemblyai";
810
- model?: string | undefined;
811
- language?: string | undefined;
812
- endOfTurnConfidence?: number | undefined;
813
- endOfTurnTimeoutMs?: number | undefined;
814
- keywords?: string[] | undefined;
815
- } | undefined;
816
938
  consultation?: {
817
939
  enabled?: boolean | undefined;
818
940
  defaultTimeoutMs?: number | undefined;
@@ -830,8 +952,8 @@ declare const CallPlan: z.ZodObject<{
830
952
  process?: {
831
953
  backendAck?: {
832
954
  url: string;
833
- headers?: Record<string, string> | undefined;
834
955
  timeoutMs?: number | undefined;
956
+ headers?: Record<string, string> | undefined;
835
957
  } | undefined;
836
958
  collect?: Record<string, {
837
959
  type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
@@ -857,15 +979,15 @@ declare const CallPlan: z.ZodObject<{
857
979
  }[] | undefined;
858
980
  } | undefined;
859
981
  openQuestions?: {
860
- kind: "decision" | "auth" | "fact";
861
982
  id: string;
983
+ kind: "decision" | "auth" | "fact";
862
984
  prompt: string;
863
985
  options?: string[] | undefined;
864
986
  deferrableToCallee?: boolean | undefined;
865
987
  }[] | undefined;
866
988
  unresolvedQuestions?: {
867
- kind: "decision" | "auth" | "fact";
868
989
  id: string;
990
+ kind: "decision" | "auth" | "fact";
869
991
  prompt: string;
870
992
  options?: string[] | undefined;
871
993
  deferrableToCallee?: boolean | undefined;
@@ -883,13 +1005,13 @@ declare const RelevantContext: z.ZodObject<{
883
1005
  account: z.ZodRecord<z.ZodString, z.ZodUnknown>;
884
1006
  platform: z.ZodRecord<z.ZodString, z.ZodUnknown>;
885
1007
  }, "strip", z.ZodTypeAny, {
886
- caller: Record<string, unknown>;
887
1008
  call: Record<string, unknown>;
1009
+ caller: Record<string, unknown>;
888
1010
  account: Record<string, unknown>;
889
1011
  platform: Record<string, unknown>;
890
1012
  }, {
891
- caller: Record<string, unknown>;
892
1013
  call: Record<string, unknown>;
1014
+ caller: Record<string, unknown>;
893
1015
  account: Record<string, unknown>;
894
1016
  platform: Record<string, unknown>;
895
1017
  }>;
@@ -947,10 +1069,10 @@ declare const DeleteCallerResponse: z.ZodObject<{
947
1069
  scopesPurged: z.ZodArray<z.ZodEnum<["call", "caller", "account", "platform"]>, "many">;
948
1070
  }, "strip", z.ZodTypeAny, {
949
1071
  ok: true;
950
- scopesPurged: ("caller" | "call" | "account" | "platform")[];
1072
+ scopesPurged: ("call" | "caller" | "account" | "platform")[];
951
1073
  }, {
952
1074
  ok: true;
953
- scopesPurged: ("caller" | "call" | "account" | "platform")[];
1075
+ scopesPurged: ("call" | "caller" | "account" | "platform")[];
954
1076
  }>;
955
1077
  type DeleteCallerResponse = z.infer<typeof DeleteCallerResponse>;
956
1078
 
@@ -1077,13 +1199,13 @@ declare const AgentConfig$1: z.ZodObject<{
1077
1199
  }, "strip", z.ZodTypeAny, {
1078
1200
  provider: "openai" | "google";
1079
1201
  model: string;
1080
- temperature?: number | undefined;
1081
1202
  voice?: string | undefined;
1203
+ temperature?: number | undefined;
1082
1204
  }, {
1083
1205
  provider: "openai" | "google";
1084
1206
  model: string;
1085
- temperature?: number | undefined;
1086
1207
  voice?: string | undefined;
1208
+ temperature?: number | undefined;
1087
1209
  }>>;
1088
1210
  language: z.ZodDefault<z.ZodString>;
1089
1211
  tools: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -1180,12 +1302,12 @@ declare const AgentConfig$1: z.ZodObject<{
1180
1302
  headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
1181
1303
  }, "strip", z.ZodTypeAny, {
1182
1304
  url: string;
1183
- headers?: Record<string, string> | undefined;
1184
1305
  timeoutMs?: number | undefined;
1306
+ headers?: Record<string, string> | undefined;
1185
1307
  }, {
1186
1308
  url: string;
1187
- headers?: Record<string, string> | undefined;
1188
1309
  timeoutMs?: number | undefined;
1310
+ headers?: Record<string, string> | undefined;
1189
1311
  }>>;
1190
1312
  }, "strip", z.ZodTypeAny, {
1191
1313
  collect: Record<string, {
@@ -1201,14 +1323,14 @@ declare const AgentConfig$1: z.ZodObject<{
1201
1323
  completeWhen: "all-required-captured" | "all-captured";
1202
1324
  backendAck?: {
1203
1325
  url: string;
1204
- headers?: Record<string, string> | undefined;
1205
1326
  timeoutMs?: number | undefined;
1327
+ headers?: Record<string, string> | undefined;
1206
1328
  } | undefined;
1207
1329
  }, {
1208
1330
  backendAck?: {
1209
1331
  url: string;
1210
- headers?: Record<string, string> | undefined;
1211
1332
  timeoutMs?: number | undefined;
1333
+ headers?: Record<string, string> | undefined;
1212
1334
  } | undefined;
1213
1335
  collect?: Record<string, {
1214
1336
  type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
@@ -1228,22 +1350,22 @@ declare const AgentConfig$1: z.ZodObject<{
1228
1350
  pattern: z.ZodString;
1229
1351
  flags: z.ZodOptional<z.ZodString>;
1230
1352
  }, "strip", z.ZodTypeAny, {
1231
- kind: "regex";
1232
1353
  pattern: string;
1354
+ kind: "regex";
1233
1355
  flags?: string | undefined;
1234
1356
  }, {
1235
- kind: "regex";
1236
1357
  pattern: string;
1358
+ kind: "regex";
1237
1359
  flags?: string | undefined;
1238
1360
  }>, z.ZodObject<{
1239
1361
  kind: z.ZodLiteral<"signal">;
1240
1362
  name: z.ZodString;
1241
1363
  }, "strip", z.ZodTypeAny, {
1242
- kind: "signal";
1243
1364
  name: string;
1244
- }, {
1245
1365
  kind: "signal";
1366
+ }, {
1246
1367
  name: string;
1368
+ kind: "signal";
1247
1369
  }>]>;
1248
1370
  then: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
1249
1371
  kind: z.ZodLiteral<"handoff">;
@@ -1261,11 +1383,11 @@ declare const AgentConfig$1: z.ZodObject<{
1261
1383
  kind: z.ZodLiteral<"say">;
1262
1384
  text: z.ZodString;
1263
1385
  }, "strip", z.ZodTypeAny, {
1264
- kind: "say";
1265
1386
  text: string;
1266
- }, {
1267
1387
  kind: "say";
1388
+ }, {
1268
1389
  text: string;
1390
+ kind: "say";
1269
1391
  }>]>;
1270
1392
  onlyWhile: z.ZodOptional<z.ZodString>;
1271
1393
  }, "strip", z.ZodTypeAny, {
@@ -1274,16 +1396,16 @@ declare const AgentConfig$1: z.ZodObject<{
1274
1396
  } | {
1275
1397
  kind: "endCall";
1276
1398
  } | {
1277
- kind: "say";
1278
1399
  text: string;
1400
+ kind: "say";
1279
1401
  };
1280
1402
  on: {
1281
- kind: "regex";
1282
1403
  pattern: string;
1404
+ kind: "regex";
1283
1405
  flags?: string | undefined;
1284
1406
  } | {
1285
- kind: "signal";
1286
1407
  name: string;
1408
+ kind: "signal";
1287
1409
  };
1288
1410
  onlyWhile?: string | undefined;
1289
1411
  }, {
@@ -1292,16 +1414,16 @@ declare const AgentConfig$1: z.ZodObject<{
1292
1414
  } | {
1293
1415
  kind: "endCall";
1294
1416
  } | {
1295
- kind: "say";
1296
1417
  text: string;
1418
+ kind: "say";
1297
1419
  };
1298
1420
  on: {
1299
- kind: "regex";
1300
1421
  pattern: string;
1422
+ kind: "regex";
1301
1423
  flags?: string | undefined;
1302
1424
  } | {
1303
- kind: "signal";
1304
1425
  name: string;
1426
+ kind: "signal";
1305
1427
  };
1306
1428
  onlyWhile?: string | undefined;
1307
1429
  }>>>;
@@ -1332,15 +1454,21 @@ declare const AgentConfig$1: z.ZodObject<{
1332
1454
  updatedAt: z.ZodString;
1333
1455
  }, "strip", z.ZodTypeAny, {
1334
1456
  id: string;
1335
- projectId: string;
1336
1457
  name: string;
1337
- createdAt: string;
1338
- updatedAt: string;
1339
1458
  tools: {
1340
1459
  toolName: string;
1341
1460
  defaultArgs?: Record<string, unknown> | undefined;
1342
1461
  }[];
1343
- mode: "cascade" | "realtime";
1462
+ voice: {
1463
+ provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
1464
+ voiceId: string;
1465
+ model?: string | undefined;
1466
+ rate?: number | undefined;
1467
+ };
1468
+ projectId: string;
1469
+ createdAt: string;
1470
+ updatedAt: string;
1471
+ mode: "realtime" | "cascade";
1344
1472
  model: {
1345
1473
  provider: "openai" | "anthropic" | "gemini";
1346
1474
  model: string;
@@ -1349,12 +1477,6 @@ declare const AgentConfig$1: z.ZodObject<{
1349
1477
  topP?: number | undefined;
1350
1478
  };
1351
1479
  language: string;
1352
- voice: {
1353
- provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
1354
- voiceId: string;
1355
- model?: string | undefined;
1356
- rate?: number | undefined;
1357
- };
1358
1480
  consultation: {
1359
1481
  enabled: boolean;
1360
1482
  defaultTimeoutMs: number;
@@ -1376,34 +1498,25 @@ declare const AgentConfig$1: z.ZodObject<{
1376
1498
  enum?: string[] | undefined;
1377
1499
  description?: string | undefined;
1378
1500
  }[];
1379
- source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
1380
1501
  triggers?: Record<string, {
1381
1502
  then: {
1382
1503
  kind: "handoff";
1383
1504
  } | {
1384
1505
  kind: "endCall";
1385
1506
  } | {
1386
- kind: "say";
1387
1507
  text: string;
1508
+ kind: "say";
1388
1509
  };
1389
1510
  on: {
1390
- kind: "regex";
1391
1511
  pattern: string;
1512
+ kind: "regex";
1392
1513
  flags?: string | undefined;
1393
1514
  } | {
1394
- kind: "signal";
1395
1515
  name: string;
1516
+ kind: "signal";
1396
1517
  };
1397
1518
  onlyWhile?: string | undefined;
1398
1519
  }> | undefined;
1399
- realtime?: {
1400
- provider: "openai" | "google";
1401
- model: string;
1402
- temperature?: number | undefined;
1403
- voice?: string | undefined;
1404
- } | undefined;
1405
- systemPrompt?: string | undefined;
1406
- routingInstructions?: string | undefined;
1407
1520
  stt?: {
1408
1521
  provider: "deepgram" | "cartesia" | "assemblyai";
1409
1522
  model?: string | undefined;
@@ -1412,6 +1525,15 @@ declare const AgentConfig$1: z.ZodObject<{
1412
1525
  endOfTurnTimeoutMs?: number | undefined;
1413
1526
  keywords?: string[] | undefined;
1414
1527
  } | undefined;
1528
+ realtime?: {
1529
+ provider: "openai" | "google";
1530
+ model: string;
1531
+ voice?: string | undefined;
1532
+ temperature?: number | undefined;
1533
+ } | undefined;
1534
+ source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
1535
+ systemPrompt?: string | undefined;
1536
+ routingInstructions?: string | undefined;
1415
1537
  process?: {
1416
1538
  collect: Record<string, {
1417
1539
  type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
@@ -1426,8 +1548,8 @@ declare const AgentConfig$1: z.ZodObject<{
1426
1548
  completeWhen: "all-required-captured" | "all-captured";
1427
1549
  backendAck?: {
1428
1550
  url: string;
1429
- headers?: Record<string, string> | undefined;
1430
1551
  timeoutMs?: number | undefined;
1552
+ headers?: Record<string, string> | undefined;
1431
1553
  } | undefined;
1432
1554
  } | undefined;
1433
1555
  tags?: string[] | undefined;
@@ -1435,8 +1557,14 @@ declare const AgentConfig$1: z.ZodObject<{
1435
1557
  modeLocked?: boolean | undefined;
1436
1558
  }, {
1437
1559
  id: string;
1438
- projectId: string;
1439
1560
  name: string;
1561
+ voice: {
1562
+ provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
1563
+ voiceId: string;
1564
+ model?: string | undefined;
1565
+ rate?: number | undefined;
1566
+ };
1567
+ projectId: string;
1440
1568
  createdAt: string;
1441
1569
  updatedAt: string;
1442
1570
  model: {
@@ -1446,12 +1574,6 @@ declare const AgentConfig$1: z.ZodObject<{
1446
1574
  maxOutputTokens?: number | undefined;
1447
1575
  topP?: number | undefined;
1448
1576
  };
1449
- voice: {
1450
- provider: "deepgram" | "elevenlabs" | "openai" | "cartesia";
1451
- voiceId: string;
1452
- model?: string | undefined;
1453
- rate?: number | undefined;
1454
- };
1455
1577
  consultation: {
1456
1578
  enabled?: boolean | undefined;
1457
1579
  defaultTimeoutMs?: number | undefined;
@@ -1466,23 +1588,22 @@ declare const AgentConfig$1: z.ZodObject<{
1466
1588
  normal?: number | undefined;
1467
1589
  } | undefined;
1468
1590
  };
1469
- source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
1470
1591
  triggers?: Record<string, {
1471
1592
  then: {
1472
1593
  kind: "handoff";
1473
1594
  } | {
1474
1595
  kind: "endCall";
1475
1596
  } | {
1476
- kind: "say";
1477
1597
  text: string;
1598
+ kind: "say";
1478
1599
  };
1479
1600
  on: {
1480
- kind: "regex";
1481
1601
  pattern: string;
1602
+ kind: "regex";
1482
1603
  flags?: string | undefined;
1483
1604
  } | {
1484
- kind: "signal";
1485
1605
  name: string;
1606
+ kind: "signal";
1486
1607
  };
1487
1608
  onlyWhile?: string | undefined;
1488
1609
  }> | undefined;
@@ -1490,16 +1611,6 @@ declare const AgentConfig$1: z.ZodObject<{
1490
1611
  toolName: string;
1491
1612
  defaultArgs?: Record<string, unknown> | undefined;
1492
1613
  }[] | undefined;
1493
- mode?: "cascade" | "realtime" | undefined;
1494
- language?: string | undefined;
1495
- realtime?: {
1496
- provider: "openai" | "google";
1497
- model: string;
1498
- temperature?: number | undefined;
1499
- voice?: string | undefined;
1500
- } | undefined;
1501
- systemPrompt?: string | undefined;
1502
- routingInstructions?: string | undefined;
1503
1614
  stt?: {
1504
1615
  provider: "deepgram" | "cartesia" | "assemblyai";
1505
1616
  model?: string | undefined;
@@ -1508,11 +1619,22 @@ declare const AgentConfig$1: z.ZodObject<{
1508
1619
  endOfTurnTimeoutMs?: number | undefined;
1509
1620
  keywords?: string[] | undefined;
1510
1621
  } | undefined;
1622
+ realtime?: {
1623
+ provider: "openai" | "google";
1624
+ model: string;
1625
+ voice?: string | undefined;
1626
+ temperature?: number | undefined;
1627
+ } | undefined;
1628
+ source?: "playbook" | "sdk" | "flow" | "connector" | undefined;
1629
+ mode?: "realtime" | "cascade" | undefined;
1630
+ language?: string | undefined;
1631
+ systemPrompt?: string | undefined;
1632
+ routingInstructions?: string | undefined;
1511
1633
  process?: {
1512
1634
  backendAck?: {
1513
1635
  url: string;
1514
- headers?: Record<string, string> | undefined;
1515
1636
  timeoutMs?: number | undefined;
1637
+ headers?: Record<string, string> | undefined;
1516
1638
  } | undefined;
1517
1639
  collect?: Record<string, {
1518
1640
  type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
@@ -1539,132 +1661,14 @@ declare const AgentConfig$1: z.ZodObject<{
1539
1661
  }>;
1540
1662
  type AgentConfig$1 = z.infer<typeof AgentConfig$1>;
1541
1663
 
1542
- /** Frames a daemon sends up to the relay. */
1543
- declare const ConnectorUpFrame: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
1544
- kind: z.ZodLiteral<"hello">;
1545
- token: z.ZodString;
1546
- replicaId: z.ZodString;
1547
- version: z.ZodString;
1548
- caps: z.ZodObject<{
1549
- streaming: z.ZodBoolean;
1550
- tools: z.ZodBoolean;
1551
- litellm: z.ZodBoolean;
1552
- }, "strip", z.ZodTypeAny, {
1553
- tools: boolean;
1554
- streaming: boolean;
1555
- litellm: boolean;
1556
- }, {
1557
- tools: boolean;
1558
- streaming: boolean;
1559
- litellm: boolean;
1560
- }>;
1561
- }, "strip", z.ZodTypeAny, {
1562
- kind: "hello";
1563
- version: string;
1564
- token: string;
1565
- replicaId: string;
1566
- caps: {
1567
- tools: boolean;
1568
- streaming: boolean;
1569
- litellm: boolean;
1570
- };
1571
- }, {
1572
- kind: "hello";
1573
- version: string;
1574
- token: string;
1575
- replicaId: string;
1576
- caps: {
1577
- tools: boolean;
1578
- streaming: boolean;
1579
- litellm: boolean;
1580
- };
1581
- }>, z.ZodObject<{
1582
- kind: z.ZodLiteral<"pong">;
1583
- ts: z.ZodNumber;
1584
- }, "strip", z.ZodTypeAny, {
1585
- kind: "pong";
1586
- ts: number;
1587
- }, {
1588
- kind: "pong";
1589
- ts: number;
1590
- }>, z.ZodObject<{
1591
- kind: z.ZodLiteral<"brain.delta">;
1592
- streamId: z.ZodString;
1593
- content: z.ZodString;
1594
- }, "strip", z.ZodTypeAny, {
1595
- kind: "brain.delta";
1596
- content: string;
1597
- streamId: string;
1598
- }, {
1599
- kind: "brain.delta";
1600
- content: string;
1601
- streamId: string;
1602
- }>, z.ZodObject<{
1603
- kind: z.ZodLiteral<"brain.done">;
1604
- streamId: z.ZodString;
1605
- finishReason: z.ZodString;
1606
- }, "strip", z.ZodTypeAny, {
1607
- kind: "brain.done";
1608
- streamId: string;
1609
- finishReason: string;
1610
- }, {
1611
- kind: "brain.done";
1612
- streamId: string;
1613
- finishReason: string;
1614
- }>, z.ZodObject<{
1615
- kind: z.ZodLiteral<"brain.error">;
1616
- streamId: z.ZodString;
1617
- code: z.ZodEnum<["upstream_timeout", "upstream_error", "bad_response", "normalize_failed", "unreachable"]>;
1618
- message: z.ZodString;
1619
- }, "strip", z.ZodTypeAny, {
1620
- message: string;
1621
- kind: "brain.error";
1622
- code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
1623
- streamId: string;
1624
- }, {
1625
- message: string;
1626
- kind: "brain.error";
1627
- code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
1628
- streamId: string;
1629
- }>]>;
1630
- type ConnectorUpFrame = z.infer<typeof ConnectorUpFrame>;
1631
-
1632
- interface TransportOptions {
1633
- readonly apiKey: string;
1634
- readonly baseUrl: string;
1635
- readonly fetch?: typeof fetch;
1636
- readonly maxRetries?: number;
1637
- readonly initialBackoffMs?: number;
1638
- readonly userAgent?: string;
1664
+ interface ReadinessResult {
1665
+ readonly ok: boolean;
1666
+ /** Human-readable explanation when ok=false. Surfaced in metadata. */
1667
+ readonly detail?: string;
1639
1668
  }
1640
- interface RequestOptions {
1641
- readonly method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
1642
- readonly path: string;
1643
- readonly body?: unknown;
1644
- readonly query?: Record<string, string | undefined>;
1645
- readonly signal?: AbortSignal;
1646
- /** Extra request headers, merged on top of the defaults (auth/content-type
1647
- * etc). Lowercase keys recommended. */
1648
- readonly headers?: Record<string, string>;
1649
- }
1650
- declare class Transport {
1651
- private readonly options;
1652
- private readonly fetchImpl;
1653
- private readonly maxRetries;
1654
- private readonly initialBackoffMs;
1655
- constructor(options: TransportOptions);
1656
- request<T>(opts: RequestOptions, schema: ZodType<T>): Promise<T>;
1657
- private backoffMs;
1658
- }
1659
-
1660
- interface ReadinessResult {
1661
- readonly ok: boolean;
1662
- /** Human-readable explanation when ok=false. Surfaced in metadata. */
1663
- readonly detail?: string;
1664
- }
1665
- interface ReadinessProbe {
1666
- readonly name: string;
1667
- check(): Promise<ReadinessResult>;
1669
+ interface ReadinessProbe {
1670
+ readonly name: string;
1671
+ check(): Promise<ReadinessResult>;
1668
1672
  }
1669
1673
  /** Aggregate result the SDK records in metadata.readiness. */
1670
1674
  interface ReadinessReport {
@@ -1758,1150 +1762,1184 @@ interface AgentEventEmitter {
1758
1762
  emit(event: AgentLifecycleEvent): void;
1759
1763
  }
1760
1764
 
1761
- interface RegisterInput {
1762
- readonly name: string;
1763
- readonly version: string;
1764
- readonly environment: AgentEnvironment;
1765
- /** Capability tags (e.g. ['fnol', 'es-MX']). Surfaced in the dashboard. */
1766
- readonly capabilities?: readonly string[];
1767
- /**
1768
- * JSON-serializable process schema for the dashboard "what this agent does"
1769
- * view. Built by `buildProcessSchemaDTO` from the agent's ProcessDefinition.
1770
- */
1771
- readonly processSchema?: ProcessSchemaDTO | null;
1772
- /**
1773
- * Opt this agent into MCP exposure. When true, the API upserts a matching
1774
- * agent_config row keyed by (project_id, name, environment) so MCP /
1775
- * dashboard / REST can list and inspect this agent. Default false — pure
1776
- * SDK agents that don't need MCP visibility stay invisible to it. See
1777
- * docs/architecture/contracts-design.md §2b.
1778
- */
1779
- readonly mcpExposed?: boolean;
1780
- /**
1781
- * Self-checks run before sending the register request. Each result is
1782
- * recorded on the agent. See RegisterOptions.requireReady for failure
1783
- * policy.
1784
- */
1785
- readonly readiness?: readonly ReadinessProbe[];
1786
- /** User metadata. Merged on top of default metadata (user wins on conflict). */
1787
- readonly metadata?: Record<string, unknown>;
1765
+ /** Primitive field types accepted in a process definition. */
1766
+ type ProcessFieldType = 'string' | 'string[]' | 'number' | 'boolean' | 'datetime' | 'email' | 'phone';
1767
+ interface ProcessField {
1768
+ readonly type: ProcessFieldType;
1769
+ readonly required?: boolean;
1770
+ /** Regex pattern for `string` / `string[]` items. */
1771
+ readonly pattern?: RegExp;
1772
+ /** Inclusive lower bound on a number or array length. */
1773
+ readonly min?: number;
1774
+ /** Inclusive upper bound on a number or array length. */
1775
+ readonly max?: number;
1776
+ /** One of N — restricts the captured value to this set. */
1777
+ readonly enum?: readonly string[];
1778
+ /** Override the auto-generated prompt for capturing this field. */
1779
+ readonly ask?: string;
1780
+ /** Override the field-extraction hint shown to the LLM. */
1781
+ readonly extract?: string;
1782
+ }
1783
+ type CompletionStrategy = 'all-required-captured' | 'all-captured' | {
1784
+ custom: (data: Record<string, unknown>, ctx: AgentContext) => boolean | Promise<boolean>;
1785
+ };
1786
+ interface ProcessBackendAck {
1787
+ /** URL to POST captured data to. The call cannot complete until this 2xx's. */
1788
+ readonly url: string;
1789
+ readonly timeoutMs?: number;
1790
+ readonly headers?: Readonly<Record<string, string>>;
1791
+ }
1792
+ interface ProcessDefinition<T extends Record<string, ProcessField> = Record<string, ProcessField>> {
1793
+ /** Field schema. Order is preserved when the SDK auto-asks for fields. */
1794
+ readonly collect: T;
1795
+ /** When the call can end. Defaults to 'all-required-captured'. */
1796
+ readonly completeWhen?: CompletionStrategy;
1797
+ /** Optional external system that must ACK before completion. */
1798
+ readonly backendAck?: ProcessBackendAck;
1799
+ /** Fires once all completion conditions are met. */
1800
+ readonly onComplete?: (data: InferProcessData<T>, ctx: AgentContext) => Promise<void> | void;
1801
+ /** Fires whenever a field is captured (good for live CRM updates). */
1802
+ readonly onField?: <K extends keyof T>(field: K, value: InferFieldValue<T[K]>, ctx: AgentContext) => Promise<void> | void;
1803
+ }
1804
+ /** Inferred TS type for the data bag a process produces. */
1805
+ type InferProcessData<T extends Record<string, ProcessField>> = {
1806
+ [K in keyof T]: T[K]['required'] extends true ? InferFieldValue<T[K]> : InferFieldValue<T[K]> | undefined;
1807
+ };
1808
+ type InferFieldValue<F extends ProcessField> = F['type'] extends 'string' ? string : F['type'] extends 'string[]' ? string[] : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'datetime' ? Date : F['type'] extends 'email' ? string : F['type'] extends 'phone' ? string : never;
1809
+ type TriggerCondition = RegExp | `signal:${string}` | ((text: string, ctx: AgentContext) => boolean | Promise<boolean>);
1810
+ type TriggerAction = 'handoff' | 'endCall' | {
1811
+ say: string;
1812
+ } | {
1813
+ run: (ctx: AgentContext) => Promise<void> | void;
1814
+ }
1815
+ /** Jump the flow-graph cursor to a node id. Only meaningful under the graph
1816
+ * interpreter (the flat goals+rails path has no cursor and ignores it). */
1817
+ | {
1818
+ goto: string;
1819
+ };
1820
+ interface TriggerDefinition {
1821
+ readonly on: TriggerCondition;
1822
+ readonly then: TriggerAction;
1823
+ /** If set, the trigger only fires while the named field is uncaptured. */
1824
+ readonly onlyWhile?: string;
1825
+ }
1826
+ interface HandoffConfig {
1827
+ /** Default human number when a trigger says { then: 'handoff' }. */
1828
+ readonly fallback: string;
1829
+ /** Map signal/trigger names to specific destinations. */
1830
+ readonly routes?: Readonly<Record<string, string>>;
1831
+ /** Build the briefing text passed to the human agent (or PSTN whisper). */
1832
+ readonly briefing?: (args: {
1833
+ readonly data: Record<string, unknown>;
1834
+ readonly transcript: TranscriptHandle;
1835
+ readonly call: AgentContext['call'];
1836
+ }) => string | Promise<string>;
1788
1837
  /**
1789
- * Whether to auto-collect host/runtime/build metadata. Default true. Set
1790
- * false to send exactly what you pass in `metadata`.
1838
+ * 'warm' (default) dials the human into the room as a conference, lets the
1839
+ * agent brief them live, then drops the agent — caller + human stay
1840
+ * connected. 'cold' is a blind SIP REFER: the caller is transferred away
1841
+ * immediately. Warm falls back to cold when no outbound trunk is configured.
1791
1842
  */
1792
- readonly collectDefaults?: boolean;
1843
+ readonly mode?: 'warm' | 'cold';
1793
1844
  }
1794
- interface RegisterOptions {
1845
+ interface TranscriptHandle {
1846
+ /** Last N turns as `speaker: text` lines. */
1847
+ tail(n: number): string;
1848
+ full(): string;
1849
+ }
1850
+ /**
1851
+ * Memory scope. `'participant'` and `'caller'` are synonyms — `'caller'`
1852
+ * is the historical name from the 1:1 era; new code should prefer
1853
+ * `'participant'`, which makes the multi-party semantics explicit.
1854
+ */
1855
+ type MemoryScope = 'call' | 'caller' | 'participant' | 'account' | 'platform';
1856
+ interface MemoryConfig {
1857
+ /** Which scope to persist to. Defaults to 'caller'. */
1858
+ readonly scope?: MemoryScope;
1859
+ readonly retentionDays?: number;
1860
+ /** Fields auto-redacted on write. Recognized: ssn, dob, email, phone, ccn. */
1861
+ readonly piiFields?: readonly string[];
1862
+ /** Opt in to cross-tenant aggregate memory (anonymized). */
1863
+ readonly platformOptIn?: boolean;
1864
+ }
1865
+ /**
1866
+ * Multi-participant configuration. Optional — when omitted, the agent runs
1867
+ * in 1:1 mode (one human + one agent) and the SDK still populates
1868
+ * `ctx.room.participants` so participant-aware code paths work.
1869
+ */
1870
+ interface ParticipantsConfig {
1795
1871
  /**
1796
- * Override server-suggested heartbeat cadence (ms). When omitted, the SDK
1797
- * uses the value returned by /v1/agents/register, falling back to
1798
- * AGENT_HEARTBEAT_INTERVAL_MS.
1872
+ * Fires when a human participant joins the room. In 1:1 calls this
1873
+ * fires once at session start for the caller. In multi-party calls it
1874
+ * fires per join.
1799
1875
  */
1800
- readonly heartbeatIntervalMs?: number;
1876
+ readonly onJoin?: (participant: Participant, ctx: AgentContext) => Promise<void> | void;
1877
+ /** Fires when a participant disconnects (hangup, transfer, kick). */
1878
+ readonly onLeave?: (participant: Participant, ctx: AgentContext) => Promise<void> | void;
1801
1879
  /**
1802
- * Disable signal handlers (SIGTERM/SIGINT). Useful in tests and in hosts
1803
- * that own their own shutdown lifecycle.
1880
+ * Synchronously enrich a participant's attribute bag before `onJoin`
1881
+ * fires. Useful for phone-number → language lookups, etc. The returned
1882
+ * map is merged into `participant.attributes`.
1804
1883
  */
1805
- readonly attachSignalHandlers?: boolean;
1884
+ readonly attributes?: (participant: Participant) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
1806
1885
  /**
1807
- * On SIGTERM/SIGINT, call DELETE /v1/agents/:id before exiting so the
1808
- * dashboard reflects "gone" immediately instead of waiting for offline
1809
- * timeout. Default true. Best-effort: errors are swallowed.
1886
+ * Reject participants beyond this count. Default: unlimited. The cap
1887
+ * is enforced by the worker when wiring participant lifecycle.
1810
1888
  */
1811
- readonly deregisterOnSignal?: boolean;
1889
+ readonly max?: number;
1890
+ }
1891
+ /**
1892
+ * A connector instance. Created by per-system factories like `salesforce()`,
1893
+ * `twilio()`, etc. The factory returns an opaque handle that the SDK wires
1894
+ * into `ctx.connectors` and (when `expose: true`) into the LLM tool list.
1895
+ */
1896
+ interface ConnectorInstance<TName extends string = string, TApi = unknown> {
1897
+ readonly __connector: true;
1898
+ readonly name: TName;
1899
+ readonly api: TApi;
1900
+ /** If true, every method on `api` becomes an LLM-callable tool. */
1901
+ readonly expose?: boolean;
1902
+ }
1903
+ type ComplianceTag = 'tcpa' | 'hipaa' | 'pci' | 'gdpr' | 'soc2';
1904
+ /**
1905
+ * Duck-typed pipeline component markers. The SDK never inspects these — they
1906
+ * are passed through to LiveKit's AgentSession as-is. Three ways to satisfy:
1907
+ *
1908
+ * 1. SDK factory: `deepgram.tts({ model: 'aura-2' })`
1909
+ * 2. Wrapped LK: `wrap(new TTS({...}), { trace: true })`
1910
+ * 3. User-built: class MyTTS extends BaseTTS { ... } // BaseTTS
1911
+ * // re-exported
1912
+ * // from the SDK
1913
+ *
1914
+ * Anything implementing the duck-type — even a plain object — is accepted.
1915
+ */
1916
+ interface STTProvider {
1917
+ readonly __vlPipeline?: 'stt';
1918
+ }
1919
+ interface LLMProvider {
1920
+ readonly __vlPipeline?: 'llm';
1921
+ }
1922
+ interface TTSProvider {
1923
+ readonly __vlPipeline?: 'tts';
1924
+ }
1925
+ interface VADProvider {
1926
+ readonly __vlPipeline?: 'vad';
1927
+ }
1928
+ interface TurnDetectorProvider {
1929
+ readonly __vlPipeline?: 'turn';
1930
+ }
1931
+ /**
1932
+ * Speech-to-speech / realtime model marker (OpenAI Realtime, Gemini Live).
1933
+ * A realtime model handles STT + LLM + TTS + turn-taking server-side, so when
1934
+ * `models.realtime` is set the SDK builds the AgentSession around it and
1935
+ * ignores the stt/llm/tts slots.
1936
+ */
1937
+ interface RealtimeProvider {
1938
+ readonly __vlPipeline?: 'realtime';
1939
+ }
1940
+ /**
1941
+ * Lazy form so users can pick a provider per call (e.g. by caller locale).
1942
+ * The factory runs once per call, before AgentSession is constructed, so it
1943
+ * receives the call envelope (callerId, to, metadata) rather than the full
1944
+ * AgentContext (which depends on AgentSession existing).
1945
+ */
1946
+ type ProviderFactory<T> = (call: CallInfo) => T | Promise<T>;
1947
+ interface ModelConfig {
1812
1948
  /**
1813
- * If any readiness probe reports !ok, throw before calling register.
1814
- * Default false: probes that fail mark the agent as `degraded` instead.
1949
+ * String form: 'openai/gpt-4o' (resolves via SDK defaults).
1950
+ * Instance form: any LLMProvider (LK plugin, wrap()-ed, or user-built).
1951
+ * Factory form: `(ctx) => provider` for per-call selection.
1815
1952
  */
1816
- readonly requireReady?: boolean;
1953
+ readonly llm?: string | LLMProvider | ProviderFactory<LLMProvider>;
1954
+ readonly stt?: string | STTProvider | ProviderFactory<STTProvider>;
1955
+ readonly tts?: string | TTSProvider | ProviderFactory<TTSProvider>;
1956
+ /** VAD has no string form — always pass an instance or factory. */
1957
+ readonly vad?: VADProvider | ProviderFactory<VADProvider>;
1958
+ readonly turnDetector?: TurnDetectorProvider | ProviderFactory<TurnDetectorProvider>;
1817
1959
  /**
1818
- * Listener for lifecycle events. Equivalent to `agent.events.on(fn)` after
1819
- * register; register-time events (readiness, registered) are also delivered.
1960
+ * Speech-to-speech / realtime model. When set, the STT→LLM→TTS pipeline is
1961
+ * bypassed: the realtime model drives the whole turn. No string form — pass
1962
+ * an instance (`openai.realtime({ voice: 'alloy' })`) or a per-call factory.
1820
1963
  */
1821
- readonly onEvent?: (event: AgentLifecycleEvent) => void;
1964
+ readonly realtime?: RealtimeProvider | ProviderFactory<RealtimeProvider>;
1965
+ /** Spoken language; defaults to 'en-US'. Used by string-form defaults. */
1966
+ readonly language?: string;
1822
1967
  }
1823
- interface RegisteredAgent {
1824
- readonly agent: AgentDTO;
1825
- readonly events: AgentEventEmitter;
1826
- /** Push a status change immediately (next heartbeat carries it too). */
1827
- setStatus(status: 'online' | 'degraded', detail?: string): Promise<void>;
1828
- /** Replace metadata on the next heartbeat. Pass {} to clear. */
1829
- updateMetadata(metadata: Record<string, unknown>): Promise<void>;
1830
- /** Best-effort DELETE; safe to call multiple times. */
1831
- deregister(): Promise<void>;
1832
- /** Stop the heartbeat ticker without deleting the row. Idempotent. */
1833
- stop(): Promise<void>;
1834
- }
1835
- interface SchedulerLike {
1836
- setTimeout(cb: () => void, ms: number): NodeJS.Timeout | number;
1837
- clearTimeout(handle: NodeJS.Timeout | number | undefined): void;
1838
- }
1839
- interface AgentsClientOptions {
1840
- readonly scheduler?: SchedulerLike;
1841
- readonly attachSignalHandlers?: boolean;
1842
- }
1843
- declare class AgentsClient {
1844
- private readonly transport;
1845
- private readonly options;
1846
- constructor(transport: Transport, options?: AgentsClientOptions);
1847
- /**
1848
- * Fetch a deployed agent's compiled process_schema. A flow-runtime worker
1849
- * calls this per dispatched call to boot a visually-built flow. Returns
1850
- * null on 404 or when the agent has no schema.
1851
- */
1852
- getProcessSchema(agentId: string): Promise<ProcessSchemaDTO | null>;
1853
- /**
1854
- * Fetch a deployed agent's stored AgentConfig — the pipeline the dashboard
1855
- * set (model / voice / stt / mode / realtime). A flow-runtime worker reads
1856
- * this per call so the no-code agent's runtime matches the builder. Returns
1857
- * null on 404 (agent not MCP-exposed or absent).
1858
- */
1859
- getConfig(agentId: string): Promise<AgentConfig$1 | null>;
1860
- register(input: RegisterInput, opts?: RegisterOptions): Promise<RegisteredAgent>;
1861
- list(query?: {
1862
- environment?: AgentEnvironment;
1863
- }): Promise<{
1864
- agents: {
1865
- status: "online" | "offline" | "degraded";
1866
- id: string;
1867
- projectId: string;
1868
- name: string;
1869
- createdAt: string;
1870
- updatedAt: string;
1871
- version: string;
1872
- environment: "dev" | "stg" | "prd";
1873
- statusDetail: string | null;
1874
- capabilities: string[];
1875
- readiness: {
1876
- probe: string;
1877
- ok: boolean;
1878
- detail?: string | undefined;
1879
- }[];
1880
- metadata: Record<string, unknown>;
1881
- lastSeenAt: string | null;
1882
- processSchema?: {
1883
- id: string;
1884
- completionGate: {
1885
- requiredFields: string[];
1886
- backendAck?: {
1887
- url: string;
1888
- timeoutMs: number;
1889
- } | undefined;
1890
- };
1891
- fields: {
1892
- type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
1893
- name: string;
1894
- required: boolean;
1895
- ask?: string | undefined;
1896
- pattern?: string | undefined;
1897
- min?: number | undefined;
1898
- max?: number | undefined;
1899
- enum?: string[] | undefined;
1900
- }[];
1901
- handoff?: {
1902
- fallback?: string | undefined;
1903
- routes?: Record<string, string> | undefined;
1904
- } | undefined;
1905
- memory?: {
1906
- scope?: "caller" | "call" | "account" | "participant" | "platform" | undefined;
1907
- retentionDays?: number | undefined;
1908
- piiFields?: string[] | undefined;
1909
- } | undefined;
1910
- speech?: {
1911
- interruption?: {
1912
- enabled?: boolean | undefined;
1913
- minWords?: number | undefined;
1914
- minDuration?: number | undefined;
1915
- } | undefined;
1916
- endpointing?: {
1917
- minDelay?: number | undefined;
1918
- maxDelay?: number | undefined;
1919
- } | undefined;
1920
- } | undefined;
1921
- prompts?: {
1922
- id: string;
1923
- text: string;
1924
- }[] | undefined;
1925
- triggers?: {
1926
- then: string;
1927
- name: string;
1928
- on: string;
1929
- onlyWhile?: string | undefined;
1930
- }[] | undefined;
1931
- tools?: {
1932
- name: string;
1933
- description: string;
1934
- input: Record<string, "string" | "number" | "boolean">;
1935
- url: string;
1936
- method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
1937
- auth: "none" | "connection";
1938
- headers?: Record<string, string> | undefined;
1939
- connectionRef?: string | undefined;
1940
- }[] | undefined;
1941
- program?: {
1942
- v: 1;
1943
- id: string;
1944
- nodes: Record<string, {
1945
- type: "code" | "start" | "say" | "ask" | "confirm" | "tool" | "decision" | "handoff" | "end" | "trigger" | "gate" | "playbook" | "menu" | "set" | "subflow" | "llm" | "rag" | "memory" | "speech" | "classify" | "router" | "note";
1946
- id: string;
1947
- config: Record<string, unknown>;
1948
- out: {
1949
- to: string;
1950
- sourceHandle?: string | undefined;
1951
- label?: string | undefined;
1952
- condition?: string | undefined;
1953
- }[];
1954
- }>;
1955
- entry: string[];
1956
- completionGate: {
1957
- requiredFields: string[];
1958
- };
1959
- diagnostics?: {
1960
- acyclic: boolean;
1961
- droppedEdges: string[];
1962
- unsupportedNodes: string[];
1963
- } | undefined;
1964
- } | undefined;
1965
- } | null | undefined;
1966
- }[];
1967
- }>;
1968
- delete(agentId: string): Promise<{
1969
- ok: true;
1970
- }>;
1971
- }
1972
-
1973
- interface ContextInput {
1974
- readonly callerId: string;
1975
- readonly scopes?: readonly MemoryScope$1[];
1976
- }
1977
- interface WriteInput {
1978
- readonly scope: MemoryScope$1;
1979
- readonly callerId: string;
1980
- readonly delta: Record<string, unknown>;
1981
- readonly callId?: string;
1982
- }
1983
- interface SnapshotInput {
1984
- readonly callId: string;
1985
- readonly stage: string;
1986
- readonly snapshot: Record<string, unknown>;
1987
- }
1988
- interface ResolveInput {
1989
- readonly externalKey: string;
1990
- readonly displayName?: string;
1991
- readonly identifiers?: ReadonlyArray<{
1992
- type: string;
1993
- value: string;
1994
- }>;
1995
- }
1996
- declare class MemoryClient {
1997
- private readonly transport;
1998
- constructor(transport: Transport);
1999
- context(input: ContextInput): Promise<RelevantContext>;
2000
- write(input: WriteInput): Promise<void>;
2001
- snapshot(input: SnapshotInput): Promise<{
2002
- id: string;
2003
- }>;
2004
- resolveCaller(input: ResolveInput): Promise<ResolveCallerResponse['caller']>;
2005
- deleteCaller(callerId: string): Promise<DeleteCallerResponse>;
2006
- }
2007
-
2008
- type CallStatus = 'in_progress' | 'completed' | 'failed';
2009
- type CallAttributeValue = string | number | boolean;
2010
- type CallParticipantRole = 'caller' | 'agent' | 'callee' | 'supervisor' | 'observer' | 'unknown';
2011
- type CallParticipantKind = 'human' | 'agent' | 'phone' | 'sip' | 'system';
2012
- type CallLegKind = 'sip-inbound' | 'sip-outbound' | 'agent-session' | 'conference' | 'transfer' | 'unknown';
2013
- type CallLegStatus = 'starting' | 'active' | 'ended';
2014
- interface CallSummary {
2015
- readonly id: string;
2016
- readonly projectId: string;
2017
- readonly livekitRoom: string;
2018
- readonly phoneNumberId: string | null;
2019
- readonly agentId: string | null;
2020
- readonly bindingId: string | null;
2021
- readonly callerE164: string | null;
2022
- readonly toE164: string | null;
2023
- readonly status: CallStatus;
2024
- readonly startedAt: string;
2025
- }
2026
- interface CallUsageReport {
2027
- readonly durationMs: number;
2028
- readonly llm: readonly {
2029
- readonly provider: string;
2030
- readonly model: string;
2031
- readonly inputTokens: number;
2032
- readonly outputTokens: number;
2033
- }[];
2034
- readonly tts: readonly {
2035
- readonly provider: string;
2036
- readonly chars: number;
2037
- }[];
2038
- readonly stt: readonly {
2039
- readonly provider: string;
2040
- readonly seconds: number;
2041
- }[];
2042
- }
2043
- interface AppendTranscriptInput {
2044
- readonly speaker: 'caller' | 'agent';
2045
- readonly text: string;
2046
- readonly startMs: number;
2047
- readonly endMs: number;
2048
- readonly final?: boolean;
2049
- }
2050
- type DtmfDirection = 'received' | 'sent';
2051
- interface AppendDtmfEventInput {
2052
- readonly direction: DtmfDirection;
2053
- readonly digit: string;
2054
- readonly code: number;
2055
- readonly participantId?: string;
2056
- }
2057
- interface EnsureCallByRoomInput {
2058
- readonly roomName: string;
2059
- readonly phoneNumberId?: string;
2060
- readonly agentId?: string;
2061
- readonly bindingId?: string;
2062
- readonly callerE164?: string;
2063
- readonly toE164?: string;
2064
- readonly attributes?: Record<string, CallAttributeValue>;
2065
- readonly participants?: CallParticipantInput[];
2066
- readonly legs?: CallLegInput[];
2067
- readonly startedAt?: string;
2068
- }
2069
- interface CallParticipantInput {
2070
- readonly participantKey: string;
2071
- readonly role: CallParticipantRole;
2072
- readonly kind: CallParticipantKind;
2073
- readonly identity?: string | null;
2074
- readonly address?: string | null;
2075
- readonly displayName?: string | null;
2076
- readonly joinedAt?: string;
2077
- readonly leftAt?: string | null;
2078
- readonly metadata?: Record<string, unknown>;
2079
- }
2080
- interface CallLegInput {
2081
- readonly legKey: string;
2082
- readonly kind: CallLegKind;
2083
- readonly status: CallLegStatus;
2084
- readonly fromParticipantKey?: string | null;
2085
- readonly toParticipantKey?: string | null;
2086
- readonly fromAddress?: string | null;
2087
- readonly toAddress?: string | null;
2088
- readonly startedAt?: string;
2089
- readonly endedAt?: string | null;
2090
- readonly metadata?: Record<string, unknown>;
2091
- }
2092
- interface SyncCallStateInput {
2093
- readonly attributes?: Record<string, CallAttributeValue>;
2094
- readonly participants?: CallParticipantInput[];
2095
- readonly legs?: CallLegInput[];
2096
- }
2097
- declare class CallsClient {
2098
- private readonly transport;
2099
- constructor(transport: Transport);
2100
- getByRoom(roomName: string): Promise<CallSummary>;
2101
- ensureByRoom(input: EnsureCallByRoomInput): Promise<CallSummary>;
2102
- syncState(callId: string, input: SyncCallStateInput): Promise<void>;
2103
- appendTranscriptSegment(callId: string, input: AppendTranscriptInput): Promise<void>;
2104
- reportUsage(callId: string, report: CallUsageReport): Promise<void>;
2105
- appendDtmfEvent(callId: string, input: AppendDtmfEventInput): Promise<void>;
2106
- /**
2107
- * Append a structured call event — consultation lifecycle kinds, or the
2108
- * operational vocabulary the call-detail Timeline renders between
2109
- * transcript rows (tool.* / handoff.* / lookup.* / record.* / notify.*).
2110
- * See apps/api/src/routes/calls.ts AppendEventBody for the accepted shapes.
2111
- *
2112
- * The agent SDK's built-in `ask_host` tool calls this on consultation start
2113
- * / end; the handoff runtime and graph interpreter emit op events through it
2114
- * so the operational story (dial → answered → briefed → dropped, tool calls)
2115
- * is visible in the dashboard, not just the spoken transcript.
2116
- */
2117
- appendEvent(callId: string, input: {
2118
- readonly kind: 'consultation.requested' | 'consultation.resolved' | `tool.${string}` | `handoff.${string}` | `lookup.${string}` | `record.${string}` | `notify.${string}`;
2119
- readonly payload: Record<string, unknown>;
2120
- }): Promise<void>;
2121
- }
2122
-
2123
- interface CreateFormSessionInput {
2124
- readonly formId: string;
2125
- readonly recipientPhone: string;
2126
- readonly recipientName?: string;
2127
- readonly prefill?: Record<string, unknown>;
2128
- readonly webhookUrl?: string;
2129
- readonly callbackFromNumber?: string;
2130
- readonly ttlSeconds?: number;
2131
- /**
2132
- * When set, the API will SMS the link from this phone number immediately
2133
- * after creating the session. This is the common case for agent-led use:
2134
- * the agent calls sendFormLink during a conversation and the recipient
2135
- * gets a text right away.
2136
- */
2137
- readonly sendSms?: {
2138
- readonly phoneNumberId: string;
2139
- readonly bodyPrefix?: string;
2140
- };
2141
- /**
2142
- * When set, the API will email the link to `to` immediately after creating
2143
- * the session. Independent from sendSms — set both for belt-and-braces
2144
- * delivery, set neither to just receive the URL back. Use this when SMS is
2145
- * blocked by toll-fraud / 10DLC registration.
2146
- */
2147
- readonly sendEmail?: {
2148
- readonly to: string;
2149
- readonly subject?: string;
2150
- readonly bodyPrefix?: string;
2151
- };
2152
- }
2153
- interface CreatedFormSession {
2154
- readonly sessionId: string;
2155
- readonly token: string;
2156
- readonly url: string;
2157
- readonly smsId: string | null;
2158
- readonly emailId: string | null;
2159
- readonly expiresAt: string;
2160
- }
2161
- interface PublicFormSessionView {
2162
- readonly schema: {
2163
- readonly id: string;
2164
- readonly version: number;
2165
- readonly title: string;
2166
- readonly description?: string | undefined;
2167
- readonly survey: Record<string, unknown>;
2168
- };
2169
- readonly values: Record<string, unknown>;
2170
- readonly status: 'pending' | 'active' | 'live' | 'submitted' | 'expired';
2171
- readonly recipientPhoneMasked: string;
2172
- readonly hasActiveCall: boolean;
2173
- readonly submittedAt: string | null;
2174
- readonly expiresAt: string;
2175
- }
2176
- declare class FormsClient {
2177
- private readonly transport;
2178
- constructor(transport: Transport);
2179
- createSession(input: CreateFormSessionInput): Promise<CreatedFormSession>;
2180
- getByToken(token: string): Promise<PublicFormSessionView>;
2181
- patchValues(token: string, values: Record<string, unknown>): Promise<{
2182
- values: Record<string, unknown>;
2183
- updatedAt: string;
2184
- }>;
2185
- submit(token: string, values: Record<string, unknown>): Promise<{
2186
- responseId: string;
2187
- submittedAt: string;
2188
- }>;
2189
- }
2190
-
2191
- interface SendEmailInput {
2192
- readonly to: string;
2193
- readonly subject: string;
2194
- readonly text: string;
2195
- readonly html?: string;
2196
- }
2197
- interface SentEmail {
2198
- readonly emailId: string;
2199
- }
2200
- declare class EmailClient {
2201
- private readonly transport;
2202
- constructor(transport: Transport);
2203
- send(input: SendEmailInput): Promise<SentEmail>;
2204
- }
2205
-
2206
- declare class PlansClient {
2207
- private readonly transport;
2208
- constructor(transport: Transport);
1968
+ /**
1969
+ * Answering-machine detection mode for outbound calls. Mirrors
1970
+ * `OutboundConfig.amd` in @voicelayer/agent-spec.
1971
+ *
1972
+ * 'off' — never run AMD; treat every answer as a human.
1973
+ * 'detect' — leave the voicemail message (or hang up) the moment
1974
+ * a machine greeting is recognised.
1975
+ * 'detectMessageEnd' — recognise the machine, then wait for the greeting to
1976
+ * finish (an explicit "after the tone"-style cue or the
1977
+ * greeting going quiet) before leaving the message.
1978
+ */
1979
+ type AmdMode = 'off' | 'detect' | 'detectMessageEnd';
1980
+ /**
1981
+ * Outbound-only behavior. AMD never runs on inbound calls (the runtime gates
1982
+ * on the dispatch-metadata `direction`), so these knobs are inert unless the
1983
+ * call was placed via the outbound path.
1984
+ */
1985
+ interface OutboundCallConfig {
1986
+ /** Answering-machine detection mode. Defaults to 'off'. */
1987
+ readonly amd?: AmdMode;
2209
1988
  /**
2210
- * Fetch a plan by id. Project scoping is enforced by the API via the
2211
- * caller's VOICELAYER_API_KEY — a cross-project planId surfaces as 404.
2212
- * Returns `null` on 404 so the caller can fall back to legacy boot.
1989
+ * Spoken (via TTS) when a machine is detected. When unset, the agent hangs
1990
+ * up on detection instead of leaving a message.
2213
1991
  */
2214
- getById(planId: string): Promise<CallPlan | null>;
2215
- }
2216
-
2217
- declare const ProviderCredential: z.ZodObject<{
2218
- apiKey: z.ZodString;
2219
- baseUrl: z.ZodOptional<z.ZodString>;
2220
- }, "strip", z.ZodTypeAny, {
2221
- apiKey: string;
2222
- baseUrl?: string | undefined;
2223
- }, {
2224
- apiKey: string;
2225
- baseUrl?: string | undefined;
2226
- }>;
2227
- type ProviderCredential = z.infer<typeof ProviderCredential>;
2228
- declare const BrainConnectorConfig: z.ZodObject<{
2229
- connector: z.ZodObject<{
2230
- id: z.ZodString;
2231
- mode: z.ZodEnum<["tunnel", "direct"]>;
2232
- connectionId: z.ZodNullable<z.ZodString>;
2233
- defaultModel: z.ZodNullable<z.ZodString>;
2234
- normalize: z.ZodEnum<["auto", "on", "off"]>;
2235
- enabled: z.ZodBoolean;
2236
- credential: z.ZodOptional<z.ZodNullable<z.ZodObject<{
2237
- apiKey: z.ZodString;
2238
- baseUrl: z.ZodString;
2239
- }, "strip", z.ZodTypeAny, {
2240
- apiKey: string;
2241
- baseUrl: string;
2242
- }, {
2243
- apiKey: string;
2244
- baseUrl: string;
2245
- }>>>;
2246
- }, "strip", z.ZodTypeAny, {
2247
- id: string;
2248
- enabled: boolean;
2249
- mode: "tunnel" | "direct";
2250
- defaultModel: string | null;
2251
- connectionId: string | null;
2252
- normalize: "on" | "off" | "auto";
2253
- credential?: {
2254
- apiKey: string;
2255
- baseUrl: string;
2256
- } | null | undefined;
2257
- }, {
2258
- id: string;
2259
- enabled: boolean;
2260
- mode: "tunnel" | "direct";
2261
- defaultModel: string | null;
2262
- connectionId: string | null;
2263
- normalize: "on" | "off" | "auto";
2264
- credential?: {
2265
- apiKey: string;
2266
- baseUrl: string;
2267
- } | null | undefined;
2268
- }>;
2269
- }, "strip", z.ZodTypeAny, {
2270
- connector: {
2271
- id: string;
2272
- enabled: boolean;
2273
- mode: "tunnel" | "direct";
2274
- defaultModel: string | null;
2275
- connectionId: string | null;
2276
- normalize: "on" | "off" | "auto";
2277
- credential?: {
2278
- apiKey: string;
2279
- baseUrl: string;
2280
- } | null | undefined;
2281
- };
2282
- }, {
2283
- connector: {
2284
- id: string;
2285
- enabled: boolean;
2286
- mode: "tunnel" | "direct";
2287
- defaultModel: string | null;
2288
- connectionId: string | null;
2289
- normalize: "on" | "off" | "auto";
2290
- credential?: {
2291
- apiKey: string;
2292
- baseUrl: string;
2293
- } | null | undefined;
2294
- };
2295
- }>;
2296
- type BrainConnectorConfig = z.infer<typeof BrainConnectorConfig>['connector'];
2297
- declare class ConnectionsClient {
2298
- private readonly transport;
2299
- constructor(transport: Transport);
2300
- resolveProviderCredential(provider: string): Promise<ProviderCredential | null>;
2301
- resolveBrainConnectorConfig(id: string): Promise<BrainConnectorConfig | null>;
2302
- }
2303
-
2304
- interface BrainMessage {
2305
- readonly role: 'system' | 'user' | 'assistant';
2306
- readonly content: string;
2307
- }
2308
- interface BrainCallMetadata {
2309
- readonly channel: 'voice' | 'text';
2310
- readonly callId?: string;
2311
- readonly projectId?: string;
1992
+ readonly voicemailScript?: string;
2312
1993
  }
2313
- interface BrainRequest {
2314
- readonly messages: readonly BrainMessage[];
2315
- /** Upstream model id / alias. Omitted → the brain's own default. */
2316
- readonly model?: string;
2317
- readonly temperature?: number;
2318
- readonly metadata: BrainCallMetadata;
2319
- }
2320
- /** One streamed piece of the brain's reply. */
2321
- interface BrainChunk {
2322
- readonly content?: string;
2323
- }
2324
- interface BrainCapabilities {
2325
- readonly reachable: boolean;
2326
- readonly streaming: boolean;
2327
- }
2328
- interface BrainTransport {
2329
- readonly kind: 'callback' | 'http' | 'tunnel';
2330
- /** Stream the reply token-by-token (the voice path: first sentence → TTS ASAP). */
2331
- stream(req: BrainRequest, signal: AbortSignal): AsyncIterable<BrainChunk>;
2332
- /** Non-streaming convenience (the text path). */
2333
- complete(req: BrainRequest, signal: AbortSignal): Promise<string>;
2334
- }
2335
- /** Context handed to a customer's in-process `onQuery` brain. */
2336
- interface OnQueryContext {
2337
- /** Full conversation so far (system + prior turns + latest user message). */
2338
- readonly messages: readonly BrainMessage[];
2339
- /** Aborts when the caller barges in / the turn is cancelled. */
2340
- readonly signal: AbortSignal;
2341
- }
2342
- type OnQueryResult = string | AsyncIterable<string>;
2343
1994
  /**
2344
- * Bring-your-own brain, in-process. Receives the latest user utterance (and the
2345
- * full history via `ctx.messages`) and returns the reply — either a string or an
2346
- * async-iterable of string pieces for token streaming.
1995
+ * Barge-in tuning. The pipeline allows interruptions by default (LK defaults:
1996
+ * any speech ≥500ms cuts the agent off). These knobs tune that behavior per
1997
+ * agent WITHOUT switching to puppet/hostControlled mode — e.g. a senior-living
1998
+ * help desk wants `minWords: 2` so backchannels ("mm-hm", "okay") don't
1999
+ * truncate the agent mid-sentence, while a fast-paced escalation desk keeps
2000
+ * the zero-word default. Set `enabled: false` to make the agent
2001
+ * non-interruptible (kiosk / broadcast announcements).
2347
2002
  */
2348
- type OnQuery = (text: string, ctx: OnQueryContext) => OnQueryResult | Promise<OnQueryResult>;
2349
-
2350
- /** Primitive field types accepted in a process definition. */
2351
- type ProcessFieldType = 'string' | 'string[]' | 'number' | 'boolean' | 'datetime' | 'email' | 'phone';
2352
- interface ProcessField {
2353
- readonly type: ProcessFieldType;
2354
- readonly required?: boolean;
2355
- /** Regex pattern for `string` / `string[]` items. */
2356
- readonly pattern?: RegExp;
2357
- /** Inclusive lower bound on a number or array length. */
2358
- readonly min?: number;
2359
- /** Inclusive upper bound on a number or array length. */
2360
- readonly max?: number;
2361
- /** One of N — restricts the captured value to this set. */
2362
- readonly enum?: readonly string[];
2363
- /** Override the auto-generated prompt for capturing this field. */
2364
- readonly ask?: string;
2365
- /** Override the field-extraction hint shown to the LLM. */
2366
- readonly extract?: string;
2367
- }
2368
- type CompletionStrategy = 'all-required-captured' | 'all-captured' | {
2369
- custom: (data: Record<string, unknown>, ctx: AgentContext) => boolean | Promise<boolean>;
2370
- };
2371
- interface ProcessBackendAck {
2372
- /** URL to POST captured data to. The call cannot complete until this 2xx's. */
2373
- readonly url: string;
2374
- readonly timeoutMs?: number;
2375
- readonly headers?: Readonly<Record<string, string>>;
2003
+ interface InterruptionConfig {
2004
+ /** Allow the caller to barge in over agent speech. Default true. */
2005
+ readonly enabled?: boolean;
2006
+ /** Words the caller must say before it counts as an interruption. Default 0
2007
+ * (any speech interrupts). 2–3 filters out backchannels. */
2008
+ readonly minWords?: number;
2009
+ /** Minimum caller speech duration (ms) to count as an interruption. Default 500. */
2010
+ readonly minDuration?: number;
2376
2011
  }
2377
- interface ProcessDefinition<T extends Record<string, ProcessField> = Record<string, ProcessField>> {
2378
- /** Field schema. Order is preserved when the SDK auto-asks for fields. */
2379
- readonly collect: T;
2380
- /** When the call can end. Defaults to 'all-required-captured'. */
2381
- readonly completeWhen?: CompletionStrategy;
2382
- /** Optional external system that must ACK before completion. */
2383
- readonly backendAck?: ProcessBackendAck;
2384
- /** Fires once all completion conditions are met. */
2385
- readonly onComplete?: (data: InferProcessData<T>, ctx: AgentContext) => Promise<void> | void;
2386
- /** Fires whenever a field is captured (good for live CRM updates). */
2387
- readonly onField?: <K extends keyof T>(field: K, value: InferFieldValue<T[K]>, ctx: AgentContext) => Promise<void> | void;
2012
+ /**
2013
+ * End-of-turn detection tuning: how long the pipeline waits after the caller
2014
+ * stops speaking before treating the turn as finished. Raise `minDelay` for
2015
+ * callers who pause mid-thought (e.g. elderly speakers); lower it for
2016
+ * fast-paced lines.
2017
+ */
2018
+ interface EndpointingConfig {
2019
+ /** Minimum silence (ms) before the caller's turn is considered done. Default 500. */
2020
+ readonly minDelay?: number;
2021
+ /** Hard ceiling (ms) after which the turn ends regardless. Default 3000. */
2022
+ readonly maxDelay?: number;
2388
2023
  }
2389
- /** Inferred TS type for the data bag a process produces. */
2390
- type InferProcessData<T extends Record<string, ProcessField>> = {
2391
- [K in keyof T]: T[K]['required'] extends true ? InferFieldValue<T[K]> : InferFieldValue<T[K]> | undefined;
2392
- };
2393
- type InferFieldValue<F extends ProcessField> = F['type'] extends 'string' ? string : F['type'] extends 'string[]' ? string[] : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'datetime' ? Date : F['type'] extends 'email' ? string : F['type'] extends 'phone' ? string : never;
2394
- type TriggerCondition = RegExp | `signal:${string}` | ((text: string, ctx: AgentContext) => boolean | Promise<boolean>);
2395
- type TriggerAction = 'handoff' | 'endCall' | {
2396
- say: string;
2397
- } | {
2398
- run: (ctx: AgentContext) => Promise<void> | void;
2024
+ /**
2025
+ * Speech polish. `pronunciations` rewrites brand names / acronyms / jargon to
2026
+ * a spoken form before TTS (e.g. `{ VoiceLayer: 'Voice Layer', API: 'A P I' }`)
2027
+ * via applyPronunciations(). `backgroundAudio` plays ambient room tone under
2028
+ * the agent so silence feels less dead (a URL or a named preset).
2029
+ * `interruption` + `endpointing` tune barge-in and turn-taking per agent.
2030
+ */
2031
+ interface SpeechConfig {
2032
+ readonly pronunciations?: Readonly<Record<string, string>>;
2033
+ readonly backgroundAudio?: string | {
2034
+ readonly url?: string;
2035
+ readonly volume?: number;
2036
+ };
2037
+ readonly interruption?: InterruptionConfig;
2038
+ readonly endpointing?: EndpointingConfig;
2399
2039
  }
2400
- /** Jump the flow-graph cursor to a node id. Only meaningful under the graph
2401
- * interpreter (the flat goals+rails path has no cursor and ignores it). */
2402
- | {
2403
- goto: string;
2404
- };
2405
- interface TriggerDefinition {
2406
- readonly on: TriggerCondition;
2407
- readonly then: TriggerAction;
2408
- /** If set, the trigger only fires while the named field is uncaptured. */
2409
- readonly onlyWhile?: string;
2040
+ /** What caused the call to end. Surfaced to `endCall.onEnd` + logs. */
2041
+ type EndCallTrigger =
2042
+ /** The LLM invoked the built-in `end_call` tool. */
2043
+ 'tool'
2044
+ /** An external controller (MCP host) sent a `hangup` command. */
2045
+ | 'host'
2046
+ /** The dead-air backstop fired (`idleHangupMs` of silence while idle). */
2047
+ | 'idle'
2048
+ /** The hard per-call ceiling fired (`maxCallDurationMs` elapsed). */
2049
+ | 'max_duration'
2050
+ /** The last non-agent participant left the room. */
2051
+ | 'participant-left'
2052
+ /** A flow/graph run finished and asked to hang up. */
2053
+ | 'flow'
2054
+ /** The realtime engine closed / disconnected under the session. */
2055
+ | 'engine-closed'
2056
+ /** `ctx.endCall()` called directly from user code. */
2057
+ | 'user';
2058
+ /** Passed to `endCall.onEnd` describing the teardown about to happen. */
2059
+ interface EndCallInfo {
2060
+ /** Why the call is ending (e.g. the `end_call` tool's `reason`). */
2061
+ readonly reason?: string;
2062
+ /** What triggered the hang-up. */
2063
+ readonly trigger: EndCallTrigger;
2064
+ /** The teardown strategy that will run (after the policy is resolved). */
2065
+ readonly teardown: 'room' | 'agent';
2410
2066
  }
2411
- interface HandoffConfig {
2412
- /** Default human number when a trigger says { then: 'handoff' }. */
2413
- readonly fallback: string;
2414
- /** Map signal/trigger names to specific destinations. */
2415
- readonly routes?: Readonly<Record<string, string>>;
2416
- /** Build the briefing text passed to the human agent (or PSTN whisper). */
2417
- readonly briefing?: (args: {
2418
- readonly data: Record<string, unknown>;
2419
- readonly transcript: TranscriptHandle;
2420
- readonly call: AgentContext['call'];
2421
- }) => string | Promise<string>;
2067
+ /**
2068
+ * Controls how the agent ENDS a call. The SDK — not the agent prompt or an
2069
+ * external puppet driver — owns teardown, so a hang-up is reliable even when
2070
+ * the realtime transport has died mid-wrap.
2071
+ *
2072
+ * Defaults are "best case" and active without opt-in: the whole LiveKit room
2073
+ * is deleted (which drops the SIP/PSTN leg too, so the carrier gets a BYE),
2074
+ * a guarantee-watchdog re-attempts teardown if the first try doesn't land, and
2075
+ * a dead-air backstop hangs up after the line has been silent too long. Every
2076
+ * knob is overridable; set a field to `false` to disable that guard.
2077
+ */
2078
+ interface EndCallPolicy {
2422
2079
  /**
2423
- * 'warm' (default) dials the human into the room as a conference, lets the
2424
- * agent brief them live, then drops the agent — caller + human stay
2425
- * connected. 'cold' is a blind SIP REFER: the caller is transferred away
2426
- * immediately. Warm falls back to cold when no outbound trunk is configured.
2080
+ * Teardown strategy. `'room'` (default) deletes the LiveKit room via the
2081
+ * room service — this removes the SIP participant too, so the call actually
2082
+ * disconnects on the carrier side. `'agent'` only drops the agent's own
2083
+ * participant (leaves any SIP leg up); use it only when something else owns
2084
+ * the room lifecycle.
2427
2085
  */
2428
- readonly mode?: 'warm' | 'cold';
2086
+ readonly teardown?: 'room' | 'agent';
2087
+ /**
2088
+ * After a hang-up is requested, keep re-attempting teardown until the room
2089
+ * is actually gone or this many ms elapse. Guards against a teardown call
2090
+ * that silently doesn't land (transport race, transient room-service error).
2091
+ * Default 4000. `false` disables (single best-effort attempt).
2092
+ */
2093
+ readonly guaranteeMs?: number | false;
2094
+ /**
2095
+ * Dead-air backstop: when the agent is idle (waiting on the caller) and the
2096
+ * line stays silent — no agent turn, no caller speech — for this many ms,
2097
+ * end the call. Catches a wedged session whose normal `end_call` never ran.
2098
+ * Only armed while the agent is idle, so it never interrupts agent speech or
2099
+ * a long tool call. Default 20000. `false` disables.
2100
+ */
2101
+ readonly idleHangupMs?: number | false;
2102
+ /**
2103
+ * Hard call ceiling: hang up once the call has run this many ms from when
2104
+ * the session becomes ready, regardless of activity. Catches runaway calls
2105
+ * that never end naturally (stuck loops, hijacked keys dialing premium
2106
+ * numbers). Fires with trigger `'max_duration'`. Default 3600000 (60
2107
+ * minutes). `false` disables.
2108
+ */
2109
+ readonly maxCallDurationMs?: number | false;
2110
+ /**
2111
+ * Hook fired the moment a hang-up is decided, just before teardown — for
2112
+ * every trigger (tool, host, idle, max_duration, engine-closed, …). Return
2113
+ * `false` to take over teardown yourself (the SDK then does nothing — the
2114
+ * call will NOT end unless you end it). Returning anything else (or nothing)
2115
+ * runs the default teardown. Throwing is caught + logged, then the default
2116
+ * teardown still runs (safe by default).
2117
+ *
2118
+ * EXCEPT a host hangup (`trigger: 'host'` — MCP `call_hangup`): the host is
2119
+ * the operator, so the hook is told (with the host's reason) and given 2
2120
+ * seconds, but can't keep the call open; the room is always deleted, even
2121
+ * after an earlier hang-up was vetoed and whatever `teardown` says (0.2.0).
2122
+ */
2123
+ readonly onEnd?: (ctx: AgentContext, info: EndCallInfo) => boolean | void | Promise<boolean | void>;
2429
2124
  }
2430
- interface TranscriptHandle {
2431
- /** Last N turns as `speaker: text` lines. */
2432
- tail(n: number): string;
2433
- full(): string;
2125
+ type ShorthandPrimitive$1 = 'string' | 'number' | 'boolean';
2126
+ type ToolInputShape$1 = Record<string, ShorthandPrimitive$1> | z.ZodTypeAny;
2127
+ interface ToolDefinition$1<I = unknown, R = unknown> {
2128
+ readonly description: string;
2129
+ readonly input: ToolInputShape$1;
2130
+ readonly run: (input: I, ctx: AgentContext) => Promise<R> | R;
2131
+ /**
2132
+ * Capability this tool requires. Action Guard hard-blocks the call if not
2133
+ * declared (PRD §B.5 — "no soft failures, ever"). Defaults to
2134
+ * `tool.<name>` when omitted; passing a domain-scoped string
2135
+ * (`crm.write`, `payment.refund`) lets multiple tools share a capability
2136
+ * for centralised policy.
2137
+ */
2138
+ readonly capability?: string;
2434
2139
  }
2435
2140
  /**
2436
- * Memory scope. `'participant'` and `'caller'` are synonyms — `'caller'`
2437
- * is the historical name from the 1:1 era; new code should prefer
2438
- * `'participant'`, which makes the multi-party semantics explicit.
2141
+ * Optional security adapters. The SDK always enforces the local-only synchronous
2142
+ * guards (PRD §B.2 input regex, §B.3 system seal + PII tokenisation, §B.4
2143
+ * markdown strip + PII partial-mask, §B.5 capability check). Setting any of
2144
+ * these augments the local floor with external services. Each is independently
2145
+ * optional — none has to be live for the floor guards to function.
2146
+ *
2147
+ * URLs can also come from env (`SECURITY_LLM_GUARD_URL`,
2148
+ * `SECURITY_PRESIDIO_ANALYZER_URL`, `SECURITY_PRESIDIO_ANONYMIZER_URL`,
2149
+ * `SECURITY_OPA_URL`, `SECURITY_OPA_DECISION_PATH`); explicit config wins.
2439
2150
  */
2440
- type MemoryScope = 'call' | 'caller' | 'participant' | 'account' | 'platform';
2441
- interface MemoryConfig {
2442
- /** Which scope to persist to. Defaults to 'caller'. */
2443
- readonly scope?: MemoryScope;
2444
- readonly retentionDays?: number;
2445
- /** Fields auto-redacted on write. Recognized: ssn, dob, email, phone, ccn. */
2446
- readonly piiFields?: readonly string[];
2447
- /** Opt in to cross-tenant aggregate memory (anonymized). */
2448
- readonly platformOptIn?: boolean;
2151
+ interface SecurityConfig {
2152
+ /** Disable the primitive entirely. Use only for tests. Production code MUST NOT set this. */
2153
+ readonly disabled?: boolean;
2154
+ /** External LLM-Guard adapter for richer injection detection. */
2155
+ readonly llmGuardUrl?: string;
2156
+ /** Presidio analyzer URL for PII detection beyond local regex. */
2157
+ readonly presidioAnalyzerUrl?: string;
2158
+ /** Presidio anonymizer URL — if set, output is redacted before TTS. */
2159
+ readonly presidioAnonymizerUrl?: string;
2160
+ /** OPA decision API base URL (e.g. `http://opa:8181`). */
2161
+ readonly opaUrl?: string;
2162
+ /** OPA decision path (e.g. `voicelayer/security/decision`). */
2163
+ readonly opaDecisionPath?: string;
2164
+ /** Per-request timeout for security adapter calls. */
2165
+ readonly adapterTimeoutMs?: number;
2449
2166
  }
2450
2167
  /**
2451
- * Multi-participant configuration. Optional — when omitted, the agent runs
2452
- * in 1:1 mode (one human + one agent) and the SDK still populates
2453
- * `ctx.room.participants` so participant-aware code paths work.
2168
+ * Marks an agent as a *flow-runtime* worker: instead of a fixed process it
2169
+ * resolves the deployed flow from the dispatch metadata (`agentId`) at call
2170
+ * time, fetches that agent's compiled process_schema, and boots from it. One
2171
+ * process serves many flows (the shared pool). See defineFlowRuntime().
2454
2172
  */
2455
- interface ParticipantsConfig {
2173
+ interface FlowRuntimeConfig {
2174
+ /** Prepended to the flow's compiled say/confirm prompt fragments. */
2175
+ readonly basePrompt?: string;
2176
+ /** Spoken (verbatim) before hanging up when a flow call's schema cannot be
2177
+ * loaded. A failed flow boot NEVER silently answers as a generic assistant. */
2178
+ readonly bootFailureMessage?: string;
2179
+ }
2180
+ /** Output content-moderation guard config (P5). Mirrors @voicelayer/plugin-guard's
2181
+ * GuardConfig; the pure inspector lives in runtime/guard.ts. */
2182
+ interface GuardConfig {
2183
+ /** Flag content longer than this many characters. Default 8000. */
2184
+ readonly maxLength?: number;
2185
+ /** Substrings that flag content (case-insensitive). Default none. */
2186
+ readonly bannedSubstrings?: readonly string[];
2187
+ }
2188
+ interface AgentConfig<TProcess extends Record<string, ProcessField> = Record<string, ProcessField>> {
2189
+ /** Lowercase, kebab-case identifier. Used for LiveKit dispatch + presence. */
2190
+ readonly name: string;
2191
+ /** System prompt the LLM sees. */
2192
+ readonly prompt: string;
2193
+ /** Fixed opening line, spoken instantly via TTS at the start of the default
2194
+ * conversation flow — NO LLM. Eliminates the dead air of an LLM-generated
2195
+ * greeting (the first generateReply must process the whole system prompt).
2196
+ * Absent → the SDK falls back to an LLM-generated greeting. */
2197
+ readonly greeting?: string;
2198
+ /** Agent-level Instructions (the routing/decision layer): plain-language guidance
2199
+ * for WHEN the agent acts, appended below the persona under a `# Routing` header.
2200
+ * Interpolated with {{ }} by the process runtime. Optional. */
2201
+ readonly routingInstructions?: string;
2202
+ /** Capability tags surfaced in the dashboard. */
2203
+ readonly capabilities?: readonly string[];
2204
+ /** Semantic version. Defaults to AGENT_VERSION env or '0.0.0'. */
2205
+ readonly version?: string;
2206
+ /** dev / stg / prd. Defaults to AGENT_ENVIRONMENT env or 'dev'. */
2207
+ readonly environment?: AgentEnvironment;
2208
+ readonly process?: ProcessDefinition<TProcess>;
2209
+ readonly triggers?: Readonly<Record<string, TriggerDefinition>>;
2210
+ readonly handoff?: HandoffConfig;
2211
+ readonly memory?: MemoryConfig;
2212
+ readonly participants?: ParticipantsConfig;
2213
+ readonly connectors?: Readonly<Record<string, ConnectorInstance>>;
2214
+ readonly compliance?: readonly ComplianceTag[];
2215
+ readonly models?: ModelConfig;
2216
+ readonly outbound?: OutboundCallConfig;
2217
+ readonly speech?: SpeechConfig;
2218
+ readonly endCall?: EndCallPolicy;
2219
+ readonly tools?: Readonly<Record<string, ToolDefinition$1>>;
2220
+ /** Per-agent registry-tool scoping (stored ToolBinding names, applied at
2221
+ * boot). Non-empty → only these dashboard HTTP tools attach; absent/[] →
2222
+ * every enabled registry tool attaches (the historical default). */
2223
+ readonly toolBindings?: readonly string[];
2224
+ readonly security?: SecurityConfig;
2225
+ /** Output content-moderation guard (P5). When set, each assistant turn is
2226
+ * inspected and a violation is recorded as an engine.guard.blocked event on
2227
+ * the call timeline. OBSERVE-ONLY on voice — it audits, it does not unsay a
2228
+ * spoken turn. Absent → no guard. */
2229
+ readonly guard?: GuardConfig;
2456
2230
  /**
2457
- * Fires when a human participant joins the room. In 1:1 calls this
2458
- * fires once at session start for the caller. In multi-party calls it
2459
- * fires per join.
2231
+ * Per-call ConsultationPolicy used by the built-in `ask_host` tool. When
2232
+ * omitted the SDK uses the contract defaults (30s per-consult, 120s
2233
+ * cumulative). Plan-first calls override this at boot from
2234
+ * `plan.draftConfig.consultation`. See
2235
+ * packages/contracts/src/consultation.ts for the schema + semantics.
2460
2236
  */
2461
- readonly onJoin?: (participant: Participant, ctx: AgentContext) => Promise<void> | void;
2462
- /** Fires when a participant disconnects (hangup, transfer, kick). */
2463
- readonly onLeave?: (participant: Participant, ctx: AgentContext) => Promise<void> | void;
2237
+ readonly consultation?: ConsultationPolicy;
2464
2238
  /**
2465
- * Synchronously enrich a participant's attribute bag before `onJoin`
2466
- * fires. Useful for phone-number → language lookups, etc. The returned
2467
- * map is merged into `participant.attributes`.
2239
+ * Use your existing text agent as the LLM. When set (and `models.llm` is
2240
+ * unset), defineAgent wires the pipeline's LLM slot to this function: the
2241
+ * caller's STT transcript is passed to `onQuery`, and its returned text (or
2242
+ * streamed pieces) is spoken by TTS. The "two lines, keep your stack" path.
2243
+ *
2244
+ * Equivalent to `models: { llm: connector.llm({ onQuery }) }`. For a remote
2245
+ * brain instead, use `connector.llm({ url })` (direct) or a tunnel transport.
2246
+ * See docs/specs/voice-brain-connector/.
2468
2247
  */
2469
- readonly attributes?: (participant: Participant) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
2248
+ readonly onQuery?: OnQuery;
2249
+ readonly onUtterance?: (text: string, ctx: AgentContext) => Promise<void> | void;
2250
+ readonly onFieldCaptured?: (field: string, value: unknown, ctx: AgentContext) => Promise<void> | void;
2251
+ readonly onCallEnd?: (outcome: CallOutcomeSummary, ctx: AgentContext) => Promise<void> | void;
2252
+ readonly onEvent?: (event: AgentLifecycleEvent) => void;
2253
+ /** Replace the default conversation loop. The SDK does NOT auto-greet. */
2254
+ readonly onCall?: (ctx: AgentContext) => Promise<void>;
2255
+ readonly readiness?: readonly ReadinessProbe[];
2470
2256
  /**
2471
- * Reject participants beyond this count. Default: unlimited. The cap
2472
- * is enforced by the worker when wiring participant lifecycle.
2257
+ * Run as a remote-controlled (puppet) agent: no autonomous LLM loop, no
2258
+ * process/triggers pipeline. STT utterances are still published to
2259
+ * `call-events:{callId}` via the existing transcript-segments sync, and
2260
+ * the SDK subscribes to `call-control:{room}` to receive `say`,
2261
+ * `hangup`, `dtmf` commands from an external driver (typically the MCP
2262
+ * server invoked by a coding agent).
2263
+ *
2264
+ * When this is on, `process`, `triggers`, `onUtterance`, `onCall` are
2265
+ * ignored. `tools`, `connectors`, `memory` still work.
2266
+ */
2267
+ readonly puppetMode?: boolean;
2268
+ /**
2269
+ * Host-controlled autonomous agent (the "smart puppet"). UNLIKE puppetMode,
2270
+ * the agent keeps its REAL LLM and drives the conversation itself from its
2271
+ * prompt (the per-call `intent` is appended at boot). Since 0.2.0 EVERY
2272
+ * agent listens on its call's control channel (the MCP host can interject
2273
+ * with `say`, `hangup` or send `dtmf`, and answer `ask_host`), so this flag
2274
+ * now only shapes turn handling for a host-driven call. Use this for an agent that takes a customer's
2275
+ * intent and runs the call like a human secretary, asking the host for any
2276
+ * info it's missing. Mutually exclusive in spirit with puppetMode (which is
2277
+ * the older NoOp "dumb mouth").
2278
+ */
2279
+ readonly hostControlled?: boolean;
2280
+ /** When set, this agent boots each call from a deployed flow's process_schema. */
2281
+ readonly flowRuntime?: FlowRuntimeConfig;
2282
+ /**
2283
+ * Opt a hand-coded (non-flow) agent into the dashboard-driven pipeline: on
2284
+ * each call the SDK fetches this agent's PUBLISHED configuration (a saved
2285
+ * dashboard draft applies only once the owner publishes it) and applies
2286
+ * the operator-selected voice / model / STT over the coded defaults. The
2287
+ * pipeline *mode* (cascade vs realtime) stays pinned to what the code
2288
+ * declares — a stale `mode=realtime` in the dashboard can't flip a
2289
+ * cascade-only worker. Flow agents (`flowRuntime`) get this implicitly and
2290
+ * may additionally switch mode; this flag is the SDK opt-in. The agent id is
2291
+ * read from dispatch metadata (the inbound router injects it from
2292
+ * phone_numbers.agentId), so it's a no-op for calls without one.
2293
+ */
2294
+ readonly pipelineFromConfig?: boolean;
2295
+ /**
2296
+ * Opt this agent into MCP-layer visibility. When true, on register the API
2297
+ * also writes an `agent_config` row keyed by (project_id, name,
2298
+ * environment) so MCP / dashboard / REST can list and inspect this agent
2299
+ * (and, post-step-7, drive call_say / call_send_guidance / etc against
2300
+ * its live calls).
2301
+ *
2302
+ * Defaults to true so newly-registered agents show up in dashboards and
2303
+ * MCP-host listings without opt-in. Pass `false` for autonomous-only
2304
+ * agents that should stay invisible to MCP. See
2305
+ * docs/architecture/contracts-design.md §2b.
2473
2306
  */
2474
- readonly max?: number;
2307
+ readonly mcpExposed?: boolean;
2475
2308
  }
2476
- /**
2477
- * A connector instance. Created by per-system factories like `salesforce()`,
2478
- * `twilio()`, etc. The factory returns an opaque handle that the SDK wires
2479
- * into `ctx.connectors` and (when `expose: true`) into the LLM tool list.
2480
- */
2481
- interface ConnectorInstance<TName extends string = string, TApi = unknown> {
2482
- readonly __connector: true;
2483
- readonly name: TName;
2484
- readonly api: TApi;
2485
- /** If true, every method on `api` becomes an LLM-callable tool. */
2486
- readonly expose?: boolean;
2309
+ interface CallOutcomeSummary {
2310
+ readonly reason: 'completed' | 'handoff' | 'caller_hung_up' | 'agent_hung_up' | 'error';
2311
+ readonly durationMs: number;
2312
+ readonly processCompleted: boolean;
2313
+ readonly fieldsCaptured: number;
2314
+ readonly handoffOccurred: boolean;
2487
2315
  }
2488
- type ComplianceTag = 'tcpa' | 'hipaa' | 'pci' | 'gdpr' | 'soc2';
2489
2316
  /**
2490
- * Duck-typed pipeline component markers. The SDK never inspects these — they
2491
- * are passed through to LiveKit's AgentSession as-is. Three ways to satisfy:
2492
- *
2493
- * 1. SDK factory: `deepgram.tts({ model: 'aura-2' })`
2494
- * 2. Wrapped LK: `wrap(new TTS({...}), { trace: true })`
2495
- * 3. User-built: class MyTTS extends BaseTTS { ... } // BaseTTS
2496
- * // re-exported
2497
- * // from the SDK
2317
+ * Identity helper that gives users a typed `defineProcess` entry point with
2318
+ * full inference on `onComplete`'s `data` argument.
2498
2319
  *
2499
- * Anything implementing the duck-type — even a plain object — is accepted.
2320
+ * defineProcess({
2321
+ * collect: { name: { type: 'string', required: true } },
2322
+ * onComplete: (data) => { data.name // string },
2323
+ * })
2500
2324
  */
2501
- interface STTProvider {
2502
- readonly __vlPipeline?: 'stt';
2503
- }
2504
- interface LLMProvider {
2505
- readonly __vlPipeline?: 'llm';
2506
- }
2507
- interface TTSProvider {
2508
- readonly __vlPipeline?: 'tts';
2509
- }
2510
- interface VADProvider {
2511
- readonly __vlPipeline?: 'vad';
2325
+ declare function defineProcess<T extends Record<string, ProcessField>>(def: ProcessDefinition<T>): ProcessDefinition<T>;
2326
+
2327
+ interface TransportOptions {
2328
+ readonly apiKey: string;
2329
+ readonly baseUrl: string;
2330
+ readonly fetch?: typeof fetch;
2331
+ readonly maxRetries?: number;
2332
+ readonly initialBackoffMs?: number;
2333
+ readonly userAgent?: string;
2512
2334
  }
2513
- interface TurnDetectorProvider {
2514
- readonly __vlPipeline?: 'turn';
2335
+ interface RequestOptions {
2336
+ readonly method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
2337
+ readonly path: string;
2338
+ readonly body?: unknown;
2339
+ readonly query?: Record<string, string | undefined>;
2340
+ readonly signal?: AbortSignal;
2341
+ /** Extra request headers, merged on top of the defaults (auth/content-type
2342
+ * etc). Lowercase keys recommended. */
2343
+ readonly headers?: Record<string, string>;
2515
2344
  }
2516
- /**
2517
- * Speech-to-speech / realtime model marker (OpenAI Realtime, Gemini Live).
2518
- * A realtime model handles STT + LLM + TTS + turn-taking server-side, so when
2519
- * `models.realtime` is set the SDK builds the AgentSession around it and
2520
- * ignores the stt/llm/tts slots.
2521
- */
2522
- interface RealtimeProvider {
2523
- readonly __vlPipeline?: 'realtime';
2345
+ declare class Transport {
2346
+ private readonly options;
2347
+ private readonly fetchImpl;
2348
+ private readonly maxRetries;
2349
+ private readonly initialBackoffMs;
2350
+ constructor(options: TransportOptions);
2351
+ request<T>(opts: RequestOptions, schema: ZodType<T>): Promise<T>;
2352
+ private backoffMs;
2524
2353
  }
2525
- /**
2526
- * Lazy form so users can pick a provider per call (e.g. by caller locale).
2527
- * The factory runs once per call, before AgentSession is constructed, so it
2528
- * receives the call envelope (callerId, to, metadata) rather than the full
2529
- * AgentContext (which depends on AgentSession existing).
2530
- */
2531
- type ProviderFactory<T> = (call: CallInfo) => T | Promise<T>;
2532
- interface ModelConfig {
2354
+
2355
+ interface RegisterInput {
2356
+ readonly name: string;
2357
+ readonly version: string;
2358
+ readonly environment: AgentEnvironment;
2359
+ /** Capability tags (e.g. ['fnol', 'es-MX']). Surfaced in the dashboard. */
2360
+ readonly capabilities?: readonly string[];
2533
2361
  /**
2534
- * String form: 'openai/gpt-4o' (resolves via SDK defaults).
2535
- * Instance form: any LLMProvider (LK plugin, wrap()-ed, or user-built).
2536
- * Factory form: `(ctx) => provider` for per-call selection.
2362
+ * JSON-serializable process schema for the dashboard "what this agent does"
2363
+ * view. Built by `buildProcessSchemaDTO` from the agent's ProcessDefinition.
2537
2364
  */
2538
- readonly llm?: string | LLMProvider | ProviderFactory<LLMProvider>;
2539
- readonly stt?: string | STTProvider | ProviderFactory<STTProvider>;
2540
- readonly tts?: string | TTSProvider | ProviderFactory<TTSProvider>;
2541
- /** VAD has no string form — always pass an instance or factory. */
2542
- readonly vad?: VADProvider | ProviderFactory<VADProvider>;
2543
- readonly turnDetector?: TurnDetectorProvider | ProviderFactory<TurnDetectorProvider>;
2365
+ readonly processSchema?: ProcessSchemaDTO | null;
2544
2366
  /**
2545
- * Speech-to-speech / realtime model. When set, the STT→LLM→TTS pipeline is
2546
- * bypassed: the realtime model drives the whole turn. No string form — pass
2547
- * an instance (`openai.realtime({ voice: 'alloy' })`) or a per-call factory.
2367
+ * A code-first agent's base prompt (its `defineAgent({ prompt })`). Synced to
2368
+ * the agent's record (the dashboard shows it). Omit for flow agents (their
2369
+ * behavior lives in the compiled program).
2548
2370
  */
2549
- readonly realtime?: RealtimeProvider | ProviderFactory<RealtimeProvider>;
2550
- /** Spoken language; defaults to 'en-US'. Used by string-form defaults. */
2551
- readonly language?: string;
2552
- }
2553
- /**
2554
- * Answering-machine detection mode for outbound calls. Mirrors
2555
- * `OutboundConfig.amd` in @voicelayer/agent-spec.
2556
- *
2557
- * 'off' — never run AMD; treat every answer as a human.
2558
- * 'detect' — leave the voicemail message (or hang up) the moment
2559
- * a machine greeting is recognised.
2560
- * 'detectMessageEnd' — recognise the machine, then wait for the greeting to
2561
- * finish (an explicit "after the tone"-style cue or the
2562
- * greeting going quiet) before leaving the message.
2563
- */
2564
- type AmdMode = 'off' | 'detect' | 'detectMessageEnd';
2565
- /**
2566
- * Outbound-only behavior. AMD never runs on inbound calls (the runtime gates
2567
- * on the dispatch-metadata `direction`), so these knobs are inert unless the
2568
- * call was placed via the outbound path.
2569
- */
2570
- interface OutboundCallConfig {
2571
- /** Answering-machine detection mode. Defaults to 'off'. */
2572
- readonly amd?: AmdMode;
2371
+ readonly prompt?: string | null;
2573
2372
  /**
2574
- * Spoken (via TTS) when a machine is detected. When unset, the agent hangs
2575
- * up on detection instead of leaving a message.
2373
+ * The text-turn protocol this worker speaks (burn-down G-4): it registered `<name>::text` and answers text turns as
2374
+ * the agent. Omit when it doesn't — the agent is then not text-runnable.
2576
2375
  */
2577
- readonly voicemailScript?: string;
2578
- }
2579
- /**
2580
- * Barge-in tuning. The pipeline allows interruptions by default (LK defaults:
2581
- * any speech ≥500ms cuts the agent off). These knobs tune that behavior per
2582
- * agent WITHOUT switching to puppet/hostControlled mode — e.g. a senior-living
2583
- * help desk wants `minWords: 2` so backchannels ("mm-hm", "okay") don't
2584
- * truncate the agent mid-sentence, while a fast-paced escalation desk keeps
2585
- * the zero-word default. Set `enabled: false` to make the agent
2586
- * non-interruptible (kiosk / broadcast announcements).
2587
- */
2588
- interface InterruptionConfig {
2589
- /** Allow the caller to barge in over agent speech. Default true. */
2590
- readonly enabled?: boolean;
2591
- /** Words the caller must say before it counts as an interruption. Default 0
2592
- * (any speech interrupts). 2–3 filters out backchannels. */
2593
- readonly minWords?: number;
2594
- /** Minimum caller speech duration (ms) to count as an interruption. Default 500. */
2595
- readonly minDuration?: number;
2596
- }
2597
- /**
2598
- * End-of-turn detection tuning: how long the pipeline waits after the caller
2599
- * stops speaking before treating the turn as finished. Raise `minDelay` for
2600
- * callers who pause mid-thought (e.g. elderly speakers); lower it for
2601
- * fast-paced lines.
2602
- */
2603
- interface EndpointingConfig {
2604
- /** Minimum silence (ms) before the caller's turn is considered done. Default 500. */
2605
- readonly minDelay?: number;
2606
- /** Hard ceiling (ms) after which the turn ends regardless. Default 3000. */
2607
- readonly maxDelay?: number;
2608
- }
2609
- /**
2610
- * Speech polish. `pronunciations` rewrites brand names / acronyms / jargon to
2611
- * a spoken form before TTS (e.g. `{ VoiceLayer: 'Voice Layer', API: 'A P I' }`)
2612
- * via applyPronunciations(). `backgroundAudio` plays ambient room tone under
2613
- * the agent so silence feels less dead (a URL or a named preset).
2614
- * `interruption` + `endpointing` tune barge-in and turn-taking per agent.
2615
- */
2616
- interface SpeechConfig {
2617
- readonly pronunciations?: Readonly<Record<string, string>>;
2618
- readonly backgroundAudio?: string | {
2619
- readonly url?: string;
2620
- readonly volume?: number;
2621
- };
2622
- readonly interruption?: InterruptionConfig;
2623
- readonly endpointing?: EndpointingConfig;
2624
- }
2625
- /** What caused the call to end. Surfaced to `endCall.onEnd` + logs. */
2626
- type EndCallTrigger =
2627
- /** The LLM invoked the built-in `end_call` tool. */
2628
- 'tool'
2629
- /** An external controller (MCP host) sent a `hangup` command. */
2630
- | 'host'
2631
- /** The dead-air backstop fired (`idleHangupMs` of silence while idle). */
2632
- | 'idle'
2633
- /** The hard per-call ceiling fired (`maxCallDurationMs` elapsed). */
2634
- | 'max_duration'
2635
- /** The last non-agent participant left the room. */
2636
- | 'participant-left'
2637
- /** A flow/graph run finished and asked to hang up. */
2638
- | 'flow'
2639
- /** The realtime engine closed / disconnected under the session. */
2640
- | 'engine-closed'
2641
- /** `ctx.endCall()` called directly from user code. */
2642
- | 'user';
2643
- /** Passed to `endCall.onEnd` describing the teardown about to happen. */
2644
- interface EndCallInfo {
2645
- /** Why the call is ending (e.g. the `end_call` tool's `reason`). */
2646
- readonly reason?: string;
2647
- /** What triggered the hang-up. */
2648
- readonly trigger: EndCallTrigger;
2649
- /** The teardown strategy that will run (after the policy is resolved). */
2650
- readonly teardown: 'room' | 'agent';
2651
- }
2652
- /**
2653
- * Controls how the agent ENDS a call. The SDK — not the agent prompt or an
2654
- * external puppet driver — owns teardown, so a hang-up is reliable even when
2655
- * the realtime transport has died mid-wrap.
2656
- *
2657
- * Defaults are "best case" and active without opt-in: the whole LiveKit room
2658
- * is deleted (which drops the SIP/PSTN leg too, so the carrier gets a BYE),
2659
- * a guarantee-watchdog re-attempts teardown if the first try doesn't land, and
2660
- * a dead-air backstop hangs up after the line has been silent too long. Every
2661
- * knob is overridable; set a field to `false` to disable that guard.
2662
- */
2663
- interface EndCallPolicy {
2376
+ readonly textTurns?: number;
2377
+ /**
2378
+ * Opt this agent into MCP exposure. When true, the API upserts a matching
2379
+ * agent_config row keyed by (project_id, name, environment) so MCP /
2380
+ * dashboard / REST can list and inspect this agent. Default false — pure
2381
+ * SDK agents that don't need MCP visibility stay invisible to it. See
2382
+ * docs/architecture/contracts-design.md §2b.
2383
+ */
2384
+ readonly mcpExposed?: boolean;
2385
+ /**
2386
+ * Self-checks run before sending the register request. Each result is
2387
+ * recorded on the agent. See RegisterOptions.requireReady for failure
2388
+ * policy.
2389
+ */
2390
+ readonly readiness?: readonly ReadinessProbe[];
2391
+ /** User metadata. Merged on top of default metadata (user wins on conflict). */
2392
+ readonly metadata?: Record<string, unknown>;
2393
+ /**
2394
+ * Whether to auto-collect host/runtime/build metadata. Default true. Set
2395
+ * false to send exactly what you pass in `metadata`.
2396
+ */
2397
+ readonly collectDefaults?: boolean;
2398
+ }
2399
+ interface RegisterOptions {
2664
2400
  /**
2665
- * Teardown strategy. `'room'` (default) deletes the LiveKit room via the
2666
- * room service — this removes the SIP participant too, so the call actually
2667
- * disconnects on the carrier side. `'agent'` only drops the agent's own
2668
- * participant (leaves any SIP leg up); use it only when something else owns
2669
- * the room lifecycle.
2401
+ * Override server-suggested heartbeat cadence (ms). When omitted, the SDK
2402
+ * uses the value returned by /v1/agents/register, falling back to
2403
+ * AGENT_HEARTBEAT_INTERVAL_MS.
2670
2404
  */
2671
- readonly teardown?: 'room' | 'agent';
2405
+ readonly heartbeatIntervalMs?: number;
2672
2406
  /**
2673
- * After a hang-up is requested, keep re-attempting teardown until the room
2674
- * is actually gone or this many ms elapse. Guards against a teardown call
2675
- * that silently doesn't land (transport race, transient room-service error).
2676
- * Default 4000. `false` disables (single best-effort attempt).
2407
+ * Disable signal handlers (SIGTERM/SIGINT). Useful in tests and in hosts
2408
+ * that own their own shutdown lifecycle.
2677
2409
  */
2678
- readonly guaranteeMs?: number | false;
2410
+ readonly attachSignalHandlers?: boolean;
2679
2411
  /**
2680
- * Dead-air backstop: when the agent is idle (waiting on the caller) and the
2681
- * line stays silent — no agent turn, no caller speech — for this many ms,
2682
- * end the call. Catches a wedged session whose normal `end_call` never ran.
2683
- * Only armed while the agent is idle, so it never interrupts agent speech or
2684
- * a long tool call. Default 20000. `false` disables.
2412
+ * On SIGTERM/SIGINT, call DELETE /v1/agents/:id before exiting so the
2413
+ * dashboard reflects "gone" immediately instead of waiting for offline
2414
+ * timeout. Default true. Best-effort: errors are swallowed.
2685
2415
  */
2686
- readonly idleHangupMs?: number | false;
2416
+ readonly deregisterOnSignal?: boolean;
2687
2417
  /**
2688
- * Hard call ceiling: hang up once the call has run this many ms from when
2689
- * the session becomes ready, regardless of activity. Catches runaway calls
2690
- * that never end naturally (stuck loops, hijacked keys dialing premium
2691
- * numbers). Fires with trigger `'max_duration'`. Default 3600000 (60
2692
- * minutes). `false` disables.
2418
+ * If any readiness probe reports !ok, throw before calling register.
2419
+ * Default false: probes that fail mark the agent as `degraded` instead.
2693
2420
  */
2694
- readonly maxCallDurationMs?: number | false;
2421
+ readonly requireReady?: boolean;
2695
2422
  /**
2696
- * Hook fired the moment a hang-up is decided, just before teardown — for
2697
- * every trigger (tool, host, idle, max_duration, engine-closed, …). Return
2698
- * `false` to take over teardown yourself (the SDK then does nothing — the
2699
- * call will NOT end unless you end it). Returning anything else (or nothing)
2700
- * runs the default teardown. Throwing is caught + logged, then the default
2701
- * teardown still runs (safe by default).
2423
+ * Listener for lifecycle events. Equivalent to `agent.events.on(fn)` after
2424
+ * register; register-time events (readiness, registered) are also delivered.
2702
2425
  */
2703
- readonly onEnd?: (ctx: AgentContext, info: EndCallInfo) => boolean | void | Promise<boolean | void>;
2426
+ readonly onEvent?: (event: AgentLifecycleEvent) => void;
2427
+ }
2428
+ interface RegisteredAgent {
2429
+ readonly agent: AgentDTO;
2430
+ readonly events: AgentEventEmitter;
2431
+ /** Push a status change immediately (next heartbeat carries it too). */
2432
+ setStatus(status: 'online' | 'degraded', detail?: string): Promise<void>;
2433
+ /** Replace metadata on the next heartbeat. Pass {} to clear. */
2434
+ updateMetadata(metadata: Record<string, unknown>): Promise<void>;
2435
+ /** Best-effort DELETE; safe to call multiple times. */
2436
+ deregister(): Promise<void>;
2437
+ /** Stop the heartbeat ticker without deleting the row. Idempotent. */
2438
+ stop(): Promise<void>;
2439
+ }
2440
+ interface SchedulerLike {
2441
+ setTimeout(cb: () => void, ms: number): NodeJS.Timeout | number;
2442
+ clearTimeout(handle: NodeJS.Timeout | number | undefined): void;
2443
+ }
2444
+ interface AgentsClientOptions {
2445
+ readonly scheduler?: SchedulerLike;
2446
+ readonly attachSignalHandlers?: boolean;
2447
+ }
2448
+ declare class AgentsClient {
2449
+ private readonly transport;
2450
+ private readonly options;
2451
+ constructor(transport: Transport, options?: AgentsClientOptions);
2452
+ /**
2453
+ * Fetch a deployed agent's compiled process_schema. A flow-runtime worker
2454
+ * calls this per dispatched call to boot a visually-built flow. Returns
2455
+ * null on 404 or when the agent has no schema.
2456
+ */
2457
+ getProcessSchema(agentId: string): Promise<ProcessSchemaDTO | null>;
2458
+ /**
2459
+ * Fetch a code-first agent's synced base prompt (its `defineAgent({ prompt })`,
2460
+ * captured on register). The generic text runner reads this to run the agent
2461
+ * through the engine over text. Returns null on 404 or when the agent has no
2462
+ * synced prompt (flow agents, or agents registered before the sync landed).
2463
+ */
2464
+ /** A text turn dispatched to this worker (burn-down G-4); null when it's gone or isn't this agent's. */
2465
+ fetchTextTurn(turnId: string, agentId: string): Promise<TextTurn | null>;
2466
+ /** Answer a text turn. False when the API no longer waits for it (answered already, or past its deadline). */
2467
+ replyTextTurn(turnId: string, reply: TextTurnReply): Promise<boolean>;
2468
+ getPrompt(agentId: string): Promise<string | null>;
2469
+ /**
2470
+ * Fetch a deployed agent's PUBLISHED AgentConfig — the pipeline the owner
2471
+ * published (model / voice / stt / mode / realtime). A flow-runtime worker
2472
+ * reads this per call so the no-code agent's runtime matches what was
2473
+ * published; a saved-but-unpublished dashboard draft is never returned here
2474
+ * (docs/specs/agents/draft-publish.md). Returns null on 404 (agent absent).
2475
+ */
2476
+ getConfig(agentId: string): Promise<AgentConfig$1 | null>;
2477
+ register(input: RegisterInput, opts?: RegisterOptions): Promise<RegisteredAgent>;
2478
+ list(query?: {
2479
+ environment?: AgentEnvironment;
2480
+ }): Promise<{
2481
+ agents: {
2482
+ status: "online" | "offline" | "degraded";
2483
+ id: string;
2484
+ name: string;
2485
+ projectId: string;
2486
+ createdAt: string;
2487
+ updatedAt: string;
2488
+ version: string;
2489
+ environment: "dev" | "stg" | "prd";
2490
+ statusDetail: string | null;
2491
+ capabilities: string[];
2492
+ readiness: {
2493
+ probe: string;
2494
+ ok: boolean;
2495
+ detail?: string | undefined;
2496
+ }[];
2497
+ metadata: Record<string, unknown>;
2498
+ lastSeenAt: string | null;
2499
+ processSchema?: {
2500
+ id: string;
2501
+ completionGate: {
2502
+ requiredFields: string[];
2503
+ backendAck?: {
2504
+ url: string;
2505
+ timeoutMs: number;
2506
+ } | undefined;
2507
+ };
2508
+ fields: {
2509
+ type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
2510
+ name: string;
2511
+ required: boolean;
2512
+ ask?: string | undefined;
2513
+ pattern?: string | undefined;
2514
+ min?: number | undefined;
2515
+ max?: number | undefined;
2516
+ enum?: string[] | undefined;
2517
+ }[];
2518
+ handoff?: {
2519
+ fallback?: string | undefined;
2520
+ routes?: Record<string, string> | undefined;
2521
+ } | undefined;
2522
+ memory?: {
2523
+ scope?: "call" | "caller" | "participant" | "account" | "platform" | undefined;
2524
+ retentionDays?: number | undefined;
2525
+ piiFields?: string[] | undefined;
2526
+ } | undefined;
2527
+ speech?: {
2528
+ interruption?: {
2529
+ enabled?: boolean | undefined;
2530
+ minWords?: number | undefined;
2531
+ minDuration?: number | undefined;
2532
+ } | undefined;
2533
+ endpointing?: {
2534
+ minDelay?: number | undefined;
2535
+ maxDelay?: number | undefined;
2536
+ } | undefined;
2537
+ } | undefined;
2538
+ prompts?: {
2539
+ id: string;
2540
+ text: string;
2541
+ }[] | undefined;
2542
+ triggers?: {
2543
+ then: string;
2544
+ name: string;
2545
+ on: string;
2546
+ onlyWhile?: string | undefined;
2547
+ }[] | undefined;
2548
+ tools?: {
2549
+ name: string;
2550
+ url: string;
2551
+ description: string;
2552
+ input: Record<string, "string" | "number" | "boolean">;
2553
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
2554
+ auth: "none" | "connection";
2555
+ headers?: Record<string, string> | undefined;
2556
+ connectionRef?: string | undefined;
2557
+ }[] | undefined;
2558
+ program?: {
2559
+ v: 1;
2560
+ id: string;
2561
+ entry: string[];
2562
+ nodes: Record<string, {
2563
+ type: "code" | "set" | "start" | "say" | "ask" | "confirm" | "tool" | "decision" | "handoff" | "end" | "trigger" | "gate" | "playbook" | "menu" | "subflow" | "llm" | "rag" | "memory" | "speech" | "classify" | "router" | "note";
2564
+ id: string;
2565
+ config: Record<string, unknown>;
2566
+ out: {
2567
+ to: string;
2568
+ condition?: string | undefined;
2569
+ sourceHandle?: string | undefined;
2570
+ label?: string | undefined;
2571
+ }[];
2572
+ }>;
2573
+ completionGate: {
2574
+ requiredFields: string[];
2575
+ };
2576
+ diagnostics?: {
2577
+ acyclic: boolean;
2578
+ droppedEdges: string[];
2579
+ unsupportedNodes: string[];
2580
+ labelOnlyEdges?: string[] | undefined;
2581
+ } | undefined;
2582
+ } | undefined;
2583
+ } | null | undefined;
2584
+ textRunnable?: boolean | undefined;
2585
+ }[];
2586
+ }>;
2587
+ delete(agentId: string): Promise<{
2588
+ ok: true;
2589
+ }>;
2590
+ }
2591
+
2592
+ interface ContextInput {
2593
+ readonly callerId: string;
2594
+ readonly scopes?: readonly MemoryScope$1[];
2595
+ }
2596
+ interface WriteInput {
2597
+ readonly scope: MemoryScope$1;
2598
+ readonly callerId: string;
2599
+ readonly delta: Record<string, unknown>;
2600
+ readonly callId?: string;
2601
+ }
2602
+ interface SnapshotInput {
2603
+ readonly callId: string;
2604
+ readonly stage: string;
2605
+ readonly snapshot: Record<string, unknown>;
2606
+ }
2607
+ interface ResolveInput {
2608
+ readonly externalKey: string;
2609
+ readonly displayName?: string;
2610
+ readonly identifiers?: ReadonlyArray<{
2611
+ type: string;
2612
+ value: string;
2613
+ }>;
2614
+ }
2615
+ declare class MemoryClient {
2616
+ private readonly transport;
2617
+ constructor(transport: Transport);
2618
+ context(input: ContextInput): Promise<RelevantContext>;
2619
+ write(input: WriteInput): Promise<void>;
2620
+ snapshot(input: SnapshotInput): Promise<{
2621
+ id: string;
2622
+ }>;
2623
+ resolveCaller(input: ResolveInput): Promise<ResolveCallerResponse['caller']>;
2624
+ deleteCaller(callerId: string): Promise<DeleteCallerResponse>;
2625
+ }
2626
+
2627
+ type CallStatus = 'in_progress' | 'completed' | 'failed';
2628
+ type CallAttributeValue = string | number | boolean;
2629
+ type CallParticipantRole = 'caller' | 'agent' | 'callee' | 'supervisor' | 'observer' | 'unknown';
2630
+ type CallParticipantKind = 'human' | 'agent' | 'phone' | 'sip' | 'system';
2631
+ type CallLegKind = 'sip-inbound' | 'sip-outbound' | 'agent-session' | 'conference' | 'transfer' | 'unknown';
2632
+ type CallLegStatus = 'starting' | 'active' | 'ended';
2633
+ interface CallSummary {
2634
+ readonly id: string;
2635
+ readonly projectId: string;
2636
+ readonly livekitRoom: string;
2637
+ readonly phoneNumberId: string | null;
2638
+ readonly agentId: string | null;
2639
+ readonly bindingId: string | null;
2640
+ readonly callerE164: string | null;
2641
+ readonly toE164: string | null;
2642
+ readonly status: CallStatus;
2643
+ readonly startedAt: string;
2644
+ }
2645
+ interface CallUsageReport {
2646
+ readonly durationMs: number;
2647
+ readonly llm: readonly {
2648
+ readonly provider: string;
2649
+ readonly model: string;
2650
+ readonly inputTokens: number;
2651
+ readonly outputTokens: number;
2652
+ }[];
2653
+ readonly tts: readonly {
2654
+ readonly provider: string;
2655
+ readonly chars: number;
2656
+ }[];
2657
+ readonly stt: readonly {
2658
+ readonly provider: string;
2659
+ readonly seconds: number;
2660
+ }[];
2704
2661
  }
2705
- type ShorthandPrimitive$1 = 'string' | 'number' | 'boolean';
2706
- type ToolInputShape$1 = Record<string, ShorthandPrimitive$1> | z.ZodTypeAny;
2707
- interface ToolDefinition$1<I = unknown, R = unknown> {
2708
- readonly description: string;
2709
- readonly input: ToolInputShape$1;
2710
- readonly run: (input: I, ctx: AgentContext) => Promise<R> | R;
2711
- /**
2712
- * Capability this tool requires. Action Guard hard-blocks the call if not
2713
- * declared (PRD §B.5 — "no soft failures, ever"). Defaults to
2714
- * `tool.<name>` when omitted; passing a domain-scoped string
2715
- * (`crm.write`, `payment.refund`) lets multiple tools share a capability
2716
- * for centralised policy.
2717
- */
2718
- readonly capability?: string;
2662
+ interface AppendTranscriptInput {
2663
+ readonly speaker: 'caller' | 'agent';
2664
+ readonly text: string;
2665
+ readonly startMs: number;
2666
+ readonly endMs: number;
2667
+ readonly final?: boolean;
2719
2668
  }
2720
- /**
2721
- * Optional security adapters. The SDK always enforces the local-only synchronous
2722
- * guards (PRD §B.2 input regex, §B.3 system seal + PII tokenisation, §B.4
2723
- * markdown strip + PII partial-mask, §B.5 capability check). Setting any of
2724
- * these augments the local floor with external services. Each is independently
2725
- * optional — none has to be live for the floor guards to function.
2726
- *
2727
- * URLs can also come from env (`SECURITY_LLM_GUARD_URL`,
2728
- * `SECURITY_PRESIDIO_ANALYZER_URL`, `SECURITY_PRESIDIO_ANONYMIZER_URL`,
2729
- * `SECURITY_OPA_URL`, `SECURITY_OPA_DECISION_PATH`); explicit config wins.
2730
- */
2731
- interface SecurityConfig {
2732
- /** Disable the primitive entirely. Use only for tests. Production code MUST NOT set this. */
2733
- readonly disabled?: boolean;
2734
- /** External LLM-Guard adapter for richer injection detection. */
2735
- readonly llmGuardUrl?: string;
2736
- /** Presidio analyzer URL for PII detection beyond local regex. */
2737
- readonly presidioAnalyzerUrl?: string;
2738
- /** Presidio anonymizer URL — if set, output is redacted before TTS. */
2739
- readonly presidioAnonymizerUrl?: string;
2740
- /** OPA decision API base URL (e.g. `http://opa:8181`). */
2741
- readonly opaUrl?: string;
2742
- /** OPA decision path (e.g. `voicelayer/security/decision`). */
2743
- readonly opaDecisionPath?: string;
2744
- /** Per-request timeout for security adapter calls. */
2745
- readonly adapterTimeoutMs?: number;
2669
+ type DtmfDirection = 'received' | 'sent';
2670
+ interface AppendDtmfEventInput {
2671
+ readonly direction: DtmfDirection;
2672
+ readonly digit: string;
2673
+ readonly code: number;
2674
+ readonly participantId?: string;
2746
2675
  }
2747
- /**
2748
- * Marks an agent as a *flow-runtime* worker: instead of a fixed process it
2749
- * resolves the deployed flow from the dispatch metadata (`agentId`) at call
2750
- * time, fetches that agent's compiled process_schema, and boots from it. One
2751
- * process serves many flows (the shared pool). See defineFlowRuntime().
2752
- */
2753
- interface FlowRuntimeConfig {
2754
- /** Prepended to the flow's compiled say/confirm prompt fragments. */
2755
- readonly basePrompt?: string;
2756
- /** Spoken (verbatim) before hanging up when a flow call's schema cannot be
2757
- * loaded. A failed flow boot NEVER silently answers as a generic assistant. */
2758
- readonly bootFailureMessage?: string;
2676
+ interface EnsureCallByRoomInput {
2677
+ readonly roomName: string;
2678
+ readonly phoneNumberId?: string;
2679
+ readonly agentId?: string;
2680
+ readonly bindingId?: string;
2681
+ readonly callerE164?: string;
2682
+ readonly toE164?: string;
2683
+ readonly attributes?: Record<string, CallAttributeValue>;
2684
+ readonly participants?: CallParticipantInput[];
2685
+ readonly legs?: CallLegInput[];
2686
+ readonly startedAt?: string;
2759
2687
  }
2760
- interface AgentConfig<TProcess extends Record<string, ProcessField> = Record<string, ProcessField>> {
2761
- /** Lowercase, kebab-case identifier. Used for LiveKit dispatch + presence. */
2762
- readonly name: string;
2763
- /** System prompt the LLM sees. */
2764
- readonly prompt: string;
2765
- /** Agent-level Instructions (the routing/decision layer): plain-language guidance
2766
- * for WHEN the agent acts, appended below the persona under a `# Routing` header.
2767
- * Interpolated with {{ }} by the process runtime. Optional. */
2768
- readonly routingInstructions?: string;
2769
- /** Capability tags surfaced in the dashboard. */
2770
- readonly capabilities?: readonly string[];
2771
- /** Semantic version. Defaults to AGENT_VERSION env or '0.0.0'. */
2772
- readonly version?: string;
2773
- /** dev / stg / prd. Defaults to AGENT_ENVIRONMENT env or 'dev'. */
2774
- readonly environment?: AgentEnvironment;
2775
- readonly process?: ProcessDefinition<TProcess>;
2776
- readonly triggers?: Readonly<Record<string, TriggerDefinition>>;
2777
- readonly handoff?: HandoffConfig;
2778
- readonly memory?: MemoryConfig;
2779
- readonly participants?: ParticipantsConfig;
2780
- readonly connectors?: Readonly<Record<string, ConnectorInstance>>;
2781
- readonly compliance?: readonly ComplianceTag[];
2782
- readonly models?: ModelConfig;
2783
- readonly outbound?: OutboundCallConfig;
2784
- readonly speech?: SpeechConfig;
2785
- readonly endCall?: EndCallPolicy;
2786
- readonly tools?: Readonly<Record<string, ToolDefinition$1>>;
2787
- /** Per-agent registry-tool scoping (stored ToolBinding names, applied at
2788
- * boot). Non-empty → only these dashboard HTTP tools attach; absent/[] →
2789
- * every enabled registry tool attaches (the historical default). */
2790
- readonly toolBindings?: readonly string[];
2791
- readonly security?: SecurityConfig;
2792
- /**
2793
- * Per-call ConsultationPolicy used by the built-in `ask_host` tool. When
2794
- * omitted the SDK uses the contract defaults (30s per-consult, 120s
2795
- * cumulative). Plan-first calls override this at boot from
2796
- * `plan.draftConfig.consultation`. See
2797
- * packages/contracts/src/consultation.ts for the schema + semantics.
2798
- */
2799
- readonly consultation?: ConsultationPolicy;
2800
- /**
2801
- * Use your existing text agent as the LLM. When set (and `models.llm` is
2802
- * unset), defineAgent wires the pipeline's LLM slot to this function: the
2803
- * caller's STT transcript is passed to `onQuery`, and its returned text (or
2804
- * streamed pieces) is spoken by TTS. The "two lines, keep your stack" path.
2805
- *
2806
- * Equivalent to `models: { llm: connector.llm({ onQuery }) }`. For a remote
2807
- * brain instead, use `connector.llm({ url })` (direct) or a tunnel transport.
2808
- * See docs/specs/voice-brain-connector/.
2809
- */
2810
- readonly onQuery?: OnQuery;
2811
- readonly onUtterance?: (text: string, ctx: AgentContext) => Promise<void> | void;
2812
- readonly onFieldCaptured?: (field: string, value: unknown, ctx: AgentContext) => Promise<void> | void;
2813
- readonly onCallEnd?: (outcome: CallOutcomeSummary, ctx: AgentContext) => Promise<void> | void;
2814
- readonly onEvent?: (event: AgentLifecycleEvent) => void;
2815
- /** Replace the default conversation loop. The SDK does NOT auto-greet. */
2816
- readonly onCall?: (ctx: AgentContext) => Promise<void>;
2817
- readonly readiness?: readonly ReadinessProbe[];
2688
+ interface CallParticipantInput {
2689
+ readonly participantKey: string;
2690
+ readonly role: CallParticipantRole;
2691
+ readonly kind: CallParticipantKind;
2692
+ readonly identity?: string | null;
2693
+ readonly address?: string | null;
2694
+ readonly displayName?: string | null;
2695
+ readonly joinedAt?: string;
2696
+ readonly leftAt?: string | null;
2697
+ readonly metadata?: Record<string, unknown>;
2698
+ }
2699
+ interface CallLegInput {
2700
+ readonly legKey: string;
2701
+ readonly kind: CallLegKind;
2702
+ readonly status: CallLegStatus;
2703
+ readonly fromParticipantKey?: string | null;
2704
+ readonly toParticipantKey?: string | null;
2705
+ readonly fromAddress?: string | null;
2706
+ readonly toAddress?: string | null;
2707
+ readonly startedAt?: string;
2708
+ readonly endedAt?: string | null;
2709
+ readonly metadata?: Record<string, unknown>;
2710
+ }
2711
+ interface SyncCallStateInput {
2712
+ readonly attributes?: Record<string, CallAttributeValue>;
2713
+ readonly participants?: CallParticipantInput[];
2714
+ readonly legs?: CallLegInput[];
2715
+ }
2716
+ declare class CallsClient {
2717
+ private readonly transport;
2718
+ constructor(transport: Transport);
2719
+ getByRoom(roomName: string): Promise<CallSummary>;
2720
+ ensureByRoom(input: EnsureCallByRoomInput): Promise<CallSummary>;
2721
+ syncState(callId: string, input: SyncCallStateInput): Promise<void>;
2722
+ appendTranscriptSegment(callId: string, input: AppendTranscriptInput): Promise<void>;
2723
+ reportUsage(callId: string, report: CallUsageReport): Promise<void>;
2724
+ appendDtmfEvent(callId: string, input: AppendDtmfEventInput): Promise<void>;
2818
2725
  /**
2819
- * Run as a remote-controlled (puppet) agent: no autonomous LLM loop, no
2820
- * process/triggers pipeline. STT utterances are still published to
2821
- * `call-events:{callId}` via the existing transcript-segments sync, and
2822
- * the SDK subscribes to `call-control:{callId}` to receive `say`,
2823
- * `hangup`, `dtmf` commands from an external driver (typically the MCP
2824
- * server invoked by a coding agent).
2726
+ * Append a structured call event — consultation lifecycle kinds, or the
2727
+ * operational vocabulary the call-detail Timeline renders between
2728
+ * transcript rows (tool.* / handoff.* / lookup.* / record.* / notify.*).
2729
+ * See apps/api/src/routes/calls.ts AppendEventBody for the accepted shapes.
2825
2730
  *
2826
- * When this is on, `process`, `triggers`, `onUtterance`, `onCall` are
2827
- * ignored. `tools`, `connectors`, `memory` still work.
2731
+ * The agent SDK's built-in `ask_host` tool calls this on consultation start
2732
+ * / end; the handoff runtime and graph interpreter emit op events through it
2733
+ * so the operational story (dial → answered → briefed → dropped, tool calls)
2734
+ * is visible in the dashboard, not just the spoken transcript.
2828
2735
  */
2829
- readonly puppetMode?: boolean;
2736
+ appendEvent(callId: string, input: {
2737
+ readonly kind: 'consultation.requested' | 'consultation.resolved' | `tool.${string}` | `handoff.${string}` | `lookup.${string}` | `record.${string}` | `notify.${string}`;
2738
+ readonly payload: Record<string, unknown>;
2739
+ }): Promise<void>;
2740
+ }
2741
+
2742
+ interface CreateFormSessionInput {
2743
+ readonly formId: string;
2744
+ readonly recipientPhone: string;
2745
+ readonly recipientName?: string;
2746
+ readonly prefill?: Record<string, unknown>;
2747
+ readonly webhookUrl?: string;
2748
+ readonly callbackFromNumber?: string;
2749
+ readonly ttlSeconds?: number;
2830
2750
  /**
2831
- * Host-controlled autonomous agent (the "smart puppet"). UNLIKE puppetMode,
2832
- * the agent keeps its REAL LLM and drives the conversation itself from its
2833
- * prompt (the per-call `intent` is appended at boot). This flag only wires
2834
- * the `call-control:{room}` channel so the MCP host can still interject
2835
- * (`say`), end the call (`hangup`), or send `dtmf` — and answer the agent's
2836
- * `ask_host` consultations. Use this for an agent that takes a customer's
2837
- * intent and runs the call like a human secretary, asking the host for any
2838
- * info it's missing. Mutually exclusive in spirit with puppetMode (which is
2839
- * the older NoOp "dumb mouth").
2751
+ * When set, the API will SMS the link from this phone number immediately
2752
+ * after creating the session. This is the common case for agent-led use:
2753
+ * the agent calls sendFormLink during a conversation and the recipient
2754
+ * gets a text right away.
2840
2755
  */
2841
- readonly hostControlled?: boolean;
2842
- /** When set, this agent boots each call from a deployed flow's process_schema. */
2843
- readonly flowRuntime?: FlowRuntimeConfig;
2756
+ readonly sendSms?: {
2757
+ readonly phoneNumberId: string;
2758
+ readonly bodyPrefix?: string;
2759
+ };
2844
2760
  /**
2845
- * Opt a hand-coded (non-flow) agent into the dashboard-driven pipeline: on
2846
- * each call the SDK fetches this agent's stored `agent_config` and applies
2847
- * the operator-selected voice / model / STT over the coded defaults. The
2848
- * pipeline *mode* (cascade vs realtime) stays pinned to what the code
2849
- * declares — a stale `mode=realtime` in the dashboard can't flip a
2850
- * cascade-only worker. Flow agents (`flowRuntime`) get this implicitly and
2851
- * may additionally switch mode; this flag is the SDK opt-in. The agent id is
2852
- * read from dispatch metadata (the inbound router injects it from
2853
- * phone_numbers.agentId), so it's a no-op for calls without one.
2761
+ * When set, the API will email the link to `to` immediately after creating
2762
+ * the session. Independent from sendSms — set both for belt-and-braces
2763
+ * delivery, set neither to just receive the URL back. Use this when SMS is
2764
+ * blocked by toll-fraud / 10DLC registration.
2854
2765
  */
2855
- readonly pipelineFromConfig?: boolean;
2766
+ readonly sendEmail?: {
2767
+ readonly to: string;
2768
+ readonly subject?: string;
2769
+ readonly bodyPrefix?: string;
2770
+ };
2771
+ }
2772
+ interface CreatedFormSession {
2773
+ readonly sessionId: string;
2774
+ readonly token: string;
2775
+ readonly url: string;
2776
+ readonly smsId: string | null;
2777
+ readonly emailId: string | null;
2778
+ readonly expiresAt: string;
2779
+ }
2780
+ interface PublicFormSessionView {
2781
+ readonly schema: {
2782
+ readonly id: string;
2783
+ readonly version: number;
2784
+ readonly title: string;
2785
+ readonly description?: string | undefined;
2786
+ readonly survey: Record<string, unknown>;
2787
+ };
2788
+ readonly values: Record<string, unknown>;
2789
+ readonly status: 'pending' | 'active' | 'live' | 'submitted' | 'expired';
2790
+ readonly recipientPhoneMasked: string;
2791
+ readonly hasActiveCall: boolean;
2792
+ readonly submittedAt: string | null;
2793
+ readonly expiresAt: string;
2794
+ }
2795
+ declare class FormsClient {
2796
+ private readonly transport;
2797
+ constructor(transport: Transport);
2798
+ createSession(input: CreateFormSessionInput): Promise<CreatedFormSession>;
2799
+ getByToken(token: string): Promise<PublicFormSessionView>;
2800
+ patchValues(token: string, values: Record<string, unknown>): Promise<{
2801
+ values: Record<string, unknown>;
2802
+ updatedAt: string;
2803
+ }>;
2804
+ submit(token: string, values: Record<string, unknown>): Promise<{
2805
+ responseId: string;
2806
+ submittedAt: string;
2807
+ }>;
2808
+ }
2809
+
2810
+ interface SendEmailInput {
2811
+ readonly to: string;
2812
+ readonly subject: string;
2813
+ readonly text: string;
2814
+ readonly html?: string;
2815
+ }
2816
+ interface SentEmail {
2817
+ readonly emailId: string;
2818
+ }
2819
+ declare class EmailClient {
2820
+ private readonly transport;
2821
+ constructor(transport: Transport);
2822
+ send(input: SendEmailInput): Promise<SentEmail>;
2823
+ }
2824
+
2825
+ declare class PlansClient {
2826
+ private readonly transport;
2827
+ constructor(transport: Transport);
2856
2828
  /**
2857
- * Opt this agent into MCP-layer visibility. When true, on register the API
2858
- * also writes an `agent_config` row keyed by (project_id, name,
2859
- * environment) so MCP / dashboard / REST can list and inspect this agent
2860
- * (and, post-step-7, drive call_say / call_send_guidance / etc against
2861
- * its live calls).
2862
- *
2863
- * Defaults to true so newly-registered agents show up in dashboards and
2864
- * MCP-host listings without opt-in. Pass `false` for autonomous-only
2865
- * agents that should stay invisible to MCP. See
2866
- * docs/architecture/contracts-design.md §2b.
2829
+ * Fetch a plan by id. Project scoping is enforced by the API via the
2830
+ * caller's VOICELAYER_API_KEY — a cross-project planId surfaces as 404.
2831
+ * Returns `null` on 404 so the caller can fall back to legacy boot.
2867
2832
  */
2868
- readonly mcpExposed?: boolean;
2833
+ getById(planId: string): Promise<CallPlan | null>;
2869
2834
  }
2870
- interface CallOutcomeSummary {
2871
- readonly reason: 'completed' | 'handoff' | 'caller_hung_up' | 'agent_hung_up' | 'error';
2872
- readonly durationMs: number;
2873
- readonly processCompleted: boolean;
2874
- readonly fieldsCaptured: number;
2875
- readonly handoffOccurred: boolean;
2835
+
2836
+ declare const ProviderCredential: z.ZodObject<{
2837
+ apiKey: z.ZodString;
2838
+ baseUrl: z.ZodOptional<z.ZodString>;
2839
+ }, "strip", z.ZodTypeAny, {
2840
+ apiKey: string;
2841
+ baseUrl?: string | undefined;
2842
+ }, {
2843
+ apiKey: string;
2844
+ baseUrl?: string | undefined;
2845
+ }>;
2846
+ type ProviderCredential = z.infer<typeof ProviderCredential>;
2847
+ declare const BrainConnectorConfig: z.ZodObject<{
2848
+ connector: z.ZodObject<{
2849
+ id: z.ZodString;
2850
+ mode: z.ZodEnum<["tunnel", "direct"]>;
2851
+ connectionId: z.ZodNullable<z.ZodString>;
2852
+ defaultModel: z.ZodNullable<z.ZodString>;
2853
+ normalize: z.ZodEnum<["auto", "on", "off"]>;
2854
+ enabled: z.ZodBoolean;
2855
+ credential: z.ZodOptional<z.ZodNullable<z.ZodObject<{
2856
+ apiKey: z.ZodString;
2857
+ baseUrl: z.ZodString;
2858
+ }, "strip", z.ZodTypeAny, {
2859
+ apiKey: string;
2860
+ baseUrl: string;
2861
+ }, {
2862
+ apiKey: string;
2863
+ baseUrl: string;
2864
+ }>>>;
2865
+ }, "strip", z.ZodTypeAny, {
2866
+ id: string;
2867
+ enabled: boolean;
2868
+ mode: "tunnel" | "direct";
2869
+ defaultModel: string | null;
2870
+ connectionId: string | null;
2871
+ normalize: "on" | "off" | "auto";
2872
+ credential?: {
2873
+ apiKey: string;
2874
+ baseUrl: string;
2875
+ } | null | undefined;
2876
+ }, {
2877
+ id: string;
2878
+ enabled: boolean;
2879
+ mode: "tunnel" | "direct";
2880
+ defaultModel: string | null;
2881
+ connectionId: string | null;
2882
+ normalize: "on" | "off" | "auto";
2883
+ credential?: {
2884
+ apiKey: string;
2885
+ baseUrl: string;
2886
+ } | null | undefined;
2887
+ }>;
2888
+ }, "strip", z.ZodTypeAny, {
2889
+ connector: {
2890
+ id: string;
2891
+ enabled: boolean;
2892
+ mode: "tunnel" | "direct";
2893
+ defaultModel: string | null;
2894
+ connectionId: string | null;
2895
+ normalize: "on" | "off" | "auto";
2896
+ credential?: {
2897
+ apiKey: string;
2898
+ baseUrl: string;
2899
+ } | null | undefined;
2900
+ };
2901
+ }, {
2902
+ connector: {
2903
+ id: string;
2904
+ enabled: boolean;
2905
+ mode: "tunnel" | "direct";
2906
+ defaultModel: string | null;
2907
+ connectionId: string | null;
2908
+ normalize: "on" | "off" | "auto";
2909
+ credential?: {
2910
+ apiKey: string;
2911
+ baseUrl: string;
2912
+ } | null | undefined;
2913
+ };
2914
+ }>;
2915
+ type BrainConnectorConfig = z.infer<typeof BrainConnectorConfig>['connector'];
2916
+ declare class ConnectionsClient {
2917
+ private readonly transport;
2918
+ constructor(transport: Transport);
2919
+ resolveProviderCredential(provider: string): Promise<ProviderCredential | null>;
2920
+ resolveBrainConnectorConfig(id: string): Promise<BrainConnectorConfig | null>;
2876
2921
  }
2877
- /**
2878
- * Identity helper that gives users a typed `defineProcess` entry point with
2879
- * full inference on `onComplete`'s `data` argument.
2880
- *
2881
- * defineProcess({
2882
- * collect: { name: { type: 'string', required: true } },
2883
- * onComplete: (data) => { data.name // string },
2884
- * })
2885
- */
2886
- declare function defineProcess<T extends Record<string, ProcessField>>(def: ProcessDefinition<T>): ProcessDefinition<T>;
2887
2922
 
2888
- interface RunAgentTextTranscriptOptions {
2889
- /** The agent's system prompt / instructions (its code-defined behavior). */
2890
- readonly instructions: string;
2891
- /** The LLM that generates replies — injected so this stays provider-agnostic and
2892
- * unit-testable (real inference/openai LLM in prod; a scripted fake in tests). */
2893
- readonly llm: llm.LLM;
2894
- /** Scripted caller turns, run in order; each produces the agent's reply turn(s). */
2895
- readonly messages: readonly string[];
2896
- /** Optional id surfaced on the Agent (for traceability). */
2897
- readonly agentId?: string;
2923
+ interface CreateClientOptions {
2924
+ readonly apiKey?: string;
2925
+ readonly baseUrl?: string;
2926
+ readonly fetch?: typeof fetch;
2927
+ readonly maxRetries?: number;
2928
+ readonly initialBackoffMs?: number;
2929
+ readonly userAgent?: string;
2930
+ readonly scheduler?: AgentsClientOptions['scheduler'];
2931
+ readonly attachSignalHandlers?: boolean;
2898
2932
  }
2899
- interface AgentTextTranscriptResult {
2900
- readonly replies: string[];
2933
+ interface VoiceLayerClient {
2934
+ readonly agents: AgentsClient;
2935
+ readonly memory: MemoryClient;
2936
+ readonly calls: CallsClient;
2937
+ readonly forms: FormsClient;
2938
+ readonly email: EmailClient;
2939
+ readonly plans: PlansClient;
2940
+ readonly connections: ConnectionsClient;
2901
2941
  }
2902
- /** Drive an instruction-based agent over text and collect its replies. Stateless
2903
- * batch turn — the request/response shape the text playground's agent path uses. */
2904
- declare function runAgentTextTranscript(opts: RunAgentTextTranscriptOptions): Promise<AgentTextTranscriptResult>;
2942
+ declare function createClient(options?: CreateClientOptions): VoiceLayerClient;
2905
2943
 
2906
2944
  interface DefaultMetadata {
2907
2945
  readonly hostname: string;
@@ -2989,6 +3027,8 @@ declare function formTools(vl: VoiceLayerClient, options?: FormToolsOptions): Re
2989
3027
  declare class Agent {
2990
3028
  private readonly config;
2991
3029
  private registered;
3030
+ /** Whether this process registered `<name>::text` and takes text turns (said so at registration). */
3031
+ private textTurns;
2992
3032
  private processStatePublisher;
2993
3033
  constructor(config: AgentConfig);
2994
3034
  /**
@@ -3029,37 +3069,6 @@ declare function defineFlowRuntime(opts: {
3029
3069
  readonly version?: string;
3030
3070
  }): Agent;
3031
3071
 
3032
- interface PuppetControlDeps {
3033
- /**
3034
- * LiveKit room name — used as the control-channel key. This is the only
3035
- * identifier the agent reliably has at dispatch time (the API-side
3036
- * project_calls UUID may not even exist yet when the agent boots, since
3037
- * the LK `room_started` webhook fires after dispatch).
3038
- *
3039
- * The API translates UUID → room name before publishing — see
3040
- * apps/api/src/routes/call-control.ts.
3041
- */
3042
- readonly roomName: string;
3043
- readonly session: unknown;
3044
- readonly onHangup: () => Promise<void>;
3045
- readonly onDtmf?: (digits: string) => Promise<void>;
3046
- readonly log?: (msg: string, attrs?: Record<string, unknown>) => void;
3047
- }
3048
- interface PuppetControlHandle {
3049
- /** Stop listening for commands and tear down the Redis subscription. */
3050
- close(): Promise<void>;
3051
- }
3052
- /** True if we should run puppet wiring — REDIS_URL must be set. */
3053
- declare function puppetEnvAvailable(): boolean;
3054
- /**
3055
- * Start a puppet-mode control listener for the given call. Returns a handle
3056
- * the caller invokes when the call ends to release the Redis connection.
3057
- *
3058
- * Pubsub semantics: one IORedis subscriber per call. Cheap (Valkey handles
3059
- * thousands of subscriptions per node) and isolates listener teardown from
3060
- * other calls in the same agent process.
3061
- */
3062
- declare function startPuppetControl(deps: PuppetControlDeps): Promise<PuppetControlHandle>;
3063
3072
  /**
3064
3073
  * Build a no-op LLM compatible with @livekit/agents voice.AgentSession.
3065
3074
  * Used in puppet mode to suppress autonomous replies — every STT turn
@@ -3102,26 +3111,11 @@ declare function webhook(config: WebhookConfig): ConnectorInstance<'webhook', We
3102
3111
  /** Subset of ModelConfig the Agent class converts AgentConfig.models into. */
3103
3112
  type PipelineConfig = ModelConfig;
3104
3113
 
3105
- type ProviderKind = 'tts' | 'stt' | 'llm' | 'vad' | 'turn';
3106
3114
  interface WrapOptions<T> {
3107
3115
  /** Emit OTel spans around each method call. Default: true. */
3108
3116
  readonly trace?: boolean;
3109
3117
  /** Tag spans with `vl.provider.label` for easy filtering. */
3110
3118
  readonly label?: string;
3111
- /**
3112
- * Provider role. When set, the wrapper additionally emits OTel Counters
3113
- * (vl.tts.chars / vl.llm.input_tokens / vl.stt.seconds) so /v1/calls/:id/
3114
- * metrics returns real per-call usage. The TTS path is wired today —
3115
- * chars are counted from the synthesize() text argument. LLM/STT counters
3116
- * still depend on the underlying adapter exposing usage on its response
3117
- * shape; see TODO below.
3118
- */
3119
- readonly kind?: ProviderKind;
3120
- /**
3121
- * Provider name surfaced in metric attributes (deepgram, openai, …).
3122
- * Falls back to `label` when omitted.
3123
- */
3124
- readonly provider?: string;
3125
3119
  /**
3126
3120
  * Fallback provider used if the primary throws. Accepts an instance OR a
3127
3121
  * ProviderFactory (so `deepgram.tts(...)` works directly). The fallback is
@@ -3245,108 +3239,6 @@ declare const connector: {
3245
3239
  llm(config?: ConnectorLLMConfig): ProviderFactory<LLMProvider>;
3246
3240
  };
3247
3241
 
3248
- declare function callbackTransport(onQuery: OnQuery): BrainTransport;
3249
-
3250
- interface ConnectorLLMOptions {
3251
- readonly model?: string;
3252
- readonly temperature?: number;
3253
- readonly callId?: string;
3254
- readonly projectId?: string;
3255
- /** Spoken instead of dead air when the brain errors before any reply. */
3256
- readonly fallbackText?: string;
3257
- }
3258
- /**
3259
- * Build a ConnectorLLM instance for the pipeline's `llm` slot. The returned
3260
- * object's chat() yields the brain reply and exposes close() for barge-in.
3261
- */
3262
- declare function createConnectorLLM(transport: BrainTransport, options?: ConnectorLLMOptions): Promise<unknown>;
3263
-
3264
- interface ConnectorChatModelOptions {
3265
- readonly model?: string;
3266
- }
3267
- interface ChatModelInput {
3268
- readonly messages: readonly {
3269
- readonly role: 'system' | 'user' | 'assistant';
3270
- readonly content: string;
3271
- }[];
3272
- readonly json?: boolean;
3273
- readonly temperature?: number;
3274
- readonly model?: string;
3275
- }
3276
- declare class ConnectorChatModel {
3277
- private readonly transport;
3278
- private readonly options;
3279
- constructor(transport: BrainTransport, options?: ConnectorChatModelOptions);
3280
- complete(input: ChatModelInput): Promise<string>;
3281
- }
3282
-
3283
- declare class BrainConfigError extends Error {
3284
- constructor(message: string);
3285
- }
3286
- /** Resolve a hostname to a list of IP strings. Injectable for tests. */
3287
- type HostLookup = (host: string) => Promise<readonly string[]>;
3288
- interface AssertUrlOptions {
3289
- /** Hostnames that bypass IP checks (explicit per-connector allowlist). */
3290
- readonly allowHosts?: readonly string[];
3291
- /** Override DNS resolution (tests). */
3292
- readonly lookup?: HostLookup;
3293
- }
3294
- /**
3295
- * Validate a brain URL for direct egress. Throws BrainConfigError on any
3296
- * violation; returns the parsed URL when safe.
3297
- */
3298
- declare function assertPublicHttpsUrl(raw: string, opts?: AssertUrlOptions): Promise<URL>;
3299
-
3300
- interface BrainPubSub {
3301
- publish(channel: string, message: string): Promise<void>;
3302
- /** Subscribe to a channel; returns an unsubscribe handle. */
3303
- subscribe(channel: string, handler: (raw: string) => void): Promise<() => Promise<void>>;
3304
- }
3305
- interface TunnelBrainTransportOptions {
3306
- readonly connectorId: string;
3307
- readonly pubsub: BrainPubSub;
3308
- /** Fail the turn if the daemon sends nothing within this window. Default 20s. */
3309
- readonly firstChunkTimeoutMs?: number;
3310
- }
3311
- declare function tunnelBrainTransport(options: TunnelBrainTransportOptions): BrainTransport;
3312
-
3313
- declare class RedisBrainPubSub implements BrainPubSub {
3314
- private readonly sub;
3315
- private readonly pub;
3316
- private readonly listeners;
3317
- constructor(sub: Redis, pub: Redis);
3318
- publish(channel: string, message: string): Promise<void>;
3319
- subscribe(channel: string, handler: (raw: string) => void): Promise<() => Promise<void>>;
3320
- close(): Promise<void>;
3321
- }
3322
- declare function buildRedisBrainPubSub(redisUrl: string | undefined): RedisBrainPubSub | null;
3323
-
3324
- interface SseDelta {
3325
- readonly content?: string;
3326
- readonly finishReason?: string;
3327
- }
3328
- declare function parseChatCompletionSse(source: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>): AsyncGenerator<SseDelta>;
3329
-
3330
- interface BrainEndpointConfig {
3331
- /** Base URL of the OpenAI-compatible endpoint, e.g. http://localhost:4000/v1. */
3332
- readonly brainUrl: string;
3333
- readonly apiKey?: string;
3334
- readonly defaultModel?: string;
3335
- /** Injectable for tests; defaults to global fetch. */
3336
- readonly fetchImpl?: typeof fetch;
3337
- }
3338
- interface IncomingBrainRequest {
3339
- readonly streamId: string;
3340
- readonly model?: string;
3341
- readonly temperature?: number;
3342
- readonly messages: ReadonlyArray<{
3343
- role: 'system' | 'user' | 'assistant';
3344
- content: string;
3345
- }>;
3346
- }
3347
- /** Run one brain.request and yield the reply frames. Never throws. */
3348
- declare function runBrainRequest(req: IncomingBrainRequest, cfg: BrainEndpointConfig, signal: AbortSignal): AsyncGenerator<ConnectorUpFrame>;
3349
-
3350
3242
  /**
3351
3243
  * Turn the persisted `agents.process_schema` (or a freshly-compiled flow) into a
3352
3244
  * ProcessDefinition. The completion gate drives the `required` flags so the
@@ -3377,6 +3269,19 @@ declare function processSchemaToAgentParts(schema: ProcessSchemaDTO, opts?: {
3377
3269
  readonly graphNodeIds?: ReadonlySet<string>;
3378
3270
  }): CompiledAgentParts;
3379
3271
 
3272
+ interface ExchangeWorkerTokenInput {
3273
+ readonly projectId: string;
3274
+ readonly callId?: string;
3275
+ readonly fetchImpl?: typeof fetch;
3276
+ }
3277
+ /** One mint per call (cheap in-cluster HMAC mint, ~ms) so every token is
3278
+ * attributable to a specific call in the API's audit log. Returns null when
3279
+ * the exchange isn't configured or fails — callers fall back to the env key. */
3280
+ declare function exchangeWorkerToken(input: ExchangeWorkerTokenInput): Promise<string | null>;
3281
+ /** Build the per-call SDK client under the calling project's identity, with
3282
+ * the env-key fallback chain above. `md` is the parsed dispatch metadata. */
3283
+ declare function resolveWorkerClient(md: Record<string, unknown>, fetchImpl?: typeof fetch): Promise<VoiceLayerClient | null>;
3284
+
3380
3285
  /**
3381
3286
  * Extend this to author a tool with the least ceremony. `run` receives the
3382
3287
  * parsed input and the live AgentContext; whatever it returns is handed back to
@@ -3428,25 +3333,4 @@ interface HttpToolSpec {
3428
3333
  */
3429
3334
  declare function httpTool(spec: HttpToolSpec): Record<string, ToolDefinition>;
3430
3335
 
3431
- interface CreateClientOptions {
3432
- readonly apiKey?: string;
3433
- readonly baseUrl?: string;
3434
- readonly fetch?: typeof fetch;
3435
- readonly maxRetries?: number;
3436
- readonly initialBackoffMs?: number;
3437
- readonly userAgent?: string;
3438
- readonly scheduler?: AgentsClientOptions['scheduler'];
3439
- readonly attachSignalHandlers?: boolean;
3440
- }
3441
- interface VoiceLayerClient {
3442
- readonly agents: AgentsClient;
3443
- readonly memory: MemoryClient;
3444
- readonly calls: CallsClient;
3445
- readonly forms: FormsClient;
3446
- readonly email: EmailClient;
3447
- readonly plans: PlansClient;
3448
- readonly connections: ConnectionsClient;
3449
- }
3450
- declare function createClient(options?: CreateClientOptions): VoiceLayerClient;
3451
-
3452
- export { Agent, type AgentConfig, AgentContext, type AgentEventEmitter, type AgentEventListener, type AgentLifecycleEvent, type AgentTextTranscriptResult, type AppendDtmfEventInput, type AppendTranscriptInput, BaseTool, type BrainCallMetadata, type BrainCapabilities, type BrainChunk, BrainConfigError, type BrainEndpointConfig, type BrainMessage, type BrainPubSub, type BrainRequest, type BrainTransport, type CallAttributeValue, CallInfo, type CallLegInput, type CallOutcomeSummary, type CallParticipantInput, type CallStatus, type CallSummary, CallsClient, type CompiledAgentParts, type CompletionStrategy, type ComplianceTag, ConnectorChatModel, type ConnectorChatModelOptions, type ConnectorInstance, type ConnectorLLMConfig, type ConnectorLLMOptions, ConsultationPolicy, type CreateClientOptions, type CreatedFormSession, type DefaultMetadata, type DtmfDirection, EmailClient, type SendEmailInput as EmailSendInput, type EndCallInfo, type EndCallPolicy, type EndCallTrigger, type EndpointingConfig, type EnsureCallByRoomInput, type CreateFormSessionInput as FormCreateInput, type FormToolsOptions, FormsClient, type HandoffConfig, type HttpToolResult, type HttpToolSpec, type IncomingBrainRequest, type InferProcessData, type InterruptionConfig, type LLMProvider, type MemoryConfig, type MemoryScope, type ModelConfig, type OnQuery, type OnQueryContext, type OnQueryResult, Participant, type ParticipantsConfig, type PipelineConfig, PlansClient, type ProcessBackendAck, type ProcessDefinition, type ProcessField, type ProcessFieldType, type PronunciationDict, type ProviderFactory, type PublicFormSessionView, type PuppetControlDeps, type PuppetControlHandle, type ReadinessProbe, type ReadinessReport, type ReadinessResult, type RealtimeProvider, RedisBrainPubSub, type RegisterInput, type RegisterOptions, type RegisteredAgent, type ResendCredentials, type ResendEmailToolOptions, type RunAgentTextTranscriptOptions, type STTProvider, type SecurityConfig, type SentEmail, type ShorthandPrimitive$1 as ShorthandPrimitive, type SpeechConfig, type SseDelta, type SyncCallStateInput, type TTSProvider, type ToolDefinition$1 as ToolDefinition, type ToolInputShape$1 as ToolInputShape, type TriggerAction, type TriggerCondition, type TriggerDefinition, type TunnelBrainTransportOptions, type TurnDetectorProvider, type VADProvider, VoiceLayerAuthError, type VoiceLayerClient, VoiceLayerError, VoiceLayerHttpError, VoiceLayerNetworkError, VoiceLayerValidationError, type WebhookApi, type WebhookConfig, type WrapOptions, applyPronunciations, assemblyai, assertPublicHttpsUrl, asyncProbe, buildRedisBrainPubSub, callbackTransport, cartesia, collectDefaultMetadata, connector, createClient, createConnectorLLM, createNoOpLLM, deepgram, defineAgent, defineFlowRuntime, defineProcess, defineTool, elevenlabs, envProbe, formTools, google, httpTool, livekitTurn, mergeMetadata, openai, parseChatCompletionSse, processSchemaToAgentParts, processSchemaToDefinition, puppetEnvAvailable, resendEmailTool, runAgentTextTranscript, runBrainRequest, runProbes, silero, startPuppetControl, tunnelBrainTransport, urlProbe, webhook, wrap };
3336
+ export { Agent, type AgentConfig, AgentContext, type AgentEventEmitter, type AgentEventListener, type AgentLifecycleEvent, type AppendDtmfEventInput, type AppendTranscriptInput, BaseTool, BrainTransport, type CallAttributeValue, CallInfo, type CallLegInput, type CallOutcomeSummary, type CallParticipantInput, type CallStatus, type CallSummary, CallsClient, type CompiledAgentParts, type CompletionStrategy, type ComplianceTag, type ConnectorInstance, type ConnectorLLMConfig, ConsultationPolicy, type CreateClientOptions, type CreatedFormSession, type DefaultMetadata, type DtmfDirection, EmailClient, type SendEmailInput as EmailSendInput, type EndCallInfo, type EndCallPolicy, type EndCallTrigger, type EndpointingConfig, type EnsureCallByRoomInput, type ExchangeWorkerTokenInput, type CreateFormSessionInput as FormCreateInput, type FormToolsOptions, FormsClient, type HandoffConfig, type HttpToolResult, type HttpToolSpec, type InferProcessData, type InterruptionConfig, type LLMProvider, type MemoryConfig, type MemoryScope, type ModelConfig, OnQuery, Participant, type ParticipantsConfig, type PipelineConfig, PlansClient, type ProcessBackendAck, type ProcessDefinition, type ProcessField, type ProcessFieldType, type PronunciationDict, type ProviderFactory, type PublicFormSessionView, type ReadinessProbe, type ReadinessReport, type ReadinessResult, type RealtimeProvider, type RegisterInput, type RegisterOptions, type RegisteredAgent, type ResendCredentials, type ResendEmailToolOptions, type STTProvider, type SecurityConfig, type SentEmail, type ShorthandPrimitive$1 as ShorthandPrimitive, type SpeechConfig, type SyncCallStateInput, type TTSProvider, type ToolDefinition$1 as ToolDefinition, type ToolInputShape$1 as ToolInputShape, type TriggerAction, type TriggerCondition, type TriggerDefinition, type TurnDetectorProvider, type VADProvider, VoiceLayerAuthError, type VoiceLayerClient, VoiceLayerError, VoiceLayerHttpError, VoiceLayerNetworkError, VoiceLayerValidationError, type WebhookApi, type WebhookConfig, type WrapOptions, applyPronunciations, assemblyai, asyncProbe, cartesia, collectDefaultMetadata, connector, createClient, createNoOpLLM, deepgram, defineAgent, defineFlowRuntime, defineProcess, defineTool, elevenlabs, envProbe, exchangeWorkerToken, formTools, google, httpTool, livekitTurn, mergeMetadata, openai, processSchemaToAgentParts, processSchemaToDefinition, resendEmailTool, resolveWorkerClient, runProbes, silero, urlProbe, webhook, wrap };