@simple-ai-lab/sdk 0.12.0 → 0.14.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.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import type { ActionDefinition, ActionOutputParameterMappings, ActionOutputParameters, ActionRunDefinition, ActionVersionValues, BackgroundMessage, CallableActionDefinition, SourceFileReference } from "./actions.js";
2
+ import type { ActionDefinition, ActionInputLabel, ActionOutputParameterMappings, ActionOutputParameters, ActionRunDefinition, ActionVersionValues, BackgroundMessage, CallableActionDefinition, SourceFileReference } from "./actions.js";
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,108 @@ 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
+ /** The moment an Agent Assist procedure waits for, defined the way an edge is. */
332
+ export type AssistMomentTriggerWire = {
333
+ description: string;
334
+ condition: {
335
+ variable: string;
336
+ operator: ConditionOperator;
337
+ value: string;
338
+ } | null;
339
+ filter: TransitionFilterWire | null;
340
+ };
341
+ export type AssistProcedureHookWire = {
342
+ kind: 'call_start';
343
+ } | {
344
+ kind: 'moment';
345
+ trigger: AssistMomentTriggerWire;
346
+ } | {
347
+ kind: 'call_end';
348
+ };
349
+ export type AssistProcedureStepWire = {
350
+ id: string;
351
+ kind: 'run_action';
352
+ action: AssistActionUseSiteWire;
353
+ } | {
354
+ id: string;
355
+ kind: 'show_card';
356
+ cardId: string;
357
+ } | {
358
+ id: string;
359
+ kind: 'show_checklist';
360
+ checklistId: string;
361
+ };
362
+ export type AssistProcedureWire = {
363
+ id: string;
364
+ name: string;
365
+ hook: AssistProcedureHookWire;
366
+ steps: AssistProcedureStepWire[];
367
+ };
368
+ export type AssistCardButtonWire = {
369
+ id: string;
370
+ label: string;
371
+ action: AssistActionUseSiteWire;
372
+ };
373
+ export type AssistCardWire = {
374
+ id: string;
375
+ name: string;
376
+ title: string;
377
+ body: string;
378
+ buttons: AssistCardButtonWire[];
379
+ };
380
+ export type AssistChecklistWire = {
381
+ id: string;
382
+ name: string;
383
+ items: ExtractionField[];
384
+ };
385
+ /**
386
+ * An Agent Assist playbook's own configuration. Mirrors
387
+ * `assistPlaybookConfigSchema` in `@simple-ai-lab/shared`
388
+ * (`public/assist-playbook.ts`); present on every commit of an `assist` Agent
389
+ * and on no other.
390
+ */
391
+ export type AssistPlaybookConfigWire = {
392
+ procedures: AssistProcedureWire[];
393
+ cards: AssistCardWire[];
394
+ checklists: AssistChecklistWire[];
395
+ };
291
396
  export type AgentV2ConfigWire = {
292
397
  voice: {
293
398
  voiceUuid: string | null;
@@ -350,7 +455,7 @@ export type AgentV2ConfigWire = {
350
455
  beforeCallStart: (ActionUseSiteWire & {
351
456
  trigger: 'before_call_start';
352
457
  }) | null;
353
- /** Absent in commits written before the trigger existed. Source cannot author it yet; snapshots carry it. */
458
+ /** Absent in commits written before the trigger existed. */
354
459
  callEnd?: (ActionUseSiteWire & {
355
460
  trigger: 'call_end';
356
461
  }) | null;
@@ -359,6 +464,14 @@ export type AgentV2ConfigWire = {
359
464
  abTestGroupIds: string[];
360
465
  /** Absent in commits written before carts existed. */
361
466
  cart?: CartConfigWire | null;
467
+ /** Absent in commits written before guardrails existed, which means none. */
468
+ guardrails?: GuardrailAssignmentWire[];
469
+ /** The background check that moves the call to the node the conversation belongs on. Absent means off. */
470
+ nodeCheck?: {
471
+ enabled: boolean;
472
+ };
473
+ /** Present on every commit of an `assist` Agent and on no other. */
474
+ assist?: AssistPlaybookConfigWire;
362
475
  };
363
476
  type AgentV2NodeBaseWire = {
364
477
  uuid: string;
@@ -370,22 +483,27 @@ type AgentV2NodeBaseWire = {
370
483
  };
371
484
  behavior: {
372
485
  waitAfterExecuting: number;
373
- [key: string]: number | undefined;
374
486
  };
375
487
  edges: AgentV2EdgeWire[];
376
- builtInTools?: NodeBuiltInCapabilities;
377
488
  };
378
489
  export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
379
490
  type: 'global';
380
491
  prompt: PromptWire;
381
492
  }) | (AgentV2NodeBaseWire & {
382
493
  type: 'standard';
494
+ behavior: {
495
+ waitAfterExecuting: number;
496
+ vadMinSilenceDuration?: number;
497
+ waitAfterTransfer?: number;
498
+ };
383
499
  prompt: PromptWire;
384
500
  toolUuids: string[];
385
501
  toolUseSiteUuids?: string[];
386
502
  knowledgeBaseUuids: string[];
387
503
  customDataTableNames: string[];
388
- builtInTools: NodeBuiltInCapabilities;
504
+ builtInTools: NodeBuiltInCapabilities & {
505
+ transfer?: TransferCapability;
506
+ };
389
507
  sopSpec: SopSpec | null;
390
508
  overrides: {
391
509
  voice?: {
@@ -403,6 +521,7 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
403
521
  perTurnAction?: (ActionUseSiteWire & {
404
522
  trigger: 'every_turn';
405
523
  }) | null;
524
+ contactHistory?: ContactHistoryNodeOption | null;
406
525
  }) | (AgentV2NodeBaseWire & {
407
526
  type: 'http';
408
527
  url: string;
@@ -430,6 +549,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
430
549
  builtInTools: NodeBuiltInCapabilities;
431
550
  }) | (AgentV2NodeBaseWire & {
432
551
  type: 'extract';
552
+ /** Absent in commits written before the override existed, which means none. */
553
+ overrides?: {
554
+ llm?: LlmOverrideWire;
555
+ };
433
556
  fields: ExtractionField[];
434
557
  /**
435
558
  * A shared Schema to extract with instead of `fields`, which must then be
@@ -441,6 +564,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
441
564
  builtInTools: NodeBuiltInCapabilities;
442
565
  }) | (AgentV2NodeBaseWire & {
443
566
  type: 'say';
567
+ behavior: {
568
+ waitAfterExecuting: number;
569
+ waitAfterSay?: number;
570
+ };
444
571
  executionMessage: string | null;
445
572
  overrides: {
446
573
  voice?: {
@@ -475,6 +602,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
475
602
  builtInTools: NodeBuiltInCapabilities;
476
603
  }) | (AgentV2NodeBaseWire & {
477
604
  type: 'collect_credit_card';
605
+ behavior: {
606
+ waitAfterExecuting: number;
607
+ vadMinSilenceDuration?: number;
608
+ };
478
609
  instructions: string | null;
479
610
  /** When true the authored instructions replace the built-in collector prompt. */
480
611
  overrideCollectorPrompt?: boolean;
@@ -488,6 +619,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
488
619
  };
489
620
  }) | (AgentV2NodeBaseWire & {
490
621
  type: 'transfer';
622
+ behavior: {
623
+ waitAfterExecuting: number;
624
+ waitAfterTransfer?: number;
625
+ };
491
626
  executionMessage: string | null;
492
627
  builtInTools: NodeBuiltInCapabilities & {
493
628
  transfer: TransferCapability;
@@ -559,7 +694,8 @@ type NodeBaseDefinition = {
559
694
  edges?: EdgeDefinition[];
560
695
  alwaysAvailable?: AlwaysAvailableCapability;
561
696
  };
562
- export type GlobalNodeDefinition = NodeBaseDefinition & {
697
+ /** A global node has no capabilities, so it cannot be made always-available. */
698
+ export type GlobalNodeDefinition = Omit<NodeBaseDefinition, 'alwaysAvailable'> & {
563
699
  type: 'global';
564
700
  prompt: PromptReference;
565
701
  };
@@ -645,8 +781,16 @@ export type PromptNodeDefinition = NodeBaseDefinition & {
645
781
  perTurnExtraction?: ExtractionInput | null;
646
782
  perTurnRetrieval?: PerTurnRetrievalDefinition | null;
647
783
  perTurnAction?: ActionRunDefinition | null;
784
+ /** The parts of the caller's contact history this node adds to its prompt. Null adds none. */
785
+ contactHistory?: ContactHistoryNodeOption | null;
648
786
  transfer?: Pick<TransferCapability, 'enabled'> & Partial<Omit<TransferCapability, 'enabled'>>;
649
787
  };
788
+ /** Which parts of the caller's contact history a prompt node adds to its prompt. */
789
+ export type ContactHistoryNodeOption = {
790
+ summary: boolean;
791
+ facts: boolean;
792
+ entities: boolean;
793
+ };
650
794
  /** Authoring form of `PerTurnRetrievalWire`; omitted settings take the product defaults. */
651
795
  export type PerTurnRetrievalDefinition = {
652
796
  /** Defaults to true: supplying the object at all means you want retrieval on. */
@@ -699,6 +843,7 @@ export type ExtractNodeDefinition = NodeBaseDefinition & {
699
843
  */
700
844
  schema: ExtractionInput | RemoteReference;
701
845
  message?: string | null;
846
+ llmOverride?: LlmOverrideDefinition;
702
847
  };
703
848
  export type SayNodeDefinition = NodeBaseDefinition & {
704
849
  type: 'say';
@@ -792,6 +937,7 @@ export type TransferNodeDefinition = NodeBaseDefinition & {
792
937
  timeout?: TransferCapability['timeout'];
793
938
  description?: TransferCapability['description'];
794
939
  voicemailMessage?: TransferCapability['voicemailMessage'];
940
+ briefing?: TransferCapability['briefing'];
795
941
  waitAfterTransfer?: number;
796
942
  };
797
943
  export type TransferChatNodeDefinition = NodeBaseDefinition & {
@@ -894,6 +1040,16 @@ export type CartActionRef = {
894
1040
  perTurnAction: string;
895
1041
  } | {
896
1042
  beforeCallAction: true;
1043
+ } | {
1044
+ callEndAction: true;
1045
+ }
1046
+ /** An Agent Assist step that runs an Action, by the step's id. */
1047
+ | {
1048
+ assistStep: string;
1049
+ }
1050
+ /** An Agent Assist card button, by the button's id. */
1051
+ | {
1052
+ assistButton: string;
897
1053
  };
898
1054
  /**
899
1055
  * When the order counts as placed (checkout). Order ids come from an Action's outputs, so only an `action_succeeded`
@@ -937,13 +1093,61 @@ export type CartDefinition = {
937
1093
  }[];
938
1094
  checkout?: CartCheckoutDefinition | null;
939
1095
  };
1096
+ /**
1097
+ * Authoring form of `GuardrailAssignmentWire`: the guardrail by reference, and a
1098
+ * `transition` guardrail's destination by node key rather than node uuid.
1099
+ */
1100
+ export type GuardrailAssignmentDefinition = {
1101
+ guardrail: RemoteReference;
1102
+ version: number;
1103
+ mode: GuardrailMode;
1104
+ /** The key of the node a `transition` guardrail moves the call to; `null` for every other action. */
1105
+ node: string | null;
1106
+ };
1107
+ export type AssistProcedureStepDefinition = {
1108
+ id: string;
1109
+ kind: 'run_action';
1110
+ action: ActionRunDefinition;
1111
+ } | {
1112
+ id: string;
1113
+ kind: 'show_card';
1114
+ cardId: string;
1115
+ } | {
1116
+ id: string;
1117
+ kind: 'show_checklist';
1118
+ checklistId: string;
1119
+ };
1120
+ export type AssistProcedureDefinition = Omit<AssistProcedureWire, 'steps'> & {
1121
+ steps: AssistProcedureStepDefinition[];
1122
+ };
1123
+ export type AssistCardButtonDefinition = Omit<AssistCardButtonWire, 'action'> & {
1124
+ action: ActionRunDefinition;
1125
+ };
1126
+ export type AssistCardDefinition = Omit<AssistCardWire, 'buttons'> & {
1127
+ buttons: AssistCardButtonDefinition[];
1128
+ };
1129
+ /** A checklist's items are extraction fields, so they are authored the way extraction is. */
1130
+ export type AssistChecklistDefinition = Omit<AssistChecklistWire, 'items'> & {
1131
+ items: ExtractionInput;
1132
+ };
1133
+ /**
1134
+ * Authoring form of `AssistPlaybookConfigWire`. Procedures, cards, checklists
1135
+ * and their buttons keep the ids the playbook stores, since steps refer to cards
1136
+ * and checklists by them; the Actions they run are authored like any other
1137
+ * Action run.
1138
+ */
1139
+ export type AssistPlaybookDefinition = {
1140
+ procedures: AssistProcedureDefinition[];
1141
+ cards: AssistCardDefinition[];
1142
+ checklists: AssistChecklistDefinition[];
1143
+ };
940
1144
  export type AgentDefinition = {
941
1145
  kind: 'agent-definition';
942
1146
  key: string;
943
1147
  name: string;
944
1148
  description: string | null;
945
1149
  branch: string;
946
- modality: 'voice' | 'text';
1150
+ modality: AgentModality;
947
1151
  folderUuid: string | null;
948
1152
  analyzerUuids: string[];
949
1153
  tagUuids: string[];
@@ -1019,6 +1223,12 @@ export type AgentDefinition = {
1019
1223
  tools: RemoteReference[];
1020
1224
  knowledgeBases: RemoteReference[];
1021
1225
  beforeCallAction: ActionRunDefinition | null;
1226
+ /** The Action run once the call has ended, whoever ended it. */
1227
+ callEndAction: ActionRunDefinition | null;
1228
+ guardrails: GuardrailAssignmentDefinition[];
1229
+ nodeCheck: boolean;
1230
+ /** The playbook of an `assist` Agent; `null` for every other modality. */
1231
+ assist: AssistPlaybookDefinition | null;
1022
1232
  summaryPrompt: string | null;
1023
1233
  /**
1024
1234
  * A/B test groups on the Agent.
@@ -1043,7 +1253,7 @@ export type AgentDefinitionInput = {
1043
1253
  name: string;
1044
1254
  description?: string | null;
1045
1255
  branch: string;
1046
- modality?: 'voice' | 'text';
1256
+ modality?: AgentModality;
1047
1257
  folderUuid?: string | null;
1048
1258
  analyzerUuids?: string[];
1049
1259
  tagUuids?: string[];
@@ -1078,6 +1288,14 @@ export type AgentDefinitionInput = {
1078
1288
  tools?: RemoteReference[];
1079
1289
  knowledgeBases?: RemoteReference[];
1080
1290
  beforeCallAction?: ActionRunDefinition | null;
1291
+ callEndAction?: ActionRunDefinition | null;
1292
+ guardrails?: GuardrailAssignmentDefinition[];
1293
+ /**
1294
+ * Whether the background node check runs. Required: the product starts new Agents with it on, while source pulled
1295
+ * before this field existed means off, so no default fits both.
1296
+ */
1297
+ nodeCheck: boolean;
1298
+ assist?: AssistPlaybookDefinition | null;
1081
1299
  summaryPrompt?: string | null;
1082
1300
  abTestGroupIds?: string[] | null;
1083
1301
  actions?: CallableActionDefinition[] | null;
@@ -1099,7 +1317,7 @@ export type CompiledAgentProject = {
1099
1317
  key: string;
1100
1318
  name: string;
1101
1319
  description: string | null;
1102
- modality: 'voice' | 'text';
1320
+ modality: AgentModality;
1103
1321
  folderUuid: string | null;
1104
1322
  analyzerUuids: string[];
1105
1323
  tagUuids: string[];