@simple-ai-lab/sdk 0.12.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/agents.d.cts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import type { ActionDefinition, ActionOutputParameterMappings, ActionOutputParameters, ActionRunDefinition, ActionVersionValues, BackgroundMessage, CallableActionDefinition, SourceFileReference } from "./actions.cjs";
2
+ import type { ActionDefinition, ActionInputLabel, ActionOutputParameterMappings, ActionOutputParameters, ActionRunDefinition, ActionVersionValues, BackgroundMessage, CallableActionDefinition, SourceFileReference } from "./actions.cjs";
3
3
  /** A leaf path: `currentNode.name`, or a dot-delimited path rooted at `params`. */
4
4
  export type TransitionFilterPath = string;
5
5
  export type TransitionFilterValue = string | number | boolean | null;
@@ -195,12 +195,13 @@ export type TransferCapability = {
195
195
  mode: 'cold' | 'warm';
196
196
  description: string | null;
197
197
  voicemailMessage: string | null;
198
+ /** What a warm transfer tells the human agent before connecting the caller. */
199
+ briefing?: string | null;
198
200
  };
199
201
  type NodeBuiltInCapabilities = {
200
202
  alwaysAvailable?: EnabledWithDescription & {
201
203
  filter?: AlwaysAvailableTransitionFilterWire | null;
202
204
  };
203
- transfer?: TransferCapability;
204
205
  };
