@signalwire/sdk 3.7.1 → 3.7.2

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 (55) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/dist/AgentBase.d.ts +13 -1
  3. package/dist/AgentBase.js +32 -5
  4. package/dist/AgentBase.js.map +1 -1
  5. package/dist/AgentServer.d.ts +30 -6
  6. package/dist/AgentServer.js +28 -2
  7. package/dist/AgentServer.js.map +1 -1
  8. package/dist/ContextBuilder.d.ts +16 -5
  9. package/dist/ContextBuilder.js +15 -4
  10. package/dist/ContextBuilder.js.map +1 -1
  11. package/dist/Logger.d.ts +1 -1
  12. package/dist/SWMLService.d.ts +54 -9
  13. package/dist/SWMLService.js +248 -59
  14. package/dist/SWMLService.js.map +1 -1
  15. package/dist/SchemaUtils.js +14 -1
  16. package/dist/SchemaUtils.js.map +1 -1
  17. package/dist/SessionManager.d.ts +17 -6
  18. package/dist/SessionManager.js +16 -3
  19. package/dist/SessionManager.js.map +1 -1
  20. package/dist/SwaigFunction.d.ts +4 -3
  21. package/dist/SwaigFunction.js +1 -1
  22. package/dist/SwaigFunction.js.map +1 -1
  23. package/dist/TypeInference.d.ts +1 -1
  24. package/dist/TypeInference.js +1 -1
  25. package/dist/ai-chat/ChatGateway.d.ts +5 -5
  26. package/dist/ai-chat/HandoffRouter.d.ts +3 -3
  27. package/dist/cli/tsdocs/api-index.json +1 -1
  28. package/dist/index.d.ts +1 -0
  29. package/dist/index.js +1 -0
  30. package/dist/index.js.map +1 -1
  31. package/dist/livewire/index.d.ts +3 -0
  32. package/dist/livewire/index.js +3 -0
  33. package/dist/livewire/index.js.map +1 -1
  34. package/dist/relay/Call.d.ts +1 -1
  35. package/dist/relay/Call.js +1 -1
  36. package/dist/relay/Message.d.ts +1 -1
  37. package/dist/relay/Message.js +1 -1
  38. package/dist/relay/RelayClient.d.ts +0 -2
  39. package/dist/relay/RelayClient.js.map +1 -1
  40. package/dist/relay/RelayEvent.d.ts +3 -3
  41. package/dist/relay/RelayEvent.js +3 -3
  42. package/dist/relay/closedSets.d.ts +10 -10
  43. package/dist/relay/closedSets.js +2 -2
  44. package/dist/relay/types.d.ts +1 -1
  45. package/dist/rest/base/CrudResource.d.ts +1 -1
  46. package/dist/rest/base/CrudResource.js +1 -1
  47. package/dist/skills/SkillBase.d.ts +2 -2
  48. package/dist/skills/SkillBase.js +2 -2
  49. package/docs/agent-guide.md +2 -2
  50. package/docs/api-reference.md +8 -8
  51. package/docs/contexts-guide.md +2 -1
  52. package/docs/pgi_agent_guide.md +2 -1
  53. package/docs/programmatically_governed_inference.md +1 -1
  54. package/docs/swml_service_guide.md +31 -6
  55. package/package.json +3 -1
@@ -1400,7 +1400,7 @@ Import the class from the package root:
1400
1400
  import { AgentServer } from '@signalwire/sdk';
