@simple-ai-lab/sdk 0.6.0 → 0.9.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/README.md CHANGED
@@ -63,6 +63,31 @@ export default defineAction(async ({ metadata, workflow }) => {
63
63
  });
64
64
  ```
65
65
 
66
+ ### Calling an LLM
67
+
68
+ `llm.infer` sends an [OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create) request through Simple AI's LLM router, so the action needs no LLM provider key of its own. `model` is a router ladder slug, not a vendor model ID; ask Simple AI support which slugs to use. Requests are never streamed, and the response comes back with its `output` typed:
69
+
70
+ ```typescript
71
+ import { defineAction } from '@simple-ai-lab/sdk';
72
+
73
+ export default defineAction(async ({ inputs, llm }) => {
74
+ const response = await llm.infer({
75
+ model: '<router ladder slug>',
76
+ instructions: 'Summarize the caller notes in one sentence.',
77
+ input: inputs.notes,
78
+ });
79
+ const summary = response.output
80
+ .flatMap((item) => item.content ?? [])
81
+ .filter((part) => part.type === 'output_text')
82
+ .map((part) => part.text)
83
+ .join('');
84
+
85
+ return { summary };
86
+ });
87
+ ```
88
+
89
+ Router refusals throw `SimpleAIError` with the router's `status`, `code`, and message. LLM calls are available in code actions during conversations, automatic before/after-call actions, data sync, and editor test runs. Authentication is provided automatically.
90
+
66
91
  ## In your own application
67
92
 
68
93
  ```typescript
package/dist/actions.cjs CHANGED
@@ -18,7 +18,13 @@ function resolveActionHttpHeaders(headers) {
18
18
  : Object.entries(headers).map(([name, valueTemplate]) => ({ name, valueTemplate }));
19
19
  }
20
20
  function resolveActionIoSchema(schema) {
21
- return schema instanceof zod_1.z.ZodType ? actionsIoSchemaFromZod(schema) : schema;
21
+ if (schema instanceof zod_1.z.ZodType) {
22
+ return actionsIoSchemaFromZod(schema);
23
+ }
24
+ if ('_zod' in schema || '_def' in schema) {
25
+ throw new Error('Action input and output schemas must be Zod 4 objects or JSON Schema objects');
26
+ }
27
+ return schema;
22
28
  }
23
29
  function isRecord(value) {
24
30
  return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -406,6 +412,14 @@ exports.action = {
406
412
  operation: { type: 'validate_address' },
407
413
  });
408
414
  },
