@simple-ai-lab/sdk 0.3.0 → 0.6.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 (64) hide show
  1. package/README.md +56 -3
  2. package/dist/actions.cjs +438 -0
  3. package/dist/actions.d.cts +336 -0
  4. package/dist/actions.d.ts +336 -0
  5. package/dist/actions.js +429 -0
  6. package/dist/agents.cjs +1054 -0
  7. package/dist/agents.d.cts +1016 -0
  8. package/dist/agents.d.ts +1016 -0
  9. package/dist/agents.js +1044 -0
  10. package/dist/built-in-actions.cjs +356 -0
  11. package/dist/built-in-actions.d.cts +41 -0
  12. package/dist/built-in-actions.d.ts +41 -0
  13. package/dist/built-in-actions.js +353 -0
  14. package/dist/client.cjs +29 -0
  15. package/dist/client.d.cts +15 -0
  16. package/dist/client.d.ts +15 -0
  17. package/dist/client.js +25 -0
  18. package/dist/code-action/defaults.cjs +11 -0
  19. package/dist/code-action/defaults.d.cts +7 -0
  20. package/dist/code-action/defaults.d.ts +7 -0
  21. package/dist/code-action/defaults.js +8 -0
  22. package/dist/code-action/define-action.cjs +74 -0
  23. package/dist/code-action/define-action.d.cts +94 -0
  24. package/dist/code-action/define-action.d.ts +94 -0
  25. package/dist/code-action/define-action.js +69 -0
  26. package/dist/code-action/index.cjs +11 -0
  27. package/dist/code-action/index.d.cts +4 -0
  28. package/dist/code-action/index.d.ts +4 -0
  29. package/dist/code-action/index.js +3 -0
  30. package/dist/code-action/types.cjs +13 -0
  31. package/dist/code-action/types.d.cts +13 -0
  32. package/dist/code-action/types.d.ts +13 -0
  33. package/dist/code-action/types.js +10 -0
  34. package/dist/code-action/workflow.cjs +29 -0
  35. package/dist/code-action/workflow.d.cts +53 -0
  36. package/dist/code-action/workflow.d.ts +53 -0
  37. package/dist/code-action/workflow.js +26 -0
  38. package/dist/data.cjs +98 -0
  39. package/dist/data.d.cts +44 -0
  40. package/dist/data.d.ts +44 -0
  41. package/dist/data.js +94 -0
  42. package/dist/http.cjs +65 -0
  43. package/dist/http.d.cts +14 -0
  44. package/dist/http.d.ts +14 -0
  45. package/dist/http.js +62 -0
  46. package/dist/index.cjs +68 -1593
  47. package/dist/index.d.cts +12 -961
  48. package/dist/index.d.ts +12 -961
  49. package/dist/index.js +10 -1540
  50. package/dist/projects.cjs +234 -0
  51. package/dist/projects.d.cts +24 -0
  52. package/dist/projects.d.ts +24 -0
  53. package/dist/projects.js +228 -0
  54. package/dist/schemas.cjs +50 -0
  55. package/dist/schemas.d.cts +81 -0
  56. package/dist/schemas.d.ts +81 -0
  57. package/dist/schemas.js +47 -0
  58. package/dist/shared/errors.cjs +31 -0
  59. package/dist/shared/errors.d.cts +22 -0
  60. package/dist/shared/errors.d.ts +22 -0
  61. package/dist/shared/errors.js +26 -0
  62. package/package.json +27 -21
  63. package/dist/index.cjs.map +0 -1
  64. package/dist/index.js.map +0 -1
