@simple-ai-lab/sdk 0.11.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.
Files changed (42) hide show
  1. package/README.md +1 -0
  2. package/dist/actions.cjs +29 -0
  3. package/dist/actions.d.cts +35 -1
  4. package/dist/actions.d.ts +35 -1
  5. package/dist/actions.js +30 -1
  6. package/dist/agents.cjs +187 -15
  7. package/dist/agents.d.cts +231 -9
  8. package/dist/agents.d.ts +231 -9
  9. package/dist/agents.js +185 -14
  10. package/dist/built-in-actions.cjs +31 -2
  11. package/dist/built-in-actions.d.cts +27 -1
  12. package/dist/built-in-actions.d.ts +27 -1
  13. package/dist/built-in-actions.js +29 -1
  14. package/dist/client.cjs +4 -0
  15. package/dist/client.d.cts +3 -0
  16. package/dist/client.d.ts +3 -0
  17. package/dist/client.js +4 -0
  18. package/dist/code-action/define-action.cjs +2 -0
  19. package/dist/code-action/define-action.d.cts +17 -1
  20. package/dist/code-action/define-action.d.ts +17 -1
  21. package/dist/code-action/define-action.js +2 -0
  22. package/dist/code-action/index.d.cts +1 -1
  23. package/dist/code-action/index.d.ts +1 -1
  24. package/dist/code-action/types.d.cts +11 -0
  25. package/dist/code-action/types.d.ts +11 -0
  26. package/dist/index.cjs +11 -4
  27. package/dist/index.d.cts +7 -7
  28. package/dist/index.d.ts +7 -7
  29. package/dist/index.js +4 -4
  30. package/dist/oauth.cjs +18 -0
  31. package/dist/oauth.d.cts +9 -0
  32. package/dist/oauth.d.ts +9 -0
  33. package/dist/oauth.js +14 -0
  34. package/dist/projects.cjs +47 -121
  35. package/dist/projects.d.cts +5 -19
  36. package/dist/projects.d.ts +5 -19
  37. package/dist/projects.js +46 -119
  38. package/dist/schemas.cjs +27 -1
  39. package/dist/schemas.d.cts +20 -0
  40. package/dist/schemas.d.ts +20 -0
  41. package/dist/schemas.js +26 -0
  42. package/package.json +9 -9
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,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,11 +455,23 @@ export type AgentV2ConfigWire = {
350
455
  beforeCallStart: (ActionUseSiteWire & {
351
456
  trigger: 'before_call_start';
352
457
  }) | null;
458
+ /** Absent in commits written before the trigger existed. */
459
+ callEnd?: (ActionUseSiteWire & {
460
+ trigger: 'call_end';
461
+ }) | null;
353
462
  };
354
463
  knowledgeBaseIds: string[];
355
464
  abTestGroupIds: string[];
356
465
  /** Absent in commits written before carts existed. */
357
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;
358
475
  };
359
476
  type AgentV2NodeBaseWire = {
360
477
  uuid: string;
@@ -366,22 +483,27 @@ type AgentV2NodeBaseWire = {
366
483
  };
367
484
  behavior: {
368
485
  waitAfterExecuting: number;
369
- [key: string]: number | undefined;
370
486
  };
371
487
  edges: AgentV2EdgeWire[];
372
- builtInTools?: NodeBuiltInCapabilities;
373
488
  };
374
489
  export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
375
490
  type: 'global';
376
491
  prompt: PromptWire;
