@signalwire/sdk 3.7.1 → 3.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.
Files changed (96) hide show
  1. package/CHANGELOG.md +214 -0
  2. package/README.md +1 -0
  3. package/dist/AgentBase.d.ts +120 -3
  4. package/dist/AgentBase.js +291 -18
  5. package/dist/AgentBase.js.map +1 -1
  6. package/dist/AgentServer.d.ts +30 -6
  7. package/dist/AgentServer.js +28 -2
  8. package/dist/AgentServer.js.map +1 -1
  9. package/dist/AiEvents.d.ts +70 -0
  10. package/dist/AiEvents.js +94 -0
  11. package/dist/AiEvents.js.map +1 -0
  12. package/dist/ContextBuilder.d.ts +197 -14
  13. package/dist/ContextBuilder.js +422 -13
  14. package/dist/ContextBuilder.js.map +1 -1
  15. package/dist/FunctionResult.d.ts +129 -0
  16. package/dist/FunctionResult.js +170 -0
  17. package/dist/FunctionResult.js.map +1 -1
  18. package/dist/Logger.d.ts +1 -1
  19. package/dist/PostPrompt.d.ts +19 -0
  20. package/dist/PostPrompt.js +43 -0
  21. package/dist/PostPrompt.js.map +1 -1
  22. package/dist/SWMLService.d.ts +151 -10
  23. package/dist/SWMLService.js +377 -61
  24. package/dist/SWMLService.js.map +1 -1
  25. package/dist/SchemaUtils.js +14 -1
  26. package/dist/SchemaUtils.js.map +1 -1
  27. package/dist/SemanticGate.d.ts +61 -1
  28. package/dist/SemanticGate.js +108 -15
  29. package/dist/SemanticGate.js.map +1 -1
  30. package/dist/SessionManager.d.ts +17 -6
  31. package/dist/SessionManager.js +16 -3
  32. package/dist/SessionManager.js.map +1 -1
  33. package/dist/SwaigFunction.d.ts +86 -9
  34. package/dist/SwaigFunction.js +215 -59
  35. package/dist/SwaigFunction.js.map +1 -1
  36. package/dist/ToolMiddleware.d.ts +82 -0
  37. package/dist/ToolMiddleware.js +131 -0
  38. package/dist/ToolMiddleware.js.map +1 -0
  39. package/dist/TypeInference.d.ts +2 -2
  40. package/dist/TypeInference.js +1 -1
  41. package/dist/TypeInference.js.map +1 -1
  42. package/dist/ai-chat/ChatGateway.d.ts +5 -5
  43. package/dist/ai-chat/HandoffRouter.d.ts +3 -3
  44. package/dist/cli/tsdocs/api-index.json +1 -1
  45. package/dist/cli/tsdocs/topics.js +24 -4
  46. package/dist/cli/tsdocs/topics.js.map +1 -1
  47. package/dist/index.d.ts +23 -8
  48. package/dist/index.js +16 -5
  49. package/dist/index.js.map +1 -1
  50. package/dist/livewire/index.d.ts +3 -0
  51. package/dist/livewire/index.js +3 -0
  52. package/dist/livewire/index.js.map +1 -1
  53. package/dist/llms.txt +1 -0
  54. package/dist/patterns/Proposal.d.ts +146 -0
  55. package/dist/patterns/Proposal.js +212 -0
  56. package/dist/patterns/Proposal.js.map +1 -0
  57. package/dist/patterns/RequestList.d.ts +136 -0
  58. package/dist/patterns/RequestList.js +169 -0
  59. package/dist/patterns/RequestList.js.map +1 -0
  60. package/dist/relay/Call.d.ts +1 -1
  61. package/dist/relay/Call.js +1 -1
  62. package/dist/relay/Message.d.ts +1 -1
  63. package/dist/relay/Message.js +1 -1
  64. package/dist/relay/RelayClient.d.ts +0 -2
  65. package/dist/relay/RelayClient.js.map +1 -1
  66. package/dist/relay/RelayEvent.d.ts +3 -3
  67. package/dist/relay/RelayEvent.js +3 -3
  68. package/dist/relay/closedSets.d.ts +10 -10
  69. package/dist/relay/closedSets.js +2 -2
  70. package/dist/relay/types.d.ts +1 -1
  71. package/dist/rest/base/CrudResource.d.ts +1 -1
  72. package/dist/rest/base/CrudResource.js +1 -1
  73. package/dist/skills/SkillBase.d.ts +26 -3
  74. package/dist/skills/SkillBase.js +14 -3
  75. package/dist/skills/SkillBase.js.map +1 -1
  76. package/dist/speech/numbers.d.ts +66 -0
  77. package/dist/speech/numbers.js +281 -0
  78. package/dist/speech/numbers.js.map +1 -0
  79. package/dist/speech/spelling.d.ts +71 -0
  80. package/dist/speech/spelling.js +294 -0
  81. package/dist/speech/spelling.js.map +1 -0
  82. package/dist/testing/CallSimulator.d.ts +281 -0
  83. package/dist/testing/CallSimulator.js +666 -0
  84. package/dist/testing/CallSimulator.js.map +1 -0
  85. package/docs/agent-guide.md +4 -4
  86. package/docs/api-reference.md +285 -28
  87. package/docs/architecture.md +8 -4
  88. package/docs/cli-guide.md +2 -0
  89. package/docs/contexts-guide.md +47 -4
  90. package/docs/conversation_patterns.md +257 -0
  91. package/docs/mcp_integration.md +1 -1
  92. package/docs/pgi_agent_guide.md +2 -1
  93. package/docs/programmatically_governed_inference.md +2 -2
  94. package/docs/swaig-reference.md +95 -3
  95. package/docs/swml_service_guide.md +31 -6
  96. package/package.json +3 -1