1401
1401
  ```
1402
1402
 
1403
- `AgentServer` serves several agents from one HTTP server, each under its own route prefix.
1403
+ `AgentServer` serves several agents from one HTTP server, each under its own route prefix. `AgentServer<T extends SWMLService = AgentBase>` is generic over what it hosts: `new AgentServer<SWMLService>()` hosts plain `SWMLService` call flows next to agents, and its `getAgent()` and `getAgents()` then return `SWMLService`. A plain service answers at its route with or without a trailing slash, under its own basic auth, and serves its `/swaig` endpoint and routing callbacks; the agent endpoints (`/post_prompt`, `/check_for_input`, `/debug`) aren't served for it.
1404
1404
 
1405
1405
  ### Constructor
1406
1406
 
@@ -1421,10 +1421,10 @@ constructor(opts?: { host?: string; port?: number; logLevel?: string })
1421
1421
 
1422
1422
  | Method | Signature | Description |
1423
1423
  |--------|-----------|-------------|
1424
- | `register` | `(agent: AgentBase, route?: string): void` | Mount the agent's `asRouter()` at `route` (default the agent's route). Throws when the route is taken. |
1424
+ | `register` | `(agent: T, route?: string): void` | Mount the agent's (or service's) `asRouter()` at `route` (default its own route). Throws when the route is taken. |
1425
1425
  | `unregister` | `(route: string): boolean` | Remove an agent and its routes; returns `false` when none was registered there. |
1426
- | `getAgents` | `(): Map<string, AgentBase>` | Registered agents keyed by route |
1427
- | `getAgent` | `(route: string): AgentBase \| undefined` | The agent at a route |
1426
+ | `getAgents` | `(): Map<string, T>` | Registered agents keyed by route |
1427
+ | `getAgent` | `(route: string): T \| undefined` | The agent at a route |
1428
1428
  | `serveStaticFiles` | `(directory: string, route?: string): void` | Serve files from a directory, rejecting paths with `..` |
1429
1429
  | `setupSipRouting` | `(route?: string, autoMap?: boolean): void` | Route SIP requests to agents by username at `route` (default `/sip`) |
1430
1430
  | `registerSipUsername` | `(username: string, route: string): void` | Map a SIP username to an agent's route |
@@ -2110,7 +2110,7 @@ The `addStep()` options are shortcuts:
2110
2110
  | `setUserPrompt` | `(userPrompt: string): this` | Emits `user_prompt` |
2111
2111
  | `setIsolated` | `(isolated: boolean): this` | Emits `isolated: true` |
2112
2112
  | `setPrompt` | `(prompt: string): this` | Raw `prompt`. Throws when prompt POM sections exist. |
2113
- | `setHistory` | `(history: string): this` | Default history mode for the context's steps: `keep`, `default` or `hide`. Throws on any other value. |
2113
+ | `setHistory` | `(history: string): this` | Default history mode for the context's steps: `keep`, `default`, `hide` or `isolate`. Throws on any other value. |
2114
2114
 
2115
2115
  #### POM Sections
2116
2116
 
@@ -2172,7 +2172,7 @@ constructor(name: string)
2172
2172
  | `setEnd` | `(end: boolean): this` | Emits `end: true`, which leaves step mode after this step. It doesn't end the call. |
2173
2173
  | `setSkipUserTurn` | `(skip: boolean): this` | Emits `skip_user_turn: true` |
2174
2174
  | `setSkipToNextStep` | `(skip: boolean): this` | Emits `skip_to_next_step: true` |
2175
- | `setHistory` | `(history: string): this` | History mode when the step is entered: `keep`, `default` or `hide`. Throws on any other value. |
2175
+ | `setHistory` | `(history: string): this` | History mode when the step is entered: `keep`, `default`, `hide` or `isolate` (like `hide`, but only while the agent is in the step). Throws on any other value. |
2176
2176
 
2177
2177
  #### Gather Info Methods
2178
2178
 
@@ -2281,8 +2281,8 @@ The accepted history modes:
2281
2281
 
2282
2282
  <!-- snippet: no-compile API signature / type reference, not runnable code -->
2283
2283
  ```ts
2284
- const HISTORY_MODES: readonly ['keep', 'default', 'hide']
2285
- type HistoryMode = 'keep' | 'default' | 'hide'
2284
+ const HISTORY_MODES: readonly ['keep', 'default', 'hide', 'isolate']
2285
+ type HistoryMode = 'keep' | 'default' | 'hide' | 'isolate'
2286
2286
  ```
2287
2287
 
2288
2288
  ---
@@ -381,11 +381,12 @@ main.setText('Now handle the main request.');
381
381
  step.setHistory('hide');
382
382
  ```
