@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.
Files changed (75) hide show
  1. package/package.json +1 -1
  2. package/src/AgentBase.ts +113 -4
  3. package/src/AgentServer.ts +31 -4
  4. package/src/ContextBuilder.ts +33 -2
  5. package/src/DataMap.ts +30 -2
  6. package/src/FunctionResult.ts +40 -3
  7. package/src/PomBuilder.ts +29 -1
  8. package/src/SWMLService.ts +38 -6
  9. package/src/ServerlessAdapter.ts +20 -1
  10. package/src/SwmlBuilder.ts +26 -1
  11. package/src/TypeInference.ts +27 -9
  12. package/src/WebService.ts +27 -5
  13. package/src/index.ts +73 -7
  14. package/src/livewire/index.ts +343 -41
  15. package/src/prefabs/ConciergeAgent.ts +22 -0
  16. package/src/prefabs/FAQBotAgent.ts +32 -1
  17. package/src/prefabs/InfoGathererAgent.ts +41 -1
  18. package/src/prefabs/ReceptionistAgent.ts +30 -1
  19. package/src/prefabs/SurveyAgent.ts +26 -1
  20. package/src/relay/Action.ts +174 -6
  21. package/src/relay/Call.ts +459 -43
  22. package/src/relay/Deferred.ts +27 -4
  23. package/src/relay/Message.ts +54 -3
  24. package/src/relay/RelayClient.ts +167 -18
  25. package/src/relay/RelayError.ts +7 -1
  26. package/src/relay/RelayEvent.ts +52 -0
  27. package/src/rest/HttpClient.ts +61 -0
  28. package/src/rest/RestError.ts +14 -0
  29. package/src/rest/base/BaseResource.ts +16 -3
  30. package/src/rest/base/CrudResource.ts +52 -5
  31. package/src/rest/base/CrudWithAddresses.ts +12 -1
  32. package/src/rest/index.ts +30 -0
  33. package/src/rest/namespaces/addresses.ts +33 -1
  34. package/src/rest/namespaces/calling.ts +348 -1
  35. package/src/rest/namespaces/chat.ts +13 -2
  36. package/src/rest/namespaces/compat.ts +469 -9
  37. package/src/rest/namespaces/datasphere.ts +48 -5
  38. package/src/rest/namespaces/fabric.ts +197 -2
  39. package/src/rest/namespaces/imported-numbers.ts +13 -2
  40. package/src/rest/namespaces/logs.ts +68 -1
  41. package/src/rest/namespaces/lookup.ts +19 -2
  42. package/src/rest/namespaces/mfa.ts +35 -4
  43. package/src/rest/namespaces/number-groups.ts +35 -5
  44. package/src/rest/namespaces/phone-numbers.ts +35 -3
  45. package/src/rest/namespaces/project.ts +30 -1
  46. package/src/rest/namespaces/pubsub.ts +13 -2
  47. package/src/rest/namespaces/queues.ts +29 -4
  48. package/src/rest/namespaces/recordings.ts +26 -1
  49. package/src/rest/namespaces/registry.ts +100 -1
  50. package/src/rest/namespaces/short-codes.ts +27 -1
  51. package/src/rest/namespaces/sip-profile.ts +18 -3
  52. package/src/rest/namespaces/verified-callers.ts +22 -3
  53. package/src/rest/namespaces/video.ts +168 -1
  54. package/src/rest/pagination.ts +22 -8
  55. package/src/skills/SkillBase.ts +37 -2
  56. package/src/skills/SkillManager.ts +8 -4
  57. package/src/skills/builtin/api_ninjas_trivia.ts +5 -0
  58. package/src/skills/builtin/ask_claude.ts +5 -0
  59. package/src/skills/builtin/claude_skills.ts +5 -0
  60. package/src/skills/builtin/custom_skills.ts +15 -0
  61. package/src/skills/builtin/datasphere.ts +9 -0
  62. package/src/skills/builtin/datasphere_serverless.ts +8 -0
  63. package/src/skills/builtin/datetime.ts +7 -0
  64. package/src/skills/builtin/google_maps.ts +5 -0
  65. package/src/skills/builtin/info_gatherer.ts +10 -0
  66. package/src/skills/builtin/joke.ts +5 -0
  67. package/src/skills/builtin/math.ts +7 -0
  68. package/src/skills/builtin/mcp_gateway.ts +8 -0
  69. package/src/skills/builtin/native_vector_search.ts +9 -0
  70. package/src/skills/builtin/play_background_file.ts +9 -0
  71. package/src/skills/builtin/spider.ts +5 -0
  72. package/src/skills/builtin/swml_transfer.ts +10 -0
  73. package/src/skills/builtin/weather_api.ts +7 -0
  74. package/src/skills/builtin/web_search.ts +9 -0
  75. package/src/skills/builtin/wikipedia_search.ts +5 -0
@@ -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
- /** Mirrors a LiveKit voice.Agent -- holds instructions and tool definitions. */
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
- /** Called when the agent enters. Override in subclass. */
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
- /** Called when the agent exits. Override in subclass. */
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
- /** Called when the user finishes speaking. Override in subclass. */
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
- /** Noop -- SignalWire handles STT in its control plane. */
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
- /** Noop -- SignalWire handles LLM in its control plane. */
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
- /** Noop -- SignalWire handles TTS in its control plane. */
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
- /** Update the agent's instructions mid-session. */
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
- /** Update the agent's tool list mid-session. */
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
- /** Mirrors a LiveKit RunContext -- available inside tool handlers. */
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
- /** Mirrors a LiveKit AgentSession -- binds an Agent to SignalWire. */
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
- /** Start the session by binding the agent to a SignalWire AgentBase. */
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
- /** Queue text to be spoken by the agent. */
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
- /** Trigger the agent to generate a reply, optionally with extra instructions. */
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
- /** Interrupt current speech -- noop on SignalWire (barge-in is automatic). */
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
- /** Update the agent bound to this session. */
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
- /** Return the underlying SignalWire AgentBase (for testing / advanced use). */
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 -- mirrors llm.tool() from @livekit/agents-js.
523
- * Accepts a description, optional parameters (Zod or JSON schema), and an
524
- * execute function.
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
- /** Create an AgentHandoff descriptor for multi-agent scenarios. */
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
- /** Mirrors a LiveKit JobProcess -- used for prewarm/setup. */
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
- /** Stub -- SignalWire doesn't use the LiveKit room abstraction. */
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
- /** Mirrors a LiveKit JobContext -- provides room and connection info. */
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
- /** Connect is a noop on SignalWire -- the platform handles connection lifecycle. */
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
- /** Wait for a participant -- noop on SignalWire. */
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 @livekit/agents defineAgent().
643
- * Wraps an entry function (and optional prewarm) for later execution by runApp.
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 @livekit/agents-js.
877
+ * Mirrors `cli.runApp()` from `@livekit/agents-js`.
658
878
  *
659
879
  * 1. Prints the LiveWire banner
660
- * 2. Prints a random tip
661
- * 3. Creates a SignalWire AgentBase from the LiveKit-style config
662
- * 4. Calls the entry function with a fake JobContext
663
- * 5. Maps tools from llm.tool() format to SignalWire defineTool format
664
- * 6. Starts the agent with agent.run()
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
- /** Stub for LiveKit WorkerOptions. */
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
- /** Stub for LiveKit ServerOptions. */
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
- /** Stub providers matching common LiveKit plugin packages. */
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
- /** Stub inference types matching LiveKit's inference namespace. */
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 livekit ChatContext. */
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;