@signalwire/sdk 3.7.1 → 3.9.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 +214 -0
- package/README.md +1 -0
- package/dist/AgentBase.d.ts +120 -3
- package/dist/AgentBase.js +291 -18
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +30 -6
- package/dist/AgentServer.js +28 -2
- package/dist/AgentServer.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 +197 -14
- package/dist/ContextBuilder.js +422 -13
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/FunctionResult.d.ts +129 -0
- package/dist/FunctionResult.js +170 -0
- package/dist/FunctionResult.js.map +1 -1
- package/dist/Logger.d.ts +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 +151 -10
- package/dist/SWMLService.js +377 -61
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.js +14 -1
- package/dist/SchemaUtils.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/SessionManager.d.ts +17 -6
- package/dist/SessionManager.js +16 -3
- package/dist/SessionManager.js.map +1 -1
- package/dist/SwaigFunction.d.ts +86 -9
- package/dist/SwaigFunction.js +215 -59
- 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 +2 -2
- package/dist/TypeInference.js +1 -1
- package/dist/TypeInference.js.map +1 -1
- package/dist/ai-chat/ChatGateway.d.ts +5 -5
- package/dist/ai-chat/HandoffRouter.d.ts +3 -3
- 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 +23 -8
- package/dist/index.js +16 -5
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +3 -0
- package/dist/livewire/index.js +3 -0
- package/dist/livewire/index.js.map +1 -1
- package/dist/llms.txt +1 -0
- package/dist/patterns/Proposal.d.ts +146 -0
- package/dist/patterns/Proposal.js +212 -0
- package/dist/patterns/Proposal.js.map +1 -0
- package/dist/patterns/RequestList.d.ts +136 -0
- package/dist/patterns/RequestList.js +169 -0
- package/dist/patterns/RequestList.js.map +1 -0
- package/dist/relay/Call.d.ts +1 -1
- package/dist/relay/Call.js +1 -1
- package/dist/relay/Message.d.ts +1 -1
- package/dist/relay/Message.js +1 -1
- package/dist/relay/RelayClient.d.ts +0 -2
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +3 -3
- package/dist/relay/RelayEvent.js +3 -3
- package/dist/relay/closedSets.d.ts +10 -10
- package/dist/relay/closedSets.js +2 -2
- package/dist/relay/types.d.ts +1 -1
- package/dist/rest/base/CrudResource.d.ts +1 -1
- package/dist/rest/base/CrudResource.js +1 -1
- package/dist/skills/SkillBase.d.ts +26 -3
- package/dist/skills/SkillBase.js +14 -3
- 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 +281 -0
- package/dist/testing/CallSimulator.js +666 -0
- package/dist/testing/CallSimulator.js.map +1 -0
- package/docs/agent-guide.md +4 -4
- package/docs/api-reference.md +285 -28
- package/docs/architecture.md +8 -4
- package/docs/cli-guide.md +2 -0
- package/docs/contexts-guide.md +47 -4
- package/docs/conversation_patterns.md +257 -0
- package/docs/mcp_integration.md +1 -1
- package/docs/pgi_agent_guide.md +2 -1
- package/docs/programmatically_governed_inference.md +2 -2
- package/docs/swaig-reference.md +95 -3
- package/docs/swml_service_guide.md +31 -6
- package/package.json +3 -1
package/dist/AgentBase.js
CHANGED
|
@@ -15,9 +15,10 @@ import { PromptManager } from './PromptManager.js';
|
|
|
15
15
|
import { SessionManager } from './SessionManager.js';
|
|
16
16
|
import { SwmlBuilder } from './SwmlBuilder.js';
|
|
17
17
|
import { SWMLService } from './SWMLService.js';
|
|
18
|
+
import { SpeechLog, SPEECH_DETECT } from './AiEvents.js';
|
|
18
19
|
import { ConfigLoader } from './ConfigLoader.js';
|
|
19
|
-
import { SwaigFunction
|
|
20
|
-
import { _checkGatedFunction } from './SemanticGate.js';
|
|
20
|
+
import { SwaigFunction } from './SwaigFunction.js';
|
|
21
|
+
import { _checkGatedFunction, GATE_DIALOGUES, } from './SemanticGate.js';
|
|
21
22
|
import { inferSchema, createTypedHandlerWrapper } from './TypeInference.js';
|
|
22
23
|
import { FunctionResult } from './FunctionResult.js';
|
|
23
24
|
import { Context as ConversationContext, ContextBuilder, GatherInfo, GatherQuestion, Step, } from './ContextBuilder.js';
|
|
@@ -49,6 +50,13 @@ function headersOf(c) {
|
|
|
49
50
|
});
|
|
50
51
|
return headers;
|
|
51
52
|
}
|
|
53
|
+
/** A request body's `conversation_id`, if it names one. */
|
|
54
|
+
function conversationIdOf(body) {
|
|
55
|
+
if (body === null || typeof body !== 'object')
|
|
56
|
+
return undefined;
|
|
57
|
+
const value = body['conversation_id'];
|
|
58
|
+
return typeof value === 'string' && value ? value : undefined;
|
|
59
|
+
}
|
|
52
60
|
/** The Hono context of the served request being handled, for onSwmlRequest. */
|
|
53
61
|
const servedRequestContext = new AsyncLocalStorage();
|
|
54
62
|
/** Compare two strings in constant time, whatever their lengths. */
|
|
@@ -209,7 +217,7 @@ function relativePath(path, routePath) {
|
|
|
209
217
|
* - `POST /post_prompt` receives the end-of-call summary and invokes {@link onSummary}
|
|
210
218
|
*
|
|
211
219
|
* Most user agents either (a) subclass `AgentBase` and override `defineTools()` / `onSummary()`
|
|
212
|
-
* or (b) use one of the
|
|
220
|
+
* or (b) use one of the prefab agents (e.g. {@link ReceptionistAgent}).
|
|
213
221
|
*
|
|
214
222
|
* @example Subclass with a custom tool
|
|
215
223
|
* ```ts
|
|
@@ -300,6 +308,10 @@ export class AgentBase extends SWMLService {
|
|
|
300
308
|
perCallConfigs = [];
|
|
301
309
|
/** Set once serve() runs an HTTP server; getFullUrl then ignores serverless environments. */
|
|
302
310
|
_serving = false;
|
|
311
|
+
/** Handlers registered with {@link onAiEvent}. */
|
|
312
|
+
_aiEventHandlers = [];
|
|
313
|
+
/** The recognizer's finals per call, once {@link recordSpeechFinals} is on. */
|
|
314
|
+
_speechLog = null;
|
|
303
315
|
/** Handlers registered with {@link onCallStart}. */
|
|
304
316
|
callStartHandlers = [];
|
|
305
317
|
/** Handlers registered with {@link onCallEnd}. */
|
|
@@ -312,6 +324,8 @@ export class AgentBase extends SWMLService {
|
|
|
312
324
|
postPromptUrlOverride = null;
|
|
313
325
|
// Contexts
|
|
314
326
|
contextsBuilder = null;
|
|
327
|
+
/** Tools the contexts reported as offered by no step; shared with per-request copies. */
|
|
328
|
+
_unofferedToolsWarned = new Set();
|
|
315
329
|
/** Contexts given as a plain object, rendered as they are. */
|
|
316
330
|
_rawContexts = null;
|
|
317
331
|
// MCP
|
|
@@ -784,7 +798,7 @@ export class AgentBase extends SWMLService {
|
|
|
784
798
|
}
|
|
785
799
|
// Attach agent reference so ContextBuilder.validate() can check
|
|
786
800
|
// user tool names against reserved native tool names.
|
|
787
|
-
this.contextsBuilder.attachAgent(this);
|
|
801
|
+
this.contextsBuilder.attachAgent(this)._shareUnofferedWarnings(this._unofferedToolsWarned);
|
|
788
802
|
return this.contextsBuilder;
|
|
789
803
|
}
|
|
790
804
|
/**
|
|
@@ -1039,15 +1053,27 @@ export class AgentBase extends SWMLService {
|
|
|
1039
1053
|
* `semantic_gate_timeout_ms`.
|
|
1040
1054
|
* @param opts.history - How many recent dialogue entries the decision model
|
|
1041
1055
|
* sees, 0 to 100. Default 20. Sent as `semantic_gate_history`.
|
|
1056
|
+
* @param opts.dialogue - Which dialogue the decision model judges:
|
|
1057
|
+
* `'window'`, the newest `history` entries, or `'proposal'`, those since
|
|
1058
|
+
* `global_data.semantic_state` last changed (see
|
|
1059
|
+
* {@link FunctionResult.setSemanticState}), from the agent's first turn
|
|
1060
|
+
* after it: the read-back and the caller's reply. With no
|
|
1061
|
+
* `semantic_state` set, the window. A gate's own `dialogue` and `history`
|
|
1062
|
+
* take the place of these for its function. Default `'window'`. Sent as
|
|
1063
|
+
* `semantic_gate_dialogue`; it needs a platform release that has it.
|
|
1042
1064
|
* @returns This agent instance for chaining.
|
|
1043
1065
|
* @throws {Error} When a value has the wrong type or is out of range.
|
|
1044
1066
|
*/
|
|
1045
1067
|
setSemanticGates(opts = {}) {
|
|
1046
1068
|
// Check every value before setting any, so a refused call changes nothing
|
|
1047
|
-
const { enabled, timeoutMs, history } = opts;
|
|
1069
|
+
const { enabled, timeoutMs, history, dialogue } = opts;
|
|
1048
1070
|
if (enabled !== undefined && typeof enabled !== 'boolean') {
|
|
1049
1071
|
throw new Error(`enabled must be a boolean, got ${JSON.stringify(enabled)}`);
|
|
1050
1072
|
}
|
|
1073
|
+
if (dialogue !== undefined &&
|
|
1074
|
+
(typeof dialogue !== 'string' || !GATE_DIALOGUES.includes(dialogue))) {
|
|
1075
|
+
throw new Error(`dialogue must be one of ${JSON.stringify(GATE_DIALOGUES)}, got ${JSON.stringify(dialogue)}`);
|
|
1076
|
+
}
|
|
1051
1077
|
const ranges = [
|
|
1052
1078
|
['semantic_gate_timeout_ms', 'timeout_ms', timeoutMs, 500, 10000],
|
|
1053
1079
|
['semantic_gate_history', 'history', history, 0, 100],
|
|
@@ -1061,12 +1087,34 @@ export class AgentBase extends SWMLService {
|
|
|
1061
1087
|
}
|
|
1062
1088
|
if (enabled !== undefined)
|
|
1063
1089
|
this.params['semantic_gates_enabled'] = enabled;
|
|
1090
|
+
if (dialogue !== undefined)
|
|
1091
|
+
this.params['semantic_gate_dialogue'] = dialogue;
|
|
1064
1092
|
for (const [param, , value] of ranges) {
|
|
1065
1093
|
if (value !== undefined)
|
|
1066
1094
|
this.params[param] = value;
|
|
1067
1095
|
}
|
|
1068
1096
|
return this;
|
|
1069
1097
|
}
|
|
1098
|
+
/**
|
|
1099
|
+
* Set what the model is told when it calls a tool it can't use now.
|
|
1100
|
+
*
|
|
1101
|
+
* Without it, the platform says nothing ran, which steps offer the tool, and
|
|
1102
|
+
* which tools are available now. `text` takes its place, with `${function}`
|
|
1103
|
+
* for the tool's name, `${tools}` for the tools the request offered,
|
|
1104
|
+
* comma-separated, and `${steps}` for the current context's steps whose
|
|
1105
|
+
* functions include it (empty for a name the agent doesn't have). Sent as
|
|
1106
|
+
* the `unavailable_function_response` param; it needs a platform release
|
|
1107
|
+
* that has it.
|
|
1108
|
+
* @param text - The text.
|
|
1109
|
+
* @returns This agent instance for chaining.
|
|
1110
|
+
* @throws {Error} When `text` isn't a non-empty string.
|
|
1111
|
+
*/
|
|
1112
|
+
setUnavailableFunctionResponse(text) {
|
|
1113
|
+
if (typeof text !== 'string' || !text)
|
|
1114
|
+
throw new Error('text must be a non-empty string');
|
|
1115
|
+
this.params['unavailable_function_response'] = text;
|
|
1116
|
+
return this;
|
|
1117
|
+
}
|
|
1070
1118
|
/**
|
|
1071
1119
|
* **MERGES** `data` into the global_data object passed into the AI
|
|
1072
1120
|
* configuration. **Despite the name, this does NOT replace** the existing
|
|
@@ -1486,7 +1534,7 @@ export class AgentBase extends SWMLService {
|
|
|
1486
1534
|
name,
|
|
1487
1535
|
description: fn.description || name,
|
|
1488
1536
|
};
|
|
1489
|
-
tool['inputSchema'] =
|
|
1537
|
+
tool['inputSchema'] = fn._parameterSchema(this._nullableOptionalDefault());
|
|
1490
1538
|
tools.push(tool);
|
|
1491
1539
|
}
|
|
1492
1540
|
}
|
|
@@ -1544,7 +1592,7 @@ export class AgentBase extends SWMLService {
|
|
|
1544
1592
|
function: toolName,
|
|
1545
1593
|
argument: { parsed: [args] },
|
|
1546
1594
|
};
|
|
1547
|
-
const resultDict = await
|
|
1595
|
+
const resultDict = await this._executeFunction(fn, args, rawData);
|
|
1548
1596
|
// MCP content is text: a structured { tool_result, tool_prompt }
|
|
1549
1597
|
// response goes as its JSON.
|
|
1550
1598
|
const response = resultDict['response'] ?? '';
|
|
@@ -1625,6 +1673,10 @@ export class AgentBase extends SWMLService {
|
|
|
1625
1673
|
isTypedHandler: true,
|
|
1626
1674
|
gates: opts.gates,
|
|
1627
1675
|
gateFillers: opts.gateFillers,
|
|
1676
|
+
vouched: opts.vouched,
|
|
1677
|
+
nullableOptional: opts.nullableOptional,
|
|
1678
|
+
needsConversation: opts.needsConversation,
|
|
1679
|
+
middleware: opts.middleware,
|
|
1628
1680
|
});
|
|
1629
1681
|
this.toolRegistry.set(opts.name, fn);
|
|
1630
1682
|
return this;
|
|
@@ -1773,7 +1825,10 @@ export class AgentBase extends SWMLService {
|
|
|
1773
1825
|
// (skill_base.py:59-79), swaig_fields are define_tool arguments with the
|
|
1774
1826
|
// tool's own fields winning: `secure` sets whether the tool needs a token,
|
|
1775
1827
|
// and the other keys go into the SWAIG definition.
|
|
1776
|
-
|
|
1828
|
+
// The SDK's own execution options aren't wire fields: they become tool
|
|
1829
|
+
// options, so the SDK enforces them (a vouched tool's refusal, say).
|
|
1830
|
+
const { secure: skillSecure, vouched: skillVouched, nullable_optional: skillNullable, needs_conversation: skillNeedsConversation, middleware: skillMiddleware, ...skillExtraFields } = skill.swaigFields;
|
|
1831
|
+
const skillBool = (value) => (typeof value === 'boolean' ? value : undefined);
|
|
1777
1832
|
for (const toolDef of skill.getTools()) {
|
|
1778
1833
|
// Skill-level swaigFields are the base and the tool's own fields win —
|
|
1779
1834
|
// Python skill_base.py:70-73 (swaig_fields base, explicit kwargs win) and
|
|
@@ -1802,11 +1857,20 @@ export class AgentBase extends SWMLService {
|
|
|
1802
1857
|
extraFields['gates'] = toolDef.gates;
|
|
1803
1858
|
if (toolDef.gate_fillers !== undefined)
|
|
1804
1859
|
extraFields['gate_fillers'] = toolDef.gate_fillers;
|
|
1860
|
+
// The options as SwaigFunctionOptions spells them, for a tool given that way
|
|
1861
|
+
const camel = toolDef;
|
|
1805
1862
|
this.defineTool({
|
|
1806
1863
|
...toolDef,
|
|
1807
1864
|
...(toolDef.secure === undefined && typeof skillSecure === 'boolean'
|
|
1808
1865
|
? { secure: skillSecure }
|
|
1809
1866
|
: {}),
|
|
1867
|
+
vouched: toolDef.vouched ?? skillBool(skillVouched),
|
|
1868
|
+
nullableOptional: toolDef.nullable_optional ?? camel.nullableOptional ?? skillBool(skillNullable),
|
|
1869
|
+
needsConversation: toolDef.needs_conversation ??
|
|
1870
|
+
camel.needsConversation ??
|
|
1871
|
+
skillBool(skillNeedsConversation),
|
|
1872
|
+
middleware: toolDef.middleware ??
|
|
1873
|
+
(Array.isArray(skillMiddleware) ? skillMiddleware : undefined),
|
|
1810
1874
|
extraFields,
|
|
1811
1875
|
});
|
|
1812
1876
|
}
|
|
@@ -1996,6 +2060,75 @@ export class AgentBase extends SWMLService {
|
|
|
1996
2060
|
this.perCallConfigs = [...this.perCallConfigs, cb];
|
|
1997
2061
|
return this;
|
|
1998
2062
|
}
|
|
2063
|
+
/**
|
|
2064
|
+
* Register a handler for the AI events the platform posts during calls.
|
|
2065
|
+
*
|
|
2066
|
+
* The agent sets the call's `event_webhook_url` to its own `/ai_events`
|
|
2067
|
+
* endpoint, unless you set `event_webhook_url` yourself, and calls each
|
|
2068
|
+
* handler with every event posted there. An event is `ai.speech_detect` for
|
|
2069
|
+
* each final of the caller's speech, with its `text` and the recognizer's
|
|
2070
|
+
* `words` and confidences, or one of the platform's other AI events.
|
|
2071
|
+
* Register handlers on the agent, not in a per-call configuration callback:
|
|
2072
|
+
* the endpoint runs on the agent. The handler may be async; its return value
|
|
2073
|
+
* is ignored, and an error is logged.
|
|
2074
|
+
* @param handler - Called with `(eventType, params, event)`: the event, such
|
|
2075
|
+
* as `'ai.speech_detect'`; its fields, with the `call_id`; and the whole
|
|
2076
|
+
* event as posted, with its `timestamp`.
|
|
2077
|
+
* @returns The handler.
|
|
2078
|
+
*
|
|
2079
|
+
* @example
|
|
2080
|
+
* ```ts
|
|
2081
|
+
* agent.onAiEvent((eventType, params) => {
|
|
2082
|
+
* if (eventType === 'ai.speech_detect') console.log(params['call_id'], params['text']);
|
|
2083
|
+
* });
|
|
2084
|
+
* ```
|
|
2085
|
+
*/
|
|
2086
|
+
onAiEvent(handler) {
|
|
2087
|
+
// Rebind rather than push: a per-request copy shares this array
|
|
2088
|
+
this._aiEventHandlers = [...this._aiEventHandlers, handler];
|
|
2089
|
+
this.warnIfEventWebhookTaken();
|
|
2090
|
+
return handler;
|
|
2091
|
+
}
|
|
2092
|
+
/**
|
|
2093
|
+
* Keep each call's recognizer finals, with their word confidences, for tool
|
|
2094
|
+
* handlers to read with {@link speechFinals}.
|
|
2095
|
+
*
|
|
2096
|
+
* A final is what the recognizer heard for one turn of the caller's, from
|
|
2097
|
+
* the platform's `ai.speech_detect` event: `{ text, words, timestamp }`, with
|
|
2098
|
+
* `words` as `[{ word, confidence }]` as heard, before hearing hints and
|
|
2099
|
+
* number formatting change the text. A handler can ask the caller again
|
|
2100
|
+
* about a word the recognizer wasn't sure of, such as a letter of a spelled
|
|
2101
|
+
* name. Like {@link onAiEvent}, it sets the call's `event_webhook_url` to the
|
|
2102
|
+
* agent's `/ai_events`, unless you set it yourself. A call with
|
|
2103
|
+
* `redact_prompt` sends no finals unless debug is on. The finals live in the
|
|
2104
|
+
* process: replicas each keep their own.
|
|
2105
|
+
* @param maxCalls - The most calls to keep finals for; the oldest call's go first.
|
|
2106
|
+
* @param maxFinals - The most finals to keep for one call.
|
|
2107
|
+
* @returns This agent instance for chaining.
|
|
2108
|
+
*/
|
|
2109
|
+
recordSpeechFinals(maxCalls = 500, maxFinals = 200) {
|
|
2110
|
+
this._speechLog ??= new SpeechLog(maxCalls, maxFinals);
|
|
2111
|
+
this.warnIfEventWebhookTaken();
|
|
2112
|
+
return this;
|
|
2113
|
+
}
|
|
2114
|
+
/**
|
|
2115
|
+
* The recognizer's finals for a call, oldest first, once
|
|
2116
|
+
* {@link recordSpeechFinals} is on: `{ text, words, timestamp }`.
|
|
2117
|
+
* @param callId - The call, as a tool request's `rawData.call_id`.
|
|
2118
|
+
* @param since - Only the finals from this time on, in seconds since the
|
|
2119
|
+
* epoch (the event's `timestamp`).
|
|
2120
|
+
* @returns The finals, empty for a call with none or with recording off.
|
|
2121
|
+
*/
|
|
2122
|
+
speechFinals(callId, since) {
|
|
2123
|
+
return this._speechLog ? this._speechLog.finals(callId, since) : [];
|
|
2124
|
+
}
|
|
2125
|
+
warnIfEventWebhookTaken() {
|
|
2126
|
+
if (this.params['event_webhook_url'] !== undefined) {
|
|
2127
|
+
this.log.warn('event_webhook_url_already_set', {
|
|
2128
|
+
message: "event_webhook_url is set to another URL, so AI events go there and this agent's onAiEvent handlers and speech finals get none",
|
|
2129
|
+
});
|
|
2130
|
+
}
|
|
2131
|
+
}
|
|
1999
2132
|
/**
|
|
2000
2133
|
* Register a handler that runs when the call starts, before the AI speaks.
|
|
2001
2134
|
*
|
|
@@ -2631,6 +2764,15 @@ export class AgentBase extends SWMLService {
|
|
|
2631
2764
|
onFunctionCall(_name, _args, _rawData) {
|
|
2632
2765
|
// Default no-op
|
|
2633
2766
|
}
|
|
2767
|
+
/**
|
|
2768
|
+
* Run a tool on this agent as the `/swaig` route does once the request is
|
|
2769
|
+
* checked: its middleware, handler and outcome rules, with the agent's
|
|
2770
|
+
* error hook. The MCP bridge and the call simulator run tools through it too.
|
|
2771
|
+
* @internal
|
|
2772
|
+
*/
|
|
2773
|
+
_executeFunction(fn, args, rawData) {
|
|
2774
|
+
return fn._executeAs(this, args, rawData, this._onError);
|
|
2775
|
+
}
|
|
2634
2776
|
/**
|
|
2635
2777
|
* Extract the tool-call arguments from a SWAIG request body.
|
|
2636
2778
|
*
|
|
@@ -2656,10 +2798,15 @@ export class AgentBase extends SWMLService {
|
|
|
2656
2798
|
* missing `call_id`, is refused like a wrong token. A non-secure function
|
|
2657
2799
|
* runs without a token.
|
|
2658
2800
|
*
|
|
2801
|
+
* The token may name the request's `call_id` or its `conversation_id`. A
|
|
2802
|
+
* chat session fetches its SWML, and so gets its tokens, under the
|
|
2803
|
+
* conversation's id, then sends every request under the chat service's own
|
|
2804
|
+
* call id, with the conversation's id beside it.
|
|
2805
|
+
*
|
|
2659
2806
|
* @returns The SWAIG response to send instead of running the function, or
|
|
2660
2807
|
* `null` when the function may run.
|
|
2661
2808
|
*/
|
|
2662
|
-
swaigTokenRefusal(fn, token, callId, reqLog) {
|
|
2809
|
+
swaigTokenRefusal(fn, token, callId, reqLog, conversationId) {
|
|
2663
2810
|
if (!fn.secure)
|
|
2664
2811
|
return null;
|
|
2665
2812
|
if (!token) {
|
|
@@ -2668,7 +2815,7 @@ export class AgentBase extends SWMLService {
|
|
|
2668
2815
|
else if (!callId) {
|
|
2669
2816
|
reqLog.warn('token_rejected_no_call_id');
|
|
2670
2817
|
}
|
|
2671
|
-
else if (this.
|
|
2818
|
+
else if (this.tokenNamesCall(fn.name, token, callId, conversationId)) {
|
|
2672
2819
|
reqLog.debug('token_valid');
|
|
2673
2820
|
return null;
|
|
2674
2821
|
}
|
|
@@ -2678,7 +2825,20 @@ export class AgentBase extends SWMLService {
|
|
|
2678
2825
|
// The reference's exact wording: the refusal is part of the SWAIG wire contract.
|
|
2679
2826
|
return new FunctionResult("I'm sorry, the security token for this function is invalid or expired. I cannot execute this action.").toDict();
|
|
2680
2827
|
}
|
|
2681
|
-
|
|
2828
|
+
/**
|
|
2829
|
+
* Whether `token` was minted for `functionName` and the request's call:
|
|
2830
|
+
* its `call_id`, or its `conversation_id` when it names a different one.
|
|
2831
|
+
* The request must name a call: a `call_id` that isn't a non-empty string
|
|
2832
|
+
* is refused, so the conversation can't stand in for a malformed one.
|
|
2833
|
+
*/
|
|
2834
|
+
tokenNamesCall(functionName, token, callId, conversationId) {
|
|
2835
|
+
if (typeof callId !== 'string' || !callId)
|
|
2836
|
+
return false;
|
|
2837
|
+
const ids = conversationId && conversationId !== callId ? [callId, conversationId] : [callId];
|
|
2838
|
+
return this.sessionManager._validateTokenFor(ids, functionName, token);
|
|
2839
|
+
}
|
|
2840
|
+
/** @internal The call simulator replays recorded requests through it. */
|
|
2841
|
+
_extractSwaigArgs(body, reqLog = this.log) {
|
|
2682
2842
|
const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
|
|
2683
2843
|
const argument = body['argument'];
|
|
2684
2844
|
if (isPlainObject(argument)) {
|
|
@@ -2751,7 +2911,7 @@ export class AgentBase extends SWMLService {
|
|
|
2751
2911
|
const entry = {
|
|
2752
2912
|
function: name,
|
|
2753
2913
|
description: fn.description,
|
|
2754
|
-
parameters:
|
|
2914
|
+
parameters: fn._parameterSchema(this._nullableOptionalDefault()),
|
|
2755
2915
|
};
|
|
2756
2916
|
if (fn.fillers && Object.keys(fn.fillers).length)
|
|
2757
2917
|
entry['fillers'] = fn.fillers;
|
|
@@ -2870,8 +3030,20 @@ export class AgentBase extends SWMLService {
|
|
|
2870
3030
|
aiConfig['multilingual'] = this.multilingual;
|
|
2871
3031
|
if (this.pronounce.length)
|
|
2872
3032
|
aiConfig['pronounce'] = this.pronounce;
|
|
2873
|
-
|
|
2874
|
-
|
|
3033
|
+
const params = { ...this.params };
|
|
3034
|
+
// A tool that reads the conversation needs it in its requests
|
|
3035
|
+
if (!('swaig_post_conversation' in params) &&
|
|
3036
|
+
[...this.toolRegistry.values()].some((f) => f instanceof SwaigFunction && f.needsConversation)) {
|
|
3037
|
+
params['swaig_post_conversation'] = true;
|
|
3038
|
+
}
|
|
3039
|
+
// AI events go to this agent's /ai_events when it handles them, unless
|
|
3040
|
+
// event_webhook_url was set to something else
|
|
3041
|
+
if ((this._aiEventHandlers.length > 0 || this._speechLog) &&
|
|
3042
|
+
params['event_webhook_url'] === undefined) {
|
|
3043
|
+
params['event_webhook_url'] = this.buildWebhookUrl('ai_events', { ...this.swaigQueryParams });
|
|
3044
|
+
}
|
|
3045
|
+
if (Object.keys(params).length)
|
|
3046
|
+
aiConfig['params'] = params;
|
|
2875
3047
|
if (Object.keys(this.globalData).length)
|
|
2876
3048
|
aiConfig['global_data'] = this.globalData;
|
|
2877
3049
|
// Debug events
|
|
@@ -2944,6 +3116,8 @@ export class AgentBase extends SWMLService {
|
|
|
2944
3116
|
copy._sipUsernames = this._sipUsernames ? new Map(this._sipUsernames) : null;
|
|
2945
3117
|
copy._routingCallbacks = new Map(this._routingCallbacks);
|
|
2946
3118
|
copy.contextsBuilder = clone(this.contextsBuilder);
|
|
3119
|
+
// The warnings already logged stay shared, so each request doesn't repeat them
|
|
3120
|
+
copy.contextsBuilder?._shareUnofferedWarnings(this._unofferedToolsWarned);
|
|
2947
3121
|
copy._rawContexts = clone(this._rawContexts);
|
|
2948
3122
|
// Back-reference points at the COPY, not `this` (see _promptManager above).
|
|
2949
3123
|
copy.swmlBuilder = new SwmlBuilder({ service: copy, ...this._builderSchemaOptions });
|
|
@@ -3239,10 +3413,10 @@ export class AgentBase extends SWMLService {
|
|
|
3239
3413
|
}
|
|
3240
3414
|
const url = new URL(c.req.url);
|
|
3241
3415
|
const token = url.searchParams.get('__token') ?? url.searchParams.get('token');
|
|
3242
|
-
const refusal = target.swaigTokenRefusal(fn, token, callIdStr, reqLog);
|
|
3416
|
+
const refusal = target.swaigTokenRefusal(fn, token, callIdStr, reqLog, conversationIdOf(body));
|
|
3243
3417
|
if (refusal)
|
|
3244
3418
|
return c.json(refusal);
|
|
3245
|
-
const args = this.
|
|
3419
|
+
const args = this._extractSwaigArgs(body, reqLog);
|
|
3246
3420
|
reqLog.debug('executing_function', { args: JSON.stringify(args) });
|
|
3247
3421
|
const hookResult = await target.onFunctionCall(fnName, args, body);
|
|
3248
3422
|
// If onFunctionCall returned a result, use it (dispatch interception)
|
|
@@ -3251,7 +3425,7 @@ export class AgentBase extends SWMLService {
|
|
|
3251
3425
|
return c.json(hookResult);
|
|
3252
3426
|
}
|
|
3253
3427
|
try {
|
|
3254
|
-
const result = await
|
|
3428
|
+
const result = await target._executeFunction(fn, args, body);
|
|
3255
3429
|
reqLog.info('function_executed_successfully');
|
|
3256
3430
|
reqLog.debug('function_result', { result_size: JSON.stringify(result).length });
|
|
3257
3431
|
return c.json(result);
|
|
@@ -3308,7 +3482,10 @@ export class AgentBase extends SWMLService {
|
|
|
3308
3482
|
reqLog.warn('token_missing');
|
|
3309
3483
|
return c.json({ error: 'Invalid or missing token' }, 403);
|
|
3310
3484
|
}
|
|
3311
|
-
|
|
3485
|
+
// A chat session's summary arrives under the chat service's own call id,
|
|
3486
|
+
// with the conversation its SWML, and so its token, was made for beside it.
|
|
3487
|
+
const conversationId = conversationIdOf(body);
|
|
3488
|
+
if (!callId || !this.tokenNamesCall('post_prompt', token, callId, conversationId)) {
|
|
3312
3489
|
reqLog.warn('invalid_token');
|
|
3313
3490
|
return c.json({ error: 'Invalid or missing token' }, 403);
|
|
3314
3491
|
}
|
|
@@ -3343,6 +3520,66 @@ export class AgentBase extends SWMLService {
|
|
|
3343
3520
|
else {
|
|
3344
3521
|
app.on('POST', postPromptPaths, authMw, handlePostPrompt);
|
|
3345
3522
|
}
|
|
3523
|
+
// AI events (event_webhook_url): to the speech log and onAiEvent handlers.
|
|
3524
|
+
// The body is read to the size limit before the signature check, which
|
|
3525
|
+
// would otherwise read all of it first.
|
|
3526
|
+
const readBounded = async (c, next) => {
|
|
3527
|
+
if (!(c.req.header('content-type') ?? '').toLowerCase().startsWith('application/json')) {
|
|
3528
|
+
return c.json({ error: 'Content-Type must be application/json' }, 415);
|
|
3529
|
+
}
|
|
3530
|
+
const text = await readBodyWithin(c.req, maxRequestSize);
|
|
3531
|
+
if (text === null)
|
|
3532
|
+
return c.json({ error: 'Request body too large' }, 413);
|
|
3533
|
+
// The signature check and the handler read this, not the spent stream
|
|
3534
|
+
c.req.bodyCache['text'] =
|
|
3535
|
+
Promise.resolve(text);
|
|
3536
|
+
await next();
|
|
3537
|
+
};
|
|
3538
|
+
const handleAiEvents = async (c) => {
|
|
3539
|
+
const reqLog = this.log.bind({ endpoint: `${basePath}/ai_events` });
|
|
3540
|
+
let event;
|
|
3541
|
+
try {
|
|
3542
|
+
event = await c.req.json();
|
|
3543
|
+
}
|
|
3544
|
+
catch (err) {
|
|
3545
|
+
reqLog.error('error_parsing_request_body', {
|
|
3546
|
+
error: err instanceof Error ? err.message : String(err),
|
|
3547
|
+
});
|
|
3548
|
+
return c.json({ status: 'error', message: 'invalid JSON' });
|
|
3549
|
+
}
|
|
3550
|
+
if (typeof event !== 'object' || event === null || Array.isArray(event)) {
|
|
3551
|
+
return c.json({ status: 'error', message: 'an event must be an object' });
|
|
3552
|
+
}
|
|
3553
|
+
const e = event;
|
|
3554
|
+
const eventType = String(e['event_type'] ?? 'unknown');
|
|
3555
|
+
const given = e['params'];
|
|
3556
|
+
const params = typeof given === 'object' && given !== null && !Array.isArray(given)
|
|
3557
|
+
? given
|
|
3558
|
+
: {};
|
|
3559
|
+
reqLog.debug('ai_event', { event_type: eventType, call_id: params['call_id'] });
|
|
3560
|
+
if (this._speechLog && eventType === SPEECH_DETECT)
|
|
3561
|
+
this._speechLog.add(e);
|
|
3562
|
+
for (const handler of this._aiEventHandlers) {
|
|
3563
|
+
// Each handler is isolated, so one failure doesn't keep the others from the event
|
|
3564
|
+
try {
|
|
3565
|
+
await handler(eventType, params, e);
|
|
3566
|
+
}
|
|
3567
|
+
catch (err) {
|
|
3568
|
+
reqLog.error('ai_event_handler_error', {
|
|
3569
|
+
error: err instanceof Error ? err.message : String(err),
|
|
3570
|
+
});
|
|
3571
|
+
}
|
|
3572
|
+
}
|
|
3573
|
+
return c.json({ status: 'ok' });
|
|
3574
|
+
};
|
|
3575
|
+
const aiEventsPaths = withSlash(`${basePath}/ai_events`);
|
|
3576
|
+
app.on('GET', aiEventsPaths, authMw, (c) => c.json({ error: 'POST required' }, 405));
|
|
3577
|
+
if (sigMw) {
|
|
3578
|
+
app.on('POST', aiEventsPaths, authMw, readBounded, sigMw, handleAiEvents);
|
|
3579
|
+
}
|
|
3580
|
+
else {
|
|
3581
|
+
app.on('POST', aiEventsPaths, authMw, readBounded, handleAiEvents);
|
|
3582
|
+
}
|
|
3346
3583
|
// Debug events handler
|
|
3347
3584
|
const handleDebugEvents = async (c) => {
|
|
3348
3585
|
const reqLog = this.log.bind({ endpoint: `${basePath}/debug_events` });
|
|
@@ -3685,4 +3922,40 @@ export class AgentBase extends SWMLService {
|
|
|
3685
3922
|
return this.basicAuthCreds;
|
|
3686
3923
|
}
|
|
3687
3924
|
}
|
|
3925
|
+
/**
|
|
3926
|
+
* A request's body as text, or null when it's over `limit` bytes. The body is
|
|
3927
|
+
* read in chunks and abandoned as soon as it passes the limit. One that
|
|
3928
|
+
* middleware ahead of the route already read (`c.req.text()`, `json()`,
|
|
3929
|
+
* `arrayBuffer()`) is in Hono's cache, so it's read from there and measured.
|
|
3930
|
+
*/
|
|
3931
|
+
async function readBodyWithin(req, limit) {
|
|
3932
|
+
const request = req.raw;
|
|
3933
|
+
if (request.bodyUsed || Object.keys(req.bodyCache).length > 0) {
|
|
3934
|
+
// Already in memory: only its size is left to check
|
|
3935
|
+
const text = await req.text();
|
|
3936
|
+
return Buffer.byteLength(text, 'utf8') > limit ? null : text;
|
|
3937
|
+
}
|
|
3938
|
+
if (!request.body)
|
|
3939
|
+
return '';
|
|
3940
|
+
const reader = request.body.getReader();
|
|
3941
|
+
const chunks = [];
|
|
3942
|
+
let size = 0;
|
|
3943
|
+
for (;;) {
|
|
3944
|
+
const { done, value } = await reader.read();
|
|
3945
|
+
if (done)
|
|
3946
|
+
break;
|
|
3947
|
+
size += value.byteLength;
|
|
3948
|
+
if (size > limit) {
|
|
3949
|
+
// Not awaited: when middleware has cloned the request, the body is one
|
|
3950
|
+
// branch of a tee, and cancelling it waits until the other branch is
|
|
3951
|
+
// read, which that middleware can do only after this route has answered.
|
|
3952
|
+
reader.cancel().catch(() => undefined);
|
|
3953
|
+
reader.releaseLock();
|
|
3954
|
+
return null;
|
|
3955
|
+
}
|
|
3956
|
+
chunks.push(value);
|
|
3957
|
+
}
|
|
3958
|
+
reader.releaseLock();
|
|
3959
|
+
return new TextDecoder().decode(Buffer.concat(chunks));
|
|
3960
|
+
}
|
|
3688
3961
|
//# sourceMappingURL=AgentBase.js.map
|