@signalwire/sdk 2.0.0 → 2.0.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/package.json +1 -1
- package/src/AgentBase.ts +113 -4
- package/src/AgentServer.ts +31 -4
- package/src/ContextBuilder.ts +33 -2
- package/src/DataMap.ts +30 -2
- package/src/FunctionResult.ts +40 -3
- package/src/PomBuilder.ts +29 -1
- package/src/SWMLService.ts +38 -6
- package/src/ServerlessAdapter.ts +20 -1
- package/src/SwmlBuilder.ts +26 -1
- package/src/TypeInference.ts +27 -9
- package/src/WebService.ts +27 -5
- package/src/index.ts +73 -7
- package/src/livewire/index.ts +343 -41
- package/src/prefabs/ConciergeAgent.ts +22 -0
- package/src/prefabs/FAQBotAgent.ts +32 -1
- package/src/prefabs/InfoGathererAgent.ts +41 -1
- package/src/prefabs/ReceptionistAgent.ts +30 -1
- package/src/prefabs/SurveyAgent.ts +26 -1
- package/src/relay/Action.ts +174 -6
- package/src/relay/Call.ts +459 -43
- package/src/relay/Deferred.ts +27 -4
- package/src/relay/Message.ts +54 -3
- package/src/relay/RelayClient.ts +167 -18
- package/src/relay/RelayError.ts +7 -1
- package/src/relay/RelayEvent.ts +52 -0
- package/src/rest/HttpClient.ts +61 -0
- package/src/rest/RestError.ts +14 -0
- package/src/rest/base/BaseResource.ts +16 -3
- package/src/rest/base/CrudResource.ts +52 -5
- package/src/rest/base/CrudWithAddresses.ts +12 -1
- package/src/rest/index.ts +30 -0
- package/src/rest/namespaces/addresses.ts +33 -1
- package/src/rest/namespaces/calling.ts +348 -1
- package/src/rest/namespaces/chat.ts +13 -2
- package/src/rest/namespaces/compat.ts +469 -9
- package/src/rest/namespaces/datasphere.ts +48 -5
- package/src/rest/namespaces/fabric.ts +197 -2
- package/src/rest/namespaces/imported-numbers.ts +13 -2
- package/src/rest/namespaces/logs.ts +68 -1
- package/src/rest/namespaces/lookup.ts +19 -2
- package/src/rest/namespaces/mfa.ts +35 -4
- package/src/rest/namespaces/number-groups.ts +35 -5
- package/src/rest/namespaces/phone-numbers.ts +35 -3
- package/src/rest/namespaces/project.ts +30 -1
- package/src/rest/namespaces/pubsub.ts +13 -2
- package/src/rest/namespaces/queues.ts +29 -4
- package/src/rest/namespaces/recordings.ts +26 -1
- package/src/rest/namespaces/registry.ts +100 -1
- package/src/rest/namespaces/short-codes.ts +27 -1
- package/src/rest/namespaces/sip-profile.ts +18 -3
- package/src/rest/namespaces/verified-callers.ts +22 -3
- package/src/rest/namespaces/video.ts +168 -1
- package/src/rest/pagination.ts +22 -8
- package/src/skills/SkillBase.ts +37 -2
- package/src/skills/SkillManager.ts +8 -4
- package/src/skills/builtin/api_ninjas_trivia.ts +5 -0
- package/src/skills/builtin/ask_claude.ts +5 -0
- package/src/skills/builtin/claude_skills.ts +5 -0
- package/src/skills/builtin/custom_skills.ts +15 -0
- package/src/skills/builtin/datasphere.ts +9 -0
- package/src/skills/builtin/datasphere_serverless.ts +8 -0
- package/src/skills/builtin/datetime.ts +7 -0
- package/src/skills/builtin/google_maps.ts +5 -0
- package/src/skills/builtin/info_gatherer.ts +10 -0
- package/src/skills/builtin/joke.ts +5 -0
- package/src/skills/builtin/math.ts +7 -0
- package/src/skills/builtin/mcp_gateway.ts +8 -0
- package/src/skills/builtin/native_vector_search.ts +9 -0
- package/src/skills/builtin/play_background_file.ts +9 -0
- package/src/skills/builtin/spider.ts +5 -0
- package/src/skills/builtin/swml_transfer.ts +10 -0
- package/src/skills/builtin/weather_api.ts +7 -0
- package/src/skills/builtin/web_search.ts +9 -0
- package/src/skills/builtin/wikipedia_search.ts +5 -0
package/src/livewire/index.ts
CHANGED
|
@@ -39,6 +39,10 @@ function printBanner(): void {
|
|
|
39
39
|
// "Did You Know?" Tips
|
|
40
40
|
// ---------------------------------------------------------------------------
|
|
41
41
|
|
|
42
|
+
/**
|
|
43
|
+
* Rotating "Did you know?" tips printed to stderr by the LiveWire banner.
|
|
44
|
+
* Exported for tests; reorder or extend to change what's displayed.
|
|
45
|
+
*/
|
|
42
46
|
export const tips: string[] = [
|
|
43
47
|
"SignalWire agents support DataMap tools that execute server-side — no webhook infrastructure needed. See: docs/datamap-guide.md",
|
|
44
48
|
"SignalWire Contexts & Steps give you mechanical state control over conversations — no prompt engineering needed. See: docs/contexts-guide.md",
|
|
@@ -68,6 +72,12 @@ function printTip(): void {
|
|
|
68
72
|
class NoopTracker {
|
|
69
73
|
private logged = new Set<string>();
|
|
70
74
|
|
|
75
|
+
/**
|
|
76
|
+
* Log the given message the first time this key is seen.
|
|
77
|
+
*
|
|
78
|
+
* @param key - Dedup key. Subsequent calls with the same key are silent.
|
|
79
|
+
* @param message - Message to write to stderr on first occurrence.
|
|
80
|
+
*/
|
|
71
81
|
once(key: string, message: string): void {
|
|
72
82
|
if (this.logged.has(key)) return;
|
|
73
83
|
this.logged.add(key);
|
|
@@ -96,8 +106,11 @@ export { NoopTracker, globalNoop };
|
|
|
96
106
|
|
|
97
107
|
/** Voice configuration options passed through to the SignalWire AI config. */
|
|
98
108
|
export interface VoiceOptions {
|
|
109
|
+
/** TTS voice identifier (e.g. `"en-US-Standard-A"`). */
|
|
99
110
|
voice: string;
|
|
111
|
+
/** TTS engine identifier (e.g. `"google"`, `"elevenlabs"`). */
|
|
100
112
|
engine: string;
|
|
113
|
+
/** BCP-47 language code (e.g. `"en-US"`). */
|
|
101
114
|
language: string;
|
|
102
115
|
}
|
|
103
116
|
|
|
@@ -105,11 +118,15 @@ export interface VoiceOptions {
|
|
|
105
118
|
// FunctionTool
|
|
106
119
|
// ---------------------------------------------------------------------------
|
|
107
120
|
|
|
108
|
-
/** A tool definition that can be registered on an Agent. */
|
|
121
|
+
/** A tool definition that can be registered on an {@link Agent}. */
|
|
109
122
|
export interface FunctionTool {
|
|
123
|
+
/** Tool name. Populated when the tool is attached to an `Agent.tools` map. */
|
|
110
124
|
name: string;
|
|
125
|
+
/** Human-readable description shown to the LLM. */
|
|
111
126
|
description: string;
|
|
127
|
+
/** JSON schema (or Zod schema passthrough) for the tool's parameters. */
|
|
112
128
|
parameters?: Record<string, unknown>;
|
|
129
|
+
/** Handler invoked by the platform when the LLM calls this tool. */
|
|
113
130
|
execute: (params: any, context: { ctx: RunContext }) => any;
|
|
114
131
|
}
|
|
115
132
|
|
|
@@ -117,10 +134,38 @@ export interface FunctionTool {
|
|
|
117
134
|
// Agent
|
|
118
135
|
// ---------------------------------------------------------------------------
|
|
119
136
|
|
|
120
|
-
/**
|
|
137
|
+
/**
|
|
138
|
+
* Mirrors a LiveKit `voice.Agent` — holds instructions and tool definitions.
|
|
139
|
+
*
|
|
140
|
+
* Pipeline options (`stt`, `tts`, `vad`, `llm`, `turnDetection`) are accepted
|
|
141
|
+
* for API parity but are **no-ops** — SignalWire's control plane handles the
|
|
142
|
+
* entire AI pipeline server-side. Set instructions and tools; everything else
|
|
143
|
+
* just logs once and continues.
|
|
144
|
+
*
|
|
145
|
+
* @example Minimal LiveKit-compatible agent
|
|
146
|
+
* ```ts
|
|
147
|
+
* import { livewire } from '@signalwire/sdk';
|
|
148
|
+
*
|
|
149
|
+
* const timeTool = livewire.tool({
|
|
150
|
+
* description: 'Return the current time.',
|
|
151
|
+
* execute: () => new Date().toISOString(),
|
|
152
|
+
* });
|
|
153
|
+
*
|
|
154
|
+
* const agent = new livewire.Agent({
|
|
155
|
+
* instructions: 'You are a friendly helper.',
|
|
156
|
+
* tools: [{ ...timeTool, name: 'time' }],
|
|
157
|
+
* });
|
|
158
|
+
*
|
|
159
|
+
* const session = new livewire.AgentSession();
|
|
160
|
+
* await session.start({ agent });
|
|
161
|
+
* ```
|
|
162
|
+
*/
|
|
121
163
|
export class Agent<UserData = any> {
|
|
164
|
+
/** System instructions passed through to the SignalWire AI prompt. */
|
|
122
165
|
instructions: string;
|
|
166
|
+
/** Registered tools keyed by name. Mutated by {@link updateTools}. */
|
|
123
167
|
tools: Record<string, FunctionTool>;
|
|
168
|
+
/** Arbitrary per-session user data passed to tool handlers via {@link RunContext.userData}. */
|
|
124
169
|
userData?: UserData;
|
|
125
170
|
|
|
126
171
|
/** @internal Pipeline hint stored for AgentSession mapping. */
|
|
@@ -206,6 +251,7 @@ export class Agent<UserData = any> {
|
|
|
206
251
|
// session property
|
|
207
252
|
// ------------------------------------------------------------------
|
|
208
253
|
|
|
254
|
+
/** The currently-bound {@link AgentSession}, or `undefined` until {@link AgentSession.start} is called. */
|
|
209
255
|
get session(): AgentSession<UserData> | undefined {
|
|
210
256
|
return this._session;
|
|
211
257
|
}
|
|
@@ -218,20 +264,39 @@ export class Agent<UserData = any> {
|
|
|
218
264
|
// Lifecycle hooks (override in subclass)
|
|
219
265
|
// ------------------------------------------------------------------
|
|
220
266
|
|
|
221
|
-
/**
|
|
267
|
+
/**
|
|
268
|
+
* Lifecycle hook called when the agent enters an active call.
|
|
269
|
+
* Override in a subclass to run setup logic — the default is a no-op.
|
|
270
|
+
*/
|
|
222
271
|
async onEnter(): Promise<void> {}
|
|
223
272
|
|
|
224
|
-
/**
|
|
273
|
+
/**
|
|
274
|
+
* Lifecycle hook called when the agent exits (call ended or handoff).
|
|
275
|
+
* Override in a subclass to run teardown logic — the default is a no-op.
|
|
276
|
+
*/
|
|
225
277
|
async onExit(): Promise<void> {}
|
|
226
278
|
|
|
227
|
-
/**
|
|
279
|
+
/**
|
|
280
|
+
* Lifecycle hook called when the user finishes speaking.
|
|
281
|
+
* Override in a subclass to inspect / mutate the turn context before the
|
|
282
|
+
* LLM responds — the default is a no-op.
|
|
283
|
+
*
|
|
284
|
+
* @param _turnCtx - Turn context (LiveKit shape; passed through opaquely).
|
|
285
|
+
* @param _newMessage - Newly-captured user message.
|
|
286
|
+
*/
|
|
228
287
|
async onUserTurnCompleted(_turnCtx?: unknown, _newMessage?: unknown): Promise<void> {}
|
|
229
288
|
|
|
230
289
|
// ------------------------------------------------------------------
|
|
231
290
|
// Pipeline nodes -- all noop + log (SignalWire handles these)
|
|
232
291
|
// ------------------------------------------------------------------
|
|
233
292
|
|
|
234
|
-
/**
|
|
293
|
+
/**
|
|
294
|
+
* LiveKit-compatible STT node. **No-op** on SignalWire — the control plane
|
|
295
|
+
* handles speech recognition server-side.
|
|
296
|
+
*
|
|
297
|
+
* @param _audio - Audio input (ignored).
|
|
298
|
+
* @param _modelSettings - Model settings (ignored).
|
|
299
|
+
*/
|
|
235
300
|
async sttNode(_audio?: unknown, _modelSettings?: unknown): Promise<void> {
|
|
236
301
|
globalNoop.once(
|
|
237
302
|
'stt_node',
|
|
@@ -239,7 +304,14 @@ export class Agent<UserData = any> {
|
|
|
239
304
|
);
|
|
240
305
|
}
|
|
241
306
|
|
|
242
|
-
/**
|
|
307
|
+
/**
|
|
308
|
+
* LiveKit-compatible LLM node. **No-op** on SignalWire — the control plane
|
|
309
|
+
* handles LLM inference server-side.
|
|
310
|
+
*
|
|
311
|
+
* @param _chatCtx - Chat context (ignored).
|
|
312
|
+
* @param _tools - Tool list (ignored).
|
|
313
|
+
* @param _modelSettings - Model settings (ignored).
|
|
314
|
+
*/
|
|
243
315
|
async llmNode(_chatCtx?: unknown, _tools?: unknown, _modelSettings?: unknown): Promise<void> {
|
|
244
316
|
globalNoop.once(
|
|
245
317
|
'llm_node',
|
|
@@ -247,7 +319,13 @@ export class Agent<UserData = any> {
|
|
|
247
319
|
);
|
|
248
320
|
}
|
|
249
321
|
|
|
250
|
-
/**
|
|
322
|
+
/**
|
|
323
|
+
* LiveKit-compatible TTS node. **No-op** on SignalWire — the control plane
|
|
324
|
+
* handles text-to-speech server-side.
|
|
325
|
+
*
|
|
326
|
+
* @param _text - Text to synthesise (ignored).
|
|
327
|
+
* @param _modelSettings - Model settings (ignored).
|
|
328
|
+
*/
|
|
251
329
|
async ttsNode(_text?: unknown, _modelSettings?: unknown): Promise<void> {
|
|
252
330
|
globalNoop.once(
|
|
253
331
|
'tts_node',
|
|
@@ -259,12 +337,25 @@ export class Agent<UserData = any> {
|
|
|
259
337
|
// Dynamic updates
|
|
260
338
|
// ------------------------------------------------------------------
|
|
261
339
|
|
|
262
|
-
/**
|
|
340
|
+
/**
|
|
341
|
+
* Update the agent's instructions mid-session.
|
|
342
|
+
*
|
|
343
|
+
* @param instructions - New system-instructions string for the agent.
|
|
344
|
+
*/
|
|
263
345
|
async updateInstructions(instructions: string): Promise<void> {
|
|
264
346
|
this.instructions = instructions;
|
|
265
347
|
}
|
|
266
348
|
|
|
267
|
-
/**
|
|
349
|
+
/**
|
|
350
|
+
* Update the agent's tool list mid-session.
|
|
351
|
+
*
|
|
352
|
+
* Replaces the current tool record with one built from the given array,
|
|
353
|
+
* keyed by `tool.name`. Useful for dynamic tool injection based on
|
|
354
|
+
* conversation state.
|
|
355
|
+
*
|
|
356
|
+
* @param tools - Ordered array of {@link FunctionTool} definitions. Each
|
|
357
|
+
* tool's `name` is used as its map key.
|
|
358
|
+
*/
|
|
268
359
|
async updateTools(tools: FunctionTool[]): Promise<void> {
|
|
269
360
|
const record: Record<string, FunctionTool> = {};
|
|
270
361
|
for (const t of tools) {
|
|
@@ -278,12 +369,24 @@ export class Agent<UserData = any> {
|
|
|
278
369
|
// RunContext
|
|
279
370
|
// ---------------------------------------------------------------------------
|
|
280
371
|
|
|
281
|
-
/**
|
|
372
|
+
/**
|
|
373
|
+
* Mirrors a LiveKit `RunContext` — passed to tool handlers so they can
|
|
374
|
+
* read the current session, call handle, and user data.
|
|
375
|
+
*/
|
|
282
376
|
export class RunContext<UserData = any> {
|
|
377
|
+
/** The owning {@link AgentSession}, when one is bound. */
|
|
283
378
|
session?: AgentSession<UserData>;
|
|
379
|
+
/** Opaque speech-turn handle (LiveKit shape; passed through untouched). */
|
|
284
380
|
speechHandle?: unknown;
|
|
381
|
+
/** Opaque function-call descriptor (LiveKit shape; passed through untouched). */
|
|
285
382
|
functionCall?: unknown;
|
|
286
383
|
|
|
384
|
+
/**
|
|
385
|
+
* @param session - Owning session, when available.
|
|
386
|
+
* @param options - Optional pass-through values.
|
|
387
|
+
* @param options.speechHandle - Opaque LiveKit speech handle.
|
|
388
|
+
* @param options.functionCall - Opaque LiveKit function-call descriptor.
|
|
389
|
+
*/
|
|
287
390
|
constructor(
|
|
288
391
|
session?: AgentSession<UserData>,
|
|
289
392
|
options?: { speechHandle?: unknown; functionCall?: unknown },
|
|
@@ -293,6 +396,11 @@ export class RunContext<UserData = any> {
|
|
|
293
396
|
this.functionCall = options?.functionCall;
|
|
294
397
|
}
|
|
295
398
|
|
|
399
|
+
/**
|
|
400
|
+
* Per-session user data, or an empty object when no session is bound.
|
|
401
|
+
*
|
|
402
|
+
* @returns The {@link AgentSession.userData} payload cast to `UserData`.
|
|
403
|
+
*/
|
|
296
404
|
get userData(): UserData {
|
|
297
405
|
return (this.session?.userData ?? {}) as UserData;
|
|
298
406
|
}
|
|
@@ -302,7 +410,13 @@ export class RunContext<UserData = any> {
|
|
|
302
410
|
// AgentSession
|
|
303
411
|
// ---------------------------------------------------------------------------
|
|
304
412
|
|
|
305
|
-
/**
|
|
413
|
+
/**
|
|
414
|
+
* Mirrors a LiveKit `AgentSession` — binds an {@link Agent} to SignalWire.
|
|
415
|
+
*
|
|
416
|
+
* Call {@link AgentSession.start} with an `Agent` to construct an internal
|
|
417
|
+
* {@link AgentBase} and begin serving SWML. Pipeline-related options are
|
|
418
|
+
* accepted for API parity but are no-ops server-side.
|
|
419
|
+
*/
|
|
306
420
|
export class AgentSession<UserData = any> {
|
|
307
421
|
private _llm: any;
|
|
308
422
|
private _tools: FunctionTool[];
|
|
@@ -383,7 +497,20 @@ export class AgentSession<UserData = any> {
|
|
|
383
497
|
}
|
|
384
498
|
}
|
|
385
499
|
|
|
386
|
-
/**
|
|
500
|
+
/**
|
|
501
|
+
* Start the session by binding the agent to a freshly-constructed
|
|
502
|
+
* {@link AgentBase}, mapping LiveKit-style options onto SignalWire AI params.
|
|
503
|
+
*
|
|
504
|
+
* Must be called before any other method on this session. The underlying
|
|
505
|
+
* `AgentBase` is not started here — use {@link runApp} or an `AgentServer`
|
|
506
|
+
* to serve it.
|
|
507
|
+
*
|
|
508
|
+
* @param params - Start parameters.
|
|
509
|
+
* @param params.agent - The {@link Agent} to bind.
|
|
510
|
+
* @param params.room - LiveKit room placeholder; ignored on SignalWire.
|
|
511
|
+
* @param params.record - Call-recording flag placeholder; ignored on SignalWire.
|
|
512
|
+
* @returns Resolves once the underlying `AgentBase` has been built.
|
|
513
|
+
*/
|
|
387
514
|
async start(params: { agent: Agent<UserData>; room?: any; record?: boolean }): Promise<void> {
|
|
388
515
|
this._agent = params.agent;
|
|
389
516
|
params.agent.session = this;
|
|
@@ -463,7 +590,15 @@ export class AgentSession<UserData = any> {
|
|
|
463
590
|
this._swAgent = swAgent;
|
|
464
591
|
}
|
|
465
592
|
|
|
466
|
-
/**
|
|
593
|
+
/**
|
|
594
|
+
* Queue text to be spoken by the agent.
|
|
595
|
+
*
|
|
596
|
+
* Before {@link start} is called, text is buffered and injected at start
|
|
597
|
+
* time as the agent's initial greeting. After start, text is added as an
|
|
598
|
+
* additional prompt section.
|
|
599
|
+
*
|
|
600
|
+
* @param text - Line for the agent to speak.
|
|
601
|
+
*/
|
|
467
602
|
say(text: string): void {
|
|
468
603
|
// If the session is already started, inject directly into the SWML flow.
|
|
469
604
|
// Otherwise queue the text so it is replayed when start() is called.
|
|
@@ -474,19 +609,35 @@ export class AgentSession<UserData = any> {
|
|
|
474
609
|
}
|
|
475
610
|
}
|
|
476
611
|
|
|
477
|
-
/**
|
|
612
|
+
/**
|
|
613
|
+
* Trigger the agent to generate a reply, optionally with extra instructions.
|
|
614
|
+
*
|
|
615
|
+
* @param options - Generation options.
|
|
616
|
+
* @param options.instructions - Extra instructions injected as a new prompt
|
|
617
|
+
* section before the next LLM turn.
|
|
618
|
+
*/
|
|
478
619
|
generateReply(options?: { instructions?: string }): void {
|
|
479
620
|
if (options?.instructions && this._swAgent) {
|
|
480
621
|
this._swAgent.promptAddSection('Initial Greeting', { body: options.instructions });
|
|
481
622
|
}
|
|
482
623
|
}
|
|
483
624
|
|
|
484
|
-
/**
|
|
625
|
+
/**
|
|
626
|
+
* Interrupt current speech. **No-op** on SignalWire — barge-in is handled
|
|
627
|
+
* automatically by the control plane.
|
|
628
|
+
*/
|
|
485
629
|
interrupt(): void {
|
|
486
630
|
this.noop.once('interrupt', "Interrupt(): SignalWire handles barge-in automatically via its control plane");
|
|
487
631
|
}
|
|
488
632
|
|
|
489
|
-
/**
|
|
633
|
+
/**
|
|
634
|
+
* Swap the {@link Agent} bound to this session.
|
|
635
|
+
*
|
|
636
|
+
* Preserves the underlying `AgentBase` but replaces its prompt with the new
|
|
637
|
+
* agent's instructions.
|
|
638
|
+
*
|
|
639
|
+
* @param agent - Replacement agent.
|
|
640
|
+
*/
|
|
490
641
|
updateAgent(agent: Agent<UserData>): void {
|
|
491
642
|
this._agent = agent;
|
|
492
643
|
agent.session = this;
|
|
@@ -495,6 +646,7 @@ export class AgentSession<UserData = any> {
|
|
|
495
646
|
}
|
|
496
647
|
}
|
|
497
648
|
|
|
649
|
+
/** Current per-session user data. Set by the constructor or via the setter. */
|
|
498
650
|
get userData(): UserData {
|
|
499
651
|
return this._userData;
|
|
500
652
|
}
|
|
@@ -503,12 +655,17 @@ export class AgentSession<UserData = any> {
|
|
|
503
655
|
this._userData = val;
|
|
504
656
|
}
|
|
505
657
|
|
|
506
|
-
/** Conversation history entries. */
|
|
658
|
+
/** Conversation history entries captured over the session's lifetime. */
|
|
507
659
|
get history(): Array<Record<string, string>> {
|
|
508
660
|
return this._history;
|
|
509
661
|
}
|
|
510
662
|
|
|
511
|
-
/**
|
|
663
|
+
/**
|
|
664
|
+
* Return the underlying SignalWire {@link AgentBase}. Useful for tests and
|
|
665
|
+
* advanced use cases that need to reach past the LiveKit facade.
|
|
666
|
+
*
|
|
667
|
+
* @returns The wrapped `AgentBase`, or `undefined` before {@link start}.
|
|
668
|
+
*/
|
|
512
669
|
getSwAgent(): AgentBase | undefined {
|
|
513
670
|
return this._swAgent;
|
|
514
671
|
}
|
|
@@ -519,9 +676,17 @@ export class AgentSession<UserData = any> {
|
|
|
519
676
|
// ---------------------------------------------------------------------------
|
|
520
677
|
|
|
521
678
|
/**
|
|
522
|
-
* Create a tool definition
|
|
523
|
-
*
|
|
524
|
-
*
|
|
679
|
+
* Create a tool definition — mirrors `llm.tool()` from `@livekit/agents-js`.
|
|
680
|
+
*
|
|
681
|
+
* The returned tool has an empty `name` — the caller assigns it when the tool
|
|
682
|
+
* is attached to an agent's tools map (see the {@link Agent} example).
|
|
683
|
+
*
|
|
684
|
+
* @typeParam P - Parameter type passed into `execute`.
|
|
685
|
+
* @param options - Tool configuration.
|
|
686
|
+
* @param options.description - Human-readable tool description exposed to the LLM.
|
|
687
|
+
* @param options.parameters - JSON Schema or Zod schema describing the tool's inputs.
|
|
688
|
+
* @param options.execute - Handler invoked when the LLM calls the tool.
|
|
689
|
+
* @returns A {@link FunctionTool} ready to be attached to an agent.
|
|
525
690
|
*/
|
|
526
691
|
export function tool<P = any>(options: {
|
|
527
692
|
description: string;
|
|
@@ -552,7 +717,15 @@ export function tool<P = any>(options: {
|
|
|
552
717
|
// handoff()
|
|
553
718
|
// ---------------------------------------------------------------------------
|
|
554
719
|
|
|
555
|
-
/**
|
|
720
|
+
/**
|
|
721
|
+
* Create an {@link AgentHandoff} descriptor for multi-agent scenarios.
|
|
722
|
+
*
|
|
723
|
+
* @param options - Handoff parameters.
|
|
724
|
+
* @param options.agent - Agent to transfer control to.
|
|
725
|
+
* @param options.returns - Optional string returned to the current agent when
|
|
726
|
+
* the handoff completes.
|
|
727
|
+
* @returns A handoff descriptor that can be returned from a tool handler.
|
|
728
|
+
*/
|
|
556
729
|
export function handoff(options: { agent: Agent; returns?: string }): AgentHandoff {
|
|
557
730
|
const h = new AgentHandoff();
|
|
558
731
|
h.agent = options.agent;
|
|
@@ -566,12 +739,17 @@ export function handoff(options: { agent: Agent; returns?: string }): AgentHando
|
|
|
566
739
|
|
|
567
740
|
/** Signals a handoff to another agent in multi-agent scenarios. */
|
|
568
741
|
export class AgentHandoff {
|
|
742
|
+
/** Target agent that should take over the conversation. */
|
|
569
743
|
agent!: Agent;
|
|
744
|
+
/** Optional return value surfaced when the handoff completes. */
|
|
570
745
|
returns?: string;
|
|
571
746
|
}
|
|
572
747
|
|
|
573
748
|
/** Signals that a tool should not trigger another LLM reply. */
|
|
574
749
|
export class StopResponse extends Error {
|
|
750
|
+
/**
|
|
751
|
+
* @param message - Optional error message. Defaults to `"StopResponse"`.
|
|
752
|
+
*/
|
|
575
753
|
constructor(message?: string) {
|
|
576
754
|
super(message ?? 'StopResponse');
|
|
577
755
|
this.name = 'StopResponse';
|
|
@@ -580,6 +758,9 @@ export class StopResponse extends Error {
|
|
|
580
758
|
|
|
581
759
|
/** Error thrown from a tool to signal failure back to the LLM. */
|
|
582
760
|
export class ToolError extends Error {
|
|
761
|
+
/**
|
|
762
|
+
* @param message - Error message surfaced to the LLM.
|
|
763
|
+
*/
|
|
583
764
|
constructor(message: string) {
|
|
584
765
|
super(message);
|
|
585
766
|
this.name = 'ToolError';
|
|
@@ -590,8 +771,14 @@ export class ToolError extends Error {
|
|
|
590
771
|
// JobProcess
|
|
591
772
|
// ---------------------------------------------------------------------------
|
|
592
773
|
|
|
593
|
-
/**
|
|
774
|
+
/**
|
|
775
|
+
* Mirrors a LiveKit `JobProcess` — placeholder for prewarm / setup hooks.
|
|
776
|
+
*
|
|
777
|
+
* On SignalWire the control plane pre-warms infrastructure at scale, so this
|
|
778
|
+
* class carries no real state beyond the LiveKit-compatible `userData` bag.
|
|
779
|
+
*/
|
|
594
780
|
export class JobProcess {
|
|
781
|
+
/** Mutable bag shared across prewarm and entry-point callbacks. */
|
|
595
782
|
userData: Record<string, any> = {};
|
|
596
783
|
}
|
|
597
784
|
|
|
@@ -599,8 +786,14 @@ export class JobProcess {
|
|
|
599
786
|
// Room
|
|
600
787
|
// ---------------------------------------------------------------------------
|
|
601
788
|
|
|
602
|
-
/**
|
|
789
|
+
/**
|
|
790
|
+
* Stub `Room` — SignalWire does not use the LiveKit room abstraction.
|
|
791
|
+
*
|
|
792
|
+
* Present purely for API parity so LiveKit-shaped code compiles; its only
|
|
793
|
+
* meaningful attribute is the constant name.
|
|
794
|
+
*/
|
|
603
795
|
export class Room {
|
|
796
|
+
/** Always `"livewire-room"` — SignalWire has no per-call room identity. */
|
|
604
797
|
readonly name: string = 'livewire-room';
|
|
605
798
|
}
|
|
606
799
|
|
|
@@ -608,9 +801,14 @@ export class Room {
|
|
|
608
801
|
// JobContext
|
|
609
802
|
// ---------------------------------------------------------------------------
|
|
610
803
|
|
|
611
|
-
/**
|
|
804
|
+
/**
|
|
805
|
+
* Mirrors a LiveKit `JobContext` — provides room and connection info to the
|
|
806
|
+
* entry-point callback registered via {@link defineAgent}.
|
|
807
|
+
*/
|
|
612
808
|
export class JobContext {
|
|
809
|
+
/** Placeholder {@link Room} (see class docs). */
|
|
613
810
|
room: Room;
|
|
811
|
+
/** Shared {@link JobProcess} instance for prewarm-to-entry data passing. */
|
|
614
812
|
proc: JobProcess;
|
|
615
813
|
/** @internal */
|
|
616
814
|
_swAgent?: AgentBase;
|
|
@@ -620,7 +818,12 @@ export class JobContext {
|
|
|
620
818
|
this.proc = new JobProcess();
|
|
621
819
|
}
|
|
622
820
|
|
|
623
|
-
/**
|
|
821
|
+
/**
|
|
822
|
+
* Connect to the platform. **No-op** on SignalWire — the control plane
|
|
823
|
+
* manages connection lifecycle automatically.
|
|
824
|
+
*
|
|
825
|
+
* @returns Resolves immediately.
|
|
826
|
+
*/
|
|
624
827
|
async connect(): Promise<void> {
|
|
625
828
|
globalNoop.once(
|
|
626
829
|
'connect',
|
|
@@ -628,7 +831,15 @@ export class JobContext {
|
|
|
628
831
|
);
|
|
629
832
|
}
|
|
630
833
|
|
|
631
|
-
/**
|
|
834
|
+
/**
|
|
835
|
+
* Wait for a participant to join. **No-op** on SignalWire — returns an
|
|
836
|
+
* immediate stub participant.
|
|
837
|
+
*
|
|
838
|
+
* @param options - Participant match options.
|
|
839
|
+
* @param options.identity - Requested identity; echoed back in the stub.
|
|
840
|
+
* Defaults to `"caller"`.
|
|
841
|
+
* @returns A stub participant `{ identity }` record.
|
|
842
|
+
*/
|
|
632
843
|
async waitForParticipant(options?: { identity?: string }): Promise<any> {
|
|
633
844
|
return { identity: options?.identity ?? 'caller' };
|
|
634
845
|
}
|
|
@@ -639,8 +850,17 @@ export class JobContext {
|
|
|
639
850
|
// ---------------------------------------------------------------------------
|
|
640
851
|
|
|
641
852
|
/**
|
|
642
|
-
* Mirrors
|
|
643
|
-
*
|
|
853
|
+
* Mirrors `@livekit/agents.defineAgent()`.
|
|
854
|
+
*
|
|
855
|
+
* Packages an entry function (plus an optional prewarm hook) for later
|
|
856
|
+
* execution by {@link runApp}. Pass-through — no side effects.
|
|
857
|
+
*
|
|
858
|
+
* @param agent - Entry and (optional) prewarm functions.
|
|
859
|
+
* @param agent.entry - Main callback invoked with a {@link JobContext} when
|
|
860
|
+
* the agent runs.
|
|
861
|
+
* @param agent.prewarm - Optional prewarm callback invoked with a
|
|
862
|
+
* {@link JobProcess} before `entry`.
|
|
863
|
+
* @returns The same record (pass-through), typed consistently.
|
|
644
864
|
*/
|
|
645
865
|
export function defineAgent(agent: {
|
|
646
866
|
entry: (ctx: JobContext) => Promise<void>;
|
|
@@ -654,14 +874,20 @@ export function defineAgent(agent: {
|
|
|
654
874
|
// ---------------------------------------------------------------------------
|
|
655
875
|
|
|
656
876
|
/**
|
|
657
|
-
* Mirrors cli.runApp() from
|
|
877
|
+
* Mirrors `cli.runApp()` from `@livekit/agents-js`.
|
|
658
878
|
*
|
|
659
879
|
* 1. Prints the LiveWire banner
|
|
660
|
-
* 2.
|
|
661
|
-
* 3. Creates a
|
|
662
|
-
* 4.
|
|
663
|
-
* 5.
|
|
664
|
-
* 6. Starts the
|
|
880
|
+
* 2. Runs the registered prewarm callback (if any) with a fresh {@link JobProcess}
|
|
881
|
+
* 3. Creates a fresh {@link JobContext}
|
|
882
|
+
* 4. Prints a random tip
|
|
883
|
+
* 5. Invokes the entry function with the context
|
|
884
|
+
* 6. Starts the underlying SignalWire `AgentBase` once the entry function
|
|
885
|
+
* binds one (via an `AgentSession.start()` call)
|
|
886
|
+
*
|
|
887
|
+
* Accepts either an object `{ entry, prewarm? }`, a bare entry function, or
|
|
888
|
+
* an {@link AgentServer} instance.
|
|
889
|
+
*
|
|
890
|
+
* @param options - Agent descriptor, entry function, or `AgentServer`.
|
|
665
891
|
*/
|
|
666
892
|
export function runApp(options: any): void {
|
|
667
893
|
printBanner();
|
|
@@ -708,13 +934,25 @@ export function runApp(options: any): void {
|
|
|
708
934
|
// WorkerOptions / ServerOptions
|
|
709
935
|
// ---------------------------------------------------------------------------
|
|
710
936
|
|
|
711
|
-
/**
|
|
937
|
+
/**
|
|
938
|
+
* Stub class mirroring LiveKit's `WorkerOptions`.
|
|
939
|
+
*
|
|
940
|
+
* Accepts any configuration for source-compatibility with LiveKit code;
|
|
941
|
+
* SignalWire ignores these settings.
|
|
942
|
+
*/
|
|
712
943
|
export class WorkerOptions {
|
|
944
|
+
/** @param _opts - LiveKit-shaped worker options (ignored). */
|
|
713
945
|
constructor(_opts?: any) {}
|
|
714
946
|
}
|
|
715
947
|
|
|
716
|
-
/**
|
|
948
|
+
/**
|
|
949
|
+
* Stub class mirroring LiveKit's `ServerOptions`.
|
|
950
|
+
*
|
|
951
|
+
* Accepts any configuration for source-compatibility with LiveKit code;
|
|
952
|
+
* SignalWire ignores these settings.
|
|
953
|
+
*/
|
|
717
954
|
export class ServerOptions {
|
|
955
|
+
/** @param _opts - LiveKit-shaped server options (ignored). */
|
|
718
956
|
constructor(_opts?: any) {}
|
|
719
957
|
}
|
|
720
958
|
|
|
@@ -823,9 +1061,17 @@ export class AgentServer {
|
|
|
823
1061
|
// Plugin stubs
|
|
824
1062
|
// ---------------------------------------------------------------------------
|
|
825
1063
|
|
|
826
|
-
/**
|
|
1064
|
+
/**
|
|
1065
|
+
* Stub providers matching common LiveKit plugin packages.
|
|
1066
|
+
*
|
|
1067
|
+
* None of these do anything — they exist so LiveKit code that imports and
|
|
1068
|
+
* constructs these classes still compiles and runs under SignalWire. The
|
|
1069
|
+
* first construction of each logs an advisory to stderr.
|
|
1070
|
+
*/
|
|
827
1071
|
export namespace plugins {
|
|
1072
|
+
/** LiveKit Deepgram-STT plugin stub. No-op on SignalWire. */
|
|
828
1073
|
export class DeepgramSTT {
|
|
1074
|
+
/** @param _opts - Deepgram options (ignored). */
|
|
829
1075
|
constructor(_opts?: any) {
|
|
830
1076
|
globalNoop.once(
|
|
831
1077
|
'stt_plugin',
|
|
@@ -834,8 +1080,16 @@ export namespace plugins {
|
|
|
834
1080
|
}
|
|
835
1081
|
}
|
|
836
1082
|
|
|
1083
|
+
/**
|
|
1084
|
+
* LiveKit OpenAI-LLM plugin stub.
|
|
1085
|
+
*
|
|
1086
|
+
* The `model` string is captured and mapped to the SignalWire AI `model`
|
|
1087
|
+
* param by {@link AgentSession.start}. Other options are ignored.
|
|
1088
|
+
*/
|
|
837
1089
|
export class OpenAILLM {
|
|
1090
|
+
/** Model identifier captured from the constructor options. */
|
|
838
1091
|
model: string;
|
|
1092
|
+
/** @param _opts - OpenAI options. `_opts.model` is captured; everything else ignored. */
|
|
839
1093
|
constructor(_opts?: any) {
|
|
840
1094
|
this.model = ((_opts as any)?.model as string) ?? '';
|
|
841
1095
|
globalNoop.once(
|
|
@@ -845,7 +1099,9 @@ export namespace plugins {
|
|
|
845
1099
|
}
|
|
846
1100
|
}
|
|
847
1101
|
|
|
1102
|
+
/** LiveKit Cartesia-TTS plugin stub. No-op on SignalWire. */
|
|
848
1103
|
export class CartesiaTTS {
|
|
1104
|
+
/** @param _opts - Cartesia options (ignored). */
|
|
849
1105
|
constructor(_opts?: any) {
|
|
850
1106
|
globalNoop.once(
|
|
851
1107
|
'cartesia_tts',
|
|
@@ -854,7 +1110,9 @@ export namespace plugins {
|
|
|
854
1110
|
}
|
|
855
1111
|
}
|
|
856
1112
|
|
|
1113
|
+
/** LiveKit ElevenLabs-TTS plugin stub. No-op on SignalWire. */
|
|
857
1114
|
export class ElevenLabsTTS {
|
|
1115
|
+
/** @param _opts - ElevenLabs options (ignored). */
|
|
858
1116
|
constructor(_opts?: any) {
|
|
859
1117
|
globalNoop.once(
|
|
860
1118
|
'elevenlabs_tts',
|
|
@@ -863,9 +1121,19 @@ export namespace plugins {
|
|
|
863
1121
|
}
|
|
864
1122
|
}
|
|
865
1123
|
|
|
1124
|
+
/** LiveKit Silero-VAD plugin stub. No-op on SignalWire. */
|
|
866
1125
|
export class SileroVAD {
|
|
1126
|
+
/** @param _opts - Silero VAD options (ignored). */
|
|
867
1127
|
constructor(_opts?: Record<string, unknown>) {}
|
|
868
1128
|
|
|
1129
|
+
/**
|
|
1130
|
+
* Load a Silero VAD model.
|
|
1131
|
+
*
|
|
1132
|
+
* **No-op** on SignalWire — returns a fresh stub instance and emits a
|
|
1133
|
+
* one-time advisory to stderr.
|
|
1134
|
+
*
|
|
1135
|
+
* @returns A new `SileroVAD` stub.
|
|
1136
|
+
*/
|
|
869
1137
|
static load(): SileroVAD {
|
|
870
1138
|
globalNoop.once(
|
|
871
1139
|
'vad_plugin',
|
|
@@ -880,10 +1148,22 @@ export namespace plugins {
|
|
|
880
1148
|
// Inference module stubs
|
|
881
1149
|
// ---------------------------------------------------------------------------
|
|
882
1150
|
|
|
883
|
-
/**
|
|
1151
|
+
/**
|
|
1152
|
+
* Stub inference types matching LiveKit's `inference` namespace.
|
|
1153
|
+
*
|
|
1154
|
+
* None of these run inference on the client — SignalWire performs STT / LLM /
|
|
1155
|
+
* TTS in its control plane. These classes exist so LiveKit code that imports
|
|
1156
|
+
* and instantiates them still compiles.
|
|
1157
|
+
*/
|
|
884
1158
|
export namespace inference {
|
|
1159
|
+
/** LiveKit inference-STT stub. Captures the model name; runs no inference locally. */
|
|
885
1160
|
export class STT {
|
|
1161
|
+
/** Model identifier captured from the constructor. */
|
|
886
1162
|
model: string;
|
|
1163
|
+
/**
|
|
1164
|
+
* @param model - Model identifier (captured).
|
|
1165
|
+
* @param _opts - Additional options (ignored).
|
|
1166
|
+
*/
|
|
887
1167
|
constructor(model: string = '', _opts?: any) {
|
|
888
1168
|
this.model = model;
|
|
889
1169
|
globalNoop.once(
|
|
@@ -893,15 +1173,27 @@ export namespace inference {
|
|
|
893
1173
|
}
|
|
894
1174
|
}
|
|
895
1175
|
|
|
1176
|
+
/** LiveKit inference-LLM stub. Captures the model name; runs no inference locally. */
|
|
896
1177
|
export class LLM {
|
|
1178
|
+
/** Model identifier captured from the constructor. */
|
|
897
1179
|
model: string;
|
|
1180
|
+
/**
|
|
1181
|
+
* @param model - Model identifier (captured).
|
|
1182
|
+
* @param _opts - Additional options (ignored).
|
|
1183
|
+
*/
|
|
898
1184
|
constructor(model: string = '', _opts?: any) {
|
|
899
1185
|
this.model = model;
|
|
900
1186
|
}
|
|
901
1187
|
}
|
|
902
1188
|
|
|
1189
|
+
/** LiveKit inference-TTS stub. Captures the model name; runs no inference locally. */
|
|
903
1190
|
export class TTS {
|
|
1191
|
+
/** Model identifier captured from the constructor. */
|
|
904
1192
|
model: string;
|
|
1193
|
+
/**
|
|
1194
|
+
* @param model - Model identifier (captured).
|
|
1195
|
+
* @param _opts - Additional options (ignored).
|
|
1196
|
+
*/
|
|
905
1197
|
constructor(model: string = '', _opts?: any) {
|
|
906
1198
|
this.model = model;
|
|
907
1199
|
globalNoop.once(
|
|
@@ -923,10 +1215,20 @@ export const voice = {
|
|
|
923
1215
|
AgentSessionEventTypes: {} as Record<string, string>,
|
|
924
1216
|
};
|
|
925
1217
|
|
|
926
|
-
/** Minimal ChatContext matching
|
|
1218
|
+
/** Minimal `ChatContext` matching LiveKit's `ChatContext`. */
|
|
927
1219
|
export class ChatContext {
|
|
1220
|
+
/** Ordered chat messages, each `{ role, content }`. */
|
|
928
1221
|
messages: Array<Record<string, string>> = [];
|
|
929
1222
|
|
|
1223
|
+
/**
|
|
1224
|
+
* Append a chat message.
|
|
1225
|
+
*
|
|
1226
|
+
* @param options - Message content.
|
|
1227
|
+
* @param options.role - Speaker role (`"user"`, `"assistant"`, or `"system"`).
|
|
1228
|
+
* Defaults to `"user"`.
|
|
1229
|
+
* @param options.text - Message text. Defaults to `""`.
|
|
1230
|
+
* @returns This instance for chaining.
|
|
1231
|
+
*/
|
|
930
1232
|
append(options: { role?: string; text?: string }): this {
|
|
931
1233
|
this.messages.push({ role: options.role ?? 'user', content: options.text ?? '' });
|
|
932
1234
|
return this;
|