@signalwire/sdk 3.6.0 → 3.7.1

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 CHANGED
@@ -3,6 +3,41 @@
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.7.1 (2026-10-14)
7
+
8
+ Parity with signalwire-python 3.7.1, and `onCallStart()` from its main branch (#118).
9
+
10
+ ### Added
11
+
12
+ - Semantic gates take `visual_input`: how many of the caller's newest video
13
+ frames the decision model sees with the gate, `true` for 1 or a whole
14
+ number up to 5 (`MAX_VISUAL_INPUT`). `new SemanticGate(..., { visualInput })`
15
+ sets it, and gate objects are checked by the platform's rule. 3.6.0
16
+ refused the key, so a gate that looks at the caller's video could only be
17
+ written in raw SWML.
18
+ - `AgentBase.onCallStart()` registers handlers that run when the call
19
+ starts, before the AI's first turn: the counterpart of `onCallEnd()`. It
20
+ wraps the platform's reserved `startup_hook` function. A handler receives
21
+ the SWAIG request and may return a `FunctionResult`: its actions run at
22
+ once, and its response text is added to the conversation as a system
23
+ message the model reads before it speaks. Handlers run in registration
24
+ order, and an exception is logged, not raised.
25
+
26
+ ### Documentation
27
+
28
+ - How to reject a call from the per-call configuration callback
29
+ (`addPerCallConfig()`): build the agent with `play` and `hangup`
30
+ post-answer verbs and no tools, and have the callback add the tools and
31
+ call `clearPostAnswerVerbs()` only for a call it accepts. A callback that
32
+ fails leaves the call rejected. See "Rejecting a Call" in
33
+ `docs/agent-guide.md`.
34
+ - The SWAIG function webhook timeout: the platform waits up to 30 seconds to
35
+ connect and 120 seconds for a tool's reply, and sends the request again, up
36
+ to 3 times, after a failed or timed-out request or a 5xx. The caller hears
37
+ nothing meanwhile, so tools should answer quickly and send late results into the call with
38
+ `calling.aiMessage()` on a `RestClient`. See "Slow tools and the webhook
39
+ timeout" in `docs/agent-guide.md`.
40
+
6
41
  ## 3.6.0 (2026-10-05)
7
42
 
8
43
  Parity with signalwire-python 3.6.0: semantic gates, `changeVoice()`, and
@@ -13,6 +13,7 @@ import { SWMLService } from './SWMLService.js';
13
13
  import { SwaigFunction, type SwaigErrorHandler } from './SwaigFunction.js';
14
14
  import { type FillerPhrases, type SemanticGate } from './SemanticGate.js';
15
15
  import { type TypedToolHandler } from './TypeInference.js';
16
+ import { FunctionResult } from './FunctionResult.js';
16
17
  import { ContextBuilder } from './ContextBuilder.js';
17
18
  import { type Logger } from './Logger.js';
18
19
  import { SkillManager } from './skills/SkillManager.js';
@@ -125,6 +126,8 @@ export declare class AgentBase extends SWMLService {
125
126
  private perCallConfigs;
126
127
  /** Set once serve() runs an HTTP server; getFullUrl then ignores serverless environments. */
127
128
  private _serving;
129
+ /** Handlers registered with {@link onCallStart}. */
130
+ private callStartHandlers;
128
131
  /** Handlers registered with {@link onCallEnd}. */
129
132
  private callEndHandlers;
130
133
  /** Apps and routers added with {@link mount}, replayed on every app build. */
@@ -1025,12 +1028,81 @@ export declare class AgentBase extends SWMLService {
1025
1028
  * without knowing about each other. `setDynamicConfigCallback` replaces
1026
1029
  * every callback registered so far.
1027
1030
  *
1031
+ * Rejecting a call: a callback can't refuse the request, but it can decide
1032
+ * what the call does. Build the agent to fail closed, with
1033
+ * `addPostAnswerVerb('play', { url: 'say:...' })` and
1034
+ * `addPostAnswerVerb('hangup', {})` and no tools, so the call hears the
1035
+ * message and hangs up before the `ai` verb runs. For a call the callback
1036
+ * accepts, add the tools to `agent` and call `agent.clearPostAnswerVerbs()`
1037
+ * last. A callback that throws is logged and the copy is rendered as it
1038
+ * stands, so a failure before that last step leaves the goodbye in place.
1039
+ * A callback that throws stops the ones after it but doesn't restore verbs
1040
+ * an earlier one cleared, so the callback that clears them must run last.
1041
+ * Callbacks run for every request of the call (the SWML fetch, each tool
1042
+ * call, the summary), and only the SWML fetch carries the caller's data
1043
+ * (such as `userVariables`): verify there, remember the `call_id`, and check
1044
+ * it on later requests. See "Rejecting a Call" in docs/agent-guide.md.
1045
+ *
1028
1046
  * @param cb - Callback receiving `(queryParams, bodyParams, headers, agent)`,
1029
1047
  * where `agent` is the per-request copy. Configure that, never the agent
1030
1048
  * itself, or the configuration leaks across callers. May be async.
1031
1049
  * @returns This agent instance for chaining.
1032
1050
  */
1033
1051
  addPerCallConfig(cb: DynamicConfigCallback): this;
1052
+ /**
1053
+ * Register a handler that runs when the call starts, before the AI speaks.
1054
+ *
1055
+ * Handlers run in registration order with `rawData`, the whole SWAIG request
1056
+ * (`call_id`, `global_data`, the caller's details). This wraps the
1057
+ * platform's reserved `startup_hook` function, the counterpart of the
1058
+ * `hangup_hook` behind {@link onCallEnd}. The platform calls it once, after
1059
+ * the call is answered and before the AI's first turn, and never offers it to
1060
+ * the model.
1061
+ *
1062
+ * The platform waits for the hook before the AI starts, so a slow handler
1063
+ * delays the greeting; it waits up to 120 seconds for a function's reply
1064
+ * and sends the request again after a timeout or a 5xx. Keep handlers
1065
+ * short; start long work without awaiting
1066
+ * it and send its result into the call later (`calling.aiMessage()` on the
1067
+ * REST client). Like any function request, the hook's request can be sent
1068
+ * again after a timeout or an error, so make handlers safe to run twice.
1069
+ *
1070
+ * A handler may return a `FunctionResult`, or nothing. What the platform
1071
+ * does with the hook's reply:
1072
+ * - its actions run at once, in registration order across handlers (for
1073
+ * example `updateGlobalData()` to give the call data before the
1074
+ * conversation starts);
1075
+ * - its response text is added to the conversation as a system message the
1076
+ * model reads before its first turn. The texts of several handlers are
1077
+ * joined, one per line. Only a plain string response is used. OpenAI
1078
+ * Realtime agents run the actions but don't add the text.
1079
+ *
1080
+ * `postProcess` isn't used: the combined result runs its actions at once.
1081
+ * The platform adds every hook reply to the conversation, so a hook whose
1082
+ * handlers return no text still adds a short placeholder line, as any
1083
+ * function with an empty reply does.
1084
+ *
1085
+ * An exception is logged, not raised, and that handler's result is dropped,
1086
+ * so a failing handler can't stop the call from starting or the other
1087
+ * handlers from running.
1088
+ *
1089
+ * @param handler - Called with `(rawData)`; may be async. Returns a
1090
+ * `FunctionResult`, or nothing.
1091
+ * @returns The handler.
1092
+ *
1093
+ * @example
1094
+ * ```ts
1095
+ * agent.onCallStart(async (rawData) => {
1096
+ * const caller = await lookupCaller(rawData.caller_id_num);
1097
+ * return new FunctionResult(`The caller's name is ${caller.name}.`).updateGlobalData({
1098
+ * customer_id: caller.id,
1099
+ * });
1100
+ * });
1101
+ * ```
1102
+ */
1103
+ onCallStart(handler: (rawData: SwaigRequest) => FunctionResult | null | undefined | void | Promise<FunctionResult | null | undefined | void>): (rawData: SwaigRequest) => FunctionResult | null | undefined | void | Promise<FunctionResult | null | undefined | void>;
1104
+ /** Register the reserved startup_hook tool once. */
1105
+ private ensureCallStartHook;
1034
1106
  /**
1035
1107
  * Register a handler that runs when the call ends, with the transcript.
1036
1108
  *
package/dist/AgentBase.js CHANGED
@@ -300,6 +300,8 @@ export class AgentBase extends SWMLService {
300
300
  perCallConfigs = [];
301
301
  /** Set once serve() runs an HTTP server; getFullUrl then ignores serverless environments. */
302
302
  _serving = false;
303
+ /** Handlers registered with {@link onCallStart}. */
304
+ callStartHandlers = [];
303
305
  /** Handlers registered with {@link onCallEnd}. */
304
306
  callEndHandlers = [];
305
307
  /** Apps and routers added with {@link mount}, replayed on every app build. */
@@ -1969,6 +1971,21 @@ export class AgentBase extends SWMLService {
1969
1971
  * without knowing about each other. `setDynamicConfigCallback` replaces
1970
1972
  * every callback registered so far.
1971
1973
  *
1974
+ * Rejecting a call: a callback can't refuse the request, but it can decide
1975
+ * what the call does. Build the agent to fail closed, with
1976
+ * `addPostAnswerVerb('play', { url: 'say:...' })` and
1977
+ * `addPostAnswerVerb('hangup', {})` and no tools, so the call hears the
1978
+ * message and hangs up before the `ai` verb runs. For a call the callback
1979
+ * accepts, add the tools to `agent` and call `agent.clearPostAnswerVerbs()`
1980
+ * last. A callback that throws is logged and the copy is rendered as it
1981
+ * stands, so a failure before that last step leaves the goodbye in place.
1982
+ * A callback that throws stops the ones after it but doesn't restore verbs
1983
+ * an earlier one cleared, so the callback that clears them must run last.
1984
+ * Callbacks run for every request of the call (the SWML fetch, each tool
1985
+ * call, the summary), and only the SWML fetch carries the caller's data
1986
+ * (such as `userVariables`): verify there, remember the `call_id`, and check
1987
+ * it on later requests. See "Rejecting a Call" in docs/agent-guide.md.
1988
+ *
1972
1989
  * @param cb - Callback receiving `(queryParams, bodyParams, headers, agent)`,
1973
1990
  * where `agent` is the per-request copy. Configure that, never the agent
1974
1991
  * itself, or the configuration leaks across callers. May be async.
@@ -1979,6 +1996,114 @@ export class AgentBase extends SWMLService {
1979
1996
  this.perCallConfigs = [...this.perCallConfigs, cb];
1980
1997
  return this;
1981
1998
  }
1999
+ /**
2000
+ * Register a handler that runs when the call starts, before the AI speaks.
2001
+ *
2002
+ * Handlers run in registration order with `rawData`, the whole SWAIG request
2003
+ * (`call_id`, `global_data`, the caller's details). This wraps the
2004
+ * platform's reserved `startup_hook` function, the counterpart of the
2005
+ * `hangup_hook` behind {@link onCallEnd}. The platform calls it once, after
2006
+ * the call is answered and before the AI's first turn, and never offers it to
2007
+ * the model.
2008
+ *
2009
+ * The platform waits for the hook before the AI starts, so a slow handler
2010
+ * delays the greeting; it waits up to 120 seconds for a function's reply
2011
+ * and sends the request again after a timeout or a 5xx. Keep handlers
2012
+ * short; start long work without awaiting
2013
+ * it and send its result into the call later (`calling.aiMessage()` on the
2014
+ * REST client). Like any function request, the hook's request can be sent
2015
+ * again after a timeout or an error, so make handlers safe to run twice.
2016
+ *
2017
+ * A handler may return a `FunctionResult`, or nothing. What the platform
2018
+ * does with the hook's reply:
2019
+ * - its actions run at once, in registration order across handlers (for
2020
+ * example `updateGlobalData()` to give the call data before the
2021
+ * conversation starts);
2022
+ * - its response text is added to the conversation as a system message the
2023
+ * model reads before its first turn. The texts of several handlers are
2024
+ * joined, one per line. Only a plain string response is used. OpenAI
2025
+ * Realtime agents run the actions but don't add the text.
2026
+ *
2027
+ * `postProcess` isn't used: the combined result runs its actions at once.
2028
+ * The platform adds every hook reply to the conversation, so a hook whose
2029
+ * handlers return no text still adds a short placeholder line, as any
2030
+ * function with an empty reply does.
2031
+ *
2032
+ * An exception is logged, not raised, and that handler's result is dropped,
2033
+ * so a failing handler can't stop the call from starting or the other
2034
+ * handlers from running.
2035
+ *
2036
+ * @param handler - Called with `(rawData)`; may be async. Returns a
2037
+ * `FunctionResult`, or nothing.
2038
+ * @returns The handler.
2039
+ *
2040
+ * @example
2041
+ * ```ts
2042
+ * agent.onCallStart(async (rawData) => {
2043
+ * const caller = await lookupCaller(rawData.caller_id_num);
2044
+ * return new FunctionResult(`The caller's name is ${caller.name}.`).updateGlobalData({
2045
+ * customer_id: caller.id,
2046
+ * });
2047
+ * });
2048
+ * ```
2049
+ */
2050
+ onCallStart(handler) {
2051
+ const first = this.callStartHandlers.length === 0;
2052
+ // Rebind rather than push: a per-request copy shares this array.
2053
+ this.callStartHandlers = [...this.callStartHandlers, handler];
2054
+ if (first)
2055
+ this.ensureCallStartHook();
2056
+ return handler;
2057
+ }
2058
+ /** Register the reserved startup_hook tool once. */
2059
+ ensureCallStartHook() {
2060
+ this.defineTool({
2061
+ name: 'startup_hook',
2062
+ description: 'Internal: fires when the call starts.',
2063
+ parameters: {},
2064
+ handler: async (_args, rawData, running) => {
2065
+ const raw = (rawData ?? {});
2066
+ const combined = new FunctionResult();
2067
+ const texts = [];
2068
+ // The handlers of the agent running the call: a per-call copy may
2069
+ // have added its own.
2070
+ const agent = running instanceof AgentBase ? running : this;
2071
+ for (const callback of agent.callStartHandlers) {
2072
+ const name = callback.name || 'anonymous';
2073
+ let result;
2074
+ // Each handler is isolated, so one failure doesn't stop the others.
2075
+ try {
2076
+ result = await callback(raw);
2077
+ }
2078
+ catch (err) {
2079
+ this.log.error('call_start_handler_failed', {
2080
+ error: err instanceof Error ? err.message : String(err),
2081
+ handler: name,
2082
+ });
2083
+ continue;
2084
+ }
2085
+ if (result === undefined || result === null)
2086
+ continue;
2087
+ if (!(result instanceof FunctionResult)) {
2088
+ this.log.warn('call_start_handler_result_ignored', {
2089
+ handler: name,
2090
+ result_type: typeof result,
2091
+ });
2092
+ continue;
2093
+ }
2094
+ const response = result.toDict().response;
2095
+ if (typeof response === 'object') {
2096
+ this.log.warn('call_start_handler_structured_response_ignored', { handler: name });
2097
+ }
2098
+ else if (result.response) {
2099
+ texts.push(result.response);
2100
+ }
2101
+ combined.addActions(result.action);
2102
+ }
2103
+ return combined.setResponse(texts.join('\n'));
2104
+ },
2105
+ });
2106
+ }
1982
2107
  /**
1983
2108
  * Register a handler that runs when the call ends, with the transcript.
1984
2109
  *