205
206
  type PromptWire = {
206
207
  type: 'inline';
@@ -221,6 +222,8 @@ export type ToolUseSiteWire = ActionUseSiteWire & {
221
222
  name: string;
222
223
  description: string;
223
224
  inputDescriptions: Record<string, string>;
225
+ /** Labels keyed by input pointer. Absent when the use site labels nothing. */
226
+ inputLabels?: Record<string, ActionInputLabel>;
224
227
  /**
225
228
  * Spoken while the Action runs. The platform stores `null` when none is set;
226
229
  * commits that predate the field omit the key, and normalization fills null.
@@ -288,6 +291,116 @@ export type CartConfigWire = {
288
291
  } | null;
289
292
  } | null;
290
293
  };
294
+ /**
295
+ * The `:` keeps these apart from callable keys, which `canonicalAuthoringKey` limits to letters, digits and `-`;
296
+ * otherwise a callable named "Call end" would take the call-end run's use site. Projects pulled before the prefix
297
+ * name the old key in their source, which is looked up first.
298
+ */
299
+ export declare const BEFORE_CALL_ACTION_KEY = "automatic:before-call-start";
300
+ export declare const CALL_END_ACTION_KEY = "automatic:call-end";
301
+ /** The identity key of an Agent Assist step or card button's run, by the id the playbook stores for it. */
302
+ export declare function assistActionRunKey({ kind, id }: {
303
+ kind: 'step' | 'button';
304
+ id: string;
305
+ }): string;
306
+ /** Which kind of Agent this is. An `assist` Agent is an Agent Assist playbook, configured by `config.assist`. */
307
+ export type AgentModality = 'voice' | 'text' | 'assist';
308
+ export declare const GUARDRAIL_MODES: readonly ["enforce", "monitor"];
309
+ /** `monitor` records when the guardrail fires without taking its action. */
310
+ export type GuardrailMode = (typeof GUARDRAIL_MODES)[number];
311
+ /**
312
+ * Pins one version of an organization guardrail to the Agent. The version owns
313
+ * the condition and the action; a `transition` guardrail moves the call to
314
+ * `nodeUuid`, which is per Agent because node uuids are, and is null for every
315
+ * other action.
316
+ */
317
+ export type GuardrailAssignmentWire = {
318
+ guardrailUuid: string;
319
+ version: number;
320
+ mode: GuardrailMode;
321
+ nodeUuid: string | null;
322
+ };
323
+ /** The Action use site an Agent Assist step or card button runs, with no trigger of its own. */
324
+ export type AssistActionUseSiteWire = ActionUseSiteWire;
325
+ /**
326
+ * A comparison on a call parameter. Mirrors `ConditionOperatorSchema` in
327
+ * `@simple-ai-lab/shared` (`public/condition-operators.ts`), which this package
328
+ * cannot depend on; server-v2's `sdk-wire-contract.test.ts` holds the two equal.
329
+ */
330
+ export type ConditionOperator = 'always' | '==' | '!=' | '>' | '<' | '>=' | '<=' | 'is_null' | 'is_not_null' | 'is_array_empty' | 'is_array_not_empty' | 'is_true' | 'is_false' | 'contains' | 'not_contains' | 'in' | 'not_in' | 'never';
331
+ export type AssistParameterConditionWire = {
332
+ variable: string;
333
+ operator: ConditionOperator;
334
+ value: string;
335
+ };
336
+ /** The moment an Agent Assist procedure waits for, defined the way an edge is. */
337
+ export type AssistMomentTriggerWire = {
338
+ description: string;
339
+ condition: AssistParameterConditionWire | null;
340
+ filter: TransitionFilterWire | null;
341
+ };
342
+ export type AssistProcedureHookWire = {
343
+ kind: 'call_start';
344
+ } | {
345
+ kind: 'moment';
346
+ trigger: AssistMomentTriggerWire;
347
+ } | {
348
+ kind: 'call_end';
349
+ };
350
+ export type AssistProcedureStepWire = {
351
+ id: string;
352
+ kind: 'run_action';
353
+ action: AssistActionUseSiteWire;
354
+ } | {
355
+ id: string;
356
+ kind: 'show_card';
357
+ cardId: string;
358
+ } | {
359
+ id: string;
360
+ kind: 'show_checklist';
361
+ checklistId: string;
362
+ };
363
+ export type AssistProcedureWire = {
364
+ id: string;
365
+ name: string;
366
+ hook: AssistProcedureHookWire;
367
+ steps: AssistProcedureStepWire[];
368
+ };
369
+ export type AssistCardButtonWire = {
370
+ id: string;
371
+ label: string;
372
+ action: AssistActionUseSiteWire;
373
+ /** Empty always holds. */
374
+ availableWhen: AssistParameterConditionWire[];
375
+ };
376
+ /** How a card reads: guidance to follow, or a caution about something the rep should not do. */
377
+ export type AssistCardTone = 'guidance' | 'caution';
378
+ export type AssistCardWire = {
379
+ id: string;
380
+ name: string;
381
+ title: string;
382
+ body: string;
383
+ tone: AssistCardTone;
384
+ /** Empty never holds: the card stays until the rep dismisses it. */
385
+ doneWhen: AssistParameterConditionWire[];
386
+ buttons: AssistCardButtonWire[];
387
+ };
388
+ export type AssistChecklistWire = {
389
+ id: string;
390
+ name: string;
391
+ items: ExtractionField[];
392
+ };
393
+ /**
394
+ * An Agent Assist playbook's own configuration. Mirrors
395
+ * `assistPlaybookConfigSchema` in `@simple-ai-lab/shared`
396
+ * (`public/assist-playbook.ts`); present on every commit of an `assist` Agent
397
+ * and on no other.
398
+ */
399
+ export type AssistPlaybookConfigWire = {
400
+ procedures: AssistProcedureWire[];
401
+ cards: AssistCardWire[];
402
+ checklists: AssistChecklistWire[];
403
+ };
291
404
  export type AgentV2ConfigWire = {
292
405
  voice: {
293
406
  voiceUuid: string | null;
@@ -350,7 +463,7 @@ export type AgentV2ConfigWire = {
350
463
  beforeCallStart: (ActionUseSiteWire & {
351
464
  trigger: 'before_call_start';
352
465
  }) | null;
353
- /** Absent in commits written before the trigger existed. Source cannot author it yet; snapshots carry it. */
466
+ /** Absent in commits written before the trigger existed. */
354
467
  callEnd?: (ActionUseSiteWire & {
355
468
  trigger: 'call_end';
356
469
  }) | null;
@@ -359,6 +472,14 @@ export type AgentV2ConfigWire = {
359
472
  abTestGroupIds: string[];
360
473
  /** Absent in commits written before carts existed. */
361
474
  cart?: CartConfigWire | null;
475
+ /** Absent in commits written before guardrails existed, which means none. */
476
+ guardrails?: GuardrailAssignmentWire[];
477
+ /** The background check that moves the call to the node the conversation belongs on. Absent means off. */
478
+ nodeCheck?: {
479
+ enabled: boolean;
480
+ };
481
+ /** Present on every commit of an `assist` Agent and on no other. */
482
+ assist?: AssistPlaybookConfigWire;
362
483
  };
363
484
  type AgentV2NodeBaseWire = {
364
485
  uuid: string;
@@ -370,22 +491,27 @@ type AgentV2NodeBaseWire = {
370
491
  };
371
492
  behavior: {
372
493
  waitAfterExecuting: number;
373
- [key: string]: number | undefined;
374
494
  };
375
495
  edges: AgentV2EdgeWire[];
376
- builtInTools?: NodeBuiltInCapabilities;
377
496
  };
378
497
  export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
379
498
  type: 'global';
380
499
  prompt: PromptWire;
381
500
  }) | (AgentV2NodeBaseWire & {
382
501
  type: 'standard';
502
+ behavior: {
503
+ waitAfterExecuting: number;
504
+ vadMinSilenceDuration?: number;
505
+ waitAfterTransfer?: number;
506
+ };
383
507
  prompt: PromptWire;
384
508
  toolUuids: string[];
385
509
  toolUseSiteUuids?: string[];
386
510
  knowledgeBaseUuids: string[];
387
511
  customDataTableNames: string[];
388
- builtInTools: NodeBuiltInCapabilities;
512
+ builtInTools: NodeBuiltInCapabilities & {
513
+ transfer?: TransferCapability;
514
+ };
389
515
  sopSpec: SopSpec | null;
390
516
  overrides: {
391
517
  voice?: {
@@ -403,6 +529,7 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
403
529
  perTurnAction?: (ActionUseSiteWire & {
404
530
  trigger: 'every_turn';
405
531
  }) | null;
532
+ contactHistory?: ContactHistoryNodeOption | null;
406
533
  }) | (AgentV2NodeBaseWire & {
407
534
  type: 'http';
408
535
  url: string;
@@ -430,6 +557,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
430
557
  builtInTools: NodeBuiltInCapabilities;
431
558
  }) | (AgentV2NodeBaseWire & {
432
559
  type: 'extract';
560
+ /** Absent in commits written before the override existed, which means none. */
561
+ overrides?: {
562
+ llm?: LlmOverrideWire;
563
+ };
433
564
  fields: ExtractionField[];
434
565
  /**
435
566
  * A shared Schema to extract with instead of `fields`, which must then be
@@ -441,6 +572,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
441
572
  builtInTools: NodeBuiltInCapabilities;
442
573
  }) | (AgentV2NodeBaseWire & {
443
574
  type: 'say';
575
+ behavior: {
576
+ waitAfterExecuting: number;
577
+ waitAfterSay?: number;
578
+ };
444
579
  executionMessage: string | null;
445
580
  overrides: {
446
581
  voice?: {
@@ -475,6 +610,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
475
610
  builtInTools: NodeBuiltInCapabilities;
476
611
  }) | (AgentV2NodeBaseWire & {
477
612
  type: 'collect_credit_card';
613
+ behavior: {
614
+ waitAfterExecuting: number;
615
+ vadMinSilenceDuration?: number;
616
+ };
478
617
  instructions: string | null;
479
618
  /** When true the authored instructions replace the built-in collector prompt. */
480
619
  overrideCollectorPrompt?: boolean;
@@ -488,6 +627,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
488
627
  };
489
628
  }) | (AgentV2NodeBaseWire & {
490
629
  type: 'transfer';
630
+ behavior: {
631
+ waitAfterExecuting: number;
632
+ waitAfterTransfer?: number;
633
+ };
491
634
  executionMessage: string | null;
492
635
  builtInTools: NodeBuiltInCapabilities & {
493
636
  transfer: TransferCapability;
@@ -559,7 +702,8 @@ type NodeBaseDefinition = {
559
702
  edges?: EdgeDefinition[];
560
703
  alwaysAvailable?: AlwaysAvailableCapability;
561
704
  };
562
- export type GlobalNodeDefinition = NodeBaseDefinition & {
705
+ /** A global node has no capabilities, so it cannot be made always-available. */
706
+ export type GlobalNodeDefinition = Omit<NodeBaseDefinition, 'alwaysAvailable'> & {
563
707
  type: 'global';
564
708
  prompt: PromptReference;
565
709
  };
@@ -645,8 +789,16 @@ export type PromptNodeDefinition = NodeBaseDefinition & {
645
789
  perTurnExtraction?: ExtractionInput | null;
646
790
  perTurnRetrieval?: PerTurnRetrievalDefinition | null;
647
791
  perTurnAction?: ActionRunDefinition | null;
792
+ /** The parts of the caller's contact history this node adds to its prompt. Null adds none. */
793
+ contactHistory?: ContactHistoryNodeOption | null;
648
794
  transfer?: Pick<TransferCapability, 'enabled'> & Partial<Omit<TransferCapability, 'enabled'>>;
649
795
  };
796
+ /** Which parts of the caller's contact history a prompt node adds to its prompt. */
797
+ export type ContactHistoryNodeOption = {
798
+ summary: boolean;
799
+ facts: boolean;
800
+ entities: boolean;
801
+ };
650
802
  /** Authoring form of `PerTurnRetrievalWire`; omitted settings take the product defaults. */
651
803
  export type PerTurnRetrievalDefinition = {
652
804
  /** Defaults to true: supplying the object at all means you want retrieval on. */
@@ -699,6 +851,7 @@ export type ExtractNodeDefinition = NodeBaseDefinition & {
699
851
  */
700
852
  schema: ExtractionInput | RemoteReference;
701
853
  message?: string | null;
854
+ llmOverride?: LlmOverrideDefinition;
702
855
  };
703
856
  export type SayNodeDefinition = NodeBaseDefinition & {
704
857
  type: 'say';
@@ -792,6 +945,7 @@ export type TransferNodeDefinition = NodeBaseDefinition & {
792
945
  timeout?: TransferCapability['timeout'];
793
946
  description?: TransferCapability['description'];
794
947
  voicemailMessage?: TransferCapability['voicemailMessage'];
948
+ briefing?: TransferCapability['briefing'];
795
949
  waitAfterTransfer?: number;
796
950
  };
797
951
  export type TransferChatNodeDefinition = NodeBaseDefinition & {
@@ -894,6 +1048,16 @@ export type CartActionRef = {
894
1048
  perTurnAction: string;
895
1049
  } | {
896
1050
  beforeCallAction: true;
1051
+ } | {
1052
+ callEndAction: true;
1053
+ }
1054
+ /** An Agent Assist step that runs an Action, by the step's id. */
1055
+ | {
1056
+ assistStep: string;
1057
+ }
1058
+ /** An Agent Assist card button, by the button's id. */
1059
+ | {
1060
+ assistButton: string;
897
1061
  };
898
1062
  /**
899
1063
  * When the order counts as placed (checkout). Order ids come from an Action's outputs, so only an `action_succeeded`
@@ -937,13 +1101,61 @@ export type CartDefinition = {
937
1101
  }[];
938
1102
  checkout?: CartCheckoutDefinition | null;
939
1103
  };
1104
+ /**
1105
+ * Authoring form of `GuardrailAssignmentWire`: the guardrail by reference, and a
1106
+ * `transition` guardrail's destination by node key rather than node uuid.
1107
+ */
1108
+ export type GuardrailAssignmentDefinition = {
1109
+ guardrail: RemoteReference;
1110
+ version: number;
1111
+ mode: GuardrailMode;
1112
+ /** The key of the node a `transition` guardrail moves the call to; `null` for every other action. */
1113
+ node: string | null;
1114
+ };
1115
+ export type AssistProcedureStepDefinition = {
1116
+ id: string;
1117
+ kind: 'run_action';
1118
+ action: ActionRunDefinition;
1119
+ } | {
1120
+ id: string;
1121
+ kind: 'show_card';
1122
+ cardId: string;
1123
+ } | {
1124
+ id: string;
1125
+ kind: 'show_checklist';
1126
+ checklistId: string;
1127
+ };
1128
+ export type AssistProcedureDefinition = Omit<AssistProcedureWire, 'steps'> & {
1129
+ steps: AssistProcedureStepDefinition[];
1130
+ };
1131
+ export type AssistCardButtonDefinition = Omit<AssistCardButtonWire, 'action'> & {
1132
+ action: ActionRunDefinition;
1133
+ };
1134
+ export type AssistCardDefinition = Omit<AssistCardWire, 'buttons'> & {
1135
+ buttons: AssistCardButtonDefinition[];
1136
+ };
1137
+ /** A checklist's items are extraction fields, so they are authored the way extraction is. */
1138
+ export type AssistChecklistDefinition = Omit<AssistChecklistWire, 'items'> & {
1139
+ items: ExtractionInput;
1140
+ };
1141
+ /**
1142
+ * Authoring form of `AssistPlaybookConfigWire`. Procedures, cards, checklists
1143
+ * and their buttons keep the ids the playbook stores, since steps refer to cards
1144
+ * and checklists by them; the Actions they run are authored like any other
1145
+ * Action run.
1146
+ */
1147
+ export type AssistPlaybookDefinition = {
1148
+ procedures: AssistProcedureDefinition[];
1149
+ cards: AssistCardDefinition[];
1150
+ checklists: AssistChecklistDefinition[];
1151
+ };
940
1152
  export type AgentDefinition = {
941
1153
  kind: 'agent-definition';
942
1154
  key: string;
943
1155
  name: string;
944
1156
  description: string | null;
945
1157
  branch: string;
946
- modality: 'voice' | 'text';
1158
+ modality: AgentModality;
947
1159
  folderUuid: string | null;
948
1160
  analyzerUuids: string[];
949
1161
  tagUuids: string[];
@@ -1019,6 +1231,12 @@ export type AgentDefinition = {
1019
1231
  tools: RemoteReference[];
1020
1232
  knowledgeBases: RemoteReference[];
1021
1233
  beforeCallAction: ActionRunDefinition | null;
1234
+ /** The Action run once the call has ended, whoever ended it. */
1235
+ callEndAction: ActionRunDefinition | null;
1236
+ guardrails: GuardrailAssignmentDefinition[];
1237
+ nodeCheck: boolean;
1238
+ /** The playbook of an `assist` Agent; `null` for every other modality. */
1239
+ assist: AssistPlaybookDefinition | null;
1022
1240
  summaryPrompt: string | null;
1023
1241
  /**
1024
1242
  * A/B test groups on the Agent.
@@ -1043,7 +1261,7 @@ export type AgentDefinitionInput = {
1043
1261
  name: string;
1044
1262
  description?: string | null;
1045
1263
  branch: string;
1046
- modality?: 'voice' | 'text';
1264
+ modality?: AgentModality;
1047
1265
  folderUuid?: string | null;
1048
1266
  analyzerUuids?: string[];
1049
1267
  tagUuids?: string[];
@@ -1078,6 +1296,14 @@ export type AgentDefinitionInput = {
1078
1296
  tools?: RemoteReference[];
1079
1297
  knowledgeBases?: RemoteReference[];
1080
1298
  beforeCallAction?: ActionRunDefinition | null;
1299
+ callEndAction?: ActionRunDefinition | null;
1300
+ guardrails?: GuardrailAssignmentDefinition[];
1301
+ /**
1302
+ * Whether the background node check runs. Required: the product starts new Agents with it on, while source pulled
1303
+ * before this field existed means off, so no default fits both.
1304
+ */
1305
+ nodeCheck: boolean;
1306
+ assist?: AssistPlaybookDefinition | null;
1081
1307
  summaryPrompt?: string | null;
1082
1308
  abTestGroupIds?: string[] | null;
1083
1309
  actions?: CallableActionDefinition[] | null;
@@ -1099,7 +1325,7 @@ export type CompiledAgentProject = {
1099
1325
  key: string;
1100
1326
  name: string;
1101
1327
  description: string | null;
1102
- modality: 'voice' | 'text';
1328
+ modality: AgentModality;
1103
1329
  folderUuid: string | null;
1104
1330
  analyzerUuids: string[];
1105
1331
  tagUuids: string[];