@signalwire/sdk 3.7.2 → 3.10.3

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 (67) hide show
  1. package/CHANGELOG.md +201 -0
  2. package/README.md +1 -0
  3. package/dist/AgentBase.d.ts +107 -2
  4. package/dist/AgentBase.js +259 -13
  5. package/dist/AgentBase.js.map +1 -1
  6. package/dist/AiEvents.d.ts +70 -0
  7. package/dist/AiEvents.js +94 -0
  8. package/dist/AiEvents.js.map +1 -0
  9. package/dist/ContextBuilder.d.ts +215 -14
  10. package/dist/ContextBuilder.js +441 -14
  11. package/dist/ContextBuilder.js.map +1 -1
  12. package/dist/FunctionResult.d.ts +146 -1
  13. package/dist/FunctionResult.js +188 -2
  14. package/dist/FunctionResult.js.map +1 -1
  15. package/dist/PostPrompt.d.ts +19 -0
  16. package/dist/PostPrompt.js +43 -0
  17. package/dist/PostPrompt.js.map +1 -1
  18. package/dist/SWMLService.d.ts +97 -1
  19. package/dist/SWMLService.js +129 -2
  20. package/dist/SWMLService.js.map +1 -1
  21. package/dist/SemanticGate.d.ts +61 -1
  22. package/dist/SemanticGate.js +108 -15
  23. package/dist/SemanticGate.js.map +1 -1
  24. package/dist/SwaigFunction.d.ts +85 -9
  25. package/dist/SwaigFunction.js +214 -58
  26. package/dist/SwaigFunction.js.map +1 -1
  27. package/dist/ToolMiddleware.d.ts +82 -0
  28. package/dist/ToolMiddleware.js +131 -0
  29. package/dist/ToolMiddleware.js.map +1 -0
  30. package/dist/TypeInference.d.ts +1 -1
  31. package/dist/TypeInference.js.map +1 -1
  32. package/dist/cli/tsdocs/api-index.json +1 -1
  33. package/dist/cli/tsdocs/topics.js +24 -4
  34. package/dist/cli/tsdocs/topics.js.map +1 -1
  35. package/dist/index.d.ts +22 -8
  36. package/dist/index.js +15 -5
  37. package/dist/index.js.map +1 -1
  38. package/dist/llms.txt +1 -0
  39. package/dist/patterns/Proposal.d.ts +148 -0
  40. package/dist/patterns/Proposal.js +214 -0
  41. package/dist/patterns/Proposal.js.map +1 -0
  42. package/dist/patterns/RequestList.d.ts +138 -0
  43. package/dist/patterns/RequestList.js +171 -0
  44. package/dist/patterns/RequestList.js.map +1 -0
  45. package/dist/skills/SkillBase.d.ts +24 -1
  46. package/dist/skills/SkillBase.js +12 -1
  47. package/dist/skills/SkillBase.js.map +1 -1
  48. package/dist/speech/numbers.d.ts +66 -0
  49. package/dist/speech/numbers.js +281 -0
  50. package/dist/speech/numbers.js.map +1 -0
  51. package/dist/speech/spelling.d.ts +71 -0
  52. package/dist/speech/spelling.js +294 -0
  53. package/dist/speech/spelling.js.map +1 -0
  54. package/dist/testing/CallSimulator.d.ts +391 -0
  55. package/dist/testing/CallSimulator.js +966 -0
  56. package/dist/testing/CallSimulator.js.map +1 -0
  57. package/docs/agent-guide.md +2 -2
  58. package/docs/api-reference.md +279 -22
  59. package/docs/architecture.md +8 -4
  60. package/docs/cli-guide.md +2 -0
  61. package/docs/contexts-guide.md +75 -4
  62. package/docs/conversation_patterns.md +257 -0
  63. package/docs/mcp_integration.md +1 -1
  64. package/docs/pgi_agent_guide.md +5 -0
  65. package/docs/programmatically_governed_inference.md +2 -2
  66. package/docs/swaig-reference.md +98 -6
  67. package/package.json +1 -1
