@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.
- package/CHANGELOG.md +60 -0
- package/dist/AgentBase.d.ts +13 -1
- package/dist/AgentBase.js +32 -5
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +30 -6
- package/dist/AgentServer.js +28 -2
- package/dist/AgentServer.js.map +1 -1
- package/dist/ContextBuilder.d.ts +16 -5
- package/dist/ContextBuilder.js +15 -4
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/Logger.d.ts +1 -1
- package/dist/SWMLService.d.ts +54 -9
- package/dist/SWMLService.js +248 -59
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.js +14 -1
- package/dist/SchemaUtils.js.map +1 -1
- package/dist/SessionManager.d.ts +17 -6
- package/dist/SessionManager.js +16 -3
- package/dist/SessionManager.js.map +1 -1
- package/dist/SwaigFunction.d.ts +4 -3
- package/dist/SwaigFunction.js +1 -1
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/TypeInference.d.ts +1 -1
- package/dist/TypeInference.js +1 -1
- package/dist/ai-chat/ChatGateway.d.ts +5 -5
- package/dist/ai-chat/HandoffRouter.d.ts +3 -3
- package/dist/cli/tsdocs/api-index.json +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +3 -0
- package/dist/livewire/index.js +3 -0
- package/dist/livewire/index.js.map +1 -1
- package/dist/relay/Call.d.ts +1 -1
- package/dist/relay/Call.js +1 -1
- package/dist/relay/Message.d.ts +1 -1
- package/dist/relay/Message.js +1 -1
- package/dist/relay/RelayClient.d.ts +0 -2
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +3 -3
- package/dist/relay/RelayEvent.js +3 -3
- package/dist/relay/closedSets.d.ts +10 -10
- package/dist/relay/closedSets.js +2 -2
- package/dist/relay/types.d.ts +1 -1
- package/dist/rest/base/CrudResource.d.ts +1 -1
- package/dist/rest/base/CrudResource.js +1 -1
- package/dist/skills/SkillBase.d.ts +2 -2
- package/dist/skills/SkillBase.js +2 -2
- package/docs/agent-guide.md +2 -2
- package/docs/api-reference.md +8 -8
- package/docs/contexts-guide.md +2 -1
- package/docs/pgi_agent_guide.md +2 -1
- package/docs/programmatically_governed_inference.md +1 -1
- package/docs/swml_service_guide.md +31 -6
- package/package.json +3 -1
package/docs/api-reference.md
CHANGED
|
@@ -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:
|
|
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,
|
|
1427
|
-
| `getAgent` | `(route: string):
|
|
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 `
|
|
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
|
|
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
|
---
|
package/docs/contexts-guide.md
CHANGED
|
@@ -381,11 +381,12 @@ main.setText('Now handle the main request.');
|
|
|
381
381
|
step.setHistory('hide');
|
|
382
382
|
```
|
|
383
383
|
|
|
384
|
-
The
|
|
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
|
|
package/docs/pgi_agent_guide.md
CHANGED
|
@@ -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
|
|
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 `
|
|
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)`
|
|
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
|
-
`
|
|
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.
|
|
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
|
|
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
|
|
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.
|
|
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"
|