@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
@@ -201,4 +201,47 @@ export function normalizePostPrompt(body) {
201
201
  raw: body,
202
202
  }));
203
203
  }
204
+ /**
205
+ * What the caller said, from a SWAIG request's conversation.
206
+ *
207
+ * A tool can check that an argument is something the caller said, not
208
+ * something the model inferred. The request carries the conversation only
209
+ * with `swaig_post_conversation` on: define the tool with
210
+ * `needsConversation: true`, which turns it on.
211
+ * @param rawData - The SWAIG request (the handler's `rawData`), or a call log
212
+ * array.
213
+ * @param since - Only the turns from this time on: the platform's
214
+ * `timestamp`, in microseconds since the epoch, of a call log entry.
215
+ * @param opts - `last`: only the newest this many turns.
216
+ * @returns The caller's turns, oldest first, as the recognizer's final text
217
+ * (after hearing hints and number formatting). Empty when the request
218
+ * carries no conversation.
219
+ */
220
+ export function callerTurns(rawData, since, opts = {}) {
221
+ let callLog = rawData;
222
+ if (typeof rawData === 'object' && rawData !== null && !Array.isArray(rawData)) {
223
+ const r = rawData;
224
+ callLog =
225
+ Array.isArray(r['call_log']) && r['call_log'].length > 0 ? r['call_log'] : r['raw_call_log'];
226
+ }
227
+ if (!Array.isArray(callLog))
228
+ return [];
229
+ let turns = [];
230
+ for (const entry of callLog) {
231
+ if (typeof entry !== 'object' || entry === null || entry['role'] !== 'user')
232
+ continue;
233
+ const content = entry['content'];
234
+ if (typeof content !== 'string' || !content.trim())
235
+ continue;
236
+ if (since !== undefined) {
237
+ const stamp = entry['timestamp'];
238
+ if (typeof stamp !== 'number' || stamp < since)
239
+ continue;
240
+ }
241
+ turns.push(content);
242
+ }
243
+ if (opts.last !== undefined)
244
+ turns = opts.last > 0 ? turns.slice(-opts.last) : [];
245
+ return turns;
246
+ }
204
247
  //# sourceMappingURL=PostPrompt.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"PostPrompt.js","sourceRoot":"","sources":["../src/PostPrompt.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"PostPrompt.js","sourceRoot":"","sources":["../src/PostPrompt.ts"],"names":[],"mappings":"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"}
@@ -12,6 +12,7 @@ import { SwmlBuilder } from './SwmlBuilder.js';
12
12
  import { SchemaUtils } from './SchemaUtils.js';
13
13
  import { Logger } from './Logger.js';
14
14
  import { SwaigFunction, type SwaigFunctionOptions } from './SwaigFunction.js';
15
+ import { type ToolMiddleware } from './ToolMiddleware.js';
15
16
  import type { ToolParameters, ToolArgs } from './ParameterSchema.js';
16
17
  import { FunctionResult } from './FunctionResult.js';
17
18
  import type { SwmlRequestData } from './PlatformContracts.js';
