@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 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
@@ -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
- this.defineTool(toolDef.secure === undefined && typeof skillSecure === 'boolean'
1731
- ? { ...toolDef, secure: skillSecure }
1732
- : toolDef);
1733
- const fn = this.toolRegistry.get(toolDef.name);
1734
- if (fn instanceof SwaigFunction) {
1735
- // Apply skill-level swaigFields as the base, then let tool-level filler
1736
- // flags override — matches Python skill_base.py:70-73 (swaig_fields base,
1737
- // explicit kwargs win) and SkillBase.defineTool() ({...swaigDefaults, ...toolDef}).
1738
- if (Object.keys(skillExtraFields).length > 0) {
1739
- safeAssign(fn.extraFields, skillExtraFields);
1740
- }
1741
- if (toolDef.wait_for_fillers !== undefined) {
1742
- fn.extraFields['wait_for_fillers'] = toolDef.wait_for_fillers;
1743
- }
1744
- if (toolDef.skip_fillers !== undefined) {
1745
- fn.extraFields['skip_fillers'] = toolDef.skip_fillers;
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
  }