@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
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,42 @@
|
|
|
3
3
|
All notable changes to `@signalwire/sdk` are documented here. This project
|
|
4
4
|
follows [Semantic Versioning](https://semver.org/).
|
|
5
5
|
|
|
6
|
+
## 3.6.0 (2026-10-05)
|
|
7
|
+
|
|
8
|
+
Parity with signalwire-python 3.6.0: semantic gates, `changeVoice()`, and
|
|
9
|
+
the settings and state they use.
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Semantic gates: `SemanticGate`, and `gates` and `gateFillers` on
|
|
14
|
+
`defineTool()`, `defineTypedTool()`, `SwaigFunction`, a skill's tools and
|
|
15
|
+
raw function definitions, and `gate()` and `gateFillers()` on DataMap. A
|
|
16
|
+
gate is a yes/no question a decision model answers about the call before
|
|
17
|
+
the platform runs the function; when one fails, the function doesn't run
|
|
18
|
+
and the model gets the gate's `on_fail` output. Gates are checked by the
|
|
19
|
+
platform's rules when the tool is defined and again when the SWML is
|
|
20
|
+
rendered, since the platform refuses a function with an invalid gate. They
|
|
21
|
+
need a platform release with semantic gates: one without them runs the
|
|
22
|
+
function ungated.
|
|
23
|
+
- `AgentBase.setSemanticGates()` sets `semantic_gates_enabled`,
|
|
24
|
+
`semantic_gate_timeout_ms` and `semantic_gate_history`, and
|
|
25
|
+
`FunctionResult.setSemanticState()` sets the state gates judge.
|
|
26
|
+
- `FunctionResult.changeVoice()` changes the AI's voice for the rest of the
|
|
27
|
+
call (`change_voice`), from the next batch of speech on. It throws on an
|
|
28
|
+
empty or whitespace-only voice, which the platform would ignore.
|
|
29
|
+
- Function fillers are documented with the `auto` key, translated into the
|
|
30
|
+
call's language on first use, and wait scripts, lists of phrases spoken one
|
|
31
|
+
at a time while the call waits. `gateFillers` is typed for both (the
|
|
32
|
+
exported `FillerPhrases`); `fillers` keeps its type, so a wait script there
|
|
33
|
+
needs a cast.
|
|
34
|
+
|
|
35
|
+
### Changed
|
|
36
|
+
|
|
37
|
+
- `addSkill()` merges a skill's `swaig_fields` and each tool's own fields
|
|
38
|
+
before it builds the tool, so the merged definition is what gets checked;
|
|
39
|
+
a tool's own fields still win. It used to copy `swaig_fields` onto the
|
|
40
|
+
tool afterwards.
|
|
41
|
+
|
|
6
42
|
## 3.5.0 (2026-09-29)
|
|
7
43
|
|
|
8
44
|
Brings the TypeScript SDK to parity with signalwire-python 3.5.1: the
|
package/dist/AgentBase.d.ts
CHANGED
|
@@ -11,6 +11,7 @@ import { PromptManager } from './PromptManager.js';
|
|
|
11
11
|
import { PromptObjectModel } from './POM/PromptObjectModel.js';
|
|
12
12
|
import { SWMLService } from './SWMLService.js';
|
|
13
13
|
import { SwaigFunction, type SwaigErrorHandler } from './SwaigFunction.js';
|
|
14
|
+
import { type FillerPhrases, type SemanticGate } from './SemanticGate.js';
|
|
14
15
|
import { type TypedToolHandler } from './TypeInference.js';
|
|
15
16
|
import { ContextBuilder } from './ContextBuilder.js';
|
|
16
17
|
import { type Logger } from './Logger.js';
|
|
@@ -530,6 +531,29 @@ export declare class AgentBase extends SWMLService {
|
|
|
530
531
|
* @returns This agent instance for chaining.
|
|
531
532
|
*/
|
|
532
533
|
setParams(params: Record<string, unknown>): this;
|
|
534
|
+
/**
|
|
535
|
+
* Set how the call checks its functions' semantic gates (see
|
|
536
|
+
* {@link SemanticGate}).
|
|
537
|
+
*
|
|
538
|
+
* Each option left out leaves its current setting as it is; the platform's
|
|
539
|
+
* default applies to a setting that was never set.
|
|
540
|
+
* @param opts - The gate settings.
|
|
541
|
+
* @param opts.enabled - `false` dispatches gated functions without checking
|
|
542
|
+
* their gates. Default `true`. Sent as `semantic_gates_enabled`.
|
|
543
|
+
* @param opts.timeoutMs - The time one check may take, 500 to 10000
|
|
544
|
+
* milliseconds, preparing the request and any retry included. A check that
|
|
545
|
+
* runs out blocks the call. Default 2500. Sent as
|
|
546
|
+
* `semantic_gate_timeout_ms`.
|
|
547
|
+
* @param opts.history - How many recent dialogue entries the decision model
|
|
548
|
+
* sees, 0 to 100. Default 20. Sent as `semantic_gate_history`.
|
|
549
|
+
* @returns This agent instance for chaining.
|
|
550
|
+
* @throws {Error} When a value has the wrong type or is out of range.
|
|
551
|
+
*/
|
|
552
|
+
setSemanticGates(opts?: {
|
|
553
|
+
enabled?: boolean;
|
|
554
|
+
timeoutMs?: number;
|
|
555
|
+
history?: number;
|
|
556
|
+
}): this;
|
|
533
557
|
/**
|
|
534
558
|
* **MERGES** `data` into the global_data object passed into the AI
|
|
535
559
|
* configuration. **Despite the name, this does NOT replace** the existing
|
|
@@ -790,10 +814,15 @@ export declare class AgentBase extends SWMLService {
|
|
|
790
814
|
*/
|
|
791
815
|
handler: TypedToolHandler;
|
|
792
816
|
secure?: boolean;
|
|
817
|
+
/** Phrases the AI says while the function runs (see `SwaigFunctionOptions.fillers`). */
|
|
793
818
|
fillers?: Record<string, string[]>;
|
|
794
819
|
waitFile?: string;
|
|
795
820
|
waitFileLoops?: number;
|
|
796
821
|
required?: string[];
|
|
822
|
+
/** Semantic gates (see `SwaigFunctionOptions.gates`). */
|
|
823
|
+
gates?: ReadonlyArray<SemanticGate | Record<string, unknown>>;
|
|
824
|
+
/** Phrases said while the gates are checked (see `SwaigFunctionOptions.gateFillers`). */
|
|
825
|
+
gateFillers?: FillerPhrases;
|
|
797
826
|
}): this;
|
|
798
827
|
/**
|
|
799
828
|
* Validate a tool-call token for the given function.
|
package/dist/AgentBase.js
CHANGED
|
@@ -17,6 +17,7 @@ import { SwmlBuilder } from './SwmlBuilder.js';
|
|
|
17
17
|
import { SWMLService } from './SWMLService.js';
|
|
18
18
|
import { ConfigLoader } from './ConfigLoader.js';
|
|
19
19
|
import { SwaigFunction, normalizeParameters, } from './SwaigFunction.js';
|
|
20
|
+
import { _checkGatedFunction } from './SemanticGate.js';
|
|
20
21
|
import { inferSchema, createTypedHandlerWrapper } from './TypeInference.js';
|
|
21
22
|
import { FunctionResult } from './FunctionResult.js';
|
|
22
23
|
import { Context as ConversationContext, ContextBuilder, GatherInfo, GatherQuestion, Step, } from './ContextBuilder.js';
|
|
@@ -1021,6 +1022,49 @@ export class AgentBase extends SWMLService {
|
|
|
1021
1022
|
safeAssign(this.params, params);
|
|
1022
1023
|
return this;
|
|
1023
1024
|
}
|
|
1025
|
+
/**
|
|
1026
|
+
* Set how the call checks its functions' semantic gates (see
|
|
1027
|
+
* {@link SemanticGate}).
|
|
1028
|
+
*
|
|
1029
|
+
* Each option left out leaves its current setting as it is; the platform's
|
|
1030
|
+
* default applies to a setting that was never set.
|
|
1031
|
+
* @param opts - The gate settings.
|
|
1032
|
+
* @param opts.enabled - `false` dispatches gated functions without checking
|
|
1033
|
+
* their gates. Default `true`. Sent as `semantic_gates_enabled`.
|
|
1034
|
+
* @param opts.timeoutMs - The time one check may take, 500 to 10000
|
|
1035
|
+
* milliseconds, preparing the request and any retry included. A check that
|
|
1036
|
+
* runs out blocks the call. Default 2500. Sent as
|
|
1037
|
+
* `semantic_gate_timeout_ms`.
|
|
1038
|
+
* @param opts.history - How many recent dialogue entries the decision model
|
|
1039
|
+
* sees, 0 to 100. Default 20. Sent as `semantic_gate_history`.
|
|
1040
|
+
* @returns This agent instance for chaining.
|
|
1041
|
+
* @throws {Error} When a value has the wrong type or is out of range.
|
|
1042
|
+
*/
|
|
1043
|
+
setSemanticGates(opts = {}) {
|
|
1044
|
+
// Check every value before setting any, so a refused call changes nothing
|
|
1045
|
+
const { enabled, timeoutMs, history } = opts;
|
|
1046
|
+
if (enabled !== undefined && typeof enabled !== 'boolean') {
|
|
1047
|
+
throw new Error(`enabled must be a boolean, got ${JSON.stringify(enabled)}`);
|
|
1048
|
+
}
|
|
1049
|
+
const ranges = [
|
|
1050
|
+
['semantic_gate_timeout_ms', 'timeout_ms', timeoutMs, 500, 10000],
|
|
1051
|
+
['semantic_gate_history', 'history', history, 0, 100],
|
|
1052
|
+
];
|
|
1053
|
+
for (const [, name, value, low, high] of ranges) {
|
|
1054
|
+
if (value === undefined)
|
|
1055
|
+
continue;
|
|
1056
|
+
if (typeof value !== 'number' || !Number.isInteger(value) || value < low || value > high) {
|
|
1057
|
+
throw new Error(`${name} must be an integer from ${low} to ${high}, got ${JSON.stringify(value)}`);
|
|
1058
|
+
}
|
|
1059
|
+
}
|
|
1060
|
+
if (enabled !== undefined)
|
|
1061
|
+
this.params['semantic_gates_enabled'] = enabled;
|
|
1062
|
+
for (const [param, , value] of ranges) {
|
|
1063
|
+
if (value !== undefined)
|
|
1064
|
+
this.params[param] = value;
|
|
1065
|
+
}
|
|
1066
|
+
return this;
|
|
1067
|
+
}
|
|
1024
1068
|
/**
|
|
1025
1069
|
* **MERGES** `data` into the global_data object passed into the AI
|
|
1026
1070
|
* configuration. **Despite the name, this does NOT replace** the existing
|
|
@@ -1577,6 +1621,8 @@ export class AgentBase extends SWMLService {
|
|
|
1577
1621
|
waitFileLoops: opts.waitFileLoops,
|
|
1578
1622
|
required,
|
|
1579
1623
|
isTypedHandler: true,
|
|
1624
|
+
gates: opts.gates,
|
|
1625
|
+
gateFillers: opts.gateFillers,
|
|
1580
1626
|
});
|
|
1581
1627
|
this.toolRegistry.set(opts.name, fn);
|
|
1582
1628
|
return this;
|
|
@@ -1727,29 +1773,40 @@ export class AgentBase extends SWMLService {
|
|
|
1727
1773
|
// and the other keys go into the SWAIG definition.
|
|
1728
1774
|
const { secure: skillSecure, ...skillExtraFields } = skill.swaigFields;
|
|
1729
1775
|
for (const toolDef of skill.getTools()) {
|
|
1730
|
-
|
|
1731
|
-
|
|
1732
|
-
|
|
1733
|
-
|
|
1734
|
-
|
|
1735
|
-
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
|
-
|
|
1742
|
-
|
|
1743
|
-
|
|
1744
|
-
|
|
1745
|
-
|
|
1746
|
-
|
|
1747
|
-
// Propagate is_hangup_hook so the SignalWire platform auto-fires this
|
|
1748
|
-
// tool on call hangup (Python equivalent: is_hangup_hook=True in define_tool).
|
|
1749
|
-
if (toolDef.isHangupHook) {
|
|
1750
|
-
fn.extraFields['is_hangup_hook'] = true;
|
|
1751
|
-
}
|
|
1776
|
+
// Skill-level swaigFields are the base and the tool's own fields win —
|
|
1777
|
+
// Python skill_base.py:70-73 (swaig_fields base, explicit kwargs win) and
|
|
1778
|
+
// SkillBase.defineTool() ({...swaigDefaults, ...toolDef}). They are merged
|
|
1779
|
+
// before the function is built, so the result is what's checked: a
|
|
1780
|
+
// skill's default gates never replace a tool's own.
|
|
1781
|
+
const extraFields = {};
|
|
1782
|
+
safeAssign(extraFields, skillExtraFields);
|
|
1783
|
+
// A tool may carry its own extra fields (getTools() can return
|
|
1784
|
+
// SwaigFunctionOptions); they win over the skill's defaults.
|
|
1785
|
+
const ownExtraFields = toolDef.extraFields;
|
|
1786
|
+
if (ownExtraFields)
|
|
1787
|
+
safeAssign(extraFields, ownExtraFields);
|
|
1788
|
+
if (toolDef.wait_for_fillers !== undefined) {
|
|
1789
|
+
extraFields['wait_for_fillers'] = toolDef.wait_for_fillers;
|
|
1790
|
+
}
|
|
1791
|
+
if (toolDef.skip_fillers !== undefined) {
|
|
1792
|
+
extraFields['skip_fillers'] = toolDef.skip_fillers;
|
|
1752
1793
|
}
|
|
1794
|
+
// Propagate is_hangup_hook so the SignalWire platform auto-fires this
|
|
1795
|
+
// tool on call hangup (Python equivalent: is_hangup_hook=True in define_tool).
|
|
1796
|
+
if (toolDef.isHangupHook) {
|
|
1797
|
+
extraFields['is_hangup_hook'] = true;
|
|
1798
|
+
}
|
|
1799
|
+
if (toolDef.gates !== undefined)
|
|
1800
|
+
extraFields['gates'] = toolDef.gates;
|
|
1801
|
+
if (toolDef.gate_fillers !== undefined)
|
|
1802
|
+
extraFields['gate_fillers'] = toolDef.gate_fillers;
|
|
1803
|
+
this.defineTool({
|
|
1804
|
+
...toolDef,
|
|
1805
|
+
...(toolDef.secure === undefined && typeof skillSecure === 'boolean'
|
|
1806
|
+
? { secure: skillSecure }
|
|
1807
|
+
: {}),
|
|
1808
|
+
extraFields,
|
|
1809
|
+
});
|
|
1753
1810
|
}
|
|
1754
1811
|
// Register DataMap-style tools — skills that build their own SWAIG JSON
|
|
1755
1812
|
// (e.g. DataSphereServerless) return them via getDataMapTools().
|
|
@@ -2587,11 +2644,16 @@ export class AgentBase extends SWMLService {
|
|
|
2587
2644
|
entry['web_hook_url'] = this.buildWebhookUrl('swaig', urlParams);
|
|
2588
2645
|
}
|
|
2589
2646
|
safeAssign(entry, fn.extraFields);
|
|
2647
|
+
// Gates are checked once more as sent: under the name the entry carries,
|
|
2648
|
+
// with its URL or the defaults' URL (the platform drops a gated
|
|
2649
|
+
// function it can't register).
|
|
2650
|
+
_checkGatedFunction(entry, defaultWebhookUrl);
|
|
2590
2651
|
functions.push(entry);
|
|
2591
2652
|
}
|
|
2592
2653
|
else {
|
|
2593
2654
|
// Raw dict (DataMap) - use as-is
|
|
2594
2655
|
const entry = { ...fn, function: name };
|
|
2656
|
+
_checkGatedFunction(entry, defaultWebhookUrl);
|
|
2595
2657
|
functions.push(entry);
|
|
2596
2658
|
}
|
|
2597
2659
|
}
|