377
492
  }) | (AgentV2NodeBaseWire & {
378
493
  type: 'standard';
494
+ behavior: {
495
+ waitAfterExecuting: number;
496
+ vadMinSilenceDuration?: number;
497
+ waitAfterTransfer?: number;
498
+ };
379
499
  prompt: PromptWire;
380
500
  toolUuids: string[];
381
501
  toolUseSiteUuids?: string[];
382
502
  knowledgeBaseUuids: string[];
383
503
  customDataTableNames: string[];
384
- builtInTools: NodeBuiltInCapabilities;
504
+ builtInTools: NodeBuiltInCapabilities & {
505
+ transfer?: TransferCapability;
506
+ };
385
507
  sopSpec: SopSpec | null;
386
508
  overrides: {
387
509
  voice?: {
@@ -399,6 +521,7 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
399
521
  perTurnAction?: (ActionUseSiteWire & {
400
522
  trigger: 'every_turn';
401
523
  }) | null;
524
+ contactHistory?: ContactHistoryNodeOption | null;
402
525
  }) | (AgentV2NodeBaseWire & {
403
526
  type: 'http';
404
527
  url: string;
@@ -426,6 +549,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
426
549
  builtInTools: NodeBuiltInCapabilities;
427
550
  }) | (AgentV2NodeBaseWire & {
428
551
  type: 'extract';
552
+ /** Absent in commits written before the override existed, which means none. */
553
+ overrides?: {
554
+ llm?: LlmOverrideWire;
555
+ };
429
556
  fields: ExtractionField[];
430
557
  /**
431
558
  * A shared Schema to extract with instead of `fields`, which must then be
@@ -437,6 +564,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
437
564
  builtInTools: NodeBuiltInCapabilities;
438
565
  }) | (AgentV2NodeBaseWire & {
439
566
  type: 'say';
567
+ behavior: {
568
+ waitAfterExecuting: number;
569
+ waitAfterSay?: number;
570
+ };
440
571
  executionMessage: string | null;
441
572
  overrides: {
442
573
  voice?: {
@@ -471,6 +602,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
471
602
  builtInTools: NodeBuiltInCapabilities;
472
603
  }) | (AgentV2NodeBaseWire & {
473
604
  type: 'collect_credit_card';
605
+ behavior: {
606
+ waitAfterExecuting: number;
607
+ vadMinSilenceDuration?: number;
608
+ };
474
609
  instructions: string | null;
475
610
  /** When true the authored instructions replace the built-in collector prompt. */
476
611
  overrideCollectorPrompt?: boolean;
@@ -484,6 +619,10 @@ export type AgentV2NodeWire = (AgentV2NodeBaseWire & {
484
619
  };
485
620
  }) | (AgentV2NodeBaseWire & {
486
621
  type: 'transfer';
622
+ behavior: {
623
+ waitAfterExecuting: number;
624
+ waitAfterTransfer?: number;
625
+ };
487
626
  executionMessage: string | null;
488
627
  builtInTools: NodeBuiltInCapabilities & {
489
628
  transfer: TransferCapability;
@@ -555,7 +694,8 @@ type NodeBaseDefinition = {
555
694
  edges?: EdgeDefinition[];
556
695
  alwaysAvailable?: AlwaysAvailableCapability;
557
696
  };
558
- 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'> & {
559
699
  type: 'global';
560
700
  prompt: PromptReference;
561
701
  };
@@ -641,8 +781,16 @@ export type PromptNodeDefinition = NodeBaseDefinition & {
641
781
  perTurnExtraction?: ExtractionInput | null;
642
782
  perTurnRetrieval?: PerTurnRetrievalDefinition | null;
643
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;
644
786
  transfer?: Pick<TransferCapability, 'enabled'> & Partial<Omit<TransferCapability, 'enabled'>>;
645
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
+ };
646
794
  /** Authoring form of `PerTurnRetrievalWire`; omitted settings take the product defaults. */
647
795
  export type PerTurnRetrievalDefinition = {
648
796
  /** Defaults to true: supplying the object at all means you want retrieval on. */
@@ -695,6 +843,7 @@ export type ExtractNodeDefinition = NodeBaseDefinition & {
695
843
  */
696
844
  schema: ExtractionInput | RemoteReference;
697
845
  message?: string | null;
846
+ llmOverride?: LlmOverrideDefinition;
698
847
  };
699
848
  export type SayNodeDefinition = NodeBaseDefinition & {
700
849
  type: 'say';
@@ -788,6 +937,7 @@ export type TransferNodeDefinition = NodeBaseDefinition & {
788
937
  timeout?: TransferCapability['timeout'];
789
938
  description?: TransferCapability['description'];
790
939
  voicemailMessage?: TransferCapability['voicemailMessage'];
940
+ briefing?: TransferCapability['briefing'];
791
941
  waitAfterTransfer?: number;
792
942
  };
793
943
  export type TransferChatNodeDefinition = NodeBaseDefinition & {
@@ -890,6 +1040,16 @@ export type CartActionRef = {
890
1040
  perTurnAction: string;
891
1041
  } | {
892
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;
893
1053
  };
894
1054
  /**
895
1055
  * When the order counts as placed (checkout). Order ids come from an Action's outputs, so only an `action_succeeded`
@@ -933,13 +1093,61 @@ export type CartDefinition = {
933
1093
  }[];
934
1094
  checkout?: CartCheckoutDefinition | null;
935
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
+ };
936
1144
  export type AgentDefinition = {
937
1145
  kind: 'agent-definition';
938
1146
  key: string;
939
1147
  name: string;
940
1148
  description: string | null;
941
1149
  branch: string;
942
- modality: 'voice' | 'text';
1150
+ modality: AgentModality;
943
1151
  folderUuid: string | null;
944
1152
  analyzerUuids: string[];
945
1153
  tagUuids: string[];
@@ -1015,6 +1223,12 @@ export type AgentDefinition = {
1015
1223
  tools: RemoteReference[];
1016
1224
  knowledgeBases: RemoteReference[];
1017
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;
1018
1232
  summaryPrompt: string | null;
1019
1233
  /**
1020
1234
  * A/B test groups on the Agent.
@@ -1039,7 +1253,7 @@ export type AgentDefinitionInput = {
1039
1253
  name: string;
1040
1254
  description?: string | null;
1041
1255
  branch: string;
1042
- modality?: 'voice' | 'text';
1256
+ modality?: AgentModality;
1043
1257
  folderUuid?: string | null;
1044
1258
  analyzerUuids?: string[];
1045
1259
  tagUuids?: string[];
@@ -1074,6 +1288,14 @@ export type AgentDefinitionInput = {
1074
1288
  tools?: RemoteReference[];
1075
1289
  knowledgeBases?: RemoteReference[];
1076
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;
1077
1299
  summaryPrompt?: string | null;
1078
1300
  abTestGroupIds?: string[] | null;
1079
1301
  actions?: CallableActionDefinition[] | null;
@@ -1095,7 +1317,7 @@ export type CompiledAgentProject = {
1095
1317
  key: string;
1096
1318
  name: string;
1097
1319
  description: string | null;
1098
- modality: 'voice' | 'text';
1320
+ modality: AgentModality;
1099
1321
  folderUuid: string | null;
1100
1322
  analyzerUuids: string[];
1101
1323
  tagUuids: string[];