@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/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';
@@ -307,6 +308,10 @@ export class AgentBase extends SWMLService {
307
308
  perCallConfigs = [];
308
309
  /** Set once serve() runs an HTTP server; getFullUrl then ignores serverless environments. */
309
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;
310
315
  /** Handlers registered with {@link onCallStart}. */
311
316
  callStartHandlers = [];
312
317
  /** Handlers registered with {@link onCallEnd}. */
@@ -319,6 +324,8 @@ export class AgentBase extends SWMLService {
319
324
  postPromptUrlOverride = null;
320
325
  // Contexts
321
326
  contextsBuilder = null;
327
+ /** Tools the contexts reported as offered by no step; shared with per-request copies. */
328
+ _unofferedToolsWarned = new Set();
322
329
  /** Contexts given as a plain object, rendered as they are. */
323
330
  _rawContexts = null;
324
331
  // MCP
@@ -791,7 +798,7 @@ export class AgentBase extends SWMLService {
791
798
  }
792
799
  // Attach agent reference so ContextBuilder.validate() can check
793
800
  // user tool names against reserved native tool names.
794
- this.contextsBuilder.attachAgent(this);
801
+ this.contextsBuilder.attachAgent(this)._shareUnofferedWarnings(this._unofferedToolsWarned);
795
802
  return this.contextsBuilder;
796
803
  }
797
804
  /**
@@ -1046,15 +1053,27 @@ export class AgentBase extends SWMLService {
1046
1053
  * `semantic_gate_timeout_ms`.
1047
1054
  * @param opts.history - How many recent dialogue entries the decision model
1048
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.
1049
1064
  * @returns This agent instance for chaining.
1050
1065
  * @throws {Error} When a value has the wrong type or is out of range.
1051
1066
  */
1052
1067
  setSemanticGates(opts = {}) {
1053
1068
  // Check every value before setting any, so a refused call changes nothing
1054
- const { enabled, timeoutMs, history } = opts;
1069
+ const { enabled, timeoutMs, history, dialogue } = opts;
1055
1070
  if (enabled !== undefined && typeof enabled !== 'boolean') {
1056
1071
  throw new Error(`enabled must be a boolean, got ${JSON.stringify(enabled)}`);
1057
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
+ }
1058
1077
  const ranges = [
1059
1078
  ['semantic_gate_timeout_ms', 'timeout_ms', timeoutMs, 500, 10000],
1060
1079
  ['semantic_gate_history', 'history', history, 0, 100],
@@ -1068,12 +1087,34 @@ export class AgentBase extends SWMLService {
1068
1087
  }
1069
1088
  if (enabled !== undefined)
1070
1089
  this.params['semantic_gates_enabled'] = enabled;
1090
+ if (dialogue !== undefined)
1091
+ this.params['semantic_gate_dialogue'] = dialogue;
1071
1092
  for (const [param, , value] of ranges) {
1072
1093
  if (value !== undefined)
1073
1094
  this.params[param] = value;
1074
1095
  }
1075
1096
  return this;
1076
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
+ }
1077
1118
  /**
1078
1119
  * **MERGES** `data` into the global_data object passed into the AI
1079
1120
  * configuration. **Despite the name, this does NOT replace** the existing
@@ -1493,7 +1534,7 @@ export class AgentBase extends SWMLService {
1493
1534
  name,
1494
1535
  description: fn.description || name,
1495
1536
  };
1496
- tool['inputSchema'] = normalizeParameters(fn.parameters, fn.required);
1537
+ tool['inputSchema'] = fn._parameterSchema(this._nullableOptionalDefault());
1497
1538
  tools.push(tool);
1498
1539
  }
1499
1540
  }
@@ -1551,7 +1592,7 @@ export class AgentBase extends SWMLService {
1551
1592
  function: toolName,
1552
1593
  argument: { parsed: [args] },
1553
1594
  };
1554
- const resultDict = await fn._executeAs(this, args, rawData, this._onError);
1595
+ const resultDict = await this._executeFunction(fn, args, rawData);
1555
1596
  // MCP content is text: a structured { tool_result, tool_prompt }
1556
1597
  // response goes as its JSON.
1557
1598
  const response = resultDict['response'] ?? '';
@@ -1632,6 +1673,10 @@ export class AgentBase extends SWMLService {
1632
1673
  isTypedHandler: true,
1633
1674
  gates: opts.gates,
1634
1675
  gateFillers: opts.gateFillers,
1676
+ vouched: opts.vouched,
1677
+ nullableOptional: opts.nullableOptional,
1678
+ needsConversation: opts.needsConversation,
1679
+ middleware: opts.middleware,
1635
1680
  });
1636
1681
  this.toolRegistry.set(opts.name, fn);
1637
1682
  return this;
@@ -1780,7 +1825,10 @@ export class AgentBase extends SWMLService {
1780
1825
  // (skill_base.py:59-79), swaig_fields are define_tool arguments with the
1781
1826
  // tool's own fields winning: `secure` sets whether the tool needs a token,
1782
1827
  // and the other keys go into the SWAIG definition.
1783
- 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);
1784
1832
  for (const toolDef of skill.getTools()) {
1785
1833
  // Skill-level swaigFields are the base and the tool's own fields win —
1786
1834
  // Python skill_base.py:70-73 (swaig_fields base, explicit kwargs win) and
@@ -1809,11 +1857,20 @@ export class AgentBase extends SWMLService {
1809
1857
  extraFields['gates'] = toolDef.gates;
1810
1858
  if (toolDef.gate_fillers !== undefined)
1811
1859
  extraFields['gate_fillers'] = toolDef.gate_fillers;
1860
+ // The options as SwaigFunctionOptions spells them, for a tool given that way
1861
+ const camel = toolDef;
1812
1862
  this.defineTool({
1813
1863
  ...toolDef,
1814
1864
  ...(toolDef.secure === undefined && typeof skillSecure === 'boolean'
1815
1865
  ? { secure: skillSecure }
1816
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),
1817
1874
  extraFields,
1818
1875
  });
1819
1876
  }
@@ -2003,6 +2060,75 @@ export class AgentBase extends SWMLService {
2003
2060
  this.perCallConfigs = [...this.perCallConfigs, cb];
2004
2061
  return this;
2005
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
+ }
2006
2132
  /**
2007
2133
  * Register a handler that runs when the call starts, before the AI speaks.
2008
2134
  *
@@ -2638,6 +2764,15 @@ export class AgentBase extends SWMLService {
2638
2764
  onFunctionCall(_name, _args, _rawData) {
2639
2765
  // Default no-op
2640
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
+ }
2641
2776
  /**
2642
2777
  * Extract the tool-call arguments from a SWAIG request body.
2643
2778
  *
@@ -2702,7 +2837,8 @@ export class AgentBase extends SWMLService {
2702
2837
  const ids = conversationId && conversationId !== callId ? [callId, conversationId] : [callId];
2703
2838
  return this.sessionManager._validateTokenFor(ids, functionName, token);
2704
2839
  }
2705
- extractSwaigArgs(body, reqLog) {
2840
+ /** @internal The call simulator replays recorded requests through it. */
2841
+ _extractSwaigArgs(body, reqLog = this.log) {
2706
2842
  const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
2707
2843
  const argument = body['argument'];
2708
2844
  if (isPlainObject(argument)) {
@@ -2775,7 +2911,7 @@ export class AgentBase extends SWMLService {
2775
2911
  const entry = {
2776
2912
  function: name,
2777
2913
  description: fn.description,
2778
- parameters: normalizeParameters(fn.parameters, fn.required),
2914
+ parameters: fn._parameterSchema(this._nullableOptionalDefault()),
2779
2915
  };
2780
2916
  if (fn.fillers && Object.keys(fn.fillers).length)
2781
2917
  entry['fillers'] = fn.fillers;
@@ -2894,8 +3030,20 @@ export class AgentBase extends SWMLService {
2894
3030
  aiConfig['multilingual'] = this.multilingual;
2895
3031
  if (this.pronounce.length)
2896
3032
  aiConfig['pronounce'] = this.pronounce;
2897
- if (Object.keys(this.params).length)
2898
- 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;
2899
3047
  if (Object.keys(this.globalData).length)
2900
3048
  aiConfig['global_data'] = this.globalData;
2901
3049
  // Debug events
@@ -2968,6 +3116,8 @@ export class AgentBase extends SWMLService {
2968
3116
  copy._sipUsernames = this._sipUsernames ? new Map(this._sipUsernames) : null;
2969
3117
  copy._routingCallbacks = new Map(this._routingCallbacks);
2970
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);
2971
3121
  copy._rawContexts = clone(this._rawContexts);
2972
3122
  // Back-reference points at the COPY, not `this` (see _promptManager above).
2973
3123
  copy.swmlBuilder = new SwmlBuilder({ service: copy, ...this._builderSchemaOptions });
@@ -3266,7 +3416,7 @@ export class AgentBase extends SWMLService {
3266
3416
  const refusal = target.swaigTokenRefusal(fn, token, callIdStr, reqLog, conversationIdOf(body));
3267
3417
  if (refusal)
3268
3418
  return c.json(refusal);
3269
- const args = this.extractSwaigArgs(body, reqLog);
3419
+ const args = this._extractSwaigArgs(body, reqLog);
3270
3420
  reqLog.debug('executing_function', { args: JSON.stringify(args) });
3271
3421
  const hookResult = await target.onFunctionCall(fnName, args, body);
3272
3422
  // If onFunctionCall returned a result, use it (dispatch interception)
@@ -3275,7 +3425,7 @@ export class AgentBase extends SWMLService {
3275
3425
  return c.json(hookResult);
3276
3426
  }
3277
3427
  try {
3278
- const result = await fn._executeAs(target, args, body, target._onError);
3428
+ const result = await target._executeFunction(fn, args, body);
3279
3429
  reqLog.info('function_executed_successfully');
3280
3430
  reqLog.debug('function_result', { result_size: JSON.stringify(result).length });
3281
3431
  return c.json(result);
@@ -3370,6 +3520,66 @@ export class AgentBase extends SWMLService {
3370
3520
  else {
3371
3521
  app.on('POST', postPromptPaths, authMw, handlePostPrompt);
3372
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
+ }
3373
3583
  // Debug events handler
3374
3584
  const handleDebugEvents = async (c) => {
3375
3585
  const reqLog = this.log.bind({ endpoint: `${basePath}/debug_events` });
@@ -3712,4 +3922,40 @@ export class AgentBase extends SWMLService {
3712
3922
  return this.basicAuthCreds;
3713
3923
  }
3714
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
+ }
3715
3961
  //# sourceMappingURL=AgentBase.js.map