@@ -53,17 +53,21 @@ The reference groups the methods by what they do:
53
53
  - [updateGlobalData](#updateglobaldata)
54
54
  - [removeGlobalData](#removeglobaldata)
55
55
  - [setSemanticState](#setsemanticstate)
56
+ - [setSemanticGateMark](#setsemanticgatemark)
56
57
  - [setMetadata](#setmetadata)
57
58
  - [removeMetadata](#removemetadata)
58
59
  - [SWML Actions](#swml-actions)
59
60
  - [executeSwml](#executeswml)
60
61
  - [switchContext](#switchcontext)
61
62
  - [swmlChangeStep](#swmlchangestep)
63
+ - [refreshStep](#refreshstep)
62
64
  - [swmlChangeContext](#swmlchangecontext)
63
65
  - [swmlUserEvent](#swmluserevent)
64
66
  - [Function Control](#function-control)
65
67
  - [toggleFunctions](#togglefunctions)
66
68
  - [enableFunctionsOnTimeout](#enablefunctionsontimeout)
69
+ - [noBargeNextResponse](#nobargenextresponse)
70
+ - [backToBackFunctions](#backtobackfunctions)
67
71
  - [updateSettings](#updatesettings)
68
72
  - [User Input and History](#user-input-and-history)
69
73
  - [simulateUserInput](#simulateuserinput)
@@ -153,11 +157,12 @@ A tool handler receives `(args, rawData, agent)`. `args` holds the parsed argume
153
157
  The SDK handles these return values:
154
158
 
155
159
  - A `FunctionResult`, or a promise that resolves to one: serialized with `toDict()`.
156
- - A plain object with a `response` key: sent as it is.
157
- - A plain object without a `response` key: replaced by `{ response: "Function completed successfully" }`.
160
+ - A plain object with a `response` or an `action` key: sent as it is.
161
+ - Any other plain object: the handler's data, sent as its JSON in `response`. An empty object tells the model the outcome is unknown.
162
+ - `undefined` or `null`, as from a handler that returns nothing: `{ response: "Function executed successfully" }`.
158
163
  - Any other value, such as a string: converted to a string and sent as the response, with a logged warning.
159
164
 
160
- If the handler throws, the SDK logs the error. It then returns the result of the tool's `onError` hook, or of the agent's `onError()` handler, when either returns a `FunctionResult`. Otherwise it returns the tool's `errorMessage`, or a default apology message.
165
+ A handler that throws `new ToolRefusal(toolResult, toolPrompt?)` declines the call with an outcome it knows, such as an item out of stock: the model gets that `tool_result` and `tool_prompt`. Any other error is logged, not sent. The SDK then returns the result of the tool's `onError` hook, or of the agent's `onError()` handler, when either returns a `FunctionResult`. Otherwise it returns the tool's `errorMessage`, or the unknown-outcome result: the function failed before it finished, so whether it took effect is unknown, with a tool prompt not to tell the caller it worked or that it didn't. A crash can come after the work was done, so the model mustn't read it as a failure. See [defineTool()](api-reference.md#definetoolopts).
161
166
 
162
167
  Tools registered with `defineTool()` are secure by default. The SWML the agent renders gives each secure tool a per-call token (`__token`). The agent runs the handler only when a `/swaig` request carries a valid token for that function and call. Otherwise it returns a refusal response. Set `swaigSecret` or `SIGNALWIRE_SWAIG_SECRET` so tokens survive a restart and work across replicas. For details, see [Secure Tools (HMAC Tokens)](security.md#secure-tools-hmac-tokens).
163
168
 
@@ -849,7 +854,7 @@ const result = new FunctionResult('The customer record is loaded.')
849
854
 
850
855
  ### setSemanticState
851
856
 
852
- Set the state the call's semantic gates judge, besides the dialogue: `global_data.semantic_state` (sent as `set_global_data`). It replaces the state as a whole: to change one field, send the whole state with that field changed, and send `{}` to reset it. Keep it to what the application has established, such as an order the caller confirmed, rather than what the caller claims. It's the only global data copied into the decision model's state; a gate question can still bring in other global data with a `${global_data.x}` template. See [Semantic gates](api-reference.md#semantic-gates).
857
+ Set the state the call's semantic gates judge, besides the dialogue: `global_data.semantic_state` (sent as `set_global_data`). It replaces the state as a whole: to change one field, send the whole state with that field changed, and send `{}` to reset it. Keep it to what the application has established, such as an order the caller confirmed, rather than what the caller claims. It's the only global data copied into the decision model's state; a gate question can still bring in other global data with a `${global_data.x}` template. A change starts a proposal, the dialogue of a gate with `dialogue: 'proposal'`, as of the start of the result's action list, so a `say` anywhere in the same result, such as the read-back, is in it. Platform releases before this start it at its own action object: set the state before `say` there, or use `Proposal` (see [Conversation Patterns](conversation_patterns.md#confirming-a-change)), which works on both. See [Semantic gates](api-reference.md#semantic-gates).
853
858
 
854
859
  <!-- snippet: no-compile API signature reference, not runnable code -->
855
860
  ```typescript
@@ -870,6 +875,29 @@ const result = new FunctionResult('The order is confirmed.').setSemanticState({
870
875
  });
871
876
  ```
872
877
 
878
+ ### setSemanticGateMark
879
+
880
+ Set a mark that semantic gates with `since: name` judge the dialogue from: the agent's first turn at or after it, at most the gate's `history` entries (`semantic_gate_mark`). The mark is set as of the start of the result's action list, so a `say` anywhere in the same result is after it, and setting it again moves it. Platform releases before this set it as of the start of its own action object: set it before `say` there. Marks last for the call; the platform keeps a call's 16 newest. It needs a platform release that has it. See [Semantic gates](api-reference.md#semantic-gates).
881
+
882
+ <!-- snippet: no-compile API signature reference, not runnable code -->
883
+ ```typescript
884
+ setSemanticGateMark(name: string): this
885
+ ```
886
+
887
+ | Parameter | Type | Description |
888
+ |-----------|----------|-----------------------------------------------------|
889
+ | `name` | `string` | The mark's name, 1 to 64 letters, digits or underscores. |
890
+
891
+ **Returns:** `this` for chaining.
892
+
893
+ **Throws:** `Error` for any other name, which the platform would refuse.
894
+
895
+ **Example:**
896
+
897
+ ```typescript
898
+ const result = new FunctionResult('Read the order back.').setSemanticGateMark('read_back');
899
+ ```
900
+
873
901
  ### removeGlobalData
874
902
 
875
903
  Remove one or more keys from the global data (`unset_global_data`).
@@ -1077,6 +1105,29 @@ const result = new FunctionResult('The premium plan is confirmed. Collect paymen
1077
1105
  .swmlChangeStep('collect_payment');
1078
1106
  ```
1079
1107
 
1108
+ ### refreshStep
1109
+
1110
+ Enter the current step again, so its text shows new global data. A step's text is expanded when the step is entered. Platform releases that re-expand it rewrite it in place before a request when a value it reads changes; on earlier releases, and with a realtime model, its `${global_data.*}` values are the ones from entry. There, after `updateGlobalData()` changes one, add `refreshStep()` with the current step's name, after the update, and the model gets the step's text again with the new values. It's the same action as `swmlChangeStep(stepName)`: entering a step starts it over, and its `history` mode applies again.
1111
+
1112
+ <!-- snippet: no-compile API signature reference, not runnable code -->
1113
+ ```typescript
1114
+ refreshStep(stepName: string): this
1115
+ ```
1116
+
1117
+ | Parameter | Type | Description |
1118
+ |------------|----------|------------------------------|
1119
+ | `stepName` | `string` | The name of the current step. |
1120
+
1121
+ **Returns:** `this` for chaining.
1122
+
1123
+ **Example:**
1124
+
1125
+ ```typescript
1126
+ const result = new FunctionResult('Added the drink.')
1127
+ .updateGlobalData({ order_total: '$14.50' })
1128
+ .refreshStep('take_order');
1129
+ ```
1130
+
1080
1131
  ### swmlChangeContext
1081
1132
 
1082
1133
  Move the conversation to another context (`change_context`). The context must exist in the agent's contexts, which you define with `defineContexts()`. A change from a tool isn't limited by `setValidContexts()`.
@@ -1182,9 +1233,50 @@ const r2 = new FunctionResult('Wait for the caller to answer.')
1182
1233
  .enableFunctionsOnTimeout(false);
1183
1234
  ```
1184
1235
 
1236
+ ### noBargeNextResponse
1237
+
1238
+ Have the next spoken reply play whole, such as a read-back the caller should hear in full before answering (`no_barge_next_response`). Until a reply that speaks has played, the caller's words neither cut it nor cancel its request: they're held and delivered after it. For semantic gates, an answer begun during the reply reads as cutting it at that point, as a barge would. Needs a platform release that has the action.
1239
+
1240
+ <!-- snippet: no-compile API signature reference, not runnable code -->
1241
+ ```typescript
1242
+ noBargeNextResponse(): this
1243
+ ```
1244
+
1245
+ **Returns:** `this` for chaining.
1246
+
1247
+ **Example:**
1248
+
1249
+ ```typescript
1250
+ const result = new FunctionResult('Read the order back to the caller.').noBargeNextResponse();
1251
+ ```
1252
+
1253
+ ### backToBackFunctions
1254
+
1255
+ Set whether the model may call another function right after a function result, without answering in words first (`back_to_back_functions`). `'forever'`, the call's default, chains freely. `false` makes the model answer in words after a function result. `true`, while chaining is off, allows one more chain, and then it's off again; it never lowers `'forever'`. The setting lasts for the call. Realtime models don't read it.
1256
+
1257
+ <!-- snippet: no-compile API signature reference, not runnable code -->
1258
+ ```typescript
1259
+ backToBackFunctions(value?: boolean | 'forever'): this
1260
+ ```
1261
+
1262
+ | Parameter | Type | Default | Description |
1263
+ |-----------|-------------------------|---------|-----------------------------------|
1264
+ | `value` | `boolean \| 'forever'` | `true` | The chaining setting for the call. |
1265
+
1266
+ **Returns:** `this` for chaining.
1267
+
1268
+ **Throws:** `Error` for any other value, which the platform ignores.
1269
+
1270
+ **Example:**
1271
+
1272
+ ```typescript
1273
+ // A read-back the caller must answer before anything else runs
1274
+ const result = new FunctionResult('Read the order back to the caller.').backToBackFunctions(false);
1275
+ ```
1276
+
1185
1277
  ### updateSettings
1186
1278
 
1187
- Update AI settings during the call (`settings`). The platform validates the keys. The Python SDK's reference lists `temperature`, `top-p`, `max-tokens`, `frequency-penalty`, `presence-penalty`, `confidence` and `barge-confidence`.
1279
+ Update the model's settings for the rest of the call (`settings`). The platform validates the keys: the model's parameters, such as `temperature`, `top-p`, `max-tokens`, `frequency-penalty` and `presence-penalty`, and `confidence` or `barge-confidence`. Each key you name replaces its current value; every other setting keeps its value, including the ones set for the prompt. A key the model doesn't take is ignored. A key can't be removed: to undo one, set it to the value you want, such as the model's default. Platform releases before this reset every key you don't name to the model's default.
1188
1280
 
1189
1281
  <!-- snippet: no-compile API signature reference, not runnable code -->
1190
1282
  ```typescript
@@ -1745,7 +1837,7 @@ const result = new FunctionResult('The held caller is being reconnected.')
1745
1837
 
1746
1838
  ### pay
1747
1839
 
1748
- Start a payment collection flow on the call. The SDK emits an inline SWML document that sets `ai_response` with the `set` verb and then runs the `pay` verb. The payment connector at `paymentConnectorUrl` processes the payment.
1840
+ Start a payment collection flow on the call. The SDK emits an inline SWML document that runs the `pay` verb and then sets `ai_response` with the `set` verb, so its `${pay_result}` is the payment's status: `set` expands it when it runs. The payment connector at `paymentConnectorUrl` processes the payment.
1749
1841
 
1750
1842
  <!-- snippet: no-compile API signature reference, not runnable code -->
1751
1843
  ```typescript
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signalwire/sdk",
3
- "version": "3.7.2",
3
+ "version": "3.10.3",
4
4
  "description": "SignalWire AI Agents SDK for TypeScript/Node.js",
5
5
  "keywords": [
6
6
  "signalwire",