@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.
Files changed (96) hide show
  1. package/CHANGELOG.md +214 -0
  2. package/README.md +1 -0
  3. package/dist/AgentBase.d.ts +120 -3
  4. package/dist/AgentBase.js +291 -18
  5. package/dist/AgentBase.js.map +1 -1
  6. package/dist/AgentServer.d.ts +30 -6
  7. package/dist/AgentServer.js +28 -2
  8. package/dist/AgentServer.js.map +1 -1
  9. package/dist/AiEvents.d.ts +70 -0
  10. package/dist/AiEvents.js +94 -0
  11. package/dist/AiEvents.js.map +1 -0
  12. package/dist/ContextBuilder.d.ts +197 -14
  13. package/dist/ContextBuilder.js +422 -13
  14. package/dist/ContextBuilder.js.map +1 -1
  15. package/dist/FunctionResult.d.ts +129 -0
  16. package/dist/FunctionResult.js +170 -0
  17. package/dist/FunctionResult.js.map +1 -1
  18. package/dist/Logger.d.ts +1 -1
  19. package/dist/PostPrompt.d.ts +19 -0
  20. package/dist/PostPrompt.js +43 -0
  21. package/dist/PostPrompt.js.map +1 -1
  22. package/dist/SWMLService.d.ts +151 -10
  23. package/dist/SWMLService.js +377 -61
  24. package/dist/SWMLService.js.map +1 -1
  25. package/dist/SchemaUtils.js +14 -1
  26. package/dist/SchemaUtils.js.map +1 -1
  27. package/dist/SemanticGate.d.ts +61 -1
  28. package/dist/SemanticGate.js +108 -15
  29. package/dist/SemanticGate.js.map +1 -1
  30. package/dist/SessionManager.d.ts +17 -6
  31. package/dist/SessionManager.js +16 -3
  32. package/dist/SessionManager.js.map +1 -1
  33. package/dist/SwaigFunction.d.ts +86 -9
  34. package/dist/SwaigFunction.js +215 -59
  35. package/dist/SwaigFunction.js.map +1 -1
  36. package/dist/ToolMiddleware.d.ts +82 -0
  37. package/dist/ToolMiddleware.js +131 -0
  38. package/dist/ToolMiddleware.js.map +1 -0
  39. package/dist/TypeInference.d.ts +2 -2
  40. package/dist/TypeInference.js +1 -1
  41. package/dist/TypeInference.js.map +1 -1
  42. package/dist/ai-chat/ChatGateway.d.ts +5 -5
  43. package/dist/ai-chat/HandoffRouter.d.ts +3 -3
  44. package/dist/cli/tsdocs/api-index.json +1 -1
  45. package/dist/cli/tsdocs/topics.js +24 -4
  46. package/dist/cli/tsdocs/topics.js.map +1 -1
  47. package/dist/index.d.ts +23 -8
  48. package/dist/index.js +16 -5
  49. package/dist/index.js.map +1 -1
  50. package/dist/livewire/index.d.ts +3 -0
  51. package/dist/livewire/index.js +3 -0
  52. package/dist/livewire/index.js.map +1 -1
  53. package/dist/llms.txt +1 -0
  54. package/dist/patterns/Proposal.d.ts +146 -0
  55. package/dist/patterns/Proposal.js +212 -0
  56. package/dist/patterns/Proposal.js.map +1 -0
  57. package/dist/patterns/RequestList.d.ts +136 -0
  58. package/dist/patterns/RequestList.js +169 -0
  59. package/dist/patterns/RequestList.js.map +1 -0
  60. package/dist/relay/Call.d.ts +1 -1
  61. package/dist/relay/Call.js +1 -1
  62. package/dist/relay/Message.d.ts +1 -1
  63. package/dist/relay/Message.js +1 -1
  64. package/dist/relay/RelayClient.d.ts +0 -2
  65. package/dist/relay/RelayClient.js.map +1 -1
  66. package/dist/relay/RelayEvent.d.ts +3 -3
  67. package/dist/relay/RelayEvent.js +3 -3
  68. package/dist/relay/closedSets.d.ts +10 -10
  69. package/dist/relay/closedSets.js +2 -2
  70. package/dist/relay/types.d.ts +1 -1
  71. package/dist/rest/base/CrudResource.d.ts +1 -1
  72. package/dist/rest/base/CrudResource.js +1 -1
  73. package/dist/skills/SkillBase.d.ts +26 -3
  74. package/dist/skills/SkillBase.js +14 -3
  75. package/dist/skills/SkillBase.js.map +1 -1
  76. package/dist/speech/numbers.d.ts +66 -0
  77. package/dist/speech/numbers.js +281 -0
  78. package/dist/speech/numbers.js.map +1 -0
  79. package/dist/speech/spelling.d.ts +71 -0
  80. package/dist/speech/spelling.js +294 -0
  81. package/dist/speech/spelling.js.map +1 -0
  82. package/dist/testing/CallSimulator.d.ts +281 -0
  83. package/dist/testing/CallSimulator.js +666 -0
  84. package/dist/testing/CallSimulator.js.map +1 -0
  85. package/docs/agent-guide.md +4 -4
  86. package/docs/api-reference.md +285 -28
  87. package/docs/architecture.md +8 -4
  88. package/docs/cli-guide.md +2 -0
  89. package/docs/contexts-guide.md +47 -4
  90. package/docs/conversation_patterns.md +257 -0
  91. package/docs/mcp_integration.md +1 -1
  92. package/docs/pgi_agent_guide.md +2 -1
  93. package/docs/programmatically_governed_inference.md +2 -2
  94. package/docs/swaig-reference.md +95 -3
  95. package/docs/swml_service_guide.md +31 -6
  96. 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, normalizeParameters, } from './SwaigFunction.js';
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 {@link ./prefabs/index.js | prefab agents} (e.g. `ReceptionistAgent`).
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'] = normalizeParameters(fn.parameters, fn.required);
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 fn._executeAs(this, args, rawData, this._onError);
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
- const { secure: skillSecure, ...skillExtraFields } = skill.swaigFields;
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.sessionManager.validateToken(callId, fn.name, token)) {
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
- extractSwaigArgs(body, reqLog) {
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: normalizeParameters(fn.parameters, fn.required),
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
- if (Object.keys(this.params).length)
2874
- aiConfig['params'] = this.params;
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.extractSwaigArgs(body, reqLog);
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 fn._executeAs(target, args, body, target._onError);
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
- if (!callId || !this.sessionManager.validateToken(callId, 'post_prompt', token)) {
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