415
+ /** Searches the web and returns the passages of each page most relevant to the question. */
416
+ webSearch(config) {
417
+ const { allowedDomains = [], blockedDomains = [] } = config;
418
+ return compileBuiltInAction({
419
+ config,
420
+ operation: { type: 'web_search', allowedDomains, blockedDomains },
421
+ });
422
+ },
409
423
  ref(config) {
410
424
  return {
411
425
  kind: 'reference',
@@ -291,6 +291,16 @@ type SendTextMessageActionConfig = BuiltInActionConfig & {
291
291
  senderPhoneNumberUuid: string;
292
292
  };
293
293
  type ValidateAddressActionConfig = BuiltInActionConfig;
294
+ type WebSearchActionConfig = BuiltInActionConfig & {
295
+ /**
296
+ * Only search these sites. Empty or omitted searches the open web. Each entry is a
297
+ * lowercase domain (`example.com`), a section of a site (`example.com/help`), or an
298
+ * ending (`.gov`).
299
+ */
300
+ allowedDomains?: string[];
301
+ /** Never search these sites. Only applies to the open web, so it can't be combined with `allowedDomains`. */
302
+ blockedDomains?: string[];
303
+ };
294
304
  export type ActionCompileOptions = {
295
305
  readSourceFile?: (path: string) => string;
296
306
  };
@@ -319,6 +329,8 @@ export declare const action: {
319
329
  sendTextMessage(config: SendTextMessageActionConfig): InlineActionDefinition;
320
330
  /** Validates and standardizes a postal address. */
321
331
  validateAddress(config: ValidateAddressActionConfig): InlineActionDefinition;
332
+ /** Searches the web and returns the passages of each page most relevant to the question. */
333
+ webSearch(config: WebSearchActionConfig): InlineActionDefinition;
322
334
  ref(config: {
323
335
  key: string;
324
336
  versionUuid: string;
package/dist/actions.d.ts CHANGED
@@ -291,6 +291,16 @@ type SendTextMessageActionConfig = BuiltInActionConfig & {
291
291
  senderPhoneNumberUuid: string;
292
292
  };
293
293
  type ValidateAddressActionConfig = BuiltInActionConfig;
294
+ type WebSearchActionConfig = BuiltInActionConfig & {
295
+ /**
296
+ * Only search these sites. Empty or omitted searches the open web. Each entry is a
297
+ * lowercase domain (`example.com`), a section of a site (`example.com/help`), or an
298
+ * ending (`.gov`).
299
+ */
300
+ allowedDomains?: string[];
301
+ /** Never search these sites. Only applies to the open web, so it can't be combined with `allowedDomains`. */
302
+ blockedDomains?: string[];
303
+ };
294
304
  export type ActionCompileOptions = {
295
305
  readSourceFile?: (path: string) => string;
296
306
  };
@@ -319,6 +329,8 @@ export declare const action: {
319
329
  sendTextMessage(config: SendTextMessageActionConfig): InlineActionDefinition;
320
330
  /** Validates and standardizes a postal address. */
321
331
  validateAddress(config: ValidateAddressActionConfig): InlineActionDefinition;
332
+ /** Searches the web and returns the passages of each page most relevant to the question. */
333
+ webSearch(config: WebSearchActionConfig): InlineActionDefinition;
322
334
  ref(config: {
323
335
  key: string;
324
336
  versionUuid: string;
package/dist/actions.js CHANGED
@@ -9,7 +9,13 @@ export function resolveActionHttpHeaders(headers) {
9
9
  : Object.entries(headers).map(([name, valueTemplate]) => ({ name, valueTemplate }));
10
10
  }
11
11
  export function resolveActionIoSchema(schema) {
12
- return schema instanceof z.ZodType ? actionsIoSchemaFromZod(schema) : schema;
12
+ if (schema instanceof z.ZodType) {
13
+ return actionsIoSchemaFromZod(schema);
14
+ }
15
+ if ('_zod' in schema || '_def' in schema) {
16
+ throw new Error('Action input and output schemas must be Zod 4 objects or JSON Schema objects');
17
+ }
18
+ return schema;
13
19
  }
14
20
  function isRecord(value) {
15
21
  return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -397,6 +403,14 @@ export const action = {
397
403
  operation: { type: 'validate_address' },
398
404
  });
399
405
  },
406
+ /** Searches the web and returns the passages of each page most relevant to the question. */
407
+ webSearch(config) {
408
+ const { allowedDomains = [], blockedDomains = [] } = config;
409
+ return compileBuiltInAction({
410
+ config,
411
+ operation: { type: 'web_search', allowedDomains, blockedDomains },
412
+ });
413
+ },
400
414
  ref(config) {
401
415
  return {
402
416
  kind: 'reference',
package/dist/agents.cjs CHANGED
@@ -118,6 +118,7 @@ function defineAgent(input) {
118
118
  pronunciations: input.speech?.pronunciations ?? [],
119
119
  },
120
120
  ...(input.toneGuidelines === undefined ? {} : { toneGuidelines: input.toneGuidelines }),
121
+ ...(input.cart === undefined ? {} : { cart: input.cart }),
121
122
  call: {
122
123
  agentSpeaksFirst: input.call?.agentSpeaksFirst ?? false,
123
124
  firstSentence: input.call?.firstSentence ?? null,
@@ -332,7 +333,13 @@ function extractionFieldFromJsonSchema({ name, value, required, path, }) {
332
333
  };
333
334
  }
334
335
  function resolveExtractionFields(schema) {
335
- return Array.isArray(schema) ? schema : extractionFieldsFromZod(schema);
336
+ if (Array.isArray(schema)) {
337
+ return schema;
338
+ }
339
+ if (schema instanceof zod_1.z.ZodType) {
340
+ return extractionFieldsFromZod(schema);
341
+ }
342
+ throw new Error('Extraction schemas must be Zod 4 objects or ExtractionField arrays');
336
343
  }
337
344
  function extractionFieldsFromZod(schema) {
338
345
  const jsonSchema = zod_1.z.toJSONSchema(schema);
@@ -901,6 +908,110 @@ function compileNode({ definition, canonicalNodeKey, canonicalCallableKeys, inde
901
908
  };
902
909
  }
903
910
  }
911
+ function describeCartActionRef(ref) {
912
+ if ('callable' in ref)
913
+ return `callable Action "${ref.callable}"`;
914
+ if ('actionNode' in ref)
915
+ return `Action node "${ref.actionNode}"`;
916
+ if ('perTurnAction' in ref)
917
+ return `the per-turn Action on node "${ref.perTurnAction}"`;
918
+ return 'the before-call Action';
919
+ }
920
+ /**
921
+ * Resolves the cart's authoring keys to the uuids the compiled commit uses. A reference to
922
+ * something the Agent doesn't have fails here, rather than at publish.
923
+ */
924
+ function compileCart({ cart, callables, toolUseSites, definitionNodes, nodes, beforeCallStart, }) {
925
+ const nodeAt = (key) => {
926
+ const index = definitionNodes.findIndex((definitionNode) => definitionNode.key === key);
927
+ return index === -1 ? null : { definition: definitionNodes[index], wire: nodes[index] };
928
+ };
929
+ const resolveAction = (ref) => {
930
+ let uuid;
931
+ if ('callable' in ref) {
932
+ const index = callables.findIndex((callable) => callable.key === ref.callable);
933
+ uuid = index === -1 ? undefined : toolUseSites[index]?.actionUseSiteUuid;
934
+ }
935
+ else if ('actionNode' in ref) {
936
+ const found = nodeAt(ref.actionNode);
937
+ uuid = found?.definition?.type === 'action' ? found.wire?.uuid : undefined;
938
+ }
939
+ else if ('perTurnAction' in ref) {
940
+ const wire = nodeAt(ref.perTurnAction)?.wire;
941
+ uuid =
942
+ wire !== undefined && 'perTurnAction' in wire
943
+ ? (wire.perTurnAction?.actionUseSiteUuid ?? undefined)
944
+ : undefined;
945
+ }
946
+ else {
947
+ uuid = beforeCallStart?.actionUseSiteUuid;
948
+ }
949
+ if (uuid === undefined) {
950
+ throw new Error(`The cart refers to ${describeCartActionRef(ref)}, which this Agent does not have`);
951
+ }
952
+ return uuid;
953
+ };
954
+ const checkout = compileCartCheckout({ checkout: cart.checkout ?? null, resolveAction, nodeAt });
955
+ return {
956
+ parameter: cart.parameter,
957
+ view: cart.view,
958
+ reasonArgument: cart.reasonArgument ?? null,
959
+ actions: (cart.actions ?? []).map((entry) => ({
960
+ actionUseSiteUuid: resolveAction(entry.action),
961
+ label: entry.label,
962
+ })),
963
+ checkout,
964
+ };
965
+ }
966
+ function compileCartCheckout({ checkout, resolveAction, nodeAt, }) {
967
+ if (checkout === null) {
968
+ return null;
969
+ }
970
+ switch (checkout.when.kind) {
971
+ case 'action_succeeded': {
972
+ if (checkout.when.actions.length === 0) {
973
+ throw new Error('The cart checkout needs at least one Action');
974
+ }
975
+ return {
976
+ when: { kind: 'action_succeeded', actionUseSiteUuids: checkout.when.actions.map(resolveAction) },
977
+ orderIds: checkout.orderIds ?? null,
978
+ };
979
+ }
980
+ case 'node_reached': {
981
+ if (checkout.when.nodes.length === 0) {
982
+ throw new Error('The cart checkout needs at least one node');
983
+ }
984
+ assertNoCheckoutOrderIds(checkout);
985
+ return {
986
+ when: {
987
+ kind: 'node_reached',
988
+ nodeUuids: checkout.when.nodes.map((key) => {
989
+ const uuid = nodeAt(key)?.wire?.uuid;
990
+ if (uuid === undefined) {
991
+ throw new Error(`The cart checkout refers to node "${key}", which this Agent does not have`);
992
+ }
993
+ return uuid;
994
+ }),
995
+ },
996
+ orderIds: null,
997
+ };
998
+ }
999
+ case 'parameter_equals': {
1000
+ assertNoCheckoutOrderIds(checkout);
1001
+ return { when: checkout.when, orderIds: null };
1002
+ }
1003
+ default: {
1004
+ checkout.when;
1005
+ throw new Error('Unhandled cart checkout rule');
1006
+ }
1007
+ }
1008
+ }
1009
+ /** Plain JavaScript callers aren't held to the types; order ids only come from an Action's outputs. */
1010
+ function assertNoCheckoutOrderIds(checkout) {
1011
+ if (checkout.orderIds != null) {
1012
+ throw new Error(`Only an action_succeeded cart checkout can name order ids, not ${checkout.when.kind}`);
1013
+ }
1014
+ }
904
1015
  function validateDefinition(definition) {
905
1016
  const keys = definition.nodes.map((definitionNode) => definitionNode.key);
906
1017
  if (new Set(keys).size !== keys.length) {
@@ -957,6 +1068,32 @@ function compileAgent(definition, options = {}) {
957
1068
  const abTestGroupIds = [
958
1069
  ...new Set(definition.nodes.flatMap((definitionNode) => definitionNode.type === 'ab-test' ? [definitionNode.abTestGroupUuid] : [])),
959
1070
  ];
1071
+ const compiledNodes = definition.nodes.map((definitionNode, index) => compileNode({
1072
+ definition: definitionNode,
1073
+ canonicalNodeKey: canonicalNodeKeysByDefinitionKey.get(definitionNode.key) ?? definitionNode.key,
1074
+ canonicalCallableKeys: canonicalCallableKeysByDefinitionKey,
1075
+ index,
1076
+ nodeUuids,
1077
+ options,
1078
+ }));
1079
+ const beforeCallStart = definition.beforeCallAction === null
1080
+ ? null
1081
+ : compileActionRun({
1082
+ run: definition.beforeCallAction,
1083
+ trigger: 'before_call_start',
1084
+ canonicalKey: 'before-call-start',
1085
+ options,
1086
+ });
1087
+ const cart = definition.cart === undefined || definition.cart === null
1088
+ ? definition.cart
1089
+ : compileCart({
1090
+ cart: definition.cart,
1091
+ callables,
1092
+ toolUseSites,
1093
+ definitionNodes: definition.nodes,
1094
+ nodes: compiledNodes,
1095
+ beforeCallStart,
1096
+ });
960
1097
  return {
961
1098
  agent: {
962
1099
  key: definition.key,
@@ -1027,27 +1164,12 @@ function compileAgent(definition, options = {}) {
1027
1164
  definition.nodes.some((definitionNode) => nodeCarriesCallableActions(definitionNode) && definitionNode.actions !== undefined)
1028
1165
  ? { toolUseSites }
1029
1166
  : {}),
1030
- automaticActions: {
1031
- beforeCallStart: definition.beforeCallAction === null
1032
- ? null
1033
- : compileActionRun({
1034
- run: definition.beforeCallAction,
1035
- trigger: 'before_call_start',
1036
- canonicalKey: 'before-call-start',
1037
- options,
1038
- }),
1039
- },
1167
+ automaticActions: { beforeCallStart },
1040
1168
  knowledgeBaseIds: definition.knowledgeBases.map((item) => item.uuid),
1041
1169
  abTestGroupIds: definition.abTestGroupIds ?? abTestGroupIds,
1170
+ ...(cart === undefined ? {} : { cart }),
1042
1171
  },
1043
- nodes: definition.nodes.map((definitionNode, index) => compileNode({
1044
- definition: definitionNode,
1045
- canonicalNodeKey: canonicalNodeKeysByDefinitionKey.get(definitionNode.key) ?? definitionNode.key,
1046
- canonicalCallableKeys: canonicalCallableKeysByDefinitionKey,
1047
- index,
1048
- nodeUuids,
1049
- options,
1050
- })),
1172
+ nodes: compiledNodes,
1051
1173
  summaryPrompt: definition.summaryPrompt,
1052
1174
  },
1053
1175
  };
package/dist/agents.d.cts CHANGED
@@ -215,6 +215,67 @@ export type ToolUseSiteWire = ActionUseSiteWire & {
215
215
  */
216
216
  backgroundMessage?: BackgroundMessage | null;
217
217
  };
218
+ /** A JSON Pointer into a cart value; the empty pointer means the value itself. */
219
+ export type CartPointer = string;
220
+ export type CartSummaryLineWire = {
221
+ key: string;
222
+ label: string;
223
+ amount: CartPointer;
224
+ };
225
+ /** Where things are inside the cart parameter. Mirrors server-v2's `cartViewMappingSchema`. */
226
+ export type CartViewWire = {
227
+ currency: string;
228
+ amountUnit: 'dollars' | 'cents';
229
+ sections: {
230
+ from: CartPointer | null;
231
+ title: CartPointer | null;
232
+ rows: {
233
+ from: CartPointer;
234
+ key: CartPointer;
235
+ label: CartPointer;
236
+ quantity: CartPointer | null;
237
+ amount: CartPointer | null;
238
+ unitPrice: CartPointer | null;
239
+ detail: CartPointer | null;
240
+ children: {
241
+ from: CartPointer;
242
+ label: CartPointer;
243
+ quantity: CartPointer | null;
244
+ } | null;
245
+ };
246
+ summary: CartSummaryLineWire[];
247
+ };
248
+ summary: CartSummaryLineWire[];
249
+ totalKey: string | null;
250
+ };
251
+ export type CartCheckoutWhenWire = {
252
+ kind: 'action_succeeded';
253
+ actionUseSiteUuids: string[];
254
+ } | {
255
+ kind: 'node_reached';
256
+ nodeUuids: string[];
257
+ } | {
258
+ kind: 'parameter_equals';
259
+ parameter: string;
260
+ value: string | number | boolean | null;
261
+ };
262
+ /** Mirrors server-v2's `cartConfigSchema`. */
263
+ export type CartConfigWire = {
264
+ parameter: string;
265
+ view: CartViewWire;
266
+ reasonArgument: string | null;
267
+ actions: {
268
+ actionUseSiteUuid: string;
269
+ label: string;
270
+ }[];
271
+ checkout: {
272
+ when: CartCheckoutWhenWire;
273
+ orderIds: {
274
+ from: CartPointer | null;
275
+ id: CartPointer;
276
+ } | null;
277
+ } | null;
278
+ };
218
279
  export type AgentV2ConfigWire = {
219
280
  voice: {
220
281
  voiceUuid: string | null;
@@ -279,6 +340,8 @@ export type AgentV2ConfigWire = {
279
340
  };
280
341
  knowledgeBaseIds: string[];
281
342
  abTestGroupIds: string[];
343
+ /** Absent in commits written before carts existed. */
344
+ cart?: CartConfigWire | null;
282
345
  };
283
346
  type AgentV2NodeBaseWire = {
284
347
  uuid: string;
@@ -803,6 +866,62 @@ export type ContainmentConfig = {
803
866
  contained: ContainedRuleSet;
804
867
  };
805
868
  export declare const MAX_CONTAINMENT_RULE_DEPTH = 5;
869
+ /**
870
+ * An Action that changes the cart, named by what the author wrote rather than by uuid:
871
+ * a callable Action's key, an Action node's key, the per-turn Action on a node, or the
872
+ * before-call Action.
873
+ */
874
+ export type CartActionRef = {
875
+ callable: string;
876
+ } | {
877
+ actionNode: string;
878
+ } | {
879
+ perTurnAction: string;
880
+ } | {
881
+ beforeCallAction: true;
882
+ };
883
+ /**
884
+ * When the order counts as placed (checkout). Order ids come from an Action's outputs, so only an `action_succeeded`
885
+ * rule can name them, and each rule names at least one Action or node.
886
+ */
887
+ export type CartCheckoutDefinition = {
888
+ when: {
889
+ kind: 'action_succeeded';
890
+ actions: [CartActionRef, ...CartActionRef[]];
891
+ };
892
+ /** Where the order ids are in the Action's outputs. */
893
+ orderIds?: {
894
+ from: CartPointer | null;
895
+ id: CartPointer;
896
+ } | null;
897
+ } | {
898
+ when: {
899
+ kind: 'node_reached';
900
+ nodes: [string, ...string[]];
901
+ };
902
+ orderIds?: null;
903
+ } | {
904
+ when: {
905
+ kind: 'parameter_equals';
906
+ parameter: string;
907
+ value: string | number | boolean | null;
908
+ };
909
+ orderIds?: null;
910
+ };
911
+ /**
912
+ * Where the Agent keeps its cart and how the call page shows it. Configuration only: nothing in
913
+ * the graph or prompts changes. Node and Action references use authoring keys.
914
+ */
915
+ export type CartDefinition = {
916
+ parameter: string;
917
+ view: CartViewWire;
918
+ reasonArgument?: string | null;
919
+ actions?: {
920
+ action: CartActionRef;
921
+ label: string;
922
+ }[];
923
+ checkout?: CartCheckoutDefinition | null;
924
+ };
806
925
  export type AgentDefinition = {
807
926
  kind: 'agent-definition';
808
927
  key: string;
@@ -835,6 +954,8 @@ export type AgentDefinition = {
835
954
  * the key out of the commit, `null` writes an explicit null, a string writes it.
836
955
  */
837
956
  toneGuidelines?: string | null;
957
+ /** Three states like `toneGuidelines`: absent keeps the key out of the commit. */
958
+ cart?: CartDefinition | null;
838
959
  call: {
839
960
  agentSpeaksFirst: boolean;
840
961
  firstSentence: string | null;
@@ -924,6 +1045,7 @@ export type AgentDefinitionInput = {
924
1045
  pronunciations?: Pronunciation[];
925
1046
  };
926
1047
  toneGuidelines?: string | null;
1048
+ cart?: CartDefinition | null;
927
1049
  call?: Partial<Omit<AgentDefinition['call'], 'checkInAfterSilence'>> & {
928
1050
  checkInAfterSilence?: CheckInAfterSilenceInput;
929
1051
  };
package/dist/agents.d.ts CHANGED
@@ -215,6 +215,67 @@ export type ToolUseSiteWire = ActionUseSiteWire & {
215
215
  */
216
216
  backgroundMessage?: BackgroundMessage | null;
217
217
  };
218
+ /** A JSON Pointer into a cart value; the empty pointer means the value itself. */
219
+ export type CartPointer = string;
220
+ export type CartSummaryLineWire = {
221
+ key: string;
222
+ label: string;
223
+ amount: CartPointer;
224
+ };
225
+ /** Where things are inside the cart parameter. Mirrors server-v2's `cartViewMappingSchema`. */
226
+ export type CartViewWire = {
227
+ currency: string;
228
+ amountUnit: 'dollars' | 'cents';
229
+ sections: {
230
+ from: CartPointer | null;
231
+ title: CartPointer | null;
232
+ rows: {
233
+ from: CartPointer;
234
+ key: CartPointer;
235
+ label: CartPointer;
236
+ quantity: CartPointer | null;
237
+ amount: CartPointer | null;
238
+ unitPrice: CartPointer | null;
239
+ detail: CartPointer | null;
240
+ children: {
241
+ from: CartPointer;
242
+ label: CartPointer;
243
+ quantity: CartPointer | null;
244
+ } | null;
245
+ };
246
+ summary: CartSummaryLineWire[];
247
+ };
248
+ summary: CartSummaryLineWire[];
249
+ totalKey: string | null;
250
+ };
251
+ export type CartCheckoutWhenWire = {
252
+ kind: 'action_succeeded';
253
+ actionUseSiteUuids: string[];
254
+ } | {
255
+ kind: 'node_reached';
256
+ nodeUuids: string[];
257
+ } | {
258
+ kind: 'parameter_equals';
259
+ parameter: string;
260
+ value: string | number | boolean | null;
261
+ };
262
+ /** Mirrors server-v2's `cartConfigSchema`. */
263
+ export type CartConfigWire = {
264
+ parameter: string;
265
+ view: CartViewWire;
266
+ reasonArgument: string | null;
267
+ actions: {
268
+ actionUseSiteUuid: string;
269
+ label: string;
270
+ }[];
271
+ checkout: {
272
+ when: CartCheckoutWhenWire;
273
+ orderIds: {
274
+ from: CartPointer | null;
275
+ id: CartPointer;
276
+ } | null;
277
+ } | null;
278
+ };
218
279
  export type AgentV2ConfigWire = {
219
280
  voice: {
220
281
  voiceUuid: string | null;
@@ -279,6 +340,8 @@ export type AgentV2ConfigWire = {
279
340
  };
280
341
  knowledgeBaseIds: string[];
281
342
  abTestGroupIds: string[];
343
+ /** Absent in commits written before carts existed. */
344
+ cart?: CartConfigWire | null;
282
345
  };
283
346
  type AgentV2NodeBaseWire = {
284
347
  uuid: string;
@@ -803,6 +866,62 @@ export type ContainmentConfig = {
803
866
  contained: ContainedRuleSet;
804
867
  };
805
868
  export declare const MAX_CONTAINMENT_RULE_DEPTH = 5;
869
+ /**
870
+ * An Action that changes the cart, named by what the author wrote rather than by uuid:
871
+ * a callable Action's key, an Action node's key, the per-turn Action on a node, or the
872
+ * before-call Action.
873
+ */
874
+ export type CartActionRef = {
875
+ callable: string;
876
+ } | {
877
+ actionNode: string;
878
+ } | {
879
+ perTurnAction: string;
880
+ } | {
881
+ beforeCallAction: true;
882
+ };
883
+ /**
884
+ * When the order counts as placed (checkout). Order ids come from an Action's outputs, so only an `action_succeeded`
885
+ * rule can name them, and each rule names at least one Action or node.
886
+ */
887
+ export type CartCheckoutDefinition = {
888
+ when: {
889
+ kind: 'action_succeeded';
890
+ actions: [CartActionRef, ...CartActionRef[]];
891
+ };
892
+ /** Where the order ids are in the Action's outputs. */
893
+ orderIds?: {
894
+ from: CartPointer | null;
895
+ id: CartPointer;
896
+ } | null;
897
+ } | {
898
+ when: {
899
+ kind: 'node_reached';
900
+ nodes: [string, ...string[]];
901
+ };
902
+ orderIds?: null;
903
+ } | {
904
+ when: {
905
+ kind: 'parameter_equals';
906
+ parameter: string;
907
+ value: string | number | boolean | null;
908
+ };
909
+ orderIds?: null;
910
+ };
911
+ /**
912
+ * Where the Agent keeps its cart and how the call page shows it. Configuration only: nothing in
913
+ * the graph or prompts changes. Node and Action references use authoring keys.
914
+ */
915
+ export type CartDefinition = {
916
+ parameter: string;
917
+ view: CartViewWire;
918
+ reasonArgument?: string | null;
919
+ actions?: {
920
+ action: CartActionRef;
921
+ label: string;
922
+ }[];
923
+ checkout?: CartCheckoutDefinition | null;
924
+ };
806
925
  export type AgentDefinition = {
807
926
  kind: 'agent-definition';
808
927
  key: string;
@@ -835,6 +954,8 @@ export type AgentDefinition = {
835
954
  * the key out of the commit, `null` writes an explicit null, a string writes it.
836
955
  */
837
956
  toneGuidelines?: string | null;
957
+ /** Three states like `toneGuidelines`: absent keeps the key out of the commit. */
958
+ cart?: CartDefinition | null;
838
959
  call: {
839
960
  agentSpeaksFirst: boolean;
840
961
  firstSentence: string | null;
@@ -924,6 +1045,7 @@ export type AgentDefinitionInput = {
924
1045
  pronunciations?: Pronunciation[];
925
1046
  };
926
1047
  toneGuidelines?: string | null;
1048
+ cart?: CartDefinition | null;
927
1049
  call?: Partial<Omit<AgentDefinition['call'], 'checkInAfterSilence'>> & {
928
1050
  checkInAfterSilence?: CheckInAfterSilenceInput;
929
1051
  };