@signalwire/sdk 3.5.0 → 3.6.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 +36 -0
- package/dist/AgentBase.d.ts +29 -0
- package/dist/AgentBase.js +84 -22
- package/dist/AgentBase.js.map +1 -1
- package/dist/DataMap.d.ts +28 -0
- package/dist/DataMap.js +43 -0
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +32 -0
- package/dist/FunctionResult.js +39 -0
- package/dist/FunctionResult.js.map +1 -1
- package/dist/SWMLService.d.ts +11 -1
- package/dist/SWMLService.js +21 -2
- package/dist/SWMLService.js.map +1 -1
- package/dist/SemanticGate.d.ts +183 -0
- package/dist/SemanticGate.js +533 -0
- package/dist/SemanticGate.js.map +1 -0
- package/dist/SwaigFunction.d.ts +29 -3
- package/dist/SwaigFunction.js +19 -3
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/cli/tsdocs/api-index.json +1 -1
- package/dist/cli/tsdocs/topics.js +4 -0
- package/dist/cli/tsdocs/topics.js.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/skills/SkillBase.d.ts +14 -1
- package/dist/skills/SkillBase.js.map +1 -1
- package/docs/api-reference.md +110 -3
- package/docs/datamap-guide.md +51 -4
- package/docs/swaig-reference.md +48 -0
- package/package.json +1 -1
|
@@ -0,0 +1,533 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Semantic gates: natural-language preconditions on a SWAIG function.
|
|
3
|
+
*
|
|
4
|
+
* A semantic gate is a yes/no question a decision model answers about the call
|
|
5
|
+
* right before the platform dispatches the function. Every gate on the function
|
|
6
|
+
* must pass for it to run. When one doesn't, the function isn't dispatched, and
|
|
7
|
+
* the model gets that gate's `on_fail` output instead, as if a data_map had
|
|
8
|
+
* returned it.
|
|
9
|
+
*
|
|
10
|
+
* The platform refuses the whole function when any of its gates is invalid, so
|
|
11
|
+
* the SDK checks gates by the platform's rules when a tool is defined, and
|
|
12
|
+
* throws instead of sending a function the platform would drop. A platform
|
|
13
|
+
* release without semantic gates ignores them and runs the function ungated.
|
|
14
|
+
*
|
|
15
|
+
* Python equivalent: `signalwire/core/semantic_gate.py`.
|
|
16
|
+
*/
|
|
17
|
+
import { FunctionResult } from './FunctionResult.js';
|
|
18
|
+
/** The most gates one function can carry. */
|
|
19
|
+
export const MAX_GATES = 8;
|
|
20
|
+
/** The longest gate question, in UTF-8 bytes. */
|
|
21
|
+
export const MAX_QUESTION_BYTES = 8192;
|
|
22
|
+
/** The longest `criteria.true` or `criteria.false`, in UTF-8 bytes. */
|
|
23
|
+
export const MAX_CRITERIA_BYTES = 2048;
|
|
24
|
+
/** The largest `on_fail` output, as compact JSON in UTF-8 bytes. */
|
|
25
|
+
export const MAX_ON_FAIL_BYTES = 8192;
|
|
26
|
+
const GATE_KEYS = new Set([
|
|
27
|
+
'id',
|
|
28
|
+
'question',
|
|
29
|
+
'criteria',
|
|
30
|
+
'threshold',
|
|
31
|
+
'on_fail',
|
|
32
|
+
]);
|
|
33
|
+
const GATE_ID = /^[A-Za-z0-9_]{1,64}$/;
|
|
34
|
+
const UNPAIRED_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
|
|
35
|
+
/**
|
|
36
|
+
* Hooks the platform calls itself, the function it intercepts by name, and the
|
|
37
|
+
* built-in function names: gates on any of them are refused.
|
|
38
|
+
*/
|
|
39
|
+
export const RESERVED_FUNCTION_NAMES = new Set([
|
|
40
|
+
'startup_hook',
|
|
41
|
+
'hangup_hook',
|
|
42
|
+
'check_for_input',
|
|
43
|
+
'end_call',
|
|
44
|
+
'hangup',
|
|
45
|
+
'check_time',
|
|
46
|
+
'wait_for_user',
|
|
47
|
+
'wait_seconds',
|
|
48
|
+
'adjust_response_latency',
|
|
49
|
+
'next_step',
|
|
50
|
+
'change_context',
|
|
51
|
+
'gather_submit',
|
|
52
|
+
'get_visual_input',
|
|
53
|
+
'get_ideal_strategy',
|
|
54
|
+
'pause_conversation',
|
|
55
|
+
]);
|
|
56
|
+
/**
|
|
57
|
+
* One semantic gate: a yes/no question about the call, and what the model gets
|
|
58
|
+
* when the answer isn't yes.
|
|
59
|
+
*
|
|
60
|
+
* The decision model sees the recent dialogue as `conversation`, the call's
|
|
61
|
+
* `global_data.semantic_state` as `semantic_state`, and the proposed call as
|
|
62
|
+
* `proposed_function`. Write each question as one proposition and name what
|
|
63
|
+
* it's about with those field names, in backticks. The model reads literally
|
|
64
|
+
* and doesn't do arithmetic or compare dates, so put a computed result in
|
|
65
|
+
* `semantic_state` instead of asking for it.
|
|
66
|
+
*
|
|
67
|
+
* The gate is checked when the tool that carries it is defined, not when it's
|
|
68
|
+
* built.
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* ```typescript
|
|
72
|
+
* new SemanticGate(
|
|
73
|
+
* 'Has the caller explicitly asked to cancel their account in `conversation`?',
|
|
74
|
+
* 0.95,
|
|
75
|
+
* new FunctionResult()
|
|
76
|
+
* .setToolResponse(
|
|
77
|
+
* 'cancel_account was not run.',
|
|
78
|
+
* 'Ask the caller to confirm that they want to cancel.',
|
|
79
|
+
* )
|
|
80
|
+
* .updateGlobalData({ cancel_attempted: true }),
|
|
81
|
+
* {
|
|
82
|
+
* id: 'explicit_request',
|
|
83
|
+
* trueMeans: 'The caller says they want to cancel.',
|
|
84
|
+
* falseMeans: 'The caller asked about cancelling, or said something else.',
|
|
85
|
+
* },
|
|
86
|
+
* );
|
|
87
|
+
* ```
|
|
88
|
+
*/
|
|
89
|
+
export class SemanticGate {
|
|
90
|
+
/** The yes/no question. */
|
|
91
|
+
question;
|
|
92
|
+
/** The probability of yes, above 0 and at most 1, at or above which the gate passes. */
|
|
93
|
+
threshold;
|
|
94
|
+
/** The gate's id, or undefined for the default `gate_<n>`. */
|
|
95
|
+
id;
|
|
96
|
+
/** What yes and no mean, keyed `true` and `false`. */
|
|
97
|
+
criteria;
|
|
98
|
+
/** The output the model gets when this is the first gate that fails. */
|
|
99
|
+
onFail;
|
|
100
|
+
/**
|
|
101
|
+
* @param question - The yes/no question, at most 8 KB. Its `${...}`
|
|
102
|
+
* variables are expanded from the call's global data when the gate is
|
|
103
|
+
* checked; `@{...}` functions are not.
|
|
104
|
+
* @param threshold - The probability of yes, above 0 and at most 1, at or
|
|
105
|
+
* above which the gate passes. Thresholds are calibrated per decision model
|
|
106
|
+
* version.
|
|
107
|
+
* @param onFail - What the model gets when this is the first gate that fails:
|
|
108
|
+
* the tool result text, a FunctionResult, or a data_map output object. A
|
|
109
|
+
* FunctionResult's response and actions are used; its `tool_prompt` becomes
|
|
110
|
+
* a system message after the tool result in the text pipeline, which OpenAI
|
|
111
|
+
* Realtime agents don't use. The actions run as written, without template
|
|
112
|
+
* expansion.
|
|
113
|
+
* @param opts - The gate's id, and what yes and no mean.
|
|
114
|
+
* @throws {Error} When `onFail` has no response: a blocked call must never
|
|
115
|
+
* read as a success.
|
|
116
|
+
*/
|
|
117
|
+
constructor(question, threshold, onFail, opts = {}) {
|
|
118
|
+
this.question = question;
|
|
119
|
+
this.threshold = threshold;
|
|
120
|
+
this.id = opts.id;
|
|
121
|
+
this.criteria = {};
|
|
122
|
+
if (opts.trueMeans !== undefined)
|
|
123
|
+
this.criteria.true = opts.trueMeans;
|
|
124
|
+
if (opts.falseMeans !== undefined)
|
|
125
|
+
this.criteria.false = opts.falseMeans;
|
|
126
|
+
this.onFail = onFailOutput(onFail);
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* The gate as the platform reads it.
|
|
130
|
+
* @returns The gate object: `id` (when set), `question`, `criteria` (when
|
|
131
|
+
* set), `threshold` and `on_fail`.
|
|
132
|
+
*/
|
|
133
|
+
toDict() {
|
|
134
|
+
const gate = {};
|
|
135
|
+
if (this.id !== undefined)
|
|
136
|
+
gate['id'] = this.id;
|
|
137
|
+
gate['question'] = this.question;
|
|
138
|
+
if (Object.keys(this.criteria).length > 0)
|
|
139
|
+
gate['criteria'] = { ...this.criteria };
|
|
140
|
+
gate['threshold'] = this.threshold;
|
|
141
|
+
gate['on_fail'] = deepCopy(this.onFail);
|
|
142
|
+
return gate;
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
/** Build an on_fail output object from a string, FunctionResult or object. */
|
|
146
|
+
function onFailOutput(onFail) {
|
|
147
|
+
if (onFail instanceof FunctionResult) {
|
|
148
|
+
const dict = onFail.toDict();
|
|
149
|
+
// toDict() fills in "Action completed." when there is no response; a
|
|
150
|
+
// blocked call must never read as a success, so the platform requires one.
|
|
151
|
+
const hasResponse = typeof dict['response'] === 'object' || onFail.response !== '';
|
|
152
|
+
if (!hasResponse) {
|
|
153
|
+
throw new Error("on_fail needs a response saying the function didn't run");
|
|
154
|
+
}
|
|
155
|
+
const output = { response: dict['response'] };
|
|
156
|
+
if (onFail.action.length > 0) {
|
|
157
|
+
output['action'] = onFail.action;
|
|
158
|
+
if (onFail.postProcess)
|
|
159
|
+
output['post_process'] = true;
|
|
160
|
+
}
|
|
161
|
+
return output;
|
|
162
|
+
}
|
|
163
|
+
if (typeof onFail === 'string') {
|
|
164
|
+
if (!onFail)
|
|
165
|
+
throw new Error("on_fail needs a response saying the function didn't run");
|
|
166
|
+
return { response: onFail };
|
|
167
|
+
}
|
|
168
|
+
return onFail;
|
|
169
|
+
}
|
|
170
|
+
function isPlainObject(value) {
|
|
171
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
172
|
+
}
|
|
173
|
+
function utf8Length(text) {
|
|
174
|
+
return Buffer.byteLength(text, 'utf8');
|
|
175
|
+
}
|
|
176
|
+
function deepCopy(value) {
|
|
177
|
+
return JSON.parse(JSON.stringify(value));
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* A value as the platform receives it: the JSON the SDK sends, so an optional
|
|
181
|
+
* key set to undefined is absent, while an explicit null stays null. A value
|
|
182
|
+
* JSON can't carry at the top level (undefined) is kept as is, for the checks
|
|
183
|
+
* to refuse.
|
|
184
|
+
*/
|
|
185
|
+
function wireForm(value) {
|
|
186
|
+
return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* The platform looks keys up the way cJSON_GetObjectItem does: without regard
|
|
190
|
+
* to case, and the first match wins.
|
|
191
|
+
*/
|
|
192
|
+
function isAscii(text) {
|
|
193
|
+
for (let i = 0; i < text.length; i++)
|
|
194
|
+
if (text.charCodeAt(i) > 0x7f)
|
|
195
|
+
return false;
|
|
196
|
+
return true;
|
|
197
|
+
}
|
|
198
|
+
function sameKey(name, key) {
|
|
199
|
+
// cJSON compares ASCII letters without case and every other byte exactly
|
|
200
|
+
return isAscii(name) && name.toLowerCase() === key;
|
|
201
|
+
}
|
|
202
|
+
function firstKey(object, key) {
|
|
203
|
+
// A key left undefined isn't in the JSON sent, so the platform never sees it
|
|
204
|
+
return Object.keys(object).find((name) => object[name] !== undefined && sameKey(name, key));
|
|
205
|
+
}
|
|
206
|
+
function cjsonGet(object, key) {
|
|
207
|
+
const found = firstKey(object, key);
|
|
208
|
+
return found === undefined ? undefined : object[found];
|
|
209
|
+
}
|
|
210
|
+
function cjsonHas(object, key) {
|
|
211
|
+
return firstKey(object, key) !== undefined;
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* Whether a function definition has a `gates` or `gate_fillers` key, found as
|
|
215
|
+
* the platform finds it: without regard to ASCII case.
|
|
216
|
+
*
|
|
217
|
+
* Internal: AgentBase and SWMLService use it to decide what to check.
|
|
218
|
+
* @param fields - A function definition.
|
|
219
|
+
* @returns True when either key is present.
|
|
220
|
+
*/
|
|
221
|
+
export function _hasGateFields(fields) {
|
|
222
|
+
return cjsonHas(fields, 'gates') || cjsonHas(fields, 'gate_fillers');
|
|
223
|
+
}
|
|
224
|
+
/** The bytes cJSON uses for one string, quotes included. */
|
|
225
|
+
function cjsonStringLength(text) {
|
|
226
|
+
let length = 2;
|
|
227
|
+
for (const char of text) {
|
|
228
|
+
const code = char.codePointAt(0);
|
|
229
|
+
if ('"\\\b\f\n\r\t'.includes(char))
|
|
230
|
+
length += 2;
|
|
231
|
+
else if (code < 32)
|
|
232
|
+
length += 6;
|
|
233
|
+
else
|
|
234
|
+
length += utf8Length(char);
|
|
235
|
+
}
|
|
236
|
+
return length;
|
|
237
|
+
}
|
|
238
|
+
/** The bytes cJSON uses for one number, as FreeSWITCH's cJSON prints it. */
|
|
239
|
+
function cjsonNumberLength(value) {
|
|
240
|
+
if (!Number.isFinite(value))
|
|
241
|
+
return 4; // "null"
|
|
242
|
+
// An integral value prints with %ld, any other with %lf (six decimals)
|
|
243
|
+
if (Number.isInteger(value))
|
|
244
|
+
return BigInt(value).toString().length;
|
|
245
|
+
return value.toFixed(6).length;
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* How many bytes cJSON_PrintUnformatted gives the JSON value, as the platform
|
|
249
|
+
* measures it. Exported for tests; the emitted values aren't changed.
|
|
250
|
+
*/
|
|
251
|
+
export function _cjsonPrintedLength(value) {
|
|
252
|
+
if (value === null || value === undefined)
|
|
253
|
+
return 4;
|
|
254
|
+
if (typeof value === 'boolean')
|
|
255
|
+
return value ? 4 : 5;
|
|
256
|
+
if (typeof value === 'number')
|
|
257
|
+
return cjsonNumberLength(value);
|
|
258
|
+
if (typeof value === 'string')
|
|
259
|
+
return cjsonStringLength(value);
|
|
260
|
+
if (Array.isArray(value)) {
|
|
261
|
+
const items = value.map(_cjsonPrintedLength);
|
|
262
|
+
return 2 + items.reduce((sum, n) => sum + n, 0) + Math.max(0, items.length - 1);
|
|
263
|
+
}
|
|
264
|
+
const entries = Object.entries(value);
|
|
265
|
+
let length = 2 + Math.max(0, entries.length - 1);
|
|
266
|
+
for (const [key, item] of entries)
|
|
267
|
+
length += cjsonStringLength(key) + 1 + _cjsonPrintedLength(item);
|
|
268
|
+
return length;
|
|
269
|
+
}
|
|
270
|
+
/**
|
|
271
|
+
* Why a string can't reach the platform as written, or an empty string. C
|
|
272
|
+
* reads a string up to its first NUL, and cJSON refuses an unpaired surrogate,
|
|
273
|
+
* so the SDK refuses both rather than send a gate the platform reads
|
|
274
|
+
* differently.
|
|
275
|
+
*/
|
|
276
|
+
function checkText(value, where) {
|
|
277
|
+
if (typeof value === 'string') {
|
|
278
|
+
if (value.includes('\0'))
|
|
279
|
+
return `${where} contains a NUL character`;
|
|
280
|
+
if (UNPAIRED_SURROGATE.test(value))
|
|
281
|
+
return `${where} contains an unpaired surrogate`;
|
|
282
|
+
return '';
|
|
283
|
+
}
|
|
284
|
+
if (Array.isArray(value)) {
|
|
285
|
+
for (const item of value) {
|
|
286
|
+
const why = checkText(item, where);
|
|
287
|
+
if (why)
|
|
288
|
+
return why;
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
else if (isPlainObject(value)) {
|
|
292
|
+
for (const [key, item] of Object.entries(value)) {
|
|
293
|
+
const why = checkText(key, where) || checkText(item, where);
|
|
294
|
+
if (why)
|
|
295
|
+
return why;
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
return '';
|
|
299
|
+
}
|
|
300
|
+
/** Why the platform would refuse `on_fail`, or an empty string. */
|
|
301
|
+
function checkOnFail(onFail) {
|
|
302
|
+
if (!isPlainObject(onFail))
|
|
303
|
+
return 'on_fail must be an object';
|
|
304
|
+
const response = cjsonGet(onFail, 'response');
|
|
305
|
+
if (typeof response === 'string') {
|
|
306
|
+
if (!response)
|
|
307
|
+
return 'on_fail.response is empty';
|
|
308
|
+
}
|
|
309
|
+
else if (isPlainObject(response)) {
|
|
310
|
+
const toolResult = cjsonGet(response, 'tool_result');
|
|
311
|
+
if (typeof toolResult !== 'string' || !toolResult) {
|
|
312
|
+
return 'on_fail.response.tool_result is missing or empty';
|
|
313
|
+
}
|
|
314
|
+
if (cjsonHas(response, 'tool_prompt') &&
|
|
315
|
+
typeof cjsonGet(response, 'tool_prompt') !== 'string') {
|
|
316
|
+
return 'on_fail.response.tool_prompt must be a string';
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
else {
|
|
320
|
+
return 'on_fail.response is missing';
|
|
321
|
+
}
|
|
322
|
+
if (cjsonHas(onFail, 'action') && !Array.isArray(cjsonGet(onFail, 'action'))) {
|
|
323
|
+
return 'on_fail.action must be an array';
|
|
324
|
+
}
|
|
325
|
+
const textWhy = checkText(onFail, 'on_fail');
|
|
326
|
+
if (textWhy)
|
|
327
|
+
return textWhy;
|
|
328
|
+
// Measured as the platform measures it: cJSON_PrintUnformatted of the JSON sent
|
|
329
|
+
if (_cjsonPrintedLength(deepCopy(onFail)) > MAX_ON_FAIL_BYTES) {
|
|
330
|
+
return `on_fail is larger than ${MAX_ON_FAIL_BYTES} bytes`;
|
|
331
|
+
}
|
|
332
|
+
return '';
|
|
333
|
+
}
|
|
334
|
+
/** Why the platform would refuse `criteria`, or an empty string. */
|
|
335
|
+
function checkCriteria(criteria) {
|
|
336
|
+
if (!isPlainObject(criteria) || Object.keys(criteria).length === 0) {
|
|
337
|
+
return 'criteria must be an object with true and/or false';
|
|
338
|
+
}
|
|
339
|
+
for (const [key, value] of Object.entries(criteria)) {
|
|
340
|
+
if (key !== 'true' && key !== 'false') {
|
|
341
|
+
return `criteria has an unknown key '${key}'; only true and false are allowed`;
|
|
342
|
+
}
|
|
343
|
+
if (typeof value !== 'string' || !value)
|
|
344
|
+
return `criteria.${key} must be a non-empty string`;
|
|
345
|
+
const textWhy = checkText(value, `criteria.${key}`);
|
|
346
|
+
if (textWhy)
|
|
347
|
+
return textWhy;
|
|
348
|
+
if (utf8Length(value) > MAX_CRITERIA_BYTES) {
|
|
349
|
+
return `criteria.${key} is longer than ${MAX_CRITERIA_BYTES} bytes`;
|
|
350
|
+
}
|
|
351
|
+
}
|
|
352
|
+
return '';
|
|
353
|
+
}
|
|
354
|
+
/** Why the platform would refuse one gate, or an empty string. */
|
|
355
|
+
function checkGate(gate) {
|
|
356
|
+
if (!isPlainObject(gate))
|
|
357
|
+
return 'must be an object';
|
|
358
|
+
for (const key of Object.keys(gate)) {
|
|
359
|
+
if (!GATE_KEYS.has(key))
|
|
360
|
+
return `unknown key '${key}'`;
|
|
361
|
+
}
|
|
362
|
+
const question = gate['question'];
|
|
363
|
+
if (typeof question !== 'string' || !question)
|
|
364
|
+
return 'question is missing or empty';
|
|
365
|
+
const questionWhy = checkText(question, 'question');
|
|
366
|
+
if (questionWhy)
|
|
367
|
+
return questionWhy;
|
|
368
|
+
if (utf8Length(question) > MAX_QUESTION_BYTES) {
|
|
369
|
+
return `question is longer than ${MAX_QUESTION_BYTES} bytes`;
|
|
370
|
+
}
|
|
371
|
+
const threshold = gate['threshold'];
|
|
372
|
+
if (typeof threshold !== 'number' ||
|
|
373
|
+
!Number.isFinite(threshold) ||
|
|
374
|
+
!(threshold > 0 && threshold <= 1)) {
|
|
375
|
+
return 'threshold must be a number above 0 and at most 1';
|
|
376
|
+
}
|
|
377
|
+
if (!('on_fail' in gate))
|
|
378
|
+
return 'on_fail is missing';
|
|
379
|
+
const onFailWhy = checkOnFail(gate['on_fail']);
|
|
380
|
+
if (onFailWhy)
|
|
381
|
+
return onFailWhy;
|
|
382
|
+
if ('criteria' in gate) {
|
|
383
|
+
const criteriaWhy = checkCriteria(gate['criteria']);
|
|
384
|
+
if (criteriaWhy)
|
|
385
|
+
return criteriaWhy;
|
|
386
|
+
}
|
|
387
|
+
if ('id' in gate) {
|
|
388
|
+
const id = gate['id'];
|
|
389
|
+
if (typeof id !== 'string' || !GATE_ID.test(id)) {
|
|
390
|
+
return 'id must be 1 to 64 letters, digits or underscores';
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
return '';
|
|
394
|
+
}
|
|
395
|
+
/**
|
|
396
|
+
* Return a function's gates as the platform reads them.
|
|
397
|
+
*
|
|
398
|
+
* Every way to define a tool runs this through {@link applyGateFields}.
|
|
399
|
+
* @param gates - SemanticGate objects or gate objects, 1 to 8.
|
|
400
|
+
* @param functionName - The function's name.
|
|
401
|
+
* @returns Each gate as a plain object, deep-copied.
|
|
402
|
+
* @throws {Error} For anything that would make the platform refuse the
|
|
403
|
+
* function, with the platform's reason.
|
|
404
|
+
*/
|
|
405
|
+
export function gateDefinitions(gates, functionName) {
|
|
406
|
+
if (RESERVED_FUNCTION_NAMES.has(functionName)) {
|
|
407
|
+
throw new Error(`gates are not supported on ${functionName}, a hook or built-in function name`);
|
|
408
|
+
}
|
|
409
|
+
if (!Array.isArray(gates))
|
|
410
|
+
throw new Error(`${functionName}: gates must be a list`);
|
|
411
|
+
if (gates.length < 1 || gates.length > MAX_GATES) {
|
|
412
|
+
throw new Error(`${functionName}: gates must hold 1 to ${MAX_GATES} gates, not ${gates.length}`);
|
|
413
|
+
}
|
|
414
|
+
const definitions = [];
|
|
415
|
+
const ids = [];
|
|
416
|
+
// Every index, holes included: a hole is sent as null, which the platform refuses
|
|
417
|
+
for (let index = 0; index < gates.length; index++) {
|
|
418
|
+
const gate = gates[index];
|
|
419
|
+
const definition = wireForm(gate instanceof SemanticGate ? gate.toDict() : gate);
|
|
420
|
+
const why = checkGate(definition);
|
|
421
|
+
if (why)
|
|
422
|
+
throw new Error(`${functionName}: gate ${index + 1}: ${why}`);
|
|
423
|
+
const gateDefinition = definition;
|
|
424
|
+
const id = gateDefinition['id'] ?? `gate_${index + 1}`;
|
|
425
|
+
const earlier = ids.indexOf(id);
|
|
426
|
+
if (earlier >= 0) {
|
|
427
|
+
throw new Error(`${functionName}: gate ${index + 1}: id '${id}' is already used by gate ${earlier + 1}`);
|
|
428
|
+
}
|
|
429
|
+
ids.push(id);
|
|
430
|
+
definitions.push(gateDefinition);
|
|
431
|
+
}
|
|
432
|
+
return definitions;
|
|
433
|
+
}
|
|
434
|
+
/**
|
|
435
|
+
* Check and normalize `gates` and `gate_fillers` in a function's fields, in
|
|
436
|
+
* place.
|
|
437
|
+
*
|
|
438
|
+
* `fields` is a function definition, or the extra fields of one. Its `gates`
|
|
439
|
+
* become the objects the platform reads. A `gate_fillers` left out or `null`
|
|
440
|
+
* is removed, as the platform ignores it.
|
|
441
|
+
* @param fields - The function definition or its extra fields.
|
|
442
|
+
* @param functionName - The function's name.
|
|
443
|
+
* @param opts - Options.
|
|
444
|
+
* @param opts.definition - True when `fields` is a whole function definition
|
|
445
|
+
* sent as written, such as a DataMap's or a raw one. Then its `gates` and
|
|
446
|
+
* `gate_fillers` keys are found as the platform finds them, without regard
|
|
447
|
+
* to case; `gates: null` is refused, as the platform refuses the function
|
|
448
|
+
* for a JSON null; and a gated function needs a description. Otherwise a
|
|
449
|
+
* null or undefined `gates` means no gates, as an option left out does.
|
|
450
|
+
* @throws {Error} For gates the platform would refuse, `gate_fillers` on a
|
|
451
|
+
* function without gates, which the platform ignores, or a gated
|
|
452
|
+
* definition without a description.
|
|
453
|
+
*/
|
|
454
|
+
export function applyGateFields(fields, functionName, opts = {}) {
|
|
455
|
+
const definition = opts.definition ?? false;
|
|
456
|
+
const gatesKey = definition ? firstKey(fields, 'gates') : 'gates' in fields ? 'gates' : undefined;
|
|
457
|
+
let gated = false;
|
|
458
|
+
if (gatesKey !== undefined) {
|
|
459
|
+
const gates = fields[gatesKey];
|
|
460
|
+
if (gates === undefined || (gates === null && !definition)) {
|
|
461
|
+
delete fields[gatesKey];
|
|
462
|
+
}
|
|
463
|
+
else {
|
|
464
|
+
// Raw definitions carry anything; gateDefinitions checks it at run time
|
|
465
|
+
fields[gatesKey] = gateDefinitions(gates, functionName);
|
|
466
|
+
gated = true;
|
|
467
|
+
}
|
|
468
|
+
}
|
|
469
|
+
if (gated && definition) {
|
|
470
|
+
// The platform reads purpose, then description; any string counts
|
|
471
|
+
if (typeof cjsonGet(fields, 'purpose') !== 'string' &&
|
|
472
|
+
typeof cjsonGet(fields, 'description') !== 'string') {
|
|
473
|
+
throw new Error(`${functionName}: a gated function needs a description; the platform refuses it without one`);
|
|
474
|
+
}
|
|
475
|
+
}
|
|
476
|
+
const fillersKey = definition
|
|
477
|
+
? firstKey(fields, 'gate_fillers')
|
|
478
|
+
: 'gate_fillers' in fields
|
|
479
|
+
? 'gate_fillers'
|
|
480
|
+
: undefined;
|
|
481
|
+
if (fillersKey === undefined)
|
|
482
|
+
return;
|
|
483
|
+
const gateFillers = fields[fillersKey];
|
|
484
|
+
if (gateFillers === undefined || gateFillers === null) {
|
|
485
|
+
// The platform reads only the first match and ignores a null one, so in a
|
|
486
|
+
// whole definition every spelling goes, lest a later one take effect
|
|
487
|
+
for (const name of Object.keys(fields)) {
|
|
488
|
+
if (definition ? sameKey(name, 'gate_fillers') : name === fillersKey)
|
|
489
|
+
delete fields[name];
|
|
490
|
+
}
|
|
491
|
+
return;
|
|
492
|
+
}
|
|
493
|
+
if (!gated) {
|
|
494
|
+
throw new Error(`${functionName}: gate_fillers needs gates; the platform ignores them on a ` +
|
|
495
|
+
'function without gates');
|
|
496
|
+
}
|
|
497
|
+
if (!isPlainObject(gateFillers)) {
|
|
498
|
+
throw new Error(`${functionName}: gate_fillers must map a language code, 'auto' or ` +
|
|
499
|
+
"'default' to a list of phrases");
|
|
500
|
+
}
|
|
501
|
+
}
|
|
502
|
+
/**
|
|
503
|
+
* Check a gated function as it will be sent, after every merge and expansion.
|
|
504
|
+
*
|
|
505
|
+
* Besides its gates, the platform needs a gated function to have a name, a
|
|
506
|
+
* description (`description` or `purpose`), and a `web_hook_url` or a
|
|
507
|
+
* `data_map`; a function without them isn't registered at all. The SWAIG
|
|
508
|
+
* `defaults.web_hook_url` counts as its URL.
|
|
509
|
+
*
|
|
510
|
+
* Internal: AgentBase calls it on each function it renders.
|
|
511
|
+
* @param definition - The function definition as it will be sent.
|
|
512
|
+
* @param defaultWebhookUrl - The SWAIG defaults `web_hook_url`, if any.
|
|
513
|
+
* @throws {Error} For gates the platform would refuse, or a gated function
|
|
514
|
+
* the platform wouldn't register.
|
|
515
|
+
*/
|
|
516
|
+
export function _checkGatedFunction(definition, defaultWebhookUrl) {
|
|
517
|
+
if (!_hasGateFields(definition))
|
|
518
|
+
return;
|
|
519
|
+
const name = typeof definition['function'] === 'string' ? definition['function'] : '';
|
|
520
|
+
applyGateFields(definition, name || '(unnamed)', { definition: true });
|
|
521
|
+
if (!cjsonHas(definition, 'gates'))
|
|
522
|
+
return;
|
|
523
|
+
// As the platform reads them: any string counts, an empty one included, as
|
|
524
|
+
// does any data_map; the SWAIG defaults' URL counts as the function's.
|
|
525
|
+
const hasUrl = typeof cjsonGet(definition, 'web_hook_url') === 'string' || Boolean(defaultWebhookUrl);
|
|
526
|
+
const dataMap = cjsonGet(definition, 'data_map');
|
|
527
|
+
if (typeof definition['function'] !== 'string' ||
|
|
528
|
+
(!hasUrl && (dataMap === undefined || dataMap === null))) {
|
|
529
|
+
throw new Error(`${name || '(unnamed)'}: a gated function needs a name, a description, and a ` +
|
|
530
|
+
'web_hook_url or data_map');
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
//# sourceMappingURL=SemanticGate.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"SemanticGate.js","sourceRoot":"","sources":["../src/SemanticGate.ts"],"names":[],"mappings":"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"}
|
package/dist/SwaigFunction.d.ts
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
import { FunctionResult, type SwaigResultDict } from './FunctionResult.js';
|
|
5
5
|
import type { SwaigRequest } from './SwaigContracts.js';
|
|
6
6
|
import type { AgentBase } from './AgentBase.js';
|
|
7
|
+
import { type FillerPhrases, type SemanticGate } from './SemanticGate.js';
|
|
7
8
|
/** @internal How many argument validators have been compiled (for tests). */
|
|
8
9
|
export declare function _compiledValidatorCount(): number;
|
|
9
10
|
/**
|
|
@@ -105,12 +106,33 @@ export interface SwaigFunctionOptions {
|
|
|
105
106
|
* `secure=True`.
|
|
106
107
|
*/
|
|
107
108
|
secure?: boolean;
|
|
108
|
-
/**
|
|
109
|
+
/**
|
|
110
|
+
* Phrases the AI says while the function runs, keyed by language code,
|
|
111
|
+
* `"auto"` (translated into the call's language on first use) or
|
|
112
|
+
* `"default"`. An entry may also be a list of phrases, a wait script, spoken
|
|
113
|
+
* one at a time while the call waits; the type predates wait scripts, so one needs a cast (the platform
|
|
114
|
+
* accepts it). {@link gateFillers} is typed for both.
|
|
115
|
+
*/
|
|
109
116
|
fillers?: Record<string, string[]>;
|
|
110
117
|
/** Audio file URL to play while waiting for the tool to complete. */
|
|
111
118
|
waitFile?: string;
|
|
112
119
|
/** Number of times to loop the wait file. */
|
|
113
120
|
waitFileLoops?: number;
|
|
121
|
+
/**
|
|
122
|
+
* Semantic gates, 1 to 8 {@link SemanticGate} objects or gate objects:
|
|
123
|
+
* yes/no preconditions a decision model checks right before the platform
|
|
124
|
+
* dispatches the function. When one fails, the function doesn't run and the
|
|
125
|
+
* model gets that gate's `on_fail` output. The fillers and wait file start
|
|
126
|
+
* only once the gates pass. Checked by the platform's rules when the tool is
|
|
127
|
+
* defined. A platform release without semantic gates runs the function
|
|
128
|
+
* ungated.
|
|
129
|
+
*/
|
|
130
|
+
gates?: ReadonlyArray<SemanticGate | Record<string, unknown>>;
|
|
131
|
+
/**
|
|
132
|
+
* Phrases the AI says while the gates are checked, shaped like
|
|
133
|
+
* {@link fillers}. Only with {@link gates}.
|
|
134
|
+
*/
|
|
135
|
+
gateFillers?: FillerPhrases;
|
|
114
136
|
/** External webhook URL; makes this an externally-hosted tool. */
|
|
115
137
|
webhookUrl?: string;
|
|
116
138
|
/** List of required parameter names. */
|
|
@@ -190,7 +212,7 @@ export declare class SwaigFunction {
|
|
|
190
212
|
parameters: Record<string, unknown>;
|
|
191
213
|
/** Whether this tool requires session token authentication. */
|
|
192
214
|
secure: boolean;
|
|
193
|
-
/**
|
|
215
|
+
/** Phrases the AI says while the function runs (see {@link SwaigFunctionOptions.fillers}). */
|
|
194
216
|
fillers?: Record<string, string[]>;
|
|
195
217
|
/** Audio file URL to play while waiting for the tool to complete. */
|
|
196
218
|
waitFile?: string;
|
|
@@ -218,7 +240,11 @@ export declare class SwaigFunction {
|
|
|
218
240
|
* (e.g. `meta_data_token`, `web_hook_auth_user`, `web_hook_auth_password`).
|
|
219
241
|
* This mirrors the Python constructor's `**extra_swaig_fields` kwargs:
|
|
220
242
|
* both are merged directly into the serialized SWAIG definition, so the
|
|
221
|
-
* wire format is identical — only the call-site syntax differs.
|
|
243
|
+
* wire format is identical — only the call-site syntax differs. `gates`
|
|
244
|
+
* and `gate_fillers` there are checked like `opts.gates` and
|
|
245
|
+
* `opts.gateFillers`.
|
|
246
|
+
* @throws {Error} For gates the platform would refuse, or gate fillers
|
|
247
|
+
* without gates.
|
|
222
248
|
*/
|
|
223
249
|
constructor(opts: SwaigFunctionOptions);
|
|
224
250
|
private ensureParameterStructure;
|
package/dist/SwaigFunction.js
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
import Ajv from 'ajv';
|
|
5
5
|
import { FunctionResult } from './FunctionResult.js';
|
|
6
6
|
import { getLogger } from './Logger.js';
|
|
7
|
+
import { applyGateFields, _checkGatedFunction, } from './SemanticGate.js';
|
|
7
8
|
const ajv = new Ajv({ allErrors: true });
|
|
8
9
|
/**
|
|
9
10
|
* Compiled argument validators, keyed by the schema's JSON, so every call of
|
|
@@ -134,7 +135,7 @@ export class SwaigFunction {
|
|
|
134
135
|
parameters;
|
|
135
136
|
/** Whether this tool requires session token authentication. */
|
|
136
137
|
secure;
|
|
137
|
-
/**
|
|
138
|
+
/** Phrases the AI says while the function runs (see {@link SwaigFunctionOptions.fillers}). */
|
|
138
139
|
fillers;
|
|
139
140
|
/** Audio file URL to play while waiting for the tool to complete. */
|
|
140
141
|
waitFile;
|
|
@@ -162,7 +163,11 @@ export class SwaigFunction {
|
|
|
162
163
|
* (e.g. `meta_data_token`, `web_hook_auth_user`, `web_hook_auth_password`).
|
|
163
164
|
* This mirrors the Python constructor's `**extra_swaig_fields` kwargs:
|
|
164
165
|
* both are merged directly into the serialized SWAIG definition, so the
|
|
165
|
-
* wire format is identical — only the call-site syntax differs.
|
|
166
|
+
* wire format is identical — only the call-site syntax differs. `gates`
|
|
167
|
+
* and `gate_fillers` there are checked like `opts.gates` and
|
|
168
|
+
* `opts.gateFillers`.
|
|
169
|
+
* @throws {Error} For gates the platform would refuse, or gate fillers
|
|
170
|
+
* without gates.
|
|
166
171
|
*/
|
|
167
172
|
constructor(opts) {
|
|
168
173
|
this.name = opts.name;
|
|
@@ -179,7 +184,17 @@ export class SwaigFunction {
|
|
|
179
184
|
this.waitFileLoops = opts.waitFileLoops;
|
|
180
185
|
this.webhookUrl = opts.webhookUrl;
|
|
181
186
|
this.required = opts.required ?? [];
|
|
182
|
-
|
|
187
|
+
// Gates given as options, or among the extra fields, are checked by the
|
|
188
|
+
// platform's rules under the name the function is sent with.
|
|
189
|
+
this.extraFields = { ...(opts.extraFields ?? {}) };
|
|
190
|
+
if (opts.gates !== undefined)
|
|
191
|
+
this.extraFields['gates'] = opts.gates;
|
|
192
|
+
if (opts.gateFillers !== undefined)
|
|
193
|
+
this.extraFields['gate_fillers'] = opts.gateFillers;
|
|
194
|
+
if ('gates' in this.extraFields || 'gate_fillers' in this.extraFields) {
|
|
195
|
+
const sentName = this.extraFields['function'];
|
|
196
|
+
applyGateFields(this.extraFields, typeof sentName === 'string' ? sentName : this.name);
|
|
197
|
+
}
|
|
183
198
|
this.isTypedHandler = opts.isTypedHandler ?? false;
|
|
184
199
|
this.isExternal = opts.webhookUrl !== undefined;
|
|
185
200
|
this.onError = opts.onError;
|
|
@@ -335,6 +350,7 @@ export class SwaigFunction {
|
|
|
335
350
|
if (this.waitFileLoops !== undefined)
|
|
336
351
|
def['wait_file_loops'] = this.waitFileLoops;
|
|
337
352
|
Object.assign(def, this.extraFields);
|
|
353
|
+
_checkGatedFunction(def);
|
|
338
354
|
return def;
|
|
339
355
|
}
|
|
340
356
|
}
|