@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
package/CHANGELOG.md CHANGED
@@ -3,6 +3,207 @@
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.10.3 (2026-11-18)
7
+
8
+ Parity with signalwire-python 3.10.3: the `spoken` history mode, and a call
9
+ simulator that shows what the model gets after each step's history mode,
10
+ checked against the platform (end and reset steps, proposal changes).
11
+ The platform behavior below is in mod_openai's release with it (7afb159);
12
+ an engine without it treats `spoken` as `default`.
13
+
14
+ ### Added
15
+
16
+ - History mode `spoken`, for `Step.setHistory()` and `Context.setHistory()`
17
+ (`HISTORY_MODES`): earlier step instructions, tool calls, tool results and
18
+ turn-scoped system notes (tool prompts, `ai-msg` injections, a gather's
19
+ preamble) leave the model's context for the rest of the call, and every
20
+ spoken turn stays, `say` actions included. An agent turn that spoke and
21
+ called a tool keeps its words. Use it at a stage boundary where the caller's
22
+ earlier requests must stay but the finished stage's tool results shouldn't.
23
+ - `CallSimulator.modelView()` gives the conversation the model gets now,
24
+ after each step's history mode: the step's instructions injected before the
25
+ next request, the exchange that entered a step kept, a result's `say` held
26
+ after the call's result and notes, and the step's text expanded again when a
27
+ value it reads changes. `gateConversation(gate)` gives the dialogue a gate
28
+ judges (its `since` mark, a proposal, or the window, then `history`
29
+ entries), and `historyMode()` the current step's mode.
30
+ - The simulator runs a `post_process` result's actions after the model's
31
+ reply, given with `agentSays()`; a newer such result replaces actions still
32
+ waiting. A proposal and a gate mark date from the start of the result's
33
+ action list.
34
+
35
+ ### Fixed
36
+
37
+ - `FunctionResult.pay()` runs `pay` before the `set` of `ai_response`. SWML
38
+ `set` expands `${pay_result}` when it runs, so setting it first gave the
39
+ model an empty payment status (#231; signalwire-python#176, 3.10.3).
40
+
41
+ ### Changed
42
+
43
+ - The docs describe the platform's history behavior: `hide`, `isolate` and
44
+ `spoken` keep the exchange that entered the step (the call whose action
45
+ changed it, its result, notes and `say`), a `post_process` change keeps its
46
+ call and what followed, and `next_step` keeps nothing; a consolidation
47
+ summary stays under `hide` and `spoken`; the step's text is expanded again
48
+ when a value it reads changes; `updateSettings()` merges per key; and a
49
+ proposal or mark dates from the start of the result's action list. A new
50
+ Contexts and Steps Guide section, Conversation History Between Steps,
51
+ covers when each mode applies.
52
+
53
+ ## 3.9.0 (2026-11-13)
54
+
55
+ Parity with signalwire-python 3.9.0: tool-name and reset checks, a
56
+ `noBargeNextResponse()` action, and doc fixes after 3.8.0. It's the first
57
+ release with the 3.8.0 changes below.
58
+
59
+ ### Added
60
+
61
+ - Rendering logs `tool_named_but_not_offered`, once each, when a step that
62
+ lists its functions names a registered tool it doesn't offer: in its text,
63
+ its criteria, its context's prompt, a gather question, or a gate's output on
64
+ one of its tools. The model reads the name and may call a tool it doesn't
65
+ have. `namedTools(text, tools)` finds the names; a one-word name counts only
66
+ in backticks or before "(".
67
+ - `FunctionResult.noBargeNextResponse()` has the next spoken reply play whole,
68
+ with what the caller says during it held until after it. It needs a platform
69
+ release that has the action.
70
+ - Rendering logs `step_reset_is_terminal` for a step with a reset, whose text
71
+ the platform never runs, and `context_reset_without_system_prompt` for a
72
+ context's consolidate, full reset or user prompt, which act only with a
73
+ system prompt. Each is logged once, across per-request copies too.
74
+ - `new CallSimulator(agent, { checkToolMentions: true })` rejects a call with
75
+ `ToolMentionError` when its result names a tool the step it leaves the call
76
+ in doesn't offer.
77
+
78
+ ### Fixed
79
+
80
+ - The docs said a slow tool can run more than once on a retry; since 3.8.0 the
81
+ agent answers a retry with the first attempt's result. They now say the
82
+ record is kept per process, so with several replicas a retry that reaches
83
+ another one runs the tool again.
84
+ - `Context.setIsolated()` says what the platform does: it drops every entry
85
+ but the base prompt, rather than the whole conversation.
86
+ - The step reset methods say what the platform does: a step with a reset is
87
+ terminal. The `next_step` schema is rewritten when a step loads, not every
88
+ turn.
89
+
90
+ ## 3.8.0 (2026-11-13)
91
+
92
+ Tagged but not published: its changes first ship in 3.9.0.
93
+
94
+ Parity with signalwire-python 3.8.0, the voice-agent toolkit: newer semantic
95
+ gate keys, tool outcomes and options, tool middleware with retry dedupe, the
96
+ caller's own words, speech helpers, conversation patterns and a call
97
+ simulator. The gate keys, `semantic_gate_dialogue`,
98
+ `unavailable_function_response`, `semantic_gate_mark` and `expected_answer`
99
+ need a platform release that has them: one with gates but without a key
100
+ refuses the function, as it treats an unknown gate key as an error.
101
+
102
+ ### Added
103
+
104
+ - Semantic gates take the platform's newer keys. `new SemanticGate(question,
105
+ threshold, onFail, { dialogue, history })` sets the dialogue one gate
106
+ judges, `'window'` or `'proposal'` and 1 to 100 entries, in place of the
107
+ agent's; every gate of a function must set the same ones, as the platform
108
+ requires, and rendering throws when they differ. `unclear: true` asks yes,
109
+ no or unclear, and `onUnclear` is what the model gets for an unclear
110
+ answer. `since` anchors a gate's dialogue at a mark your code sets with the
111
+ new `FunctionResult.setSemanticGateMark(name)` action.
112
+ `setSemanticGates({ dialogue })` sets the agent's `semantic_gate_dialogue`.
113
+ - `setUnavailableFunctionResponse(text)` sets what the model is told when it
114
+ calls a tool it can't use now, with `${function}`, `${tools}` and
115
+ `${steps}`.
116
+ - `defineTool({ vouched: true })` adds a required boolean argument,
117
+ `data_supplied_by_user`, in which the model says every argument came from
118
+ the caller. Unless it's true, the handler doesn't run, and the model is
119
+ told to get the answer from the caller first.
120
+ - `ToolRefusal`: throw `new ToolRefusal(toolResult, toolPrompt)` from a
121
+ handler or middleware to decline a call with an outcome you know. It
122
+ bypasses the `onError` hooks.
123
+ - `FunctionResult.backToBackFunctions(value)` sets whether the model may call
124
+ another function right after a result (`true`, `false` or `'forever'`).
125
+ - `FunctionResult.refreshStep(name)` enters the current step again, so step
126
+ text that shows `${global_data.*}` values, which are expanded once on
127
+ entry, shows the new ones.
128
+ - `Step.setExpectedAnswer(digits)` (or `{ minDigits, maxDigits }`), the
129
+ `expectedAnswer()` helper and a gather question's `expectedAnswer` tell the
130
+ recognizer how many digits the caller's answer has, so it ends its wait
131
+ once they're said.
132
+ - `defineTool({ nullableOptional: true })` and
133
+ `setNullableOptionalParameters()` let the model send null for optional
134
+ arguments, as strict provider schemas require; a null reaches the handler
135
+ as an argument not given.
136
+ - `defineNativeTool(name, description, parameters?, fields?)` defines a
137
+ function the platform implements itself, sent with `web_hook_url:
138
+ "native"`, under your own description.
139
+ - Tool middleware: `addToolMiddleware(fn)` and `defineTool({ middleware })`
140
+ run `fn(name, args, rawData, callNext)` around tool calls; `callNext`
141
+ returns a promise of the handler's result. On `SWMLService` too, so a
142
+ plain service's tools have them.
143
+ - A transport retry of a tool request no longer runs the tool twice.
144
+ SignalWire sends a request again, with the same `tool_call_id`, after a
145
+ timeout, a failed connection or a 5xx; the agent answers the retry with
146
+ the first attempt's result, and one that arrives while the first is still
147
+ running waits for it. A call the model makes again has a new
148
+ `tool_call_id` and runs. On by default, and shared with per-request
149
+ copies; `setToolResendDedupe(false)` turns it off. The state lives in the
150
+ process, so replicas each keep their own.
151
+ - The caller's own words in a handler: `callerTurns(rawData)` reads what the
152
+ caller said from the request's conversation, and `defineTool({
153
+ needsConversation: true })` turns on `swaig_post_conversation` so requests
154
+ carry it. `recordSpeechFinals()` and `speechFinals(callId)` keep the
155
+ recognizer's finals with their word confidences, from the platform's
156
+ `ai.speech_detect` events, and `onAiEvent(handler)` receives every AI
157
+ event; the agent sets `event_webhook_url` to its new `/ai_events` endpoint
158
+ for them (POST, JSON, size-limited, authenticated and signature-checked as
159
+ the agent's other endpoints are). Register them on the agent, not in a
160
+ per-request callback.
161
+ - Speech helpers: `sayDigits`, `sayLastDigits`, `sayMoney` and `numberWords`
162
+ give the words a voice should say for digits and amounts, which
163
+ `addPronunciation` can't fix, since the platform normalizes text before its
164
+ pronunciation rules run. `sayMoney` takes a number, a bigint or a decimal
165
+ string and rounds half up from its decimal digits. `readSpelled` reads what
166
+ a caller spelled (letters, letter names, "S as in Sam", NATO words, "double
167
+ l", digits), `spokenEmail` reads an address said aloud, and
168
+ `spellingVariants` expands letters the recognizer confuses, with groups you
169
+ supply.
170
+ - `Proposal` is the platform's confirm pattern: `propose()` reads a change
171
+ back and records it in `semantic_state` in one action object, and
172
+ `confirmGates()` gives the confirm tool the three gates (answered, agreed,
173
+ read back) judged on the proposal's dialogue, with an `onFail` that quotes
174
+ the proposal. `askAgain()` and `complete()` round it out.
175
+ - `RequestList` keeps what the caller asked for while the agent was busy, in
176
+ the call's `global_data`, with step text that lists it, to take up when the
177
+ current task is done.
178
+ - `CallSimulator` runs an agent's tools through a simulated call, checked as
179
+ the platform checks them: the step's function list (with the platform's
180
+ reply for a tool it won't run), the semantic gates from a callback, and
181
+ each result's actions on the call's state. Tools run as the `/swaig` route
182
+ runs them. `RequestRecorder` middleware records tool requests for
183
+ `CallSimulator.replay()`.
184
+ - [Conversation Patterns](docs/conversation_patterns.md), a new guide.
185
+ - `ContextBuilder.stepsOffering(name)` lists the steps whose function lists
186
+ name a tool. Rendering logs `tool_offered_by_no_step` once for a
187
+ registered tool that no step offers, when every step lists its functions.
188
+
189
+ ### Changed
190
+
191
+ - A tool handler that throws now tells the model the function failed before
192
+ it finished, so whether it took effect is unknown, with a tool prompt not
193
+ to tell the caller it worked or that it didn't. It used to return "Sorry, I
194
+ couldn't complete that action. Please try again or contact support if the
195
+ issue persists.", which let the model guess the outcome. The error is
196
+ logged; the `onError` hooks and a tool's `errorMessage` still come first.
197
+ `DEFAULT_SWAIG_ERROR_MESSAGE` is deprecated.
198
+ - A handler that returns an object with neither `response` nor `action` gives
199
+ the model the object as JSON, and an empty object says the outcome is
200
+ unknown. It used to answer "Function completed successfully", dropping the
201
+ object. A handler that returns nothing answers "Function executed
202
+ successfully"; it used to answer "undefined". Handler types allow `void`.
203
+ - A plain `SWMLService`'s `/swaig` route runs tools with the same rules as an
204
+ agent's: the vouched check, middleware, the retry dedupe and the outcome
205
+ rules.
206
+
6
207
  ## 3.7.2 (2026-11-12)
7
208
 
8
209
  Parity with signalwire-python 3.7.7: the chat-session token fix, a plain
package/README.md CHANGED
@@ -265,6 +265,7 @@ The [`docs/`](docs/) directory has these guides. They're installed with the pack
265
265
 
266
266
  - [SWAIG Reference](docs/swaig-reference.md): function results, actions, post_data lifecycle
267
267
  - [Contexts and Steps](docs/contexts-guide.md): structured workflows, navigation, gather mode
268
+ - [Conversation Patterns](docs/conversation_patterns.md): confirming a change, the caller's own words, numbers to say, testing a call flow
268
269
  - [DataMap Guide](docs/datamap-guide.md): serverless API tools without webhooks
269
270
  - [LLM Parameters](docs/llm_parameters.md): temperature, top_p, barge settings
270
271
  - [SWML Service Guide](docs/swml_service_guide.md): low-level construction of SWML documents
@@ -10,10 +10,17 @@ import type { HostAppRouter } from './web.js';
10
10
  import { PromptManager } from './PromptManager.js';
11
11
  import { PromptObjectModel } from './POM/PromptObjectModel.js';
12
12
  import { SWMLService } from './SWMLService.js';
13
+ import type { ToolMiddleware } from './ToolMiddleware.js';
14
+ import { type SpeechFinal } from './AiEvents.js';
15
+ /**
16
+ * A handler for the AI events the platform posts during calls, as
17
+ * {@link AgentBase.onAiEvent} registers it.
18
+ */
19
+ export type AiEventHandler = (eventType: string, params: Record<string, unknown>, event: Record<string, unknown>) => unknown;
13
20
  import { SwaigFunction, type SwaigErrorHandler } from './SwaigFunction.js';
14
21
  import { type FillerPhrases, type SemanticGate } from './SemanticGate.js';
15
22
  import { type TypedToolHandler } from './TypeInference.js';
16
- import { FunctionResult } from './FunctionResult.js';
23
+ import { FunctionResult, type SwaigResultDict } from './FunctionResult.js';
17
24
  import { ContextBuilder } from './ContextBuilder.js';
18
25
  import { type Logger } from './Logger.js';
19
26
  import { SkillManager } from './skills/SkillManager.js';
@@ -126,6 +133,10 @@ export declare class AgentBase extends SWMLService {
126
133
  private perCallConfigs;
127
134
  /** Set once serve() runs an HTTP server; getFullUrl then ignores serverless environments. */
128
135
  private _serving;
136
+ /** Handlers registered with {@link onAiEvent}. */
137
+ private _aiEventHandlers;
138
+ /** The recognizer's finals per call, once {@link recordSpeechFinals} is on. */
139
+ private _speechLog;
129
140
  /** Handlers registered with {@link onCallStart}. */
130
141
  private callStartHandlers;
131
142
  /** Handlers registered with {@link onCallEnd}. */
@@ -136,6 +147,8 @@ export declare class AgentBase extends SWMLService {
136
147
  private webHookUrlOverride;
137
148
  private postPromptUrlOverride;
138
149
  private contextsBuilder;
150
+ /** Tools the contexts reported as offered by no step; shared with per-request copies. */
151
+ private _unofferedToolsWarned;
139
152
  /** Contexts given as a plain object, rendered as they are. */
140
153
  private _rawContexts;
141
154
  private _mcpServers;
@@ -549,6 +562,14 @@ export declare class AgentBase extends SWMLService {
549
562
  * `semantic_gate_timeout_ms`.
550
563
  * @param opts.history - How many recent dialogue entries the decision model
551
564
  * sees, 0 to 100. Default 20. Sent as `semantic_gate_history`.
565
+ * @param opts.dialogue - Which dialogue the decision model judges:
566
+ * `'window'`, the newest `history` entries, or `'proposal'`, those since
567
+ * `global_data.semantic_state` last changed (see
568
+ * {@link FunctionResult.setSemanticState}), from the agent's first turn
569
+ * after it: the read-back and the caller's reply. With no
570
+ * `semantic_state` set, the window. A gate's own `dialogue` and `history`
571
+ * take the place of these for its function. Default `'window'`. Sent as
572
+ * `semantic_gate_dialogue`; it needs a platform release that has it.
552
573
  * @returns This agent instance for chaining.
553
574
  * @throws {Error} When a value has the wrong type or is out of range.
554
575
  */
@@ -556,7 +577,23 @@ export declare class AgentBase extends SWMLService {
556
577
  enabled?: boolean;
557
578
  timeoutMs?: number;
558
579
  history?: number;
580
+ dialogue?: 'window' | 'proposal';
559
581
  }): this;
582
+ /**
583
+ * Set what the model is told when it calls a tool it can't use now.
584
+ *
585
+ * Without it, the platform says nothing ran, which steps offer the tool, and
586
+ * which tools are available now. `text` takes its place, with `${function}`
587
+ * for the tool's name, `${tools}` for the tools the request offered,
588
+ * comma-separated, and `${steps}` for the current context's steps whose
589
+ * functions include it (empty for a name the agent doesn't have). Sent as
590
+ * the `unavailable_function_response` param; it needs a platform release
591
+ * that has it.
592
+ * @param text - The text.
593
+ * @returns This agent instance for chaining.
594
+ * @throws {Error} When `text` isn't a non-empty string.
595
+ */
596
+ setUnavailableFunctionResponse(text: string): this;
560
597
  /**
561
598
  * **MERGES** `data` into the global_data object passed into the AI
562
599
  * configuration. **Despite the name, this does NOT replace** the existing
@@ -826,6 +863,14 @@ export declare class AgentBase extends SWMLService {
826
863
  gates?: ReadonlyArray<SemanticGate | Record<string, unknown>>;
827
864
  /** Phrases said while the gates are checked (see `SwaigFunctionOptions.gateFillers`). */
828
865
  gateFillers?: FillerPhrases;
866
+ /** Whether the model must vouch for the arguments (see `SwaigFunctionOptions.vouched`). */
867
+ vouched?: boolean;
868
+ /** Whether optional arguments take null (see `SwaigFunctionOptions.nullableOptional`). */
869
+ nullableOptional?: boolean;
870
+ /** Whether the handler reads the conversation (see `SwaigFunctionOptions.needsConversation`). */
871
+ needsConversation?: boolean;
872
+ /** Middleware around this tool's calls (see `SwaigFunctionOptions.middleware`). */
873
+ middleware?: readonly ToolMiddleware[];
829
874
  }): this;
830
875
  /**
831
876
  * Validate a tool-call token for the given function.
@@ -1049,6 +1094,58 @@ export declare class AgentBase extends SWMLService {
1049
1094
  * @returns This agent instance for chaining.
1050
1095
  */
1051
1096
  addPerCallConfig(cb: DynamicConfigCallback): this;
1097
+ /**
1098
+ * Register a handler for the AI events the platform posts during calls.
1099
+ *
1100
+ * The agent sets the call's `event_webhook_url` to its own `/ai_events`
1101
+ * endpoint, unless you set `event_webhook_url` yourself, and calls each
1102
+ * handler with every event posted there. An event is `ai.speech_detect` for
1103
+ * each final of the caller's speech, with its `text` and the recognizer's
1104
+ * `words` and confidences, or one of the platform's other AI events.
1105
+ * Register handlers on the agent, not in a per-call configuration callback:
1106
+ * the endpoint runs on the agent. The handler may be async; its return value
1107
+ * is ignored, and an error is logged.
1108
+ * @param handler - Called with `(eventType, params, event)`: the event, such
1109
+ * as `'ai.speech_detect'`; its fields, with the `call_id`; and the whole
1110
+ * event as posted, with its `timestamp`.
1111
+ * @returns The handler.
1112
+ *
1113
+ * @example
1114
+ * ```ts
1115
+ * agent.onAiEvent((eventType, params) => {
1116
+ * if (eventType === 'ai.speech_detect') console.log(params['call_id'], params['text']);
1117
+ * });
1118
+ * ```
1119
+ */
1120
+ onAiEvent(handler: AiEventHandler): AiEventHandler;
1121
+ /**
1122
+ * Keep each call's recognizer finals, with their word confidences, for tool
1123
+ * handlers to read with {@link speechFinals}.
1124
+ *
1125
+ * A final is what the recognizer heard for one turn of the caller's, from
1126
+ * the platform's `ai.speech_detect` event: `{ text, words, timestamp }`, with
1127
+ * `words` as `[{ word, confidence }]` as heard, before hearing hints and
1128
+ * number formatting change the text. A handler can ask the caller again
1129
+ * about a word the recognizer wasn't sure of, such as a letter of a spelled
1130
+ * name. Like {@link onAiEvent}, it sets the call's `event_webhook_url` to the
1131
+ * agent's `/ai_events`, unless you set it yourself. A call with
1132
+ * `redact_prompt` sends no finals unless debug is on. The finals live in the
1133
+ * process: replicas each keep their own.
1134
+ * @param maxCalls - The most calls to keep finals for; the oldest call's go first.
1135
+ * @param maxFinals - The most finals to keep for one call.
1136
+ * @returns This agent instance for chaining.
1137
+ */
1138
+ recordSpeechFinals(maxCalls?: number, maxFinals?: number): this;
1139
+ /**
1140
+ * The recognizer's finals for a call, oldest first, once
1141
+ * {@link recordSpeechFinals} is on: `{ text, words, timestamp }`.
1142
+ * @param callId - The call, as a tool request's `rawData.call_id`.
1143
+ * @param since - Only the finals from this time on, in seconds since the
1144
+ * epoch (the event's `timestamp`).
1145
+ * @returns The finals, empty for a call with none or with recording off.
1146
+ */
1147
+ speechFinals(callId: string, since?: number): SpeechFinal[];
1148
+ private warnIfEventWebhookTaken;
1052
1149
  /**
1053
1150
  * Register a handler that runs when the call starts, before the AI speaks.
1054
1151
  *
@@ -1346,6 +1443,13 @@ export declare class AgentBase extends SWMLService {
1346
1443
  * or void/undefined to proceed normally.
1347
1444
  */
1348
1445
  onFunctionCall(_name: string, _args: Record<string, unknown>, _rawData: Record<string, unknown>): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
1446
+ /**
1447
+ * Run a tool on this agent as the `/swaig` route does once the request is
1448
+ * checked: its middleware, handler and outcome rules, with the agent's
1449
+ * error hook. The MCP bridge and the call simulator run tools through it too.
1450
+ * @internal
1451
+ */
1452
+ _executeFunction(fn: SwaigFunction, args: Record<string, unknown>, rawData: Record<string, unknown>): Promise<SwaigResultDict>;
1349
1453
  /**
1350
1454
  * Extract the tool-call arguments from a SWAIG request body.
1351
1455
  *
@@ -1387,7 +1491,8 @@ export declare class AgentBase extends SWMLService {
1387
1491
  * is refused, so the conversation can't stand in for a malformed one.
1388
1492
  */
1389
1493
  private tokenNamesCall;
1390
- private extractSwaigArgs;
1494
+ /** @internal The call simulator replays recorded requests through it. */
1495
+ _extractSwaigArgs(body: Record<string, unknown>, reqLog?: Logger): Record<string, unknown>;
1391
1496
  /**
1392
1497
  * Render the complete SWML document by assembling all 5 phases: pre-answer, answer,
1393
1498
  * post-answer, AI, and post-AI verbs.