@signalwire/sdk 3.9.0 → 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.
@@ -224,7 +224,7 @@ Help the customer with their billing inquiry.
224
224
 
225
225
  ### Variables in Step Text
226
226
 
227
- The platform expands a step's variables, such as `${global_data.order_total}`, once, when the step is entered. A later `updateGlobalData()` doesn't change text the model already has. To show the new value, return `FunctionResult.refreshStep()` with the current step's name after the update. Entering the step starts it over, and its `history` mode applies again.
227
+ The platform expands a step's variables, such as `${global_data.order_total}`, when the step is entered. Releases that have re-expansion rewrite the text in place before a request when a value it reads has changed (see [Conversation History Between Steps](#conversation-history-between-steps)); on earlier releases, and with a realtime model, a later `updateGlobalData()` doesn't change text the model already has. To show the new value there, return `FunctionResult.refreshStep()` with the current step's name after the update. Entering the step starts it over, and its `history` mode applies again.
228
228
 
229
229
  ```typescript
230
230
  import { FunctionResult } from '@signalwire/sdk';
@@ -419,8 +419,37 @@ The modes are these:
419
419
  - `default`: hide earlier step instructions, and keep the dialogue. This is the behavior when `history` isn't set.
420
420
  - `hide`: hide earlier instructions and the earlier dialogue. A `${step_history.*}` reference in this step's text brings back what you choose.
421
421
  - `isolate`: like `hide`, but only while the agent is in this step. When the step is left, the earlier dialogue returns and the step's own turns stay; the earlier instructions stay cleared, and what an earlier `hide` step hid stays hidden. Entering the step again isolates it again. Use it for a step that must see nothing else, such as a confirmation read-back. A platform without `isolate` treats it as `default`.
422
+ - `spoken`: hide earlier instructions, and take every earlier tool call, tool result and turn-scoped system note (tool prompts, `ai-msg` injections, a gather's preamble) out for the rest of the call, while every spoken turn stays, the caller's and the agent's. A platform without `spoken` treats it as `default`.
422
423
 
423
- `Context.setHistory()` sets the default for every step in the context, and a step's own `setHistory()` overrides it. Any other value throws.
424
+ `Context.setHistory()` sets the default for every step in the context, and a step's own `setHistory()` overrides it. Any other value throws. See [Conversation History Between Steps](#conversation-history-between-steps) for when each mode applies and what it keeps.
425
+
426
+ ### Conversation History Between Steps
427
+
428
+ The mode applies when the step's instructions are injected, before the next request to the model. For a tool whose result changed the step, that's the follow-up request right after the result, so the mode covers everything before the exchange that triggered the change.
429
+
430
+ | Mode | Earlier step instructions | Earlier tool calls and results | Earlier spoken turns |
431
+ |---|---|---|---|
432
+ | `keep` | Kept | Kept | Kept |
433
+ | `default` (when unset) | Cleared | Kept | Kept |
434
+ | `spoken` | Cleared | Gone for the rest of the call | Kept |
435
+ | `hide` | Cleared | Gone for the rest of the call | Gone for the rest of the call |
436
+ | `isolate` | Cleared | Gone while in the step | Gone while in the step |
437
+
438
+ An end step, or one with a reset, takes no history pass: what the model saw stays as it was, and what an `isolate` step hid comes back. A reset step runs its reset in place of its text.
439
+
440
+ `spoken`, `hide` and `isolate` also remove the turn-scoped system notes: tool prompts, `ai-msg` injections and a gather's preamble. All three keep the exchange that entered the step, as the step's start: the call whose action changed the step, its result, notes and `say`, and any caller words stored before the step was injected. The protection covers only the step it entered: after that the exchange is an ordinary entry, which each later step treats by its own mode. An action with `post_process` runs after the model's reply to its result, and its change keeps the call and everything stored from it on: the result and notes, the reply, and the caller's words stored meanwhile. A change by `next_step` keeps nothing. Platform releases before this keep nothing under `hide` and `isolate`, and nothing of a `post_process` change. An agent turn that spoke and called a tool keeps its words under `spoken`. `say` actions are spoken turns. Semantic gates judge the same turns the model sees, so `hide` takes the caller's earlier words from the gates as well, and `spoken` keeps them. A platform release without `isolate` or `spoken` treats the value as `default`.
441
+
442
+ A consolidation's summary stays under `hide` and `spoken`, where it was added; `isolate` hides it while the step lasts. That's the summary the platform writes when the conversation nears the model's context limit, and the one `consolidate` writes on a step's or context's reset or a context switch. Consolidation and the sliding window keep the entries in force: the current step's instructions, with its context's prompt, and during a gather its current question and preamble.
443
+
444
+ On platform releases that have it, the step's instructions are expanded again before a request when a value its text reads has changed, such as global data a tool set. The entry is rewritten in place, and no history mode runs, since the step hasn't changed. An end step, a gather question and a realtime model keep the text as it went in.
445
+
446
+ Choose by what must survive between stages:
447
+
448
+ - **`spoken`** at a stage boundary where the caller's earlier requests must stay but the finished stage's lookups shouldn't. A model that sees old tool results tends to call tools the current step doesn't offer.
449
+ - **`isolate`** on a confirm step, so the read-back is all the model has, with the earlier conversation back once the step is left.
450
+ - **`hide`** only where earlier talk must never come back.
451
+
452
+ What the next stage needs from the last one belongs in `global_data`, shown in the step's text as `${global_data.name}`, not in a tool result the next stage was never meant to see. `${step_history.prev.summary}`, `${step_history.prev.dialog}` and `${step_history.all.dialog}` in a step's text bring back a summary or the transcript of earlier steps under any mode. In a test, `CallSimulator.modelView()` shows what the model gets after each step's mode.
424
453
 
425
454
  ---
426
455
 
@@ -168,7 +168,7 @@ const ctx = agent.defineContexts().addContext('default');
168
168
  ctx.addStep('take_order').setText('Take the order.\n\n${global_data.later_text}');
169
169
  ```