383
383
 
384
- The three modes are these:
384
+ The modes are these:
385
385
 
386
386
  - `keep`: hide nothing. Earlier steps' instructions and dialogue stay visible.
387
387
  - `default`: hide earlier step instructions, and keep the dialogue. This is the behavior when `history` isn't set.
388
388
  - `hide`: hide earlier instructions and the earlier dialogue. A `${step_history.*}` reference in this step's text brings back what you choose.
389
+ - `isolate`: like `hide`, but only while the agent is in this step. When the step is left, the earlier dialogue returns and the step's own turns stay; the earlier instructions stay cleared, and what an earlier `hide` step hid stays hidden. Entering the step again isolates it again. Use it for a step that must see nothing else, such as a confirmation read-back. A platform without `isolate` treats it as `default`.
389
390
 
390
391
  `Context.setHistory()` sets the default for every step in the context, and a step's own `setHistory()` overrides it. Any other value throws.
391
392
 
@@ -311,11 +311,12 @@ List allowed model transitions when the model can choose among safe destinations
311
311
 
312
312
  **Solves:** P12-P14. **Use:** `Step.setHistory()`, `Context.setHistory()`, `${step_history.*}` references, context reset settings.
313
313
 
314
- `setHistory()` takes one of three modes:
314
+ `setHistory()` takes one of these modes:
315
315
 
316
316
  - `keep`: keep prior instructions and dialogue.
317
317
  - `default`: remove prior step instructions and keep the dialogue; the behavior when unset.
318
318
  - `hide`: remove prior instructions and dialogue from the model's view. Use `${step_history.*}` references in the step's text to bring back selected information.
319
+ - `isolate`: like `hide`, but only while the agent is in this step. When the step is left, the earlier dialogue returns and the step's own turns stay; the earlier instructions stay cleared, and what an earlier `hide` step hid stays hidden. Entering the step again isolates it again. Use it for a step that must see nothing else, such as a confirmation read-back. A platform without `isolate` treats it as `default`.
319
320
 
320
321
  Hidden turns remain in the call log, so don't describe `hide` as deletion. `Context.setIsolated()`, `setSystemPrompt()`, `setUserPrompt()`, `setConsolidate()` and `setFullReset()` add more controls for entering a context. Steps have `setResetSystemPrompt()`, `setResetUserPrompt()`, `setResetConsolidate()` and `setResetFullReset()`. Verify the combination you choose on the runtime rather than treating them all as a memory wipe. [S03]
321
322
 
@@ -243,7 +243,7 @@ PGI restores programming to the equation. In PGI, the developer's traditional sk
243
243
 
244
244
  A developer building an intake system writes a gather sequence. The platform presents the model with one question at a time and a single submission tool, `gather_submit`. The tool's schema is rebuilt for each question, with that answer's type and, when the question asks for it, a required confirmation. The model does not know how many questions remain or what the full form looks like. When an answer arrives, the platform stores it in `global_data` and silently advances to the next question. When the sequence is complete, the accumulated structured data is handed off to the next phase of the workflow. There, a handler validates the whole record before anything consequential uses it. The model never saw the form. It never had the opportunity to skip ahead, reorder questions, or submit answers to questions that were never asked.
245
245
 