@@ -4,8 +4,60 @@
4
4
  * Contexts contain ordered Steps, each with prompt text/POM sections,
5
5
  * completion criteria, function restrictions, and navigation rules.
6
6
  */
7
+ import { getLogger } from './Logger.js';
8
+ import { RESERVED_FUNCTION_NAMES } from './SemanticGate.js';
7
9
  const MAX_CONTEXTS = 50;
8
10
  const MAX_STEPS_PER_CONTEXT = 100;
11
+ const log = getLogger('contexts');
12
+ /** The most digits an expected answer can name. */
13
+ export const MAX_EXPECTED_DIGITS = 64;
14
+ /**
15
+ * An `expected_answer` as the platform reads it: `{ digits: N }`, or
16
+ * `{ min_digits: a, max_digits: b }` with a at most b, each count from 1 to
17
+ * 64. The platform logs and ignores any other shape.
18
+ * @param digits - The exact number of digits.
19
+ * @param opts - Or, without `digits`, the fewest and most digits.
20
+ * @returns The expected answer.
21
+ * @throws {Error} For a shape or count the platform would ignore.
22
+ */
23
+ export function expectedAnswer(digits, opts = {}) {
24
+ const count = (name, value) => {
25
+ if (!Number.isInteger(value) ||
26
+ value < 1 ||
27
+ value > MAX_EXPECTED_DIGITS) {
28
+ throw new Error(`${name} must be a whole number from 1 to ${MAX_EXPECTED_DIGITS}, got ${JSON.stringify(value)}`);
29
+ }
30
+ return value;
31
+ };
32
+ const { minDigits, maxDigits } = opts;
33
+ if (digits !== undefined && digits !== null) {
34
+ if (minDigits !== undefined || maxDigits !== undefined) {
35
+ throw new Error('expected_answer takes digits, or min_digits and max_digits, not both');
36
+ }
37
+ return { digits: count('digits', digits) };
38
+ }
39
+ if (minDigits === undefined || maxDigits === undefined) {
40
+ throw new Error('expected_answer needs digits, or both min_digits and max_digits');
41
+ }
42
+ const low = count('min_digits', minDigits);
43
+ const high = count('max_digits', maxDigits);
44
+ if (low > high)
45
+ throw new Error(`min_digits (${low}) must be at most max_digits (${high})`);
46
+ return { min_digits: low, max_digits: high };
47
+ }
48
+ /** A given expected_answer object, checked by the platform's rules. */
49
+ function checkExpectedAnswer(value) {
50
+ const keys = new Set(['digits', 'min_digits', 'max_digits']);
51
+ if (typeof value !== 'object' ||
52
+ value === null ||
53
+ Array.isArray(value) ||
54
+ Object.keys(value).length === 0 ||
55
+ Object.keys(value).some((k) => !keys.has(k))) {
56
+ throw new Error('expected_answer must be {"digits": N} or {"min_digits": a, "max_digits": b}');
57
+ }
58
+ const v = value;
59
+ return expectedAnswer(v['digits'], { minDigits: v['min_digits'], maxDigits: v['max_digits'] });
60
+ }
9
61
  /**
10
62
  * Valid values for a step's or context's `history` visibility mode.
11
63
  *
@@ -16,8 +68,11 @@ const MAX_STEPS_PER_CONTEXT = 100;
16
68
  * - `hide`: prior instructions hidden **and** the prior dialogue pulled
17
69
  * out of the model's context. The only way back in is an explicit
18
70
  * `${step_history.*}` reference in the new prompt.
71
+ * - `isolate`: like `hide`, but only while the agent is in this step: the
72
+ * earlier dialogue returns when the step is left, and the earlier step
73
+ * instructions stay cleared.
19
74
  */