170
170
 
171
- `later.next(rawData)` gives the oldest request with its opener, and `later.done(rawData)` removes it once it's taken up. The kinds and their openers are yours; an opener's `{about}` is replaced by what the request is about. A step's text is expanded when the step is entered, so return `refreshStep()` with a note to show the new list at once.
171
+ `later.next(rawData)` gives the oldest request with its opener, and `later.done(rawData)` removes it once it's taken up. The kinds and their openers are yours; an opener's `{about}` is replaced by what the request is about. Current platform releases expand the step's text again when the list changes, so it shows at the next request. Earlier releases, and a realtime model, keep the list from the step's entry: return `refreshStep()` with the note there to show it at once.
172
172
 
173
173
  ## What a Caller Spelled
174
174
 
@@ -229,7 +229,7 @@ assert.equal((await sim.call('place_order')).ran, true);
229
229
  assert.deepEqual(sim.semanticState, { done: 'The order is placed.' });
230
230
  ```
231
231
 
232
- The gate callback gets each gate, the simulator and the call's arguments, and returns `true`, `false`, a probability compared with the gate's threshold, or `'unclear'`, or a promise of one. A blocked call's `blockedBy` is `'step'` or the id of the gate that blocked it. With `checkToolMentions: true`, a call whose result names a tool that the step it leaves the call in doesn't offer rejects with a `ToolMentionError`: the model would read the name and might call a tool it doesn't have. Give `stubs` for DataMap tools, which run on the platform. `sim.marks` is a `Map` from each gate mark's name to its place in `sim.callLog`.
232
+ The gate callback gets each gate, the simulator and the call's arguments, and returns `true`, `false`, a probability compared with the gate's threshold, or `'unclear'`, or a promise of one. A blocked call's `blockedBy` is `'step'` or the id of the gate that blocked it. `sim.gateConversation(gate)` gives the dialogue that gate would judge: the spoken turns the model sees, chosen by its window, proposal or mark. `sim.modelView()` gives what the model gets now, after each step's history mode, and a `post_process` result's actions run after `sim.agentSays()`. With `checkToolMentions: true`, a call whose result names a tool that the step it leaves the call in doesn't offer rejects with a `ToolMentionError`: the model would read the name and might call a tool it doesn't have. Give `stubs` for DataMap tools, which run on the platform. `sim.marks` is a `Map` from each gate mark's name to its place in `sim.callLog`.
233
233
 
234
234
  The simulator renders and runs tools on the agent itself: it doesn't make the per-request copy a dynamic config callback configures. It doesn't run a model, gather questions, or the gates' decision model.
235
235
 
@@ -317,6 +317,11 @@ List allowed model transitions when the model can choose among safe destinations
317
317
  - `default`: remove prior step instructions and keep the dialogue; the behavior when unset.
318
318
  - `hide`: remove prior instructions and dialogue from the model's view. Use `${step_history.*}` references in the step's text to bring back selected information.
319
319
  - `isolate`: like `hide`, but only while the agent is in this step. When the step is left, the earlier dialogue returns and the step's own turns stay; the earlier instructions stay cleared, and what an earlier `hide` step hid stays hidden. Entering the step again isolates it again. Use it for a step that must see nothing else, such as a confirmation read-back. A platform without `isolate` treats it as `default`.
320
+ - `spoken`: remove prior instructions and every earlier tool call, tool result and turn-scoped system note (tool prompts, `ai-msg` injections, a gather's preamble) for the rest of the call, while keeping every spoken turn, the caller's and the agent's. A platform without `spoken` treats it as `default`.
321
+
322
+ `hide`, `isolate` and `spoken` keep the exchange that entered the step, as its start: the call whose action changed the step, with its result, notes and `say`, so a confirm step entered from a tool keeps the read-back the caller just heard. A `post_process` action's change, which runs after the model's reply, keeps the call and everything stored from it on, the reply included. A change by `next_step` keeps nothing, and platform releases before this keep nothing under `hide` and `isolate`.
323
+
324
+ Between the stages of a task, choose by what must survive. Use `spoken` at a stage boundary where the caller's earlier requests must stay but the finished stage's lookups shouldn't: a model that sees old tool results tends to call tools the current step doesn't offer. Use `isolate` on a confirm step. Use `hide` only where earlier talk must never come back, because it takes the caller's earlier requests too, from the model and from the semantic gates. Put any result the next stage needs in `global_data`, and show it in the step's text.
320
325
 
321
326
  Hidden turns remain in the call log, so don't describe `hide` as deletion. `Context.setIsolated()`, `setSystemPrompt()`, `setUserPrompt()`, `setConsolidate()` and `setFullReset()` add more controls for entering a context. Steps have `setResetSystemPrompt()`, `setResetUserPrompt()`, `setResetConsolidate()` and `setResetFullReset()`. Verify the combination you choose on the runtime rather than treating them all as a memory wipe. [S03]
322
327
 
@@ -243,7 +243,7 @@ PGI restores programming to the equation. In PGI, the developer's traditional sk
243
243
 
244
244
  A developer building an intake system writes a gather sequence. The platform presents the model with one question at a time and a single submission tool, `gather_submit`. The tool's schema is rebuilt for each question, with that answer's type and, when the question asks for it, a required confirmation. The model does not know how many questions remain or what the full form looks like. When an answer arrives, the platform stores it in `global_data` and silently advances to the next question. When the sequence is complete, the accumulated structured data is handed off to the next phase of the workflow. There, a handler validates the whole record before anything consequential uses it. The model never saw the form. It never had the opportunity to skip ahead, reorder questions, or submit answers to questions that were never asked.
245
245
 
246
- Visibility of what came before is itself a dial the developer controls. By default, each new phase withdraws the prior phase's instructions from the model's context while the conversation itself remains visible. At stricter settings, the platform pulls the earlier dialogue out entirely, or hides the answers already collected so the model must ask rather than infer. A hidden phase can also be brought back on purpose. The platform can hand the model a summary of an earlier phase instead of the raw transcript. The summary is one more curated projection in place of the full truth. Reality authoring extends to the past, not only the present. In the SDK, these settings are `setHistory()` on a step or context (`keep`, `default`, `hide`, or `isolate`, which hides the earlier dialogue only while the agent is in that step) and the `isolated` option of `setGatherInfo()` and `addGatherQuestion()`. A `${step_history.*}` reference in a step's text chooses what comes back. The call log keeps every message either way.
246
+ Visibility of what came before is itself a dial the developer controls. By default, each new phase withdraws the prior phase's instructions from the model's context while the conversation itself remains visible. At stricter settings, the platform pulls the earlier dialogue out entirely, or hides the answers already collected so the model must ask rather than infer. A hidden phase can also be brought back on purpose. The platform can hand the model a summary of an earlier phase instead of the raw transcript. The summary is one more curated projection in place of the full truth. Reality authoring extends to the past, not only the present. In the SDK, these settings are `setHistory()` on a step or context (`keep`, `default`, `hide`, `isolate`, which hides the earlier dialogue only while the agent is in that step, or `spoken`, which drops the earlier tool exchanges and keeps what was said) and the `isolated` option of `setGatherInfo()` and `addGatherQuestion()`. A `${step_history.*}` reference in a step's text chooses what comes back. The call log keeps every message either way.
247
247
 
248
248
  This is not the same as ordinary backend validation (clamping a quantity with `if (quantity > 20) quantity = 20;`, or rejecting a bad input). Those are single lines of defensive code any backend performs. The gather sequence is reality authoring. The developer constructs what the model believes to be true at each moment, and `global_data` carries the accumulated truth the model never sees.
249
249
 
@@ -854,7 +854,7 @@ const result = new FunctionResult('The customer record is loaded.')
854
854
 
855
855
  ### setSemanticState
856
856
 
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. 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).
858
858
 
859
859
  <!-- snippet: no-compile API signature reference, not runnable code -->
860
860
  ```typescript