@@ -205,10 +206,53 @@ export declare class SWMLService {
205
206
  protected _proxyUrlBase: string | null;
206
207
  protected _proxyUrlBaseFromEnv: boolean;
207
208
  protected _routingCallbacks: Map<string, RoutingCallback>;
209
+ /** The route-relative router {@link asRouter} returns, built on first use. */
210
+ private _router;
211
+ /** Whether the HTTP routes enforce basic auth (credentials weren't generated). */
212
+ private _enforceAuth;
208
213
  protected toolRegistry: Map<string, SwaigFunction | Record<string, unknown>>;
214
+ /** Middleware around every tool call, as {@link addToolMiddleware} adds it. */
215
+ private _toolMiddleware;
216
+ /**
217
+ * The transport-retry dedupe that runs first, or null when it's off.
218
+ * Created here, not lazily: a per-request copy shares the service's
219
+ * object, so every request sees one dedupe.
220
+ */
221
+ private _toolResendDedupe;
222
+ /** Whether optional tool arguments take null, as {@link setNullableOptionalParameters} sets it. */
223
+ private _nullableOptionalParameters;
209
224
  constructor(opts: SWMLServiceOptions);
210
225
  /** @deprecated Prefer passing an options object with a required `name`. The no-arg form defaults name to 'swml-service'. */
211
226
  constructor(opts?: Partial<SWMLServiceOptions>);
227
+ /**
228
+ * Build the app serving this service's routes under `base`: the service's
229
+ * route for its own app ({@link getApp}), or '' for the route-relative
230
+ * router {@link asRouter} returns. Each is built once; routing callbacks are
231
+ * looked up when a request arrives, so one registered or replaced later
232
+ * answers through any app or router taken before.
233
+ *
234
+ * The service's own app answers everything it's sent, so its security
235
+ * headers, CORS and basic auth apply to every request. The router
236
+ * (`scoped`) is mounted among other routes, so it has no middleware for
237
+ * every path: the service's routes and routing callbacks carry the security
238
+ * headers, CORS and basic auth in their own handler chains, with CORS
239
+ * preflight routes, and a neighbouring route is left alone. Routes the
240
+ * extension hook or a caller adds to the router check auth themselves, as
241
+ * the reference's router handlers do.
242
+ */
243
+ private _buildServiceApp;
244
+ /**
245
+ * The routing callback a request addresses, in an app built under `base`
246
+ * and mounted where routing matched it (the matched route's template,
247
+ * before its final `*`). A callback registered at `path` is served at
248
+ * `base + path`, as the reference's router serves it; the service's own app
249
+ * also serves it at `path` itself, where releases before 3.7.2 served it,
250
+ * and such an exact path takes precedence over another callback's
251
+ * `base + path`. Each candidate is matched as its whole route, mount and
252
+ * callback path together, by Hono's own routers, as routing matched it when
253
+ * callbacks were routes.
254
+ */
255
+ private _matchCallback;
212
256
  /**
213
257
  * Define a SWAIG function the AI can call. Tool descriptions and
214
258
  * parameter descriptions are LLM-facing prompt engineering — see
@@ -219,7 +263,7 @@ export declare class SWMLService {
219
263
  * `const` type parameters capture its literals and the handler's `args` is
220
264
  * inferred precisely — `args.phone` typed `string`, an `enum` prop narrowed to
221
265
  * its literal union, `required` keys present and the rest optional (see
222
- * {@link ToolArgs}/{@link InferArgs}). The WRAPPED JSON-Schema object
266
+ * `ToolArgs`/`InferArgs`). The WRAPPED JSON-Schema object
223
267
  * (`{ type:'object', properties }`) and a pre-built `Record` are still
224
268
  * accepted and keep the prior open-record `args` behavior. The args type is a
225
269
  * compile-time authoring convenience — at runtime args is the JSON the model
@@ -228,8 +272,93 @@ export declare class SWMLService {
228
272
  defineTool<const P extends ToolParameters = ToolParameters, const R extends readonly PropertyKey[] = []>(opts: Omit<SwaigFunctionOptions, 'parameters' | 'required' | 'handler'> & {
229
273
  parameters?: P;
230
274
  required?: R;
231
- handler: (args: ToolArgs<P, R>, rawData: SwaigRequest, agent?: AgentBase) => FunctionResult | Record<string, unknown> | string | Promise<FunctionResult | Record<string, unknown> | string>;
275
+ handler: (args: ToolArgs<P, R>, rawData: SwaigRequest, agent?: AgentBase) => FunctionResult | Record<string, unknown> | string | null | undefined | void | Promise<FunctionResult | Record<string, unknown> | string | null | undefined | void>;
232
276
  }): this;
277
+ /**
278
+ * Define a function the platform implements itself, under your own
279
+ * description and parameters.
280
+ *
281
+ * The platform runs its own implementation of a function whose
282
+ * `web_hook_url` is `"native"`, by name, and never calls a webhook. A tool
283
+ * defined with {@link defineTool} gets the agent's webhook URL, so it can't
284
+ * be one. Use this to describe a function the platform implements, such as
285
+ * `end_call`, in your own words, or to put it in a step's function list.
286
+ * @param name - The function's name, one the platform implements.
287
+ * @param description - The description the model reads.
288
+ * @param parameters - The JSON schema of its arguments, as the platform's
289
+ * implementation reads them. Default: none.
290
+ * @param fields - Other SWAIG fields, such as `fillers`. Its
291
+ * `web_hook_url` is always `"native"`.
292
+ * @returns This service, for chaining.
293
+ */
294
+ defineNativeTool(name: string, description: string, parameters?: Record<string, unknown>, fields?: Record<string, unknown>): this;
295
+ /**
296
+ * Let the model send null for any tool's optional arguments.
297
+ *
298
+ * Some providers' strict schemas make every argument required and refuse a
299
+ * call that leaves one out, so an optional argument has to take null
300
+ * instead. With this on, each optional argument of every tool defined with
301
+ * {@link defineTool} takes null as well as its type, and a null reaches the
302
+ * handler as an argument not given. A tool's own `nullableOptional`
303
+ * overrides it. It applies when the SWML is rendered, so it covers tools
304
+ * defined before or after it.
305
+ * @param enabled - `true` to turn it on, `false` to turn it off.
306
+ * @returns This service, for chaining.
307
+ */
308
+ setNullableOptionalParameters(enabled?: boolean): this;
309
+ /**
310
+ * The agent's default for whether optional tool arguments take null.
311
+ * @internal
312
+ */
313
+ _nullableOptionalDefault(): boolean;
314
+ /**
315
+ * Run `middleware` around every tool call, after any added before it.
316
+ *
317
+ * A middleware is `(name, args, rawData, callNext)`. It runs before the
318
+ * handler and calls `callNext(args, rawData)` for the rest of the chain and
319
+ * the handler, possibly with changed arguments. What it returns is the
320
+ * call's result: the handler's, a changed one, or its own without calling
321
+ * `callNext`, as a `FunctionResult` or an object. `callNext` returns a
322
+ * promise. One that throws {@link ToolRefusal} declines the call, and any
323
+ * other error gives the model the unknown-outcome result.
324
+ *
325
+ * It covers tools defined with {@link defineTool}, not DataMap or native
326
+ * tools, which run on the platform. Handlers for different calls interleave
327
+ * at every `await`, so guard shared state.
328
+ * @param middleware - The middleware.
329
+ * @returns This service, for chaining.
330
+ *
331
+ * @example
332
+ * ```ts
333
+ * agent.addToolMiddleware(async (name, args, rawData, callNext) => {
334
+ * const started = Date.now();
335
+ * const result = await callNext(args, rawData);
336
+ * console.log(`${name} took ${Date.now() - started} ms`);
337
+ * return result;
338
+ * });
339
+ * ```
340
+ */
341
+ addToolMiddleware(middleware: ToolMiddleware): this;
342
+ /**
343
+ * Turn the dedupe of transport retries on or off. It's on by default.
344
+ *
345
+ * SignalWire sends a tool request again, with the same body, after a
346
+ * timeout, a failed connection or a 5xx, so a slow tool can run twice. The
347
+ * dedupe answers a retry with the first attempt's result: one that arrives
348
+ * while the first is still running waits for it. A retry is a call with the
349
+ * same `call_id`, `tool_call_id` and function name; a call the model makes
350
+ * again has a new `tool_call_id` and runs, and a call without one always
351
+ * runs. The state lives in the process: replicas each keep their own.
352
+ * @param enabled - `false` to run every request, retries included.
353
+ * @returns This service, for chaining.
354
+ */
355
+ setToolResendDedupe(enabled?: boolean): this;
356
+ /**
357
+ * The middleware around a call of `fn`, outermost first: the resend
358
+ * dedupe, the service's, then the tool's own.
359
+ * @internal
360
+ */
361
+ _toolMiddlewareFor(fn: SwaigFunction): ToolMiddleware[];
233
362
  /**
234
363
  * Register a SwaigFunction instance or a raw function descriptor (DataMap).
235
364
  *
@@ -415,6 +544,13 @@ export declare class SWMLService {
415
544
  * @param path - HTTP path for the callback (default '/sip').
416
545
  */
417
546
  registerRoutingCallback(callbackFn: RoutingCallback, path?: string): void;
547
+ /**
548
+ * Answer a request for a routing callback: run it (awaited) for a POST with
549
+ * a body, redirect with 307 when it returns a route, and otherwise serve the
550
+ * SWML for the request as the main route does, as the reference does. Auth
551
+ * is the app's middleware.
552
+ */
553
+ private _serveRoutingCallback;
418
554
  /** The body (for a POST) and headers of a served request. */
419
555
  private _readRequest;
420
556
  /**
@@ -444,10 +580,10 @@ export declare class SWMLService {
444
580
  *
445
581
  * Default implementation returns `null` (no-op).
446
582
  *
447
- * @param queryParams - URL query parameters from the request.
448
- * @param bodyParams - Parsed POST body (empty object for GET requests).
449
- * @param headers - HTTP request headers.
450
- * @param callbackPath - The callback sub-path being handled, if any.
583
+ * @param _queryParams - URL query parameters from the request.
584
+ * @param _bodyParams - Parsed POST body (empty object for GET requests).
585
+ * @param _headers - HTTP request headers.
586
+ * @param _callbackPath - The callback sub-path being handled, if any.
451
587
  * @returns A `SwmlBuilder` whose document is sent as the response, or
452
588
  * `null` to delegate to the next handler in the chain.
453
589
  */
@@ -487,14 +623,19 @@ export declare class SWMLService {
487
623
  /**
488
624
  * Get a router to embed this service's routes in a host web app.
489
625
  *
490
- * Returns the fully-wired Hono app as a mountable sub-app; the host mounts it
491
- * with `hostApp.route(path, service.asRouter())`. This is the TypeScript
492
- * realization of Python's `as_router()`; the named {@link HostAppRouter} type
493
- * is the cross-port "embed my routes in a host app" contract.
626
+ * The router's routes are relative to the service's route, as Python's
627
+ * `as_router()` is: the host mounts it with
628
+ * `hostApp.route(path, service.asRouter())`, and the service's document is
629
+ * served at `path`, its SWAIG endpoint at `path/swaig` and its routing
630
+ * callbacks under `path`, with its own basic auth. The named
631
+ * {@link HostAppRouter} type is the cross-port "embed my routes in a host
632
+ * app" contract.
494
633
  *
495
634
  * @returns A mountable Hono sub-app carrying this service's routes.
496
635
  */
497
636
  asRouter(): HostAppRouter;
637
+ /** The service's route as a path prefix: '' for '/', else without a trailing slash. */
638
+ private _routeBase;
498
639
  /**
499
640
  * Start the HTTP server. Canonical entrypoint, matching Python's
500
641
  * `SWMLService.serve()`.