20
- export const HISTORY_MODES = ['keep', 'default', 'hide'];
75
+ export const HISTORY_MODES = ['keep', 'default', 'hide', 'isolate'];
21
76
  function validateHistory(mode) {
22
77
  if (!HISTORY_MODES.includes(mode)) {
23
78
  throw new Error(`history must be one of ${JSON.stringify(HISTORY_MODES)}, got ${JSON.stringify(mode)}`);
@@ -65,9 +120,15 @@ export class GatherQuestion {
65
120
  * unset — it is emitted to SWML so it can override an isolated gather.
66
121
  */
67
122
  isolated;
123
+ /**
124
+ * The number of digits the answer has, for the recognizer: while this
125
+ * question is asked, it replaces the step's expected answer.
126
+ */
127
+ expectedAnswer;
68
128
  /**
69
129
  * Creates a new GatherQuestion.
70
- * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions/isolated.
130
+ * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions/isolated/expectedAnswer.
131
+ * @throws {Error} For an `expectedAnswer` the platform would ignore.
71
132
  */
72
133
  constructor(opts) {
73
134
  this.key = opts.key;
@@ -79,6 +140,9 @@ export class GatherQuestion {
79
140
  // Tri-state: undefined means "inherit the gather_info default". Do NOT
80
141
  // collapse to a boolean — `false` must survive to the wire.
81
142
  this.isolated = opts.isolated;
143
+ if (opts.expectedAnswer !== undefined) {
144
+ this.expectedAnswer = checkExpectedAnswer(opts.expectedAnswer);
145
+ }
82
146
  }
83
147
  /**
84
148
  * Serializes this question to a plain object for SWML output.
@@ -97,6 +161,8 @@ export class GatherQuestion {
97
161
  // Emitted even when false, so it can override an isolated gather.
98
162
  if (this.isolated !== undefined && this.isolated !== null)
99
163
  d['isolated'] = this.isolated;
164
+ if (this.expectedAnswer !== undefined)
165
+ d['expected_answer'] = { ...this.expectedAnswer };
100
166
  return d;
101
167
  }
102
168
  /**
@@ -181,6 +247,8 @@ export class Step {
181
247
  text = null;
182
248
  stepCriteria = null;
183
249
  functions = null;
250
+ /** The recognizer's hint for a number the caller is asked for. */
251
+ _expectedAnswer = null;
184
252
  validSteps = null;
185
253
  validContexts = null;
186
254
  sections = [];
@@ -408,6 +476,78 @@ export class Step {
408
476
  getStepValidContexts() {
409
477
  return this.validContexts;
410
478
  }
479
+ /**
480
+ * Tell the recognizer how many digits the caller's answer in this step has,
481
+ * such as a ZIP code or a PIN.
482
+ *
483
+ * The recognizer ends its wait for a number once the caller has said that
484
+ * many digits. A gather question's own expected answer replaces this while
485
+ * that question is asked. Pass `digits` for an exact count, or `minDigits`
486
+ * and `maxDigits` for a range, each from 1 to 64. Sent as `expected_answer`;
487
+ * it needs a platform release that has it.
488
+ * @param digits - The exact number of digits.
489
+ * @param opts - Or, without `digits`, the fewest and most digits.
490
+ * @returns This step for chaining.
491
+ * @throws {Error} For a count or combination the platform would ignore.
492
+ */
493
+ setExpectedAnswer(digits, opts = {}) {
494
+ this._expectedAnswer = expectedAnswer(digits, opts);
495
+ return this;
496
+ }
497
+ /**
498
+ * Whether this step sets its own function list (an array or a string
499
+ * sentinel such as `'none'`), rather than keeping the one before it.
500
+ * @internal
501
+ */
502
+ _hasFunctionList() {
503
+ return this.functions !== null;
504
+ }
505
+ /**
506
+ * The step's own function list: null when it inherits the list before it,
507
+ * empty for `'none'`.
508
+ * @internal
509
+ */
510
+ _offeredFunctions() {
511
+ if (Array.isArray(this.functions))
512
+ return [...this.functions];
513
+ return this.functions === 'none' ? [] : null;
514
+ }
515
+ /**
516
+ * Whether the step has a reset, which makes it terminal.
517
+ * @internal
518
+ */
519
+ _hasReset() {
520
+ return (this.resetSystemPrompt !== null ||
521
+ this.resetUserPrompt !== null ||
522
+ this.resetConsolidate ||
523
+ this.resetFullReset);
524
+ }
525
+ /**
526
+ * What the model reads in this step, as `[where, text, tools also offered
527
+ * there]`: its text, its criteria, and its gather questions.
528
+ * @internal
529
+ */
530
+ _modelTexts() {
531
+ let text = '';
532
+ try {
533
+ text = this.renderText();
534
+ }
535
+ catch {
536
+ // A step without text fails validation on its own
537
+ }
538
+ const texts = [
539
+ ['text', text, []],
540
+ ['criteria', this.stepCriteria ?? '', []],
541
+ ];
542
+ for (const q of this.gatherInfo?.getQuestions() ?? []) {
543
+ texts.push([
544
+ `gather question ${q.key}`,
545
+ `${q.question} ${q.prompt ?? ''}`,
546
+ q.functions ?? [],
547
+ ]);
548
+ }
549
+ return texts;
550
+ }
411
551
  /**
412
552
  * Returns this step's function whitelist as an array of tool NAMES to
413
553
  * validate, or null when there is nothing to validate. A string value
@@ -430,7 +570,11 @@ export class Step {
430
570
  return this;
431
571
  }
432
572
  /**
433
- * Sets the system prompt to use when resetting context at this step.
573
+ * Set the system prompt this step's reset loads.
574
+ *
575
+ * A step with any reset setting is terminal: when the call enters it, the
576
+ * platform runs the reset in place of the step's text, and step mode ends
577
+ * there. Use it for a step that hands the call over to a new prompt.
434
578
  * @param systemPrompt - The replacement system prompt text.
435
579
  * @returns This step for chaining.
436
580
  */
@@ -439,7 +583,11 @@ export class Step {
439
583
  return this;
440
584
  }
441
585
  /**
442
- * Sets the user prompt to use when resetting context at this step.
586
+ * Set the user message this step's reset adds.
587
+ *
588
+ * A step with any reset setting is terminal: when the call enters it, the
589
+ * platform runs the reset in place of the step's text, and step mode ends
590
+ * there. Use it for a step that hands the call over to a new prompt.
443
591
  * @param userPrompt - The replacement user prompt text.
444
592
  * @returns This step for chaining.
445
593
  */
@@ -448,7 +596,11 @@ export class Step {
448
596
  return this;
449
597
  }
450
598
  /**
451
- * Sets whether to consolidate conversation history when resetting at this step.
599
+ * Set whether this step's reset consolidates the conversation into a summary.
600
+ *
601
+ * A step with any reset setting is terminal: when the call enters it, the
602
+ * platform runs the reset in place of the step's text, and step mode ends
603
+ * there. Use it for a step that hands the call over to a new prompt.
452
604
  * @param consolidate - Whether to consolidate.
453
605
  * @returns This step for chaining.
454
606
  */
@@ -457,7 +609,12 @@ export class Step {
457
609
  return this;
458
610
  }
459
611
  /**
460
- * Sets whether to perform a full conversation reset at this step.
612
+ * Set whether this step's reset replaces the system prompt, seeded with the
613
+ * consolidated summary, rather than adding to it.
614
+ *
615
+ * A step with any reset setting is terminal: when the call enters it, the
616
+ * platform runs the reset in place of the step's text, and step mode ends
617
+ * there. Use it for a step that hands the call over to a new prompt.
461
618
  * @param fullReset - Whether to fully reset.
462
619
  * @returns This step for chaining.
463
620
  */
@@ -480,8 +637,16 @@ export class Step {
480
637
  * - `"hide"`: hide the prior instructions *and* pull the prior dialogue
481
638
  * out of the model's context. Pair it with a `${step_history.*}`
482
639
  * reference in this step's text to choose exactly what comes back.
640
+ * - `"isolate"`: like `"hide"` (the earlier dialogue leaves the model's
641
+ * context and the earlier step instructions are cleared), but only
642
+ * while the agent is in this step. When the agent leaves it, the
643
+ * earlier dialogue comes back and this step's own turns stay; the
644
+ * earlier instructions stay cleared, and what an earlier `"hide"` step
645
+ * hid stays hidden. Entering the step again isolates it again. Use it
646
+ * for a step that must see nothing else, such as one that reads back a
647
+ * confirmation. A platform without isolate treats it as `"default"`.
483
648
  * @returns This step for chaining.
484
- * @throws {Error} If `history` is not one of the three modes.
649
+ * @throws {Error} If `history` is not one of these modes.
485
650
  */
486
651
  setHistory(history) {
487
652
  this._history = validateHistory(history);
@@ -528,6 +693,8 @@ export class Step {
528
693
  d.skip_to_next_step = true;
529
694
  if (this._history !== null)
530
695
  d.history = this._history;
696
+ if (this._expectedAnswer !== null)
697
+ d.expected_answer = { ...this._expectedAnswer };
531
698
  const reset = {};
532
699
  if (this.resetSystemPrompt !== null)
533
700
  reset.system_prompt = this.resetSystemPrompt;
@@ -720,8 +887,9 @@ export class Context {
720
887
  * Mark this context as isolated — entering it wipes conversation history.
721
888
  *
722
889
  * When `isolated=true` and the context is entered via change_context, the
723
- * runtime wipes the conversation array. The model starts fresh with only
724
- * the new context's systemPrompt + step instructions, with no memory of
890
+ * runtime calls ai_conversation_restart(), which drops every conversation
891
+ * entry but the first, the base system prompt. The model starts fresh with
892
+ * the base prompt and the new context's step instructions, with no memory of
725
893
  * prior turns.
726
894
  *
727
895
  * EXCEPTION — `reset` overrides the wipe:
@@ -851,9 +1019,9 @@ export class Context {
851
1019
  * A step's own `setHistory()` overrides this. See {@link Step.setHistory}
852
1020
  * for what each mode does.
853
1021
  *
854
- * @param history - One of `"keep"`, `"default"`, or `"hide"`.
1022
+ * @param history - One of `"keep"`, `"default"`, `"hide"`, or `"isolate"`.
855
1023
  * @returns This context for chaining.
856
- * @throws {Error} If `history` is not one of the three modes.
1024
+ * @throws {Error} If `history` is not one of these modes.
857
1025
  */
858
1026
  setHistory(history) {
859
1027
  this._history = validateHistory(history);
@@ -889,6 +1057,28 @@ export class Context {
889
1057
  return null;
890
1058
  return this.renderSections(this.systemPromptSections);
891
1059
  }
1060
+ /**
1061
+ * The context's prompt, which goes before every step's text.
1062
+ * @internal
1063
+ */
1064
+ _modelPrompt() {
1065
+ return this.renderPrompt();
1066
+ }
1067
+ /**
1068
+ * The reset settings that do nothing because the context has no system
1069
+ * prompt: the platform runs a context's reset only with one.
1070
+ * @internal
1071
+ */
1072
+ _inertResetSettings() {
1073
+ if (this.renderSystemPrompt() !== null)
1074
+ return [];
1075
+ const settings = [
1076
+ ['consolidate', this._consolidate],
1077
+ ['full_reset', this._fullReset],
1078
+ ['user_prompt', this._userPrompt],
1079
+ ];
1080
+ return settings.filter(([, value]) => value).map(([name]) => name);
1081
+ }
892
1082
  renderSections(sections) {
893
1083
  const parts = [];
894
1084
  for (const s of sections) {
@@ -971,8 +1161,8 @@ export class Context {
971
1161
  * - `next_step(step: enum)` — present when validSteps is set
972
1162
  * - `change_context(context: enum)` — present when validContexts is set
973
1163
  *
974
- * Their `enum` schemas are rewritten on every turn to match whatever
975
- * validSteps / validContexts apply to the current step. You do NOT need
1164
+ * Their `enum` schemas are rewritten when a step loads, to match whatever
1165
+ * validSteps / validContexts apply to that step. You do NOT need
976
1166
  * to define these tools yourself; they appear automatically.
977
1167
  *
978
1168
  * A third native tool — `gather_submit` — is injected during gather_info
@@ -1032,6 +1222,12 @@ export class Context {
1032
1222
  export class ContextBuilder {
1033
1223
  contexts = new Map();
1034
1224
  contextOrder = [];
1225
+ /**
1226
+ * Tools already reported as offered by no step, so a render on every request
1227
+ * doesn't repeat it. The agent shares its own set, so its per-request copies
1228
+ * don't repeat it either.
1229
+ */
1230
+ unofferedWarned = new Set();
1035
1231
  agent = null;
1036
1232
  /**
1037
1233
  * Attach an agent reference so validate() can check user tool names
@@ -1043,6 +1239,15 @@ export class ContextBuilder {
1043
1239
  this.agent = agent;
1044
1240
  return this;
1045
1241
  }
1242
+ /**
1243
+ * Record the tools reported as offered by no step in `warned`, a set the
1244
+ * agent keeps for itself and its per-request copies.
1245
+ * @internal
1246
+ */
1247
+ _shareUnofferedWarnings(warned) {
1248
+ this.unofferedWarned = warned;
1249
+ return this;
1250
+ }
1046
1251
  /**
1047
1252
  * Removes all contexts, returning the builder to its initial state.
1048
1253
  * Use this in a dynamic config callback when you need to rebuild
@@ -1264,6 +1469,148 @@ export class ContextBuilder {
1264
1469
  `Registered tools: [${knownNames.map((n) => `'${n}'`).join(', ')}]. ` +
1265
1470
  `Fix the tool name or register the missing tool.`);
1266
1471
  }
1472
+ const names = registered
1473
+ .map((t) => t?.name)
1474
+ .filter((n) => typeof n === 'string');
1475
+ this.warnUnofferedTools(names);
1476
+ const getFunction = this.agent.getFunction;
1477
+ this.warnToolMentions(names, (name) => typeof getFunction === 'function' ? getFunction.call(this.agent, name) : undefined);
1478
+ }
1479
+ this.warnInertResets();
1480
+ }
1481
+ /**
1482
+ * The steps whose function list offers `functionName`, as
1483
+ * `[context, step]` pairs in order, including a gather question's functions.
1484
+ *
1485
+ * A step without `setFunctions()` keeps whatever was active before it, so it
1486
+ * isn't counted: what it offers depends on the step the call came from. The
1487
+ * platform's reply to a call of a tool the current step doesn't offer names
1488
+ * the same steps.
1489
+ * @param functionName - The function's name.
1490
+ * @returns The `[context name, step name]` pairs, empty when no step lists it.
1491
+ */
1492
+ stepsOffering(functionName) {
1493
+ const found = [];
1494
+ for (const contextName of this.contextOrder) {
1495
+ const ctx = this.contexts.get(contextName);
1496
+ if (!ctx)
1497
+ continue;
1498
+ for (const [stepName, step] of ctx.getSteps()) {
1499
+ if (stepOffers(step, functionName))
1500
+ found.push([contextName, stepName]);
1501
+ }
1502
+ }
1503
+ return found;
1504
+ }
1505
+ /**
1506
+ * Log, once each, reset settings that don't do what they read as: a step
1507
+ * with a reset is terminal, so its text never runs; and a context's
1508
+ * consolidate, full_reset and user_prompt act only with a system prompt,
1509
+ * whose presence runs the context's reset.
1510
+ */
1511
+ warnInertResets() {
1512
+ for (const contextName of this.contextOrder) {
1513
+ const ctx = this.contexts.get(contextName);
1514
+ if (!ctx)
1515
+ continue;
1516
+ const inert = ctx._inertResetSettings();
1517
+ const contextKey = JSON.stringify(['context', contextName]);
1518
+ if (inert.length > 0 && !this.unofferedWarned.has(contextKey)) {
1519
+ this.unofferedWarned.add(contextKey);
1520
+ log.warn('context_reset_without_system_prompt', {
1521
+ context: contextName,
1522
+ settings: inert,
1523
+ hint: "The platform runs a context's reset only when it has a system_prompt, " +
1524
+ 'so these do nothing; add setSystemPrompt().',
1525
+ });
1526
+ }
1527
+ for (const [stepName, step] of ctx.getSteps()) {
1528
+ const key = JSON.stringify(['step', contextName, stepName]);
1529
+ if (this.unofferedWarned.has(key) || !step._hasReset())
1530
+ continue;
1531
+ this.unofferedWarned.add(key);
1532
+ log.warn('step_reset_is_terminal', {
1533
+ context: contextName,
1534
+ step: stepName,
1535
+ hint: 'A step with a reset is terminal: the platform runs the reset in place ' +
1536
+ 'of its text and step mode ends there.',
1537
+ });
1538
+ }
1539
+ }
1540
+ }
1541
+ /**
1542
+ * Log, once each, a registered tool named where the step doesn't offer it:
1543
+ * in its text, its criteria, its context's prompt (which goes before every
1544
+ * step's text), a gather question, or a gate's output on one of its tools.
1545
+ * The model reads the name and may call a tool it doesn't have. A step
1546
+ * without a function list is skipped: what it offers depends on the step
1547
+ * before it.
1548
+ */
1549
+ warnToolMentions(registered, definitionOf) {
1550
+ const tools = registered.filter((name) => !RESERVED_FUNCTION_NAMES.has(name) && !RESERVED_NATIVE_TOOL_NAMES.has(name));
1551
+ if (tools.length === 0)
1552
+ return;
1553
+ for (const contextName of this.contextOrder) {
1554
+ const ctx = this.contexts.get(contextName);
1555
+ if (!ctx)
1556
+ continue;
1557
+ const prompt = ctx._modelPrompt() ?? '';
1558
+ for (const [stepName, step] of ctx.getSteps()) {
1559
+ const list = step._offeredFunctions();
1560
+ if (list === null)
1561
+ continue;
1562
+ const offered = new Set(list);
1563
+ const texts = step._modelTexts();
1564
+ texts.splice(2, 0, ['context prompt', prompt, []]);
1565
+ for (const tool of [...offered].sort()) {
1566
+ for (const [gate, output] of gateTexts(definitionOf(tool))) {
1567
+ texts.push([`${tool} gate ${gate}`, output, []]);
1568
+ }
1569
+ }
1570
+ for (const [where, text, also] of texts) {
1571
+ const named = [...namedTools(text, tools)]
1572
+ .filter((t) => !offered.has(t) && !also.includes(t))
1573
+ .sort();
1574
+ for (const tool of named) {
1575
+ const key = JSON.stringify([contextName, stepName, where, tool]);
1576
+ if (this.unofferedWarned.has(key))
1577
+ continue;
1578
+ this.unofferedWarned.add(key);
1579
+ log.warn('tool_named_but_not_offered', {
1580
+ context: contextName,
1581
+ step: stepName,
1582
+ where,
1583
+ function: tool,
1584
+ hint: "The model reads this name in a step that doesn't offer the tool. " +
1585
+ "Name only the step's own tools; move the work to the step that offers it.",
1586
+ });
1587
+ }
1588
+ }
1589
+ }
1590
+ }
1591
+ }
1592
+ /**
1593
+ * Log, once per tool, a tool no step can offer: when every step lists its
1594
+ * functions and none lists it, the model never gets it, unless a function
1595
+ * result turns it on.
1596
+ */
1597
+ warnUnofferedTools(registered) {
1598
+ const steps = [...this.contexts.values()].flatMap((c) => [...c.getSteps().values()]);
1599
+ if (steps.length === 0 || steps.some((step) => !step._hasFunctionList()))
1600
+ return;
1601
+ for (const name of registered) {
1602
+ if (this.unofferedWarned.has(name) ||
1603
+ RESERVED_FUNCTION_NAMES.has(name) ||
1604
+ RESERVED_NATIVE_TOOL_NAMES.has(name) ||
1605
+ this.stepsOffering(name).length > 0) {
1606
+ continue;
1607
+ }
1608
+ this.unofferedWarned.add(name);
1609
+ log.warn('tool_offered_by_no_step', {
1610
+ function: name,
1611
+ hint: 'Every step lists its functions and none lists this one, so the model never gets it ' +
1612
+ 'unless a function result turns it on (toggle_functions). Add it to the steps that need it.',
1613
+ });
1267
1614
  }
1268
1615
  }
1269
1616
  /**
@@ -1295,4 +1642,66 @@ export class ContextBuilder {
1295
1642
  export function createSimpleContext(name = 'default') {
1296
1643
  return new Context(name);
1297
1644
  }
1645
+ /**
1646
+ * The tool names `text` names.
1647
+ *
1648
+ * A name with an underscore, such as `place_order`, counts as a whole word
1649
+ * anywhere. A one-word name, such as `help`, counts only in backticks or before
1650
+ * "(", since it's also an ordinary word.
1651
+ *
1652
+ * @param text - The text: a step's, a prompt's or a tool result's.
1653
+ * @param tools - The tool names to look for.
1654
+ * @returns The names it finds.
1655
+ */
1656
+ export function namedTools(text, tools) {
1657
+ const found = new Set();
1658
+ if (!text)
1659
+ return found;
1660
+ for (const name of tools) {
1661
+ const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
1662
+ const pattern = name.includes('_')
1663
+ ? new RegExp(`(?<![A-Za-z0-9_])${escaped}(?![A-Za-z0-9_])`)
1664
+ : new RegExp(`\`${escaped}\`|(?<![A-Za-z0-9_])${escaped}\\(`);
1665
+ if (pattern.test(text))
1666
+ found.add(name);
1667
+ }
1668
+ return found;
1669
+ }
1670
+ /** Each gate's output text on a tool, as `[gate id, text]`. */
1671
+ function gateTexts(definition) {
1672
+ let gates;
1673
+ if (definition && typeof definition === 'object') {
1674
+ const fields = definition.extraFields;
1675
+ gates = fields ? fields['gates'] : definition['gates'];
1676
+ }
1677
+ if (!Array.isArray(gates))
1678
+ return [];
1679
+ const texts = [];
1680
+ gates.forEach((gate, index) => {
1681
+ if (!gate || typeof gate !== 'object' || Array.isArray(gate))
1682
+ return;
1683
+ const g = gate;
1684
+ const gateId = String(g['id'] ?? `gate_${index + 1}`);
1685
+ for (const key of ['on_fail', 'on_unclear']) {
1686
+ const output = g[key];
1687
+ let response = output && typeof output === 'object'
1688
+ ? output['response']
1689
+ : undefined;
1690
+ if (response && typeof response === 'object') {
1691
+ const r = response;
1692
+ response = ['tool_result', 'tool_prompt'].map((k) => String(r[k] ?? '')).join(' ');
1693
+ }
1694
+ if (typeof response === 'string' && response)
1695
+ texts.push([`${gateId} ${key}`, response]);
1696
+ }
1697
+ });
1698
+ return texts;
1699
+ }
1700
+ /** Whether a step's own function list, or one of its gather questions', names `functionName`. */
1701
+ function stepOffers(step, functionName) {
1702
+ if (step.getFunctions()?.includes(functionName))
1703
+ return true;
1704
+ const gather = step.getGatherInfo();
1705
+ return !!gather && gather.getQuestions().some((q) => q.functions?.includes(functionName));
1706
+ }
1298
1707
  //# sourceMappingURL=ContextBuilder.js.map