@@ -877,7 +877,7 @@ const result = new FunctionResult('The order is confirmed.').setSemanticState({
877
877
 
878
878
  ### setSemanticGateMark
879
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 action object that sets it, so a `say` in the same object is the first turn after it, and setting it again moves it. 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).
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
881
 
882
882
  <!-- snippet: no-compile API signature reference, not runnable code -->
883
883
  ```typescript
@@ -1107,7 +1107,7 @@ const result = new FunctionResult('The premium plan is confirmed. Collect paymen
1107
1107
 
1108
1108
  ### refreshStep
1109
1109
 
1110
- Enter the current step again, so its text shows new global data. A step's text is expanded once, when the step is entered, so its `${global_data.*}` values are the ones from then. 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.
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
1111
 
1112
1112
  <!-- snippet: no-compile API signature reference, not runnable code -->
1113
1113
  ```typescript
@@ -1276,7 +1276,7 @@ const result = new FunctionResult('Read the order back to the caller.').backToBa
1276
1276
 
1277
1277
  ### updateSettings
1278
1278
 
1279
- 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.
1280
1280
 
1281
1281
  <!-- snippet: no-compile API signature reference, not runnable code -->
1282
1282
  ```typescript
@@ -1837,7 +1837,7 @@ const result = new FunctionResult('The held caller is being reconnected.')
1837
1837
 
1838
1838
  ### pay
1839
1839
 
1840
- 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.
1841
1841
 
1842
1842
  <!-- snippet: no-compile API signature reference, not runnable code -->
1843
1843
  ```typescript
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signalwire/sdk",
3
- "version": "3.9.0",
3
+ "version": "3.10.3",
4
4
  "description": "SignalWire AI Agents SDK for TypeScript/Node.js",
5
5
  "keywords": [
6
6
  "signalwire",