@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/README.md CHANGED
@@ -132,6 +132,7 @@ export default defineAgent({
132
132
  name: 'Support',
133
133
  branch: 'main',
134
134
  llm: { modelUuid: 'your-llm-model-uuid' },
135
+ nodeCheck: true,
135
136
  nodes: [
136
137
  node.prompt({
137
138
  key: 'root',
package/dist/actions.cjs CHANGED
@@ -327,6 +327,31 @@ function compileKnowledgeBaseSearchAction(config) {
327
327
  }),
328
328
  };
329
329
  }
330
+ function compileBrowserAction(config) {
331
+ const operation = {
332
+ type: 'browser_action',
333
+ rpaFlowUuid: config.rpaFlowUuid,
334
+ rpaFlowVersionUuid: config.rpaFlowVersionUuid,
335
+ environment: config.environment,
336
+ kind: config.kind,
337
+ timeoutMs: config.timeoutMs ?? built_in_actions_1.BROWSER_ACTION_TIMEOUT_MS_DEFAULT,
338
+ };
339
+ built_in_actions_1.builtInOperationSchema.parse(operation);
340
+ const contract = compileContracts(config);
341
+ return {
342
+ kind: 'inline',
343
+ key: config.key,
344
+ contract,
345
+ compile: () => ({
346
+ actionType: 'built_in',
347
+ name: config.name,
348
+ description: config.description,
349
+ ...contract,
350
+ outputMappings: (0, built_in_actions_1.browserActionOutputMappings)(contract.outputSchema),
351
+ operation,
352
+ }),
353
+ };
354
+ }
330
355
  /** Compiles built-in schema parameters through the same path as other Actions. */
331
356
  function compileBuiltInAction({ config, operation, }) {
332
357
  // Validate against the Agent v2 operation schema without applying its transforms:
@@ -412,6 +437,10 @@ exports.action = {
412
437
  operation: { type: 'validate_address' },
413
438
  });
414
439
  },
440
+ /** Runs one version of a browser action (an RPA flow) in the conversation's browser. */
441
+ browserAction(config) {
442
+ return compileBrowserAction(config);
443
+ },
415
444
  /** Searches the web and returns the passages of each page most relevant to the question. */
416
445
  webSearch(config) {
417
446
  const { allowedDomains = [], blockedDomains = [] } = config;
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { builtInOperationSchema } from "./built-in-actions.cjs";
2
+ import { type BROWSER_ACTION_ENVIRONMENTS, type BROWSER_ACTION_KINDS, builtInOperationSchema } from "./built-in-actions.cjs";
3
3
  export type ActionsIoScalarType = 'string' | 'number' | 'boolean';
4
4
  export type ActionsIoSchemaNode = {
5
5
  type: ActionsIoScalarType;
@@ -137,6 +137,20 @@ export type AgentActionInput = {
137
137
  value: string;
138
138
  description?: string;
139
139
  };
140
+ /**
141
+ * How far a sensitive input's value is scrubbed from what a call saves.
142
+ * `everywhere`: from everything saved for the rest of the call.
143
+ * `tool-call`: from this tool call's own arguments, result, error and logs only.
144
+ */
145
+ export type SensitiveInputScope = 'everywhere' | 'tool-call';
146
+ /**
147
+ * Labels on one input of a callable Action. `sensitive` keeps the value out of
148
+ * storage; `hidden` saves it as usual but collapses it in the dashboard's tool card.
149
+ */
150
+ export type ActionInputLabel = {
151
+ sensitive?: SensitiveInputScope;
152
+ hidden?: true;
153
+ };
140
154
  /** Maps each Action output name to the Agent parameter that should receive its value. */
141
155
  export type ActionOutputParameters = Record<string, string>;
142
156
  /**
@@ -161,6 +175,8 @@ export type CallableActionDefinition = {
161
175
  name: string;
162
176
  description: string;
163
177
  inputs: Record<string, AgentActionInput>;
178
+ /** Labels keyed by Action input name; any input of the Action, prefilled or model-filled. */
179
+ inputLabels?: Record<string, ActionInputLabel>;
164
180
  outputParameters?: ActionOutputParameters;
165
181
  outputParameterMappings?: ActionOutputParameterMappings;
166
182
  backgroundMessage: BackgroundMessage | null;
@@ -290,6 +306,22 @@ type SendEmailActionConfig = BuiltInActionConfig & {
290
306
  type SendTextMessageActionConfig = BuiltInActionConfig & {
291
307
  senderPhoneNumberUuid: string;
292
308
  };
309
+ /**
310
+ * A browser action runs one version of a script, and takes that version's
311
+ * inputs and outputs: Agent v2 refuses any other. They are usually authored as
312
+ * the stored `ActionsIoSchema` the script declares.
313
+ */
314
+ type BrowserActionConfig = SchemaPair & {
315
+ key: string;
316
+ name: string;
317
+ description: string;
318
+ rpaFlowUuid: string;
319
+ rpaFlowVersionUuid: string;
320
+ environment: (typeof BROWSER_ACTION_ENVIRONMENTS)[number];
321
+ kind: (typeof BROWSER_ACTION_KINDS)[number];
322
+ /** Defaults to two minutes, which suits a look-up on a slow portal. */
323
+ timeoutMs?: number;
324
+ };
293
325
  type ValidateAddressActionConfig = BuiltInActionConfig;
294
326
  type WebSearchActionConfig = BuiltInActionConfig & {
295
327
  /**
@@ -329,6 +361,8 @@ export declare const action: {
329
361
  sendTextMessage(config: SendTextMessageActionConfig): InlineActionDefinition;
330
362
  /** Validates and standardizes a postal address. */
331
363
  validateAddress(config: ValidateAddressActionConfig): InlineActionDefinition;
364
+ /** Runs one version of a browser action (an RPA flow) in the conversation's browser. */
365
+ browserAction(config: BrowserActionConfig): InlineActionDefinition;
332
366
  /** Searches the web and returns the passages of each page most relevant to the question. */
333
367
  webSearch(config: WebSearchActionConfig): InlineActionDefinition;
334
368
  ref(config: {
package/dist/actions.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { builtInOperationSchema } from "./built-in-actions.js";
2
+ import { type BROWSER_ACTION_ENVIRONMENTS, type BROWSER_ACTION_KINDS, builtInOperationSchema } from "./built-in-actions.js";
3
3
  export type ActionsIoScalarType = 'string' | 'number' | 'boolean';
4
4
  export type ActionsIoSchemaNode = {
5
5
  type: ActionsIoScalarType;
@@ -137,6 +137,20 @@ export type AgentActionInput = {
137
137
  value: string;
138
138
  description?: string;
139
139
  };
140
+ /**
141
+ * How far a sensitive input's value is scrubbed from what a call saves.
142
+ * `everywhere`: from everything saved for the rest of the call.
143
+ * `tool-call`: from this tool call's own arguments, result, error and logs only.
144
+ */
145
+ export type SensitiveInputScope = 'everywhere' | 'tool-call';
146
+ /**
147
+ * Labels on one input of a callable Action. `sensitive` keeps the value out of
148
+ * storage; `hidden` saves it as usual but collapses it in the dashboard's tool card.
149
+ */
150
+ export type ActionInputLabel = {
151
+ sensitive?: SensitiveInputScope;
152
+ hidden?: true;
153
+ };
140
154
  /** Maps each Action output name to the Agent parameter that should receive its value. */
141
155
  export type ActionOutputParameters = Record<string, string>;
142
156
  /**
@@ -161,6 +175,8 @@ export type CallableActionDefinition = {
161
175
  name: string;
162
176
  description: string;
163
177
  inputs: Record<string, AgentActionInput>;
178
+ /** Labels keyed by Action input name; any input of the Action, prefilled or model-filled. */
179
+ inputLabels?: Record<string, ActionInputLabel>;
164
180
  outputParameters?: ActionOutputParameters;
165
181
  outputParameterMappings?: ActionOutputParameterMappings;
166
182
  backgroundMessage: BackgroundMessage | null;
@@ -290,6 +306,22 @@ type SendEmailActionConfig = BuiltInActionConfig & {
290
306
  type SendTextMessageActionConfig = BuiltInActionConfig & {
291
307
  senderPhoneNumberUuid: string;
292
308
  };
309
+ /**
310
+ * A browser action runs one version of a script, and takes that version's
311
+ * inputs and outputs: Agent v2 refuses any other. They are usually authored as
312
+ * the stored `ActionsIoSchema` the script declares.
313
+ */
314
+ type BrowserActionConfig = SchemaPair & {
315
+ key: string;
316
+ name: string;
317
+ description: string;
318
+ rpaFlowUuid: string;
319
+ rpaFlowVersionUuid: string;
320
+ environment: (typeof BROWSER_ACTION_ENVIRONMENTS)[number];
321
+ kind: (typeof BROWSER_ACTION_KINDS)[number];
322
+ /** Defaults to two minutes, which suits a look-up on a slow portal. */
323
+ timeoutMs?: number;
324
+ };
293
325
  type ValidateAddressActionConfig = BuiltInActionConfig;
294
326
  type WebSearchActionConfig = BuiltInActionConfig & {
295
327
  /**
@@ -329,6 +361,8 @@ export declare const action: {
329
361
  sendTextMessage(config: SendTextMessageActionConfig): InlineActionDefinition;
330
362
  /** Validates and standardizes a postal address. */
331
363
  validateAddress(config: ValidateAddressActionConfig): InlineActionDefinition;
364
+ /** Runs one version of a browser action (an RPA flow) in the conversation's browser. */
365
+ browserAction(config: BrowserActionConfig): InlineActionDefinition;
332
366
  /** Searches the web and returns the passages of each page most relevant to the question. */
333
367
  webSearch(config: WebSearchActionConfig): InlineActionDefinition;
334
368
  ref(config: {
package/dist/actions.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { BUILT_IN_ACTION_CONTRACTS, builtInOperationSchema } from "./built-in-actions.js";
2
+ import { BROWSER_ACTION_TIMEOUT_MS_DEFAULT, BUILT_IN_ACTION_CONTRACTS, browserActionOutputMappings, builtInOperationSchema, } from "./built-in-actions.js";
3
3
  export function resolveActionHttpHeaders(headers) {
4
4
  if (headers === undefined) {
5
5
  return [];
@@ -318,6 +318,31 @@ function compileKnowledgeBaseSearchAction(config) {
318
318
  }),
319
319
  };
320
320
  }
321
+ function compileBrowserAction(config) {
322
+ const operation = {
323
+ type: 'browser_action',
324
+ rpaFlowUuid: config.rpaFlowUuid,
325
+ rpaFlowVersionUuid: config.rpaFlowVersionUuid,
326
+ environment: config.environment,
327
+ kind: config.kind,
328
+ timeoutMs: config.timeoutMs ?? BROWSER_ACTION_TIMEOUT_MS_DEFAULT,
329
+ };
330
+ builtInOperationSchema.parse(operation);
331
+ const contract = compileContracts(config);
332
+ return {
333
+ kind: 'inline',
334
+ key: config.key,
335
+ contract,
336
+ compile: () => ({
337
+ actionType: 'built_in',
338
+ name: config.name,
339
+ description: config.description,
340
+ ...contract,
341
+ outputMappings: browserActionOutputMappings(contract.outputSchema),
342
+ operation,
343
+ }),
344
+ };
345
+ }
321
346
  /** Compiles built-in schema parameters through the same path as other Actions. */
322
347
  function compileBuiltInAction({ config, operation, }) {
323
348
  // Validate against the Agent v2 operation schema without applying its transforms:
@@ -403,6 +428,10 @@ export const action = {
403
428
  operation: { type: 'validate_address' },
404
429
  });
405
430
  },
431
+ /** Runs one version of a browser action (an RPA flow) in the conversation's browser. */
432
+ browserAction(config) {
433
+ return compileBrowserAction(config);
434
+ },
406
435
  /** Searches the web and returns the passages of each page most relevant to the question. */
407
436
  webSearch(config) {
408
437
  const { allowedDomains = [], blockedDomains = [] } = config;
package/dist/agents.cjs CHANGED
@@ -1,7 +1,8 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.DEFAULT_PER_TURN_RETRIEVAL_RECENT_TURNS = exports.DEFAULT_PER_TURN_RETRIEVAL_TOP_K = exports.prompt = exports.node = exports.MAX_CONTAINMENT_RULE_DEPTH = exports.CONTAINMENT_CONTAINED_CONDITION_TYPES = exports.CONTAINMENT_CONTAINABLE_CONDITION_TYPES = exports.CONTAINMENT_RULE_MATCHES = exports.FIVE9_SIP_BYE_HEADER_NAMES = exports.SOP_TOOL_REF_TYPES = exports.DEFAULT_CHECK_IN_AFTER_SILENCE_DELAY_SECONDS = exports.DEFAULT_TRANSITION_MESSAGE = exports.TRANSITION_FILTER_MAX_CONDITIONS = exports.TRANSITION_FILTER_MAX_DEPTH = exports.PII_REDACTION_CATEGORIES = exports.TRANSITION_FILTER_EXISTENCE_OPERATORS = exports.TRANSITION_FILTER_STRING_OPERATORS = exports.TRANSITION_FILTER_CONTAINS_OPERATORS = exports.TRANSITION_FILTER_NUMERIC_OPERATORS = exports.TRANSITION_FILTER_EQUALITY_OPERATORS = void 0;
3
+ exports.DEFAULT_PER_TURN_RETRIEVAL_RECENT_TURNS = exports.DEFAULT_PER_TURN_RETRIEVAL_TOP_K = exports.prompt = exports.node = exports.MAX_CONTAINMENT_RULE_DEPTH = exports.CONTAINMENT_CONTAINED_CONDITION_TYPES = exports.CONTAINMENT_CONTAINABLE_CONDITION_TYPES = exports.CONTAINMENT_RULE_MATCHES = exports.FIVE9_SIP_BYE_HEADER_NAMES = exports.SOP_TOOL_REF_TYPES = exports.GUARDRAIL_MODES = exports.CALL_END_ACTION_KEY = exports.BEFORE_CALL_ACTION_KEY = exports.DEFAULT_CHECK_IN_AFTER_SILENCE_DELAY_SECONDS = exports.DEFAULT_TRANSITION_MESSAGE = exports.TRANSITION_FILTER_MAX_CONDITIONS = exports.TRANSITION_FILTER_MAX_DEPTH = exports.PII_REDACTION_CATEGORIES = exports.TRANSITION_FILTER_EXISTENCE_OPERATORS = exports.TRANSITION_FILTER_STRING_OPERATORS = exports.TRANSITION_FILTER_CONTAINS_OPERATORS = exports.TRANSITION_FILTER_NUMERIC_OPERATORS = exports.TRANSITION_FILTER_EQUALITY_OPERATORS = void 0;
4
4
  exports.defaultBackgroundNoise = defaultBackgroundNoise;
5
+ exports.assistActionRunKey = assistActionRunKey;
5
6
  exports.defineAgent = defineAgent;
6
7
  exports.reference = reference;
7
8
  exports.canonicalAuthoringKey = canonicalAuthoringKey;
@@ -44,6 +45,18 @@ function defaultBackgroundNoise({ voiceBackgroundNoise, }) {
44
45
  }
45
46
  /** How long the agent waits before checking in on a silent caller. Matches the product default. */
46
47
  exports.DEFAULT_CHECK_IN_AFTER_SILENCE_DELAY_SECONDS = 30;
48
+ /**
49
+ * The `:` keeps these apart from callable keys, which `canonicalAuthoringKey` limits to letters, digits and `-`;
50
+ * otherwise a callable named "Call end" would take the call-end run's use site. Projects pulled before the prefix
51
+ * name the old key in their source, which is looked up first.
52
+ */
53
+ exports.BEFORE_CALL_ACTION_KEY = 'automatic:before-call-start';
54
+ exports.CALL_END_ACTION_KEY = 'automatic:call-end';
55
+ /** The identity key of an Agent Assist step or card button's run, by the id the playbook stores for it. */
56
+ function assistActionRunKey({ kind, id }) {
57
+ return `assist-${kind}:${id}`;
58
+ }
59
+ exports.GUARDRAIL_MODES = ['enforce', 'monitor'];
47
60
  function llmOverrideWire(override) {
48
61
  return { llmModelUuid: override.modelUuid, temperature: override.temperature };
49
62
  }
@@ -89,8 +102,17 @@ function transferCapabilityFrom(authored) {
89
102
  mode: authored?.mode ?? defaults.mode,
90
103
  description: authored?.description ?? defaults.description,
91
104
  voicemailMessage: authored?.voicemailMessage ?? defaults.voicemailMessage,
105
+ ...(authored?.briefing === undefined ? {} : { briefing: authored.briefing }),
92
106
  };
93
107
  }
108
+ /** Checked at runtime too: the CLI compiles source without typechecking it. */
109
+ function requiredNodeCheck({ nodeCheck }) {
110
+ if (typeof nodeCheck !== 'boolean') {
111
+ throw new Error('`nodeCheck` is required: `true` runs the background node check, which the product starts new Agents with; ' +
112
+ '`false` is how Agents pulled before it existed run');
113
+ }
114
+ return nodeCheck;
115
+ }
94
116
  function defineAgent(input) {
95
117
  const voiceBackgroundNoise = input.voice?.backgroundNoise ?? 'off';
96
118
  return {
@@ -165,6 +187,10 @@ function defineAgent(input) {
165
187
  tools: input.tools ?? [],
166
188
  knowledgeBases: input.knowledgeBases ?? [],
167
189
  beforeCallAction: input.beforeCallAction ?? null,
190
+ callEndAction: input.callEndAction ?? null,
191
+ guardrails: input.guardrails ?? [],
192
+ nodeCheck: requiredNodeCheck({ nodeCheck: input.nodeCheck }),
193
+ assist: input.assist ?? null,
168
194
  summaryPrompt: input.summaryPrompt ?? null,
169
195
  abTestGroupIds: input.abTestGroupIds ?? null,
170
196
  actions: input.actions ?? null,
@@ -471,6 +497,22 @@ function compileCallableUseSite({ callable, canonicalKey, options, }) {
471
497
  inputMappings[pointerForInputName(MODEL_BACKGROUND_MESSAGE_PARAMETER)] === undefined) {
472
498
  throw new Error(`Callable Action "${callable.key}" cannot ask the model for a background message because the Action already declares an input named "${MODEL_BACKGROUND_MESSAGE_PARAMETER}"; prefill it with action.from(...) or use an authored message`);
473
499
  }
500
+ // Same rules as the server's, checked here so an author hears about them from `compileAgent`.
501
+ // An unknown input is only detectable when the Action's contract is known.
502
+ const labelEntries = Object.entries(callable.inputLabels ?? {});
503
+ for (const [name, label] of labelEntries) {
504
+ if (label.sensitive === undefined && label.hidden === undefined) {
505
+ throw new Error(`Callable Action "${callable.key}" labels input "${name}" with neither sensitive nor hidden`);
506
+ }
507
+ if (callable.action.contract !== null && !Object.hasOwn(contractProperties, name)) {
508
+ throw new Error(`Callable Action "${callable.key}" labels unknown Action input "${name}"`);
509
+ }
510
+ // Scrubbing a two-valued input still gives its value away; the server's commit validation says why.
511
+ if (label.sensitive !== undefined && contractProperties[name]?.type === 'boolean') {
512
+ throw new Error(`Callable Action "${callable.key}" marks boolean input "${name}" sensitive; boolean inputs can't be sensitive`);
513
+ }
514
+ }
515
+ const inputLabels = Object.fromEntries(labelEntries.map(([name, label]) => [pointerForInputName(name), label]));
474
516
  return {
475
517
  actionUseSiteUuid: resolveIdentity({
476
518
  options,
@@ -482,6 +524,7 @@ function compileCallableUseSite({ callable, canonicalKey, options, }) {
482
524
  name: callable.name,
483
525
  description: callable.description,
484
526
  inputDescriptions,
527
+ ...(labelEntries.length === 0 ? {} : { inputLabels }),
485
528
  inputMappings,
486
529
  outputParameterMappings: compileOutputParameterMappings({
487
530
  key: callable.key,
@@ -491,14 +534,13 @@ function compileCallableUseSite({ callable, canonicalKey, options, }) {
491
534
  backgroundMessage,
492
535
  };
493
536
  }
494
- function compileActionRun({ run, trigger, canonicalKey, options, }) {
537
+ function compileActionRun({ run, trigger, identityKeys, options, }) {
538
+ return { ...compileActionUseSite({ run, identityKeys, options }), trigger };
539
+ }
540
+ /** An Action run as a bare use site, which is what Agent Assist steps and card buttons store. */
541
+ function compileActionUseSite({ run, identityKeys: [key, ...fallbackKeys], options, }) {
495
542
  return {
496
- actionUseSiteUuid: resolveIdentity({
497
- options,
498
- kind: 'action-use-site',
499
- key: run.key,
500
- fallbackKeys: [canonicalKey],
501
- }),
543
+ actionUseSiteUuid: resolveIdentity({ options, kind: 'action-use-site', key, fallbackKeys }),
502
544
  actionVersionUuid: resolveActionVersion({ definition: run.action, options }),
503
545
  inputMappings: Object.fromEntries(Object.entries(run.inputs).map(([name, value]) => [
504
546
  name.startsWith('/') ? name : pointerForInputName(name),
@@ -509,7 +551,6 @@ function compileActionRun({ run, trigger, canonicalKey, options, }) {
509
551
  outputParameters: run.outputParameters,
510
552
  outputParameterMappings: run.outputParameterMappings,
511
553
  }),
512
- trigger,
513
554
  };
514
555
  }
515
556
  /** Product defaults for retrieval settings the author leaves out. */
@@ -583,6 +624,79 @@ function validateDeclaredActions({ declared, nodes, }) {
583
624
  }
584
625
  }
585
626
  }
627
+ /** Every Action an Agent Assist playbook runs: its procedures' steps first, then its card buttons. */
628
+ function assistActionRuns(assist) {
629
+ if (assist === null) {
630
+ return [];
631
+ }
632
+ return [
633
+ ...assist.procedures.flatMap((procedure) => procedure.steps.flatMap((step) => (step.kind === 'run_action' ? [step.action] : []))),
634
+ ...assist.cards.flatMap((card) => card.buttons.map((button) => button.action)),
635
+ ];
636
+ }
637
+ function compileAssist({ assist, options, }) {
638
+ // Keyed by the stored id, which the playbook keeps unique, so a run shared by several steps or keyed like a
639
+ // callable still gets a use site of its own.
640
+ const useSite = ({ run, kind, id }) => compileActionUseSite({ run, identityKeys: [assistActionRunKey({ kind, id })], options });
641
+ return {
642
+ procedures: assist.procedures.map((procedure) => ({
643
+ id: procedure.id,
644
+ name: procedure.name,
645
+ hook: procedure.hook,
646
+ steps: procedure.steps.map((step) => {
647
+ switch (step.kind) {
648
+ case 'run_action':
649
+ return {
650
+ id: step.id,
651
+ kind: 'run_action',
652
+ action: useSite({ run: step.action, kind: 'step', id: step.id }),
653
+ };
654
+ case 'show_card':
655
+ case 'show_checklist':
656
+ return step;
657
+ default: {
658
+ step;
659
+ throw new Error(`Unhandled Agent Assist step: ${JSON.stringify(step)}`);
660
+ }
661
+ }
662
+ }),
663
+ })),
664
+ cards: assist.cards.map((card) => ({
665
+ id: card.id,
666
+ name: card.name,
667
+ title: card.title,
668
+ body: card.body,
669
+ buttons: card.buttons.map((button) => ({
670
+ id: button.id,
671
+ label: button.label,
672
+ action: useSite({ run: button.action, kind: 'button', id: button.id }),
673
+ })),
674
+ })),
675
+ checklists: assist.checklists.map((checklist) => ({
676
+ id: checklist.id,
677
+ name: checklist.name,
678
+ items: resolveExtractionFields(checklist.items),
679
+ })),
680
+ };
681
+ }
682
+ function compileGuardrails({ guardrails, nodeUuids, }) {
683
+ return guardrails.map((assignment) => {
684
+ let nodeUuid = null;
685
+ if (assignment.node !== null) {
686
+ const resolved = nodeUuids.get(assignment.node);
687
+ if (resolved === undefined) {
688
+ throw new Error(`Guardrail ${assignment.guardrail.uuid} moves the call to node "${assignment.node}", which this Agent does not have`);
689
+ }
690
+ nodeUuid = resolved;
691
+ }
692
+ return {
693
+ guardrailUuid: assignment.guardrail.uuid,
694
+ version: assignment.version,
695
+ mode: assignment.mode,
696
+ nodeUuid,
697
+ };
698
+ });
699
+ }
586
700
  function collectInlineActions(definition) {
587
701
  const byKey = new Map();
588
702
  const visit = (actionDefinition) => {
@@ -598,8 +712,10 @@ function collectInlineActions(definition) {
598
712
  for (const callable of definition.actions ?? collectCallableActions(definition.nodes)) {
599
713
  visit(callable.action);
600
714
  }
601
- if (definition.beforeCallAction !== null) {
602
- visit(definition.beforeCallAction.action);
715
+ for (const run of [definition.beforeCallAction, definition.callEndAction, ...assistActionRuns(definition.assist)]) {
716
+ if (run !== null) {
717
+ visit(run.action);
718
+ }
603
719
  }
604
720
  for (const definitionNode of definition.nodes) {
605
721
  if (definitionNode.type === 'action') {
@@ -671,6 +787,13 @@ function nodeCapabilities(alwaysAvailable) {
671
787
  },
672
788
  };
673
789
  }
790
+ /** A node option must include at least one part; null is the only way to include none. */
791
+ function compileContactHistory({ nodeKey, option, }) {
792
+ if (option !== null && !option.summary && !option.facts && !option.entities) {
793
+ throw new Error(`Prompt node "${nodeKey}" includes no part of the contact history; set contactHistory to null to include none`);
794
+ }
795
+ return option;
796
+ }
674
797
  function promptNodeCapabilities(definition) {
675
798
  const base = nodeCapabilities(definition.alwaysAvailable);
676
799
  if (definition.transfer === undefined) {
@@ -716,7 +839,7 @@ function compileNode({ definition, canonicalNodeKey, canonicalCallableKeys, inde
716
839
  : compileActionRun({
717
840
  run: definition.perTurnAction,
718
841
  trigger: 'every_turn',
719
- canonicalKey: `${canonicalNodeKey}:every-turn`,
842
+ identityKeys: [definition.perTurnAction.key, `${canonicalNodeKey}:every-turn`],
720
843
  options,
721
844
  });
722
845
  return {
@@ -766,6 +889,9 @@ function compileNode({ definition, canonicalNodeKey, canonicalCallableKeys, inde
766
889
  perTurnRetrieval: definition.perTurnRetrieval === null ? null : compilePerTurnRetrieval(definition.perTurnRetrieval),
767
890
  }),
768
891
  ...(definition.perTurnAction === undefined ? {} : { perTurnAction }),
892
+ ...(definition.contactHistory === undefined
893
+ ? {}
894
+ : { contactHistory: compileContactHistory({ nodeKey: definition.key, option: definition.contactHistory }) }),
769
895
  };
770
896
  }
771
897
  case 'action':
@@ -813,6 +939,7 @@ function compileNode({ definition, canonicalNodeKey, canonicalCallableKeys, inde
813
939
  return {
814
940
  ...base,
815
941
  type: 'extract',
942
+ overrides: definition.llmOverride === undefined ? {} : { llm: llmOverrideWire(definition.llmOverride) },
816
943
  ...extraction,
817
944
  executionMessage: definition.message ?? null,
818
945
  builtInTools,
@@ -917,13 +1044,19 @@ function describeCartActionRef(ref) {
917
1044
  return `Action node "${ref.actionNode}"`;
918
1045
  if ('perTurnAction' in ref)
919
1046
  return `the per-turn Action on node "${ref.perTurnAction}"`;
1047
+ if ('callEndAction' in ref)
1048
+ return 'the call-end Action';
1049
+ if ('assistStep' in ref)
1050
+ return `Agent Assist step ${ref.assistStep}`;
1051
+ if ('assistButton' in ref)
1052
+ return `Agent Assist button ${ref.assistButton}`;
920
1053
  return 'the before-call Action';
921
1054
  }
922
1055
  /**
923
1056
  * Resolves the cart's authoring keys to the uuids the compiled commit uses. A reference to
924
1057
  * something the Agent doesn't have fails here, rather than at publish.
925
1058
  */
926
- function compileCart({ cart, callables, toolUseSites, definitionNodes, nodes, beforeCallStart, }) {
1059
+ function compileCart({ cart, callables, toolUseSites, definitionNodes, nodes, beforeCallStart, callEnd, assist, }) {
927
1060
  const nodeAt = (key) => {
928
1061
  const index = definitionNodes.findIndex((definitionNode) => definitionNode.key === key);
929
1062
  return index === -1 ? null : { definition: definitionNodes[index], wire: nodes[index] };
@@ -945,6 +1078,19 @@ function compileCart({ cart, callables, toolUseSites, definitionNodes, nodes, be
945
1078
  ? (wire.perTurnAction?.actionUseSiteUuid ?? undefined)
946
1079
  : undefined;
947
1080
  }
1081
+ else if ('callEndAction' in ref) {
1082
+ uuid = callEnd?.actionUseSiteUuid;
1083
+ }
1084
+ else if ('assistStep' in ref) {
1085
+ const step = assist?.procedures
1086
+ .flatMap((procedure) => procedure.steps)
1087
+ .find((candidate) => candidate.id === ref.assistStep);
1088
+ uuid = step?.kind === 'run_action' ? step.action.actionUseSiteUuid : undefined;
1089
+ }
1090
+ else if ('assistButton' in ref) {
1091
+ uuid = assist?.cards.flatMap((card) => card.buttons).find((button) => button.id === ref.assistButton)
1092
+ ?.action.actionUseSiteUuid;
1093
+ }
948
1094
  else {
949
1095
  uuid = beforeCallStart?.actionUseSiteUuid;
950
1096
  }
@@ -1054,8 +1200,17 @@ function validateDefinition(definition) {
1054
1200
  throw new Error('The global node cannot be the root node');
1055
1201
  }
1056
1202
  }
1203
+ function validateAssist(definition) {
1204
+ if (definition.modality === 'assist' && definition.assist === null) {
1205
+ throw new Error('An assist Agent must define its playbook in `assist`');
1206
+ }
1207
+ if (definition.modality !== 'assist' && definition.assist !== null) {
1208
+ throw new Error(`Only an assist Agent has a playbook; this Agent's modality is "${definition.modality}"`);
1209
+ }
1210
+ }
1057
1211
  function compileAgent(definition, options = {}) {
1058
1212
  validateDefinition(definition);
1213
+ validateAssist(definition);
1059
1214
  const canonicalNodeKeys = canonicalAuthoringKeys(definition.nodes.map((definitionNode, index) => ({
1060
1215
  value: definitionNode.name,
1061
1216
  fallback: `node-${index + 1}`,
@@ -1104,9 +1259,21 @@ function compileAgent(definition, options = {}) {
1104
1259
  : compileActionRun({
1105
1260
  run: definition.beforeCallAction,
1106
1261
  trigger: 'before_call_start',
1107
- canonicalKey: 'before-call-start',
1262
+ // The run's own key comes first because hand-written projects already published derived their use site
1263
+ // from it.
1264
+ identityKeys: [definition.beforeCallAction.key, exports.BEFORE_CALL_ACTION_KEY],
1265
+ options,
1266
+ });
1267
+ const callEnd = definition.callEndAction === null
1268
+ ? null
1269
+ : compileActionRun({
1270
+ run: definition.callEndAction,
1271
+ trigger: 'call_end',
1272
+ // No source could author a call-end run before this key existed, so it is the only identity.
1273
+ identityKeys: [exports.CALL_END_ACTION_KEY],
1108
1274
  options,
1109
1275
  });
1276
+ const assist = definition.assist === null ? null : compileAssist({ assist: definition.assist, options });
1110
1277
  const cart = definition.cart === undefined || definition.cart === null
1111
1278
  ? definition.cart
1112
1279
  : compileCart({
@@ -1116,6 +1283,8 @@ function compileAgent(definition, options = {}) {
1116
1283
  definitionNodes: definition.nodes,
1117
1284
  nodes: compiledNodes,
1118
1285
  beforeCallStart,
1286
+ callEnd,
1287
+ assist,
1119
1288
  });
1120
1289
  return {
1121
1290
  agent: {
@@ -1187,10 +1356,13 @@ function compileAgent(definition, options = {}) {
1187
1356
  definition.nodes.some((definitionNode) => nodeCarriesCallableActions(definitionNode) && definitionNode.actions !== undefined)
1188
1357
  ? { toolUseSites }
1189
1358
  : {}),
1190
- automaticActions: { beforeCallStart },
1359
+ automaticActions: { beforeCallStart, callEnd },
1191
1360
  knowledgeBaseIds: definition.knowledgeBases.map((item) => item.uuid),
1192
1361
  abTestGroupIds: definition.abTestGroupIds ?? abTestGroupIds,
1193
1362
  ...(cart === undefined ? {} : { cart }),
1363
+ guardrails: compileGuardrails({ guardrails: definition.guardrails, nodeUuids }),
1364
+ nodeCheck: { enabled: definition.nodeCheck },
1365
+ ...(assist === null ? {} : { assist }),
1194
1366
  },
1195
1367
  nodes: compiledNodes,
1196
1368
  summaryPrompt: definition.summaryPrompt,