246
- Visibility of what came before is itself a dial the developer controls. By default, each new phase withdraws the prior phase's instructions from the model's context while the conversation itself remains visible. At stricter settings, the platform pulls the earlier dialogue out entirely, or hides the answers already collected so the model must ask rather than infer. A hidden phase can also be brought back on purpose. The platform can hand the model a summary of an earlier phase instead of the raw transcript. The summary is one more curated projection in place of the full truth. Reality authoring extends to the past, not only the present. In the SDK, these settings are `setHistory()` on a step or context (`keep`, `default` or `hide`) and the `isolated` option of `setGatherInfo()` and `addGatherQuestion()`. A `${step_history.*}` reference in a step's text chooses what comes back. The call log keeps every message either way.
246
+ Visibility of what came before is itself a dial the developer controls. By default, each new phase withdraws the prior phase's instructions from the model's context while the conversation itself remains visible. At stricter settings, the platform pulls the earlier dialogue out entirely, or hides the answers already collected so the model must ask rather than infer. A hidden phase can also be brought back on purpose. The platform can hand the model a summary of an earlier phase instead of the raw transcript. The summary is one more curated projection in place of the full truth. Reality authoring extends to the past, not only the present. In the SDK, these settings are `setHistory()` on a step or context (`keep`, `default`, `hide`, or `isolate`, which hides the earlier dialogue only while the agent is in that step) and the `isolated` option of `setGatherInfo()` and `addGatherQuestion()`. A `${step_history.*}` reference in a step's text chooses what comes back. The call log keeps every message either way.
247
247
 
248
248
  This is not the same as ordinary backend validation (clamping a quantity with `if (quantity > 20) quantity = 20;`, or rejecting a bad input). Those are single lines of defensive code any backend performs. The gather sequence is reality authoring. The developer constructs what the model believes to be true at each moment, and `global_data` carries the accumulated truth the model never sees.
249
249
 
@@ -352,7 +352,7 @@ A routing callback inspects a request at a path you choose, and either redirects
352
352
 
353
353
  ### Registering a Routing Callback
354
354
 
355
- `registerRoutingCallback(callbackFn, path)` adds `GET` and `POST` routes at `path` (default `/sip`). The path is at the server root, not under the service's `route`. The callback receives the request's JSON body and its headers, and returns a route string or `null`:
355
+ `registerRoutingCallback(callbackFn, path)` serves `GET` and `POST` at `path` (default `/sip`) under the service's `route`: a service at `/menu` answers at `/menu/sip`. It also answers at `path` itself, where releases before 3.7.2 served it. The callback receives the request's JSON body and its headers, and returns a route string or `null`. A callback can be registered after the service has started serving:
356
356
 
357
357
  <!-- snippet: no-run illustrative fragment: references the assumed `service` object established earlier on the page -->
358
358
  ```typescript
@@ -420,17 +420,42 @@ A `POST /sip` whose body has `call.to` set to `sip:sales@example.sip.signalwire.
420
420
 
421
421
  ### Mounting into a Larger App
422
422
 
423
- `getApp()` returns the service's Hono app, so you can mount it in a larger application. `asRouter()` returns the same app:
423
+ `asRouter()` returns a router whose routes are relative to the service's route, so you can mount it at any prefix in a larger application:
424
424
 
425
425
  ```typescript
426
426
  import { Hono } from 'hono';
427
427
 
428
428
  const app = new Hono();
429
- const service = new SWMLService({ name: 'my-service' });
430
- app.route('/voice', service.getApp());
429
+ const service = new SWMLService({ name: 'my-service', route: '/menu' });
430
+ app.route('/voice', service.asRouter());
431
431
  ```
432
432
 
