@signalwire/sdk 3.7.2 → 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.
- package/CHANGELOG.md +154 -0
- package/README.md +1 -0
- package/dist/AgentBase.d.ts +107 -2
- package/dist/AgentBase.js +259 -13
- package/dist/AgentBase.js.map +1 -1
- package/dist/AiEvents.d.ts +70 -0
- package/dist/AiEvents.js +94 -0
- package/dist/AiEvents.js.map +1 -0
- package/dist/ContextBuilder.d.ts +181 -9
- package/dist/ContextBuilder.js +407 -9
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/FunctionResult.d.ts +129 -0
- package/dist/FunctionResult.js +170 -0
- package/dist/FunctionResult.js.map +1 -1
- package/dist/PostPrompt.d.ts +19 -0
- package/dist/PostPrompt.js +43 -0
- package/dist/PostPrompt.js.map +1 -1
- package/dist/SWMLService.d.ts +97 -1
- package/dist/SWMLService.js +129 -2
- package/dist/SWMLService.js.map +1 -1
- package/dist/SemanticGate.d.ts +61 -1
- package/dist/SemanticGate.js +108 -15
- package/dist/SemanticGate.js.map +1 -1
- package/dist/SwaigFunction.d.ts +85 -9
- package/dist/SwaigFunction.js +214 -58
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/ToolMiddleware.d.ts +82 -0
- package/dist/ToolMiddleware.js +131 -0
- package/dist/ToolMiddleware.js.map +1 -0
- package/dist/TypeInference.d.ts +1 -1
- package/dist/TypeInference.js.map +1 -1
- package/dist/cli/tsdocs/api-index.json +1 -1
- package/dist/cli/tsdocs/topics.js +24 -4
- package/dist/cli/tsdocs/topics.js.map +1 -1
- package/dist/index.d.ts +22 -8
- package/dist/index.js +15 -5
- package/dist/index.js.map +1 -1
- package/dist/llms.txt +1 -0
- package/dist/patterns/Proposal.d.ts +146 -0
- package/dist/patterns/Proposal.js +212 -0
- package/dist/patterns/Proposal.js.map +1 -0
- package/dist/patterns/RequestList.d.ts +136 -0
- package/dist/patterns/RequestList.js +169 -0
- package/dist/patterns/RequestList.js.map +1 -0
- package/dist/skills/SkillBase.d.ts +24 -1
- package/dist/skills/SkillBase.js +12 -1
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/speech/numbers.d.ts +66 -0
- package/dist/speech/numbers.js +281 -0
- package/dist/speech/numbers.js.map +1 -0
- package/dist/speech/spelling.d.ts +71 -0
- package/dist/speech/spelling.js +294 -0
- package/dist/speech/spelling.js.map +1 -0
- package/dist/testing/CallSimulator.d.ts +281 -0
- package/dist/testing/CallSimulator.js +666 -0
- package/dist/testing/CallSimulator.js.map +1 -0
- package/docs/agent-guide.md +2 -2
- package/docs/api-reference.md +277 -20
- package/docs/architecture.md +8 -4
- package/docs/cli-guide.md +2 -0
- package/docs/contexts-guide.md +45 -3
- package/docs/conversation_patterns.md +257 -0
- package/docs/mcp_integration.md +1 -1
- package/docs/programmatically_governed_inference.md +1 -1
- package/docs/swaig-reference.md +95 -3
- package/package.json +1 -1
package/dist/ContextBuilder.js
CHANGED
|
@@ -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
|
*
|
|
@@ -68,9 +120,15 @@ export class GatherQuestion {
|
|
|
68
120
|
* unset — it is emitted to SWML so it can override an isolated gather.
|
|
69
121
|
*/
|
|
70
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;
|
|
71
128
|
/**
|
|
72
129
|
* Creates a new GatherQuestion.
|
|
73
|
-
* @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.
|
|
74
132
|
*/
|
|
75
133
|
constructor(opts) {
|
|
76
134
|
this.key = opts.key;
|
|
@@ -82,6 +140,9 @@ export class GatherQuestion {
|
|
|
82
140
|
// Tri-state: undefined means "inherit the gather_info default". Do NOT
|
|
83
141
|
// collapse to a boolean — `false` must survive to the wire.
|
|
84
142
|
this.isolated = opts.isolated;
|
|
143
|
+
if (opts.expectedAnswer !== undefined) {
|
|
144
|
+
this.expectedAnswer = checkExpectedAnswer(opts.expectedAnswer);
|
|
145
|
+
}
|
|
85
146
|
}
|
|
86
147
|
/**
|
|
87
148
|
* Serializes this question to a plain object for SWML output.
|
|
@@ -100,6 +161,8 @@ export class GatherQuestion {
|
|
|
100
161
|
// Emitted even when false, so it can override an isolated gather.
|
|
101
162
|
if (this.isolated !== undefined && this.isolated !== null)
|
|
102
163
|
d['isolated'] = this.isolated;
|
|
164
|
+
if (this.expectedAnswer !== undefined)
|
|
165
|
+
d['expected_answer'] = { ...this.expectedAnswer };
|
|
103
166
|
return d;
|
|
104
167
|
}
|
|
105
168
|
/**
|
|
@@ -184,6 +247,8 @@ export class Step {
|
|
|
184
247
|
text = null;
|
|
185
248
|
stepCriteria = null;
|
|
186
249
|
functions = null;
|
|
250
|
+
/** The recognizer's hint for a number the caller is asked for. */
|
|
251
|
+
_expectedAnswer = null;
|
|
187
252
|
validSteps = null;
|
|
188
253
|
validContexts = null;
|
|
189
254
|
sections = [];
|
|
@@ -411,6 +476,78 @@ export class Step {
|
|
|
411
476
|
getStepValidContexts() {
|
|
412
477
|
return this.validContexts;
|
|
413
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
|
+
}
|
|
414
551
|
/**
|
|
415
552
|
* Returns this step's function whitelist as an array of tool NAMES to
|
|
416
553
|
* validate, or null when there is nothing to validate. A string value
|
|
@@ -433,7 +570,11 @@ export class Step {
|
|
|
433
570
|
return this;
|
|
434
571
|
}
|
|
435
572
|
/**
|
|
436
|
-
*
|
|
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.
|
|
437
578
|
* @param systemPrompt - The replacement system prompt text.
|
|
438
579
|
* @returns This step for chaining.
|
|
439
580
|
*/
|
|
@@ -442,7 +583,11 @@ export class Step {
|
|
|
442
583
|
return this;
|
|
443
584
|
}
|
|
444
585
|
/**
|
|
445
|
-
*
|
|
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.
|
|
446
591
|
* @param userPrompt - The replacement user prompt text.
|
|
447
592
|
* @returns This step for chaining.
|
|
448
593
|
*/
|
|
@@ -451,7 +596,11 @@ export class Step {
|
|
|
451
596
|
return this;
|
|
452
597
|
}
|
|
453
598
|
/**
|
|
454
|
-
*
|
|
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.
|
|
455
604
|
* @param consolidate - Whether to consolidate.
|
|
456
605
|
* @returns This step for chaining.
|
|
457
606
|
*/
|
|
@@ -460,7 +609,12 @@ export class Step {
|
|
|
460
609
|
return this;
|
|
461
610
|
}
|
|
462
611
|
/**
|
|
463
|
-
*
|
|
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.
|
|
464
618
|
* @param fullReset - Whether to fully reset.
|
|
465
619
|
* @returns This step for chaining.
|
|
466
620
|
*/
|
|
@@ -539,6 +693,8 @@ export class Step {
|
|
|
539
693
|
d.skip_to_next_step = true;
|
|
540
694
|
if (this._history !== null)
|
|
541
695
|
d.history = this._history;
|
|
696
|
+
if (this._expectedAnswer !== null)
|
|
697
|
+
d.expected_answer = { ...this._expectedAnswer };
|
|
542
698
|
const reset = {};
|
|
543
699
|
if (this.resetSystemPrompt !== null)
|
|
544
700
|
reset.system_prompt = this.resetSystemPrompt;
|
|
@@ -731,8 +887,9 @@ export class Context {
|
|
|
731
887
|
* Mark this context as isolated — entering it wipes conversation history.
|
|
732
888
|
*
|
|
733
889
|
* When `isolated=true` and the context is entered via change_context, the
|
|
734
|
-
* runtime
|
|
735
|
-
* the
|
|
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
|
|
736
893
|
* prior turns.
|
|
737
894
|
*
|
|
738
895
|
* EXCEPTION — `reset` overrides the wipe:
|
|
@@ -900,6 +1057,28 @@ export class Context {
|
|
|
900
1057
|
return null;
|
|
901
1058
|
return this.renderSections(this.systemPromptSections);
|
|
902
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
|
+
}
|
|
903
1082
|
renderSections(sections) {
|
|
904
1083
|
const parts = [];
|
|
905
1084
|
for (const s of sections) {
|
|
@@ -982,8 +1161,8 @@ export class Context {
|
|
|
982
1161
|
* - `next_step(step: enum)` — present when validSteps is set
|
|
983
1162
|
* - `change_context(context: enum)` — present when validContexts is set
|
|
984
1163
|
*
|
|
985
|
-
* Their `enum` schemas are rewritten
|
|
986
|
-
* validSteps / validContexts apply to
|
|
1164
|
+
* Their `enum` schemas are rewritten when a step loads, to match whatever
|
|
1165
|
+
* validSteps / validContexts apply to that step. You do NOT need
|
|
987
1166
|
* to define these tools yourself; they appear automatically.
|
|
988
1167
|
*
|
|
989
1168
|
* A third native tool — `gather_submit` — is injected during gather_info
|
|
@@ -1043,6 +1222,12 @@ export class Context {
|
|
|
1043
1222
|
export class ContextBuilder {
|
|
1044
1223
|
contexts = new Map();
|
|
1045
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();
|
|
1046
1231
|
agent = null;
|
|
1047
1232
|
/**
|
|
1048
1233
|
* Attach an agent reference so validate() can check user tool names
|
|
@@ -1054,6 +1239,15 @@ export class ContextBuilder {
|
|
|
1054
1239
|
this.agent = agent;
|
|
1055
1240
|
return this;
|
|
1056
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
|
+
}
|
|
1057
1251
|
/**
|
|
1058
1252
|
* Removes all contexts, returning the builder to its initial state.
|
|
1059
1253
|
* Use this in a dynamic config callback when you need to rebuild
|
|
@@ -1275,6 +1469,148 @@ export class ContextBuilder {
|
|
|
1275
1469
|
`Registered tools: [${knownNames.map((n) => `'${n}'`).join(', ')}]. ` +
|
|
1276
1470
|
`Fix the tool name or register the missing tool.`);
|
|
1277
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
|
+
});
|
|
1278
1614
|
}
|
|
1279
1615
|
}
|
|
1280
1616
|
/**
|
|
@@ -1306,4 +1642,66 @@ export class ContextBuilder {
|
|
|
1306
1642
|
export function createSimpleContext(name = 'default') {
|
|
1307
1643
|
return new Context(name);
|
|
1308
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
|
+
}
|
|
1309
1707
|
//# sourceMappingURL=ContextBuilder.js.map
|