@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.
- package/CHANGELOG.md +201 -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 +215 -14
- package/dist/ContextBuilder.js +441 -14
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/FunctionResult.d.ts +146 -1
- package/dist/FunctionResult.js +188 -2
- 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 +148 -0
- package/dist/patterns/Proposal.js +214 -0
- package/dist/patterns/Proposal.js.map +1 -0
- package/dist/patterns/RequestList.d.ts +138 -0
- package/dist/patterns/RequestList.js +171 -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 +391 -0
- package/dist/testing/CallSimulator.js +966 -0
- package/dist/testing/CallSimulator.js.map +1 -0
- package/docs/agent-guide.md +2 -2
- package/docs/api-reference.md +279 -22
- package/docs/architecture.md +8 -4
- package/docs/cli-guide.md +2 -0
- package/docs/contexts-guide.md +75 -4
- package/docs/conversation_patterns.md +257 -0
- package/docs/mcp_integration.md +1 -1
- package/docs/pgi_agent_guide.md +5 -0
- package/docs/programmatically_governed_inference.md +2 -2
- package/docs/swaig-reference.md +98 -6
- package/package.json +1 -1
package/docs/swaig-reference.md
CHANGED
|
@@ -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
|
-
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|