433
- Mounted this way, the service's routes are under `/voice`: its document at `/voice` and its SWAIG route at `/voice/swaig`.
433
+ Mounted this way, the service's routes are under `/voice`: its document at `/voice`, its SWAIG route at `/voice/swaig` and its routing callbacks under `/voice`, behind its own basic auth. The router has no middleware for every path, so it leaves the host's other routes alone: the service's own routes and routing callbacks carry its security headers, CORS and basic auth. A route you add to the router, or that a subclass adds in `registerAdditionalRoutes()`, isn't behind them there; check auth in it yourself (for example with Hono's `basicAuth` and the service's `validateBasicAuth()`), as the reference's router handlers do. Routes you add to `getApp()` are behind the service's basic auth. Whether `/voice/` answers as `/voice` is the host app's choice: pass `{ strict: false }` to `new Hono()` for that, as `AgentServer` does. `getApp()` returns the service's own app, whose routes are under the service's `route`.
434
+
435
+ ### Hosting a Service Next to Agents
436
+
437
+ An `AgentServer<SWMLService>` registers a plain `SWMLService` as well as agents, so a call flow without AI, such as an IVR menu, can share a server with them. SIP routing can send calls to it like any agent:
438
+
439
+ <!-- snippet: no-run starts a blocking HTTP server (serve/start/run on a fixed port); collides under the concurrent gate and cannot run standalone -->
440
+ ```typescript
441
+ import { AgentBase, AgentServer, SWMLService } from '@signalwire/sdk';
442
+
443
+ const support = new AgentBase({ name: 'support', route: '/support' });
444
+ support.promptAddSection('Role', { body: 'You help callers with their accounts.' });
445
+
446
+ const menu = new SWMLService({ name: 'menu', route: '/menu' });
447
+ menu.addVerb('answer', {});
448
+ menu.addVerb('hangup', {});
449
+
450
+ const server = new AgentServer<SWMLService>();
451
+ server.register(support, '/support');
452
+ server.register(menu, '/menu');
453
+ server.setupSipRouting('/sip');
454
+ server.registerSipUsername('menu', '/menu');
455
+ await server.run();
456
+ ```
457
+
458
+ The service answers at its route with or without a trailing slash, checks its own basic auth credentials, and serves its `/swaig` endpoint and routing callbacks. The agent endpoints (`/post_prompt`, `/check_for_input` and `/debug`) aren't served for it. A plain `new AgentServer()` hosts agents only, and its `getAgent()` and `getAgents()` return agents; on an `AgentServer<SWMLService>` they return `SWMLService`, so narrow with `instanceof AgentBase` before calling agent methods.
434
459
 
435
460
  ### Serving HTTPS
436
461
 
@@ -481,7 +506,7 @@ The document methods listed in [Document Methods](#document-methods) are the pub
481
506
  These methods serve, configure and inspect the service:
482
507
 
483
508
  - `getApp()`: Get the underlying Hono app
484
- - `asRouter()`: Return the same app as `getApp()`, to mount in a host app
509
+ - `asRouter()`: Return a router with the service's routes relative to its route, to mount at any prefix in a host app
485
510
  - `serve(hostOrOptions?, port?, sslOptions?)`: Start the HTTP or HTTPS server
486
511
  - `stop()`: Stop the server
487
512
  - `handleRequest(method, url, headers, body?)`: Answer a request without Hono, returning `[status, headers, body]`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@signalwire/sdk",
3
- "version": "3.7.1",
3
+ "version": "3.7.2",
4
4
  "description": "SignalWire AI Agents SDK for TypeScript/Node.js",
5
5
  "keywords": [
6
6
  "signalwire",
@@ -79,6 +79,7 @@
79
79
  "test": "vitest run",
80
80
  "test:watch": "vitest",
81
81
  "test:examples": "tsc --noEmit --project tsconfig.examples.json",
82
+ "docs:reference": "typedoc --options reference/typedoc.json && npx tsx scripts/inject-navbar.ts",
82
83
  "dev": "tsc --watch",
83
84
  "enumerate:doc-surface": "npx tsx scripts/enumerate-doc-surface.ts",
84
85
  "enumerate:signatures": "PORTING_SDK=\"${PORTING_SDK:-../porting-sdk}\" PORTING_SDK_PATH=\"${PORTING_SDK_PATH:-../porting-sdk}\" npx tsx scripts/enumerate-signatures.ts",
@@ -112,6 +113,7 @@
112
113
  "libphonenumber-js": "^1.13.14",
113
114
  "prettier": "^3.8.4",
114
115
  "tsx": "^4.21.0",
116
+ "typedoc": "^0.28.20",
115
117
  "typescript": "^6.0.0",
116
118
  "typescript-eslint": "^8.61.0",
117
119
  "vitest": "^4.1.5"