@@ -0,0 +1,1016 @@
1
+ import { z } from 'zod';
2
+ import type { ActionDefinition, ActionOutputParameterMappings, ActionOutputParameters, ActionRunDefinition, ActionVersionValues, BackgroundMessage, CallableActionDefinition, SourceFileReference } from "./actions.js";
3
+ /** A leaf path: `currentNode.name`, or a dot-delimited path rooted at `params`. */
4
+ export type TransitionFilterPath = string;
5
+ export type TransitionFilterValue = string | number | boolean | null;
6
+ export declare const TRANSITION_FILTER_EQUALITY_OPERATORS: readonly ["equals", "not_equals"];
7
+ export declare const TRANSITION_FILTER_NUMERIC_OPERATORS: readonly ["greater_than", "greater_than_or_equals", "less_than", "less_than_or_equals"];
8
+ export declare const TRANSITION_FILTER_CONTAINS_OPERATORS: readonly ["contains", "not_contains"];
9
+ export declare const TRANSITION_FILTER_STRING_OPERATORS: readonly ["starts_with", "ends_with"];
10
+ export declare const TRANSITION_FILTER_EXISTENCE_OPERATORS: readonly ["exists", "not_exists"];
11
+ export type TransitionFilterCondition = {
12
+ path: TransitionFilterPath;
13
+ operator: (typeof TRANSITION_FILTER_EQUALITY_OPERATORS)[number];
14
+ value: TransitionFilterValue;
15
+ } | {
16
+ path: TransitionFilterPath;
17
+ operator: (typeof TRANSITION_FILTER_NUMERIC_OPERATORS)[number];
18
+ value: number;
19
+ } | {
20
+ path: TransitionFilterPath;
21
+ operator: (typeof TRANSITION_FILTER_CONTAINS_OPERATORS)[number];
22
+ value: TransitionFilterValue;
23
+ } | {
24
+ path: TransitionFilterPath;
25
+ operator: (typeof TRANSITION_FILTER_STRING_OPERATORS)[number];
26
+ value: string;
27
+ } | {
28
+ path: TransitionFilterPath;
29
+ operator: (typeof TRANSITION_FILTER_EXISTENCE_OPERATORS)[number];
30
+ };
31
+ /**
32
+ * An inline-JavaScript predicate evaluated every turn. `code` is a full
33
+ * `function isAvailable(params) { ... }` declaration returning a boolean, which
34
+ * the Agent runs sandboxed.
35
+ */
36
+ export type TransitionFilterJs = {
37
+ type: 'js_filter';
38
+ code: string;
39
+ };
40
+ /**
41
+ * A deterministic condition evaluated inside the Agent process. `all`, `any`
42
+ * and `not` compose leaves into a condition tree.
43
+ *
44
+ * An edge filter may not read `currentNode.name`, because a node's own
45
+ * transitions always run from that node; an always-available filter may.
46
+ */
47
+ export type TransitionFilter = TransitionFilterCondition | TransitionFilterJs | {
48
+ all: TransitionFilter[];
49
+ } | {
50
+ any: TransitionFilter[];
51
+ } | {
52
+ not: TransitionFilter;
53
+ };
54
+ export declare const TRANSITION_FILTER_MAX_DEPTH = 8;
55
+ export declare const TRANSITION_FILTER_MAX_CONDITIONS = 100;
56
+ /**
57
+ * Declarative availability filter. Agent v2 owns the evaluator and validates
58
+ * filters when a commit is created; the SDK carries the value and checks only
59
+ * its shape.
60
+ */
61
+ export type TransitionFilterWire = TransitionFilter;
62
+ /** `disabled` stays silent, `authored` speaks `text` verbatim, `model` treats `text` as its instructions. */
63
+ export type TransitionMessageWire = {
64
+ source: 'disabled' | 'authored' | 'model';
65
+ text: string;
66
+ };
67
+ /** Speaking on a transition is opt-in per edge. */
68
+ export declare const DEFAULT_TRANSITION_MESSAGE: TransitionMessageWire;
69
+ export type BackgroundNoise = 'office' | 'coffee_shop' | 'driving' | 'restaurant' | 'street' | 'airport' | 'shopping_mall' | 'park' | 'off';
70
+ /**
71
+ * Agent v2's `call.backgroundNoise`: the track played under the call, and how
72
+ * loud it is relative to the recorded track.
73
+ */
74
+ export type BackgroundNoiseConfig = {
75
+ trackName: BackgroundNoise;
76
+ /** Optional in Agent v2, so leaving it out keeps the key out of the commit. */
77
+ gainMultiplier?: number;
78
+ };
79
+ /**
80
+ * The `call.backgroundNoise` a definition that says nothing about it compiles
81
+ * to, taken from `voice.backgroundNoise`. The CLI renders against this to tell
82
+ * a block it has to write from one `defineAgent` produces on its own.
83
+ */
84
+ export declare function defaultBackgroundNoise({ voiceBackgroundNoise, }: {
85
+ voiceBackgroundNoise: BackgroundNoise;
86
+ }): BackgroundNoiseConfig;
87
+ /** How readily the agent yields the floor to a caller talking over it, 1 (most reluctant) to 5 (stops on every barge-in). */
88
+ export type InterruptionEagerness = 1 | 2 | 3 | 4 | 5;
89
+ /** How eagerly end-of-turn detection hands the floor back, 1 (most patient) to 5 (most eager). */
90
+ export type EotEagerness = 1 | 2 | 3 | 4 | 5;
91
+ /**
92
+ * Automatic knowledge-base retrieval on every user turn. Independent of a prompt
93
+ * node's `knowledgeBases`, which builds the model-invoked search tool: a node can
94
+ * retrieve from a knowledge base it exposes no tool for, and vice versa.
95
+ */
96
+ export type PerTurnRetrievalWire = {
97
+ enabled: boolean;
98
+ knowledgeBaseUuids: string[];
99
+ topK: number;
100
+ recentTurns: number;
101
+ minScore: number | null;
102
+ };
103
+ /**
104
+ * How the agent should say a word the voice would otherwise mangle: `match` is
105
+ * compared case-sensitively against whole words, `say` is what gets spoken.
106
+ */
107
+ export type Pronunciation = {
108
+ match: string;
109
+ say: string;
110
+ };
111
+ export type RemoteReference = {
112
+ uuid: string;
113
+ };
114
+ /** How long the agent waits before checking in on a silent caller. Matches the product default. */
115
+ export declare const DEFAULT_CHECK_IN_AFTER_SILENCE_DELAY_SECONDS = 30;
116
+ /**
117
+ * Authored form: `delaySeconds` is left absent when it is not authored, so a
118
+ * commit that never carried the key keeps it that way. The runtime falls back to
119
+ * `DEFAULT_CHECK_IN_AFTER_SILENCE_DELAY_SECONDS` for an absent value.
120
+ */
121
+ export type CheckInAfterSilence = {
122
+ enabled: boolean;
123
+ prompt: string | null;
124
+ delaySeconds?: number;
125
+ };
126
+ /** Input form: `delaySeconds` may be left off to accept the default. */
127
+ export type CheckInAfterSilenceInput = {
128
+ enabled: boolean;
129
+ prompt: string | null;
130
+ delaySeconds?: number;
131
+ };
132
+ /** A prompt example, given inline or as a file read with `readPromptFile` at compile time. */
133
+ export type PromptExample = string | null | SourceFileReference;
134
+ export type PromptReference = {
135
+ kind: 'inline';
136
+ text: string | null;
137
+ example: PromptExample;
138
+ generatedExamples?: GeneratedExamples | null;
139
+ } | {
140
+ kind: 'file';
141
+ path: string;
142
+ example: PromptExample;
143
+ } | {
144
+ kind: 'version';
145
+ versionId: string;
146
+ };
147
+ export type ExtractionField = {
148
+ name: string;
149
+ type: string;
150
+ description: string;
151
+ required: boolean;
152
+ enum?: (string | number | boolean)[];
153
+ items?: ExtractionField;
154
+ properties?: ExtractionField[];
155
+ };
156
+ export type AgentV2EdgeWire = {
157
+ uuid: string;
158
+ toNodeUuid: string;
159
+ description: string;
160
+ priority: number;
161
+ condition: {
162
+ variable: string;
163
+ operator: string;
164
+ value: string;
165
+ } | null;
166
+ /** Optional only for commit snapshots written before edge filters existed. */
167
+ filter?: TransitionFilterWire | null;
168
+ message: TransitionMessageWire;
169
+ agentContext: string | null;
170
+ };
171
+ export type EnabledWithDescription = {
172
+ enabled: boolean;
173
+ description: string | null;
174
+ };
175
+ export type AlwaysAvailableTransitionFilterWire = TransitionFilterWire;
176
+ export type AlwaysAvailableCapability = EnabledWithDescription & {
177
+ filter?: TransitionFilterWire | null;
178
+ };
179
+ export type TransferCapability = {
180
+ enabled: boolean;
181
+ phoneNumber: string | null;
182
+ timeout: number;
183
+ mode: 'cold' | 'warm';
184
+ description: string | null;
185
+ voicemailMessage: string | null;
186
+ };
187
+ type NodeBuiltInCapabilities = {
188
+ alwaysAvailable?: EnabledWithDescription & {
189
+ filter?: AlwaysAvailableTransitionFilterWire | null;
190
+ };
191
+ transfer?: TransferCapability;
192
+ };
193
+ type PromptWire = {
194
+ type: 'inline';
195
+ prompt: string | null;
196
+ example: string | null;
197
+ generatedExamples?: GeneratedExamples | null;
198
+ } | {
199
+ type: 'reference';
200
+ promptVersionId: string;
201
+ };
202
+ type ActionUseSiteWire = {
203
+ actionUseSiteUuid: string;
204
+ actionVersionUuid: string;
205
+ inputMappings: Record<string, string>;
206
+ outputParameterMappings: Record<string, string>;
207
+ };
208
+ export type ToolUseSiteWire = ActionUseSiteWire & {
209
+ name: string;
210
+ description: string;
211
+ inputDescriptions: Record<string, string>;
212
+ /**
213
+ * Spoken while the Action runs. The platform stores `null` when none is set;
214
+ * commits that predate the field omit the key, and normalization fills null.
215
+ */
216
+ backgroundMessage?: BackgroundMessage | null;
217
+ };
218
+ export type AgentV2ConfigWire = {
219
+ voice: {
220
+ voiceUuid: string | null;
221
+ backgroundNoise: BackgroundNoise;
222
+ };
223
+ llm: {
224
+ model: string;
225
+ llmModelUuid: string | null;
226
+ temperature: number;
227
+ };
228
+ speech: {
229
+ language: string;
230
+ keyterms: string[];
231
+ voiceFormattingEnabled?: boolean;
232
+ pronunciations?: Pronunciation[];
233
+ };
234
+ /** Free-text guidance on how the agent should sound. Omitted by commits that predate the setting. */
235
+ toneGuidelines?: string | null;
236
+ call: {
237
+ agentSpeaksFirst: boolean;
238
+ firstSentence: string | null;
239
+ maxCallLengthSeconds: number;
240
+ record: boolean;
241
+ checkInAfterSilence: {
242
+ enabled: boolean;
243
+ prompt: string | null;
244
+ /** Optional only for commit snapshots written before the delay was configurable. */
245
+ delaySeconds?: number;
246
+ };
247
+ endCallAfterExtendedSilence: boolean;
248
+ pciEnabled: boolean;
249
+ /** Absent in commits with no background noise configured. */
250
+ backgroundNoise?: BackgroundNoiseConfig;
251
+ /** Optional only for commit snapshots written before the Voice Analysis settings existed. */
252
+ voiceAnalysisConfig?: {
253
+ interruptionEagerness?: InterruptionEagerness;
254
+ endOfTurnEagerness?: EotEagerness;
255
+ };
256
+ };
257
+ preCallWebhook: {
258
+ enabled: boolean;
259
+ url: string | null;
260
+ authToken: string | null;
261
+ timeout: number;
262
+ parameters: string[];
263
+ };
264
+ builtInTools: {
265
+ dtmf: EnabledWithDescription;
266
+ hangup: {
267
+ enabled: boolean;
268
+ description: string | null;
269
+ message: string | null;
270
+ };
271
+ transfer: TransferCapability;
272
+ };
273
+ assignedToolIds: string[];
274
+ toolUseSites?: ToolUseSiteWire[];
275
+ automaticActions: {
276
+ beforeCallStart: (ActionUseSiteWire & {
277
+ trigger: 'before_call_start';
278
+ }) | null;
279
+ };
280
+ knowledgeBaseIds: string[];
281
+ abTestGroupIds: string[];
282
+ };
283
+ type AgentV2NodeBaseWire = {
284
+ uuid: string;
285
+ name: string;
286
+ isRoot: boolean;
287
+ position: {
288
+ x: number;
289
+ y: number;
290
+ };
291
+ behavior: {
292
+ waitAfterExecuting: number;
293
+ [key: string]: number | undefined;
294
+ };
295
+ edges: AgentV2EdgeWire[];
296
+ builtInTools?: NodeBuiltInCapabilities;
297
+ };
298
+ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
299
+ type: 'global';
300
+ prompt: PromptWire;
301
+ }) | (AgentV2NodeBaseWire & {
302
+ type: 'standard';
303
+ prompt: PromptWire;
304
+ toolUuids: string[];
305
+ toolUseSiteUuids?: string[];
306
+ knowledgeBaseUuids: string[];
307
+ customDataTableNames: string[];
308
+ builtInTools: NodeBuiltInCapabilities;
309
+ sopSpec: SopSpec | null;
310
+ overrides: {
311
+ voice?: {
312
+ voiceUuid: string | null;
313
+ };
314
+ llm?: LlmOverrideWire;
315
+ };
316
+ perTurnWebhook?: {
317
+ enabled: boolean;
318
+ url: string;
319
+ authToken?: string | null;
320
+ } | null;
321
+ perTurnExtractionFields?: ExtractionField[] | null;
322
+ perTurnRetrieval?: PerTurnRetrievalWire | null;
323
+ perTurnAction?: (ActionUseSiteWire & {
324
+ trigger: 'every_turn';
325
+ }) | null;
326
+ }) | (AgentV2NodeBaseWire & {
327
+ type: 'http';
328
+ url: string;
329
+ method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
330
+ headers: Record<string, string>;
331
+ body: unknown;
332
+ responseSelectors: {
333
+ name: string;
334
+ value: string;
335
+ }[];
336
+ runInBackground: boolean;
337
+ backgroundMessage: string | null;
338
+ executionMessage: string | null;
339
+ mockResponseData: unknown;
340
+ builtInTools: NodeBuiltInCapabilities;
341
+ }) | (AgentV2NodeBaseWire & {
342
+ type: 'action_node';
343
+ actionVersionUuid: string;
344
+ inputMappings: Record<string, string>;
345
+ outputParameterMappings: Record<string, string>;
346
+ runInBackground: boolean;
347
+ backgroundMessage: string | null;
348
+ executionMessage: string | null;
349
+ mockResponseData: unknown;
350
+ builtInTools: NodeBuiltInCapabilities;
351
+ }) | (AgentV2NodeBaseWire & {
352
+ type: 'extract';
353
+ fields: ExtractionField[];
354
+ /**
355
+ * A shared Schema to extract with instead of `fields`, which must then be
356
+ * empty. The platform stores `null` when none is set; commits that predate
357
+ * the field omit the key, and normalization fills null.
358
+ */
359
+ schemaUuid?: string | null;
360
+ executionMessage: string | null;
361
+ builtInTools: NodeBuiltInCapabilities;
362
+ }) | (AgentV2NodeBaseWire & {
363
+ type: 'say';
364
+ executionMessage: string | null;
365
+ overrides: {
366
+ voice?: {
367
+ voiceUuid: string | null;
368
+ };
369
+ };
370
+ builtInTools: NodeBuiltInCapabilities;
371
+ }) | (AgentV2NodeBaseWire & {
372
+ type: 'end_call';
373
+ executionMessage: string | null;
374
+ /**
375
+ * Five9 routing headers attached to the BYE that ends the call; values are
376
+ * templates rendered against call parameters at hangup. Optional only for
377
+ * commit snapshots written before the setting existed.
378
+ */
379
+ sipByeHeaders?: Record<string, string>;
380
+ builtInTools: NodeBuiltInCapabilities;
381
+ }) | (AgentV2NodeBaseWire & {
382
+ type: 'ab_test';
383
+ abTestGroupUuid: string;
384
+ builtInTools: NodeBuiltInCapabilities;
385
+ }) | (AgentV2NodeBaseWire & {
386
+ type: 'update_parameters';
387
+ /** No model runs here, so the platform stores no capabilities for this node. */
388
+ parameterUpdates: ParameterUpdate[];
389
+ }) | (AgentV2NodeBaseWire & {
390
+ type: 'static_router';
391
+ /**
392
+ * Carried only so the router can be marked always-available: a standard
393
+ * node hands off to it and is then routed onward by its conditions.
394
+ */
395
+ builtInTools: NodeBuiltInCapabilities;
396
+ }) | (AgentV2NodeBaseWire & {
397
+ type: 'collect_credit_card';
398
+ instructions: string | null;
399
+ /** When true the authored instructions replace the built-in collector prompt. */
400
+ overrideCollectorPrompt?: boolean;
401
+ toolUseSiteUuids?: string[];
402
+ /**
403
+ * Only the responder that talks to the caller. The silent per-turn card
404
+ * extraction is pinned to a fixed model and is not authorable.
405
+ */
406
+ overrides: {
407
+ llm?: LlmOverrideWire;
408
+ };
409
+ }) | (AgentV2NodeBaseWire & {
410
+ type: 'transfer';
411
+ executionMessage: string | null;
412
+ builtInTools: NodeBuiltInCapabilities & {
413
+ transfer: TransferCapability;
414
+ };
415
+ }) | (AgentV2NodeBaseWire & {
416
+ type: 'transfer_chat';
417
+ executionMessage?: string | null;
418
+ mode?: 'five9' | 'teammate_handoff';
419
+ five9TenantName: string;
420
+ five9CampaignName: string;
421
+ five9ContactMapping: Record<string, unknown>;
422
+ five9AttributesMapping: Record<string, unknown>[];
423
+ builtInTools: NodeBuiltInCapabilities;
424
+ });
425
+ export type AgentV2CommitContentWire = {
426
+ config: AgentV2ConfigWire;
427
+ nodes: AgentV2NodeWire[];
428
+ summaryPrompt: string | null;
429
+ };
430
+ export type EdgeDefinition = {
431
+ key?: string;
432
+ to: string;
433
+ when: string;
434
+ priority?: number;
435
+ condition?: {
436
+ variable: string;
437
+ operator: string;
438
+ value: string;
439
+ } | null;
440
+ /** Model-routed availability guard; mutually exclusive with `condition`. */
441
+ filter?: TransitionFilterWire | null;
442
+ message?: TransitionMessageWire;
443
+ /** Told to the agent as this edge is taken, on the transition tool result. */
444
+ agentContext?: string | null;
445
+ };
446
+ /**
447
+ * One row of an Update Parameters node's map. Mirrors `ParameterUpdateSchema`
448
+ * in `@simple-ai-lab/shared` (`serialization/calls.ts`), which this package
449
+ * cannot depend on. Values resolve against the parameters as of node entry, so
450
+ * row order never changes the outcome.
451
+ */
452
+ export type ParameterUpdate = {
453
+ name: string;
454
+ value: string;
455
+ };
456
+ /** A per-node model override on the wire, where the model UUID is `llmModelUuid`. */
457
+ export type LlmOverrideWire = {
458
+ model: string | null;
459
+ llmModelUuid: string | null;
460
+ temperature: number | null;
461
+ };
462
+ /**
463
+ * Authoring form of `LlmOverrideWire`. Every node that can override the model
464
+ * takes this one type, so the prompt node and the collect-credit-card node
465
+ * cannot drift; `modelUuid` is the authoring spelling of `llmModelUuid`.
466
+ */
467
+ export type LlmOverrideDefinition = {
468
+ model: string | null;
469
+ modelUuid: string | null;
470
+ temperature: number | null;
471
+ };
472
+ type NodeBaseDefinition = {
473
+ key: string;
474
+ name: string;
475
+ root?: boolean;
476
+ position?: {
477
+ x: number;
478
+ y: number;
479
+ };
480
+ waitAfterExecuting?: number;
481
+ edges?: EdgeDefinition[];
482
+ alwaysAvailable?: AlwaysAvailableCapability;
483
+ };
484
+ export type GlobalNodeDefinition = NodeBaseDefinition & {
485
+ type: 'global';
486
+ prompt: PromptReference;
487
+ };
488
+ /** A tool a SOP section may use, by the uuid the graph already assigns it. */
489
+ export declare const SOP_TOOL_REF_TYPES: readonly ["http", "knowledge-base", "action"];
490
+ export type SopToolRef = {
491
+ type: (typeof SOP_TOOL_REF_TYPES)[number];
492
+ uuid: string;
493
+ };
494
+ /**
495
+ * A section's scoping of one edge's transition tool. An edge becomes restricted
496
+ * once a section sets `restrictToSection`, and is then offered only in sections
497
+ * that set it; `description` overrides the tool's wording for this section.
498
+ */
499
+ export type SopSectionEdge = {
500
+ edgeUuid: string;
501
+ description: string | null;
502
+ restrictToSection: boolean;
503
+ };
504
+ export type SopSection = {
505
+ uuid: string;
506
+ id: string;
507
+ name: string;
508
+ header: string;
509
+ prompt: string;
510
+ exampleUtterances: string[];
511
+ tools: SopToolRef[];
512
+ /** Absent means no edges are scoped. */
513
+ edges?: SopSectionEdge[];
514
+ };
515
+ export type SopGlobalContext = {
516
+ globalPrompt: string;
517
+ globalTools: SopToolRef[];
518
+ };
519
+ /** A node's standard operating procedure: shared context plus ordered sections. */
520
+ export type SopSpec = {
521
+ globalContext: SopGlobalContext;
522
+ sections: SopSection[];
523
+ };
524
+ /** The policy distilled from a node prompt, ordered most-important-first. */
525
+ export type GeneratedExamplesPolicy = {
526
+ goals: string[];
527
+ mustDoRules: string[];
528
+ mustNotDoRules: string[];
529
+ successCriteria: string[];
530
+ edgeCases: string[];
531
+ };
532
+ /**
533
+ * The artifact the example-generation pipeline persists on a prompt. The SDK
534
+ * carries it so a pull keeps it; `coverageCases`, `selectedPlans` and the
535
+ * examples themselves stay opaque because the pipeline owns their shape and the
536
+ * SDK never constructs one.
537
+ */
538
+ export type GeneratedExamples = {
539
+ policy: GeneratedExamplesPolicy;
540
+ coverageCases: unknown[];
541
+ selectedPlans: unknown[];
542
+ examples: {
543
+ goodExamples: unknown[];
544
+ badExamples: unknown[];
545
+ };
546
+ };
547
+ export type PromptNodeDefinition = NodeBaseDefinition & {
548
+ type: 'prompt';
549
+ prompt: PromptReference;
550
+ actions?: CallableActionDefinition[];
551
+ /** Legacy v1 tools on this node, by uuid. See `AgentDefinition.tools`. */
552
+ tools?: RemoteReference[];
553
+ knowledgeBases?: RemoteReference[];
554
+ customDataTables?: string[];
555
+ sopSpec?: SopSpec | null;
556
+ voiceOverride?: {
557
+ voiceUuid: string | null;
558
+ };
559
+ llmOverride?: LlmOverrideDefinition;
560
+ vadMinSilenceDuration?: number;
561
+ waitAfterTransfer?: number;
562
+ perTurnWebhook?: {
563
+ enabled: boolean;
564
+ url: string;
565
+ authToken?: string | null;
566
+ } | null;
567
+ perTurnExtraction?: ExtractionInput | null;
568
+ perTurnRetrieval?: PerTurnRetrievalDefinition | null;
569
+ perTurnAction?: ActionRunDefinition | null;
570
+ transfer?: Pick<TransferCapability, 'enabled'> & Partial<Omit<TransferCapability, 'enabled'>>;
571
+ };
572
+ /** Authoring form of `PerTurnRetrievalWire`; omitted settings take the product defaults. */
573
+ export type PerTurnRetrievalDefinition = {
574
+ /** Defaults to true: supplying the object at all means you want retrieval on. */
575
+ enabled?: boolean;
576
+ knowledgeBases: RemoteReference[];
577
+ topK?: number;
578
+ recentTurns?: number;
579
+ minScore?: number | null;
580
+ };
581
+ export type ActionNodeDefinition = NodeBaseDefinition & {
582
+ type: 'action';
583
+ action: ActionDefinition;
584
+ inputs: Record<string, string>;
585
+ outputParameters?: ActionOutputParameters;
586
+ outputParameterMappings?: ActionOutputParameterMappings;
587
+ runInBackground?: boolean;
588
+ backgroundMessage?: string | null;
589
+ executionMessage?: string | null;
590
+ mockResponseData?: unknown;
591
+ };
592
+ /**
593
+ * An HTTP request node in the Agent graph.
594
+ *
595
+ * Prefer `action.http(...)` plus `node.action(...)` for new work: Actions are
596
+ * versioned and reusable, HTTP nodes are neither. This exists so Agents that
597
+ * already contain HTTP nodes can be pulled into, edited as, and published from
598
+ * real source instead of an opaque snapshot.
599
+ */
600
+ export type HttpNodeDefinition = NodeBaseDefinition & {
601
+ type: 'http';
602
+ url: string;
603
+ method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
604
+ headers?: Record<string, string>;
605
+ body?: unknown;
606
+ responseSelectors?: {
607
+ name: string;
608
+ value: string;
609
+ }[];
610
+ runInBackground?: boolean;
611
+ backgroundMessage?: string | null;
612
+ executionMessage?: string | null;
613
+ mockResponseData?: unknown;
614
+ };
615
+ export type ExtractNodeDefinition = NodeBaseDefinition & {
616
+ type: 'extract';
617
+ /**
618
+ * The fields to extract: a Zod object compiled into the node, or a
619
+ * `reference(...)` to a shared Schema of the organization, resolved live when
620
+ * the call is serialized, like knowledge bases.
621
+ */
622
+ schema: ExtractionInput | RemoteReference;
623
+ message?: string | null;
624
+ };
625
+ export type SayNodeDefinition = NodeBaseDefinition & {
626
+ type: 'say';
627
+ /** `null` for a say node that has not been given its line yet. */
628
+ text: string | null;
629
+ voiceUuid?: string | null;
630
+ waitAfterSay?: number;
631
+ };
632
+ /**
633
+ * The only headers Five9's SIP trunk contract forwards on the BYE, and so the
634
+ * only ones the platform accepts. Mirrors `FIVE9_SIP_ATTRIBUTES_TO_HEADERS` in
635
+ * `@simple-ai-lab/shared` (`public/sip-bye-headers.ts`), which this package
636
+ * cannot depend on; the platform rejects any other name at publish.
637
+ */
638
+ export declare const FIVE9_SIP_BYE_HEADER_NAMES: readonly ["X-RouteReason", "X-RouteType", "X-RouteValue", "X-MetaData"];
639
+ export type Five9SipByeHeaderName = (typeof FIVE9_SIP_BYE_HEADER_NAMES)[number];
640
+ export type EndCallNodeDefinition = NodeBaseDefinition & {
641
+ type: 'end-call';
642
+ message?: string | null;
643
+ /**
644
+ * Five9 routing headers attached to the BYE that ends the call, keyed by
645
+ * header name; values are templates rendered against call parameters at
646
+ * hangup. Only the four names the platform accepts may be used.
647
+ */
648
+ sipByeHeaders?: Partial<Record<Five9SipByeHeaderName, string>>;
649
+ };
650
+ export type AbTestNodeDefinition = NodeBaseDefinition & {
651
+ type: 'ab-test';
652
+ abTestGroupUuid: string;
653
+ };
654
+ /**
655
+ * Writes a static map of call parameters, then takes the first edge whose
656
+ * condition matches. No model runs, so there is nothing to speak and nothing to
657
+ * expose as a tool: `alwaysAvailable` is omitted because the platform stores no
658
+ * capabilities for this node and setting one would be silently dropped.
659
+ *
660
+ * `parameterUpdates` is required rather than defaulted: the map is the whole
661
+ * node, and an empty one is a deliberate choice worth writing.
662
+ */
663
+ export type UpdateParametersNodeDefinition = Omit<NodeBaseDefinition, 'alwaysAvailable'> & {
664
+ type: 'update-parameters';
665
+ parameterUpdates: ParameterUpdate[];
666
+ };
667
+ /**
668
+ * Takes the first edge whose condition matches. No model runs, so it neither
669
+ * speaks nor overrides anything; `alwaysAvailable` is kept so a prompt node can
670
+ * hand off to it and be routed onward deterministically.
671
+ */
672
+ export type StaticRouterNodeDefinition = NodeBaseDefinition & {
673
+ type: 'static-router';
674
+ };
675
+ /**
676
+ * Collects a card number inside the conversation. The runtime supplies the
677
+ * PCI-safe collection prompt and the Luhn check, so `instructions` only adds
678
+ * business-specific wording. `alwaysAvailable` is omitted for the same reason
679
+ * as the update-parameters node: the platform stores no capabilities here.
680
+ */
681
+ export type CollectCreditCardNodeDefinition = Omit<NodeBaseDefinition, 'alwaysAvailable'> & {
682
+ type: 'collect-credit-card';
683
+ instructions?: string | null;
684
+ /**
685
+ * When true the instructions replace the built-in collector prompt instead of being
686
+ * appended to it, and the author owns asking for every card detail.
687
+ */
688
+ overridePrompt?: boolean;
689
+ /** Actions the node can invoke while collecting, for example an in-node card save. */
690
+ actions?: CallableActionDefinition[];
691
+ llmOverride?: LlmOverrideDefinition;
692
+ vadMinSilenceDuration?: number;
693
+ };
694
+ /**
695
+ * Every field here takes its type from `TransferCapability`, the one
696
+ * description of a transfer, so the two cannot drift. `enabled` is deliberately
697
+ * absent: a transfer node *is* the transfer, and the call serializer reports
698
+ * `transfer_enabled: true` for one whatever the stored flag says.
699
+ *
700
+ * `phoneNumber` is nullable because Agent v2 stores it that way. A transfer
701
+ * node whose number has not been chosen yet is published and served, failing
702
+ * only when the transfer is attempted.
703
+ *
704
+ * `enabled` defaults to true. Agent v2 stores the flag and the call serializer
705
+ * reports `transfer_enabled: true` for a transfer node whatever it holds, so a
706
+ * stored `false` changes nothing at runtime but is part of the commit.
707
+ */
708
+ export type TransferNodeDefinition = NodeBaseDefinition & {
709
+ type: 'transfer';
710
+ message?: string | null;
711
+ enabled?: TransferCapability['enabled'];
712
+ phoneNumber: TransferCapability['phoneNumber'];
713
+ mode?: TransferCapability['mode'];
714
+ timeout?: TransferCapability['timeout'];
715
+ description?: TransferCapability['description'];
716
+ voicemailMessage?: TransferCapability['voicemailMessage'];
717
+ waitAfterTransfer?: number;
718
+ };
719
+ export type TransferChatNodeDefinition = NodeBaseDefinition & {
720
+ type: 'transfer-chat';
721
+ /**
722
+ * Three states, like the commit: absent keeps the key out, `null` writes an
723
+ * explicit null, a string writes it.
724
+ */
725
+ message?: string | null;
726
+ /**
727
+ * Required, because Agent v2 and the agent both read an absent mode as
728
+ * `five9` and run a Five9 transfer against whatever tenant is set. Write
729
+ * `undefined` to reproduce a commit that stores no mode.
730
+ */
731
+ mode: 'five9' | 'teammate_handoff' | undefined;
732
+ five9TenantName?: string;
733
+ five9CampaignName?: string;
734
+ five9ContactMapping?: Record<string, unknown>;
735
+ five9AttributesMapping?: Record<string, unknown>[];
736
+ };
737
+ export type NodeDefinition = GlobalNodeDefinition | PromptNodeDefinition | ActionNodeDefinition | HttpNodeDefinition | ExtractNodeDefinition | SayNodeDefinition | EndCallNodeDefinition | AbTestNodeDefinition | UpdateParametersNodeDefinition | StaticRouterNodeDefinition | CollectCreditCardNodeDefinition | TransferNodeDefinition | TransferChatNodeDefinition;
738
+ /** One call parameter compared against a value, as containment rules read it. */
739
+ export type CallParameterFilter = {
740
+ path: string;
741
+ type: 'string';
742
+ op: 'eq' | 'ne' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'exists' | 'not_exists';
743
+ value: string | null;
744
+ } | {
745
+ path: string;
746
+ type: 'number';
747
+ op: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' | 'not_exists';
748
+ value: number | null;
749
+ } | {
750
+ path: string;
751
+ type: 'boolean';
752
+ op: 'eq' | 'ne' | 'exists' | 'not_exists';
753
+ value: boolean | null;
754
+ };
755
+ export type ContainmentParameterCondition = {
756
+ type: 'parameter';
757
+ filter: CallParameterFilter;
758
+ };
759
+ export declare const CONTAINMENT_RULE_MATCHES: readonly ["all", "any"];
760
+ export declare const CONTAINMENT_CONTAINABLE_CONDITION_TYPES: readonly ["parameter", "tag", "visited_node"];
761
+ export declare const CONTAINMENT_CONTAINED_CONDITION_TYPES: readonly ["parameter", "visited_node", "ended_by"];
762
+ export type ContainmentTagCondition = {
763
+ type: 'tag';
764
+ tagUuid: string;
765
+ operator: 'has' | 'does_not_have';
766
+ };
767
+ export type ContainmentVisitedNodeCondition = {
768
+ type: 'visited_node';
769
+ nodeUuid: string | null;
770
+ nodeName: string;
771
+ operator: 'visited' | 'not_visited';
772
+ };
773
+ export type ContainmentEndedByCondition = {
774
+ type: 'ended_by';
775
+ party: 'agent' | 'user';
776
+ };
777
+ export type ContainableCondition = ContainmentParameterCondition | ContainmentTagCondition | ContainmentVisitedNodeCondition;
778
+ export type ContainedCondition = ContainmentParameterCondition | ContainmentVisitedNodeCondition | ContainmentEndedByCondition;
779
+ export type ContainableRuleGroup = {
780
+ match: (typeof CONTAINMENT_RULE_MATCHES)[number];
781
+ conditions: (ContainableCondition | ContainableRuleGroup)[];
782
+ };
783
+ export type ContainedRuleGroup = {
784
+ match: (typeof CONTAINMENT_RULE_MATCHES)[number];
785
+ conditions: (ContainedCondition | ContainedRuleGroup)[];
786
+ };
787
+ export type ContainableRuleSet = {
788
+ mode: 'always';
789
+ } | {
790
+ mode: 'rules';
791
+ rules: ContainableRuleGroup;
792
+ };
793
+ export type ContainedRuleSet = {
794
+ mode: 'always';
795
+ } | {
796
+ mode: 'rules';
797
+ rules: ContainedRuleGroup;
798
+ };
799
+ /** When a call counts as containable, and when it counts as contained. */
800
+ export type ContainmentConfig = {
801
+ version: 2;
802
+ containable: ContainableRuleSet;
803
+ contained: ContainedRuleSet;
804
+ };
805
+ export declare const MAX_CONTAINMENT_RULE_DEPTH = 5;
806
+ export type AgentDefinition = {
807
+ kind: 'agent-definition';
808
+ key: string;
809
+ name: string;
810
+ description: string | null;
811
+ branch: string;
812
+ modality: 'voice' | 'text';
813
+ folderUuid: string | null;
814
+ analyzerUuids: string[];
815
+ tagUuids: string[];
816
+ containmentConfig: ContainmentConfig | null;
817
+ voice: {
818
+ voiceUuid: string | null;
819
+ backgroundNoise: BackgroundNoise;
820
+ };
821
+ llm: {
822
+ model: string;
823
+ modelUuid: string | null;
824
+ temperature: number;
825
+ };
826
+ speech: {
827
+ language: string;
828
+ keyterms: string[];
829
+ voiceFormattingEnabled: boolean;
830
+ pronunciations: Pronunciation[];
831
+ };
832
+ /**
833
+ * Free-text guidance on how the agent should sound: pronunciation, brevity,
834
+ * read-back style. Three states, like the per-turn node settings: absent keeps
835
+ * the key out of the commit, `null` writes an explicit null, a string writes it.
836
+ */
837
+ toneGuidelines?: string | null;
838
+ call: {
839
+ agentSpeaksFirst: boolean;
840
+ firstSentence: string | null;
841
+ maxCallLengthSeconds: number;
842
+ record: boolean;
843
+ checkInAfterSilence: CheckInAfterSilence;
844
+ endCallAfterExtendedSilence: boolean;
845
+ pciEnabled: boolean;
846
+ /**
847
+ * Agent v2's `call.backgroundNoise`, which is what a call actually plays.
848
+ * It is stored apart from `voice.backgroundNoise`, and the two can
849
+ * legitimately disagree (`voice: 'off'`, track: `'coffee_shop'`).
850
+ *
851
+ * `null` leaves the block out of the commit entirely. Left unset, it
852
+ * follows `voice.backgroundNoise` — see `defaultBackgroundNoise`.
853
+ */
854
+ backgroundNoise: BackgroundNoiseConfig | null;
855
+ /** `null` omits interruption config entirely rather than defaulting it. */
856
+ interruptionEagerness: InterruptionEagerness | null;
857
+ /** `null` omits the setting entirely, leaving the product default in charge. */
858
+ eotEagerness: EotEagerness | null;
859
+ };
860
+ preCallWebhook: {
861
+ enabled: boolean;
862
+ url: string | null;
863
+ authToken: string | null;
864
+ timeout: number;
865
+ parameters: string[];
866
+ };
867
+ capabilities: {
868
+ dtmf: EnabledWithDescription;
869
+ hangup: EnabledWithDescription & {
870
+ message: string | null;
871
+ };
872
+ transfer: TransferCapability;
873
+ };
874
+ /**
875
+ * Legacy v1 tools assigned to the Agent, by uuid. Superseded by callable
876
+ * Actions; held as an opaque reference the SDK never interprets, so Agents
877
+ * that still carry them round-trip.
878
+ */
879
+ tools: RemoteReference[];
880
+ knowledgeBases: RemoteReference[];
881
+ beforeCallAction: ActionRunDefinition | null;
882
+ summaryPrompt: string | null;
883
+ /**
884
+ * A/B test groups on the Agent.
885
+ *
886
+ * `null` derives the set from `ab-test` nodes, which is what authoring in code
887
+ * produces. Pulled Agents can carry groups with no corresponding node, so they
888
+ * set this explicitly.
889
+ */
890
+ abTestGroupIds: string[] | null;
891
+ /**
892
+ * The Agent's callable Action use sites, in the order Agent v2 stores them. A
893
+ * node points into this list, so it can carry an order the nodes do not, a use
894
+ * site shared by several nodes, and one no node references.
895
+ *
896
+ * `null` derives the list from the nodes, in node order.
897
+ */
898
+ actions: CallableActionDefinition[] | null;
899
+ nodes: NodeDefinition[];
900
+ };
901
+ export type AgentDefinitionInput = {
902
+ key: string;
903
+ name: string;
904
+ description?: string | null;
905
+ branch: string;
906
+ modality?: 'voice' | 'text';
907
+ folderUuid?: string | null;
908
+ analyzerUuids?: string[];
909
+ tagUuids?: string[];
910
+ containmentConfig?: ContainmentConfig | null;
911
+ voice?: {
912
+ voiceUuid?: string | null;
913
+ backgroundNoise?: BackgroundNoise;
914
+ };
915
+ llm?: {
916
+ model?: string;
917
+ modelUuid?: string | null;
918
+ temperature?: number;
919
+ };
920
+ speech?: {
921
+ language?: string;
922
+ keyterms?: string[];
923
+ voiceFormattingEnabled?: boolean;
924
+ pronunciations?: Pronunciation[];
925
+ };
926
+ toneGuidelines?: string | null;
927
+ call?: Partial<Omit<AgentDefinition['call'], 'checkInAfterSilence'>> & {
928
+ checkInAfterSilence?: CheckInAfterSilenceInput;
929
+ };
930
+ preCallWebhook?: Partial<AgentDefinition['preCallWebhook']>;
931
+ capabilities?: {
932
+ dtmf?: Partial<EnabledWithDescription>;
933
+ hangup?: Partial<EnabledWithDescription & {
934
+ message: string | null;
935
+ }>;
936
+ transfer?: Partial<TransferCapability>;
937
+ };
938
+ tools?: RemoteReference[];
939
+ knowledgeBases?: RemoteReference[];
940
+ beforeCallAction?: ActionRunDefinition | null;
941
+ summaryPrompt?: string | null;
942
+ abTestGroupIds?: string[] | null;
943
+ actions?: CallableActionDefinition[] | null;
944
+ nodes: NodeDefinition[];
945
+ };
946
+ export type AgentIdentityKind = 'node' | 'edge' | 'action-use-site' | 'action-version-placeholder';
947
+ export type AgentCompileOptions = {
948
+ actionVersionUuids?: Record<string, string>;
949
+ identity?: (input: {
950
+ kind: AgentIdentityKind;
951
+ key: string;
952
+ }) => string | undefined;
953
+ readPromptFile?: (path: string) => string;
954
+ readActionSourceFile?: (path: string) => string;
955
+ allowUnresolvedActionVersions?: boolean;
956
+ };
957
+ export type CompiledAgentProject = {
958
+ agent: {
959
+ key: string;
960
+ name: string;
961
+ description: string | null;
962
+ modality: 'voice' | 'text';
963
+ folderUuid: string | null;
964
+ analyzerUuids: string[];
965
+ tagUuids: string[];
966
+ containmentConfig: ContainmentConfig | null;
967
+ };
968
+ branch: {
969
+ name: string;
970
+ };
971
+ actions: {
972
+ key: string;
973
+ versionUuid: string;
974
+ values: ActionVersionValues;
975
+ }[];
976
+ content: AgentV2CommitContentWire;
977
+ };
978
+ export declare function defineAgent(input: AgentDefinitionInput): AgentDefinition;
979
+ export declare const node: {
980
+ global(config: Omit<GlobalNodeDefinition, "type">): GlobalNodeDefinition;
981
+ prompt(config: Omit<PromptNodeDefinition, "type">): PromptNodeDefinition;
982
+ action(config: Omit<ActionNodeDefinition, "type">): ActionNodeDefinition;
983
+ http(config: Omit<HttpNodeDefinition, "type">): HttpNodeDefinition;
984
+ extract(config: Omit<ExtractNodeDefinition, "type">): ExtractNodeDefinition;
985
+ say(config: Omit<SayNodeDefinition, "type">): SayNodeDefinition;
986
+ endCall(config: Omit<EndCallNodeDefinition, "type">): EndCallNodeDefinition;
987
+ abTest(config: Omit<AbTestNodeDefinition, "type">): AbTestNodeDefinition;
988
+ updateParameters(config: Omit<UpdateParametersNodeDefinition, "type">): UpdateParametersNodeDefinition;
989
+ staticRouter(config: Omit<StaticRouterNodeDefinition, "type">): StaticRouterNodeDefinition;
990
+ collectCreditCard(config: Omit<CollectCreditCardNodeDefinition, "type">): CollectCreditCardNodeDefinition;
991
+ transfer(config: Omit<TransferNodeDefinition, "type">): TransferNodeDefinition;
992
+ transferChat(config: Omit<TransferChatNodeDefinition, "type">): TransferChatNodeDefinition;
993
+ };
994
+ export declare const prompt: {
995
+ inline(text: string | null, example?: PromptExample, generatedExamples?: GeneratedExamples | null): PromptReference;
996
+ file(path: string, example?: PromptExample): PromptReference;
997
+ version(versionId: string): PromptReference;
998
+ };
999
+ export declare function reference(uuid: string): RemoteReference;
1000
+ export declare function canonicalAuthoringKey(value: string, fallback: string): string;
1001
+ export declare function canonicalAuthoringKeys(values: {
1002
+ value: string;
1003
+ fallback: string;
1004
+ }[]): string[];
1005
+ /**
1006
+ * The fields to extract. `ExtractionField[]` is what Agent v2 stores and Zod is
1007
+ * a convenience over it, so the stored form is accepted directly for the shapes
1008
+ * Zod has no equivalent for.
1009
+ */
1010
+ export type ExtractionInput = z.ZodObject<z.ZodRawShape> | ExtractionField[];
1011
+ export declare function resolveExtractionFields(schema: ExtractionInput): ExtractionField[];
1012
+ /** Product defaults for retrieval settings the author leaves out. */
1013
+ export declare const DEFAULT_PER_TURN_RETRIEVAL_TOP_K = 3;
1014
+ export declare const DEFAULT_PER_TURN_RETRIEVAL_RECENT_TURNS = 4;
1015
+ export declare function compileAgent(definition: AgentDefinition, options?: AgentCompileOptions): CompiledAgentProject;
1016
+ export {};