@signalwire/sdk 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,950 @@
1
+ /**
2
+ * LiveWire -- LiveKit-compatible agents powered by SignalWire.
3
+ *
4
+ * Provides the same class/function names as @livekit/agents-js so that
5
+ * developers can swap their import path and run on SignalWire's
6
+ * infrastructure. STT, TTS, VAD, LLM orchestration, and call control
7
+ * are all handled by SignalWire's control plane -- the noop'd options
8
+ * are accepted silently (logged once) to keep existing code compiling.
9
+ */
10
+
11
+ import { AgentBase } from '../AgentBase.js';
12
+ import { FunctionResult } from '../FunctionResult.js';
13
+ import type { SwaigHandler } from '../SwaigFunction.js';
14
+
15
+ // ---------------------------------------------------------------------------
16
+ // Banner
17
+ // ---------------------------------------------------------------------------
18
+
19
+ const banner = `
20
+ __ _ _ ___
21
+ / / (_) _____ | | / (_)_______
22
+ / / / / | / / _ \\ | | /| / / / ___/ _ \\
23
+ / /___/ /| |/ / __/ | |/ |/ / / / / __/
24
+ /_____/_/ |___/\\___/ |__/|__/_/_/ \\___/
25
+
26
+ LiveKit-compatible agents powered by SignalWire
27
+ `;
28
+
29
+ /** Print the ASCII banner to stderr, using ANSI cyan when stderr is a TTY. */
30
+ function printBanner(): void {
31
+ if (process.stderr.isTTY) {
32
+ process.stderr.write(`\x1b[36m${banner}\x1b[0m\n`);
33
+ } else {
34
+ process.stderr.write(`${banner}\n`);
35
+ }
36
+ }
37
+
38
+ // ---------------------------------------------------------------------------
39
+ // "Did You Know?" Tips
40
+ // ---------------------------------------------------------------------------
41
+
42
+ export const tips: string[] = [
43
+ "SignalWire agents support DataMap tools that execute server-side — no webhook infrastructure needed. See: docs/datamap-guide.md",
44
+ "SignalWire Contexts & Steps give you mechanical state control over conversations — no prompt engineering needed. See: docs/contexts-guide.md",
45
+ "SignalWire agents can transfer calls between agents with a single SwmlTransfer() action",
46
+ "SignalWire handles 18 built-in skills (datetime, math, web search, etc.) with one-liner integration via agent.addSkill()",
47
+ "SignalWire agents support SMS, conferencing, call recording, and SIP — all from the same agent",
48
+ "Your agent's entire AI pipeline (STT, LLM, TTS, VAD) runs in SignalWire's cloud — zero infrastructure to manage",
49
+ "SignalWire prefab agents (Survey, Receptionist, FAQ, Concierge) give you production patterns in 10 lines of code",
50
+ "SignalWire's RELAY client gives you real-time WebSocket call control with 57+ methods — play, record, detect, conference, and more",
51
+ "SignalWire agents auto-generate SWML documents — the platform handles media, turn detection, and barge-in for you",
52
+ "You can host multiple agents on one server with AgentServer — each with its own route, prompt, and tools",
53
+ ];
54
+
55
+ function printTip(): void {
56
+ const tip = tips[Math.floor(Math.random() * tips.length)];
57
+ process.stderr.write(`\n\u{1f4a1} Did you know? ${tip}\n\n`);
58
+ }
59
+
60
+ // ---------------------------------------------------------------------------
61
+ // Noop logging helpers
62
+ // ---------------------------------------------------------------------------
63
+
64
+ /**
65
+ * NoopTracker ensures each informational message is logged at most once,
66
+ * preventing spam when the same noop path is exercised repeatedly.
67
+ */
68
+ class NoopTracker {
69
+ private logged = new Set<string>();
70
+
71
+ once(key: string, message: string): void {
72
+ if (this.logged.has(key)) return;
73
+ this.logged.add(key);
74
+ process.stderr.write(`[LiveWire] ${message}\n`);
75
+ }
76
+
77
+ /** Expose whether a key has been logged (for testing). */
78
+ hasLogged(key: string): boolean {
79
+ return this.logged.has(key);
80
+ }
81
+
82
+ /** Reset all tracked keys (for testing). */
83
+ reset(): void {
84
+ this.logged.clear();
85
+ }
86
+ }
87
+
88
+ const globalNoop = new NoopTracker();
89
+
90
+ // Re-export for testing
91
+ export { NoopTracker, globalNoop };
92
+
93
+ // ---------------------------------------------------------------------------
94
+ // VoiceOptions
95
+ // ---------------------------------------------------------------------------
96
+
97
+ /** Voice configuration options passed through to the SignalWire AI config. */
98
+ export interface VoiceOptions {
99
+ voice: string;
100
+ engine: string;
101
+ language: string;
102
+ }
103
+
104
+ // ---------------------------------------------------------------------------
105
+ // FunctionTool
106
+ // ---------------------------------------------------------------------------
107
+
108
+ /** A tool definition that can be registered on an Agent. */
109
+ export interface FunctionTool {
110
+ name: string;
111
+ description: string;
112
+ parameters?: Record<string, unknown>;
113
+ execute: (params: any, context: { ctx: RunContext }) => any;
114
+ }
115
+
116
+ // ---------------------------------------------------------------------------
117
+ // Agent
118
+ // ---------------------------------------------------------------------------
119
+
120
+ /** Mirrors a LiveKit voice.Agent -- holds instructions and tool definitions. */
121
+ export class Agent<UserData = any> {
122
+ instructions: string;
123
+ tools: Record<string, FunctionTool>;
124
+ userData?: UserData;
125
+
126
+ /** @internal Pipeline hint stored for AgentSession mapping. */
127
+ _llmHint: unknown;
128
+ /** @internal */
129
+ _allowInterruptions: unknown;
130
+ /** @internal */
131
+ _minEndpointingDelay: unknown;
132
+ /** @internal */
133
+ _maxEndpointingDelay: unknown;
134
+
135
+ private _session?: AgentSession<UserData>;
136
+
137
+ constructor(options?: {
138
+ instructions?: string;
139
+ tools?: FunctionTool[];
140
+ userData?: UserData;
141
+ chatCtx?: unknown;
142
+ stt?: unknown;
143
+ tts?: unknown;
144
+ llm?: unknown;
145
+ vad?: unknown;
146
+ turnDetection?: unknown;
147
+ mcpServers?: unknown;
148
+ allowInterruptions?: boolean;
149
+ minEndpointingDelay?: number;
150
+ maxEndpointingDelay?: number;
151
+ }) {
152
+ this.instructions = options?.instructions ?? '';
153
+ // Mirror Python: tools is Optional[List[Any]], stored internally as a name-keyed map.
154
+ // Build the record from the array using the same pattern as updateTools().
155
+ if (options?.tools) {
156
+ const record: Record<string, FunctionTool> = {};
157
+ for (const t of options.tools) {
158
+ record[t.name] = t;
159
+ }
160
+ this.tools = record;
161
+ } else {
162
+ this.tools = {};
163
+ }
164
+ this.userData = options?.userData;
165
+
166
+ // Pipeline noop advisories (matching Python behavior)
167
+ if (options?.stt != null) {
168
+ globalNoop.once(
169
+ 'agent_stt',
170
+ "Agent(stt=...): SignalWire's control plane handles speech recognition at scale -- no configuration needed",
171
+ );
172
+ }
173
+ if (options?.tts != null) {
174
+ globalNoop.once(
175
+ 'agent_tts',
176
+ "Agent(tts=...): SignalWire's control plane handles text-to-speech at scale -- no configuration needed",
177
+ );
178
+ }
179
+ if (options?.vad != null) {
180
+ globalNoop.once(
181
+ 'agent_vad',
182
+ "Agent(vad=...): SignalWire's control plane handles voice activity detection at scale automatically",
183
+ );
184
+ }
185
+ if (options?.turnDetection != null) {
186
+ globalNoop.once(
187
+ 'agent_turn_detection',
188
+ "Agent(turnDetection=...): SignalWire's control plane handles turn detection at scale automatically",
189
+ );
190
+ }
191
+ if (options?.mcpServers != null) {
192
+ globalNoop.once(
193
+ 'agent_mcp_servers',
194
+ 'Agent(mcpServers=...): MCP servers are not yet supported in LiveWire -- tools should be registered via tool()',
195
+ );
196
+ }
197
+
198
+ // Store pipeline hints for later mapping (used by AgentSession.start)
199
+ this._llmHint = options?.llm;
200
+ this._allowInterruptions = options?.allowInterruptions;
201
+ this._minEndpointingDelay = options?.minEndpointingDelay;
202
+ this._maxEndpointingDelay = options?.maxEndpointingDelay;
203
+ }
204
+
205
+ // ------------------------------------------------------------------
206
+ // session property
207
+ // ------------------------------------------------------------------
208
+
209
+ get session(): AgentSession<UserData> | undefined {
210
+ return this._session;
211
+ }
212
+
213
+ set session(value: AgentSession<UserData> | undefined) {
214
+ this._session = value;
215
+ }
216
+
217
+ // ------------------------------------------------------------------
218
+ // Lifecycle hooks (override in subclass)
219
+ // ------------------------------------------------------------------
220
+
221
+ /** Called when the agent enters. Override in subclass. */
222
+ async onEnter(): Promise<void> {}
223
+
224
+ /** Called when the agent exits. Override in subclass. */
225
+ async onExit(): Promise<void> {}
226
+
227
+ /** Called when the user finishes speaking. Override in subclass. */
228
+ async onUserTurnCompleted(_turnCtx?: unknown, _newMessage?: unknown): Promise<void> {}
229
+
230
+ // ------------------------------------------------------------------
231
+ // Pipeline nodes -- all noop + log (SignalWire handles these)
232
+ // ------------------------------------------------------------------
233
+
234
+ /** Noop -- SignalWire handles STT in its control plane. */
235
+ async sttNode(_audio?: unknown, _modelSettings?: unknown): Promise<void> {
236
+ globalNoop.once(
237
+ 'stt_node',
238
+ "Agent.sttNode(): SignalWire's control plane handles speech recognition -- this node is a no-op",
239
+ );
240
+ }
241
+
242
+ /** Noop -- SignalWire handles LLM in its control plane. */
243
+ async llmNode(_chatCtx?: unknown, _tools?: unknown, _modelSettings?: unknown): Promise<void> {
244
+ globalNoop.once(
245
+ 'llm_node',
246
+ "Agent.llmNode(): SignalWire's control plane handles LLM inference -- this node is a no-op",
247
+ );
248
+ }
249
+
250
+ /** Noop -- SignalWire handles TTS in its control plane. */
251
+ async ttsNode(_text?: unknown, _modelSettings?: unknown): Promise<void> {
252
+ globalNoop.once(
253
+ 'tts_node',
254
+ "Agent.ttsNode(): SignalWire's control plane handles text-to-speech -- this node is a no-op",
255
+ );
256
+ }
257
+
258
+ // ------------------------------------------------------------------
259
+ // Dynamic updates
260
+ // ------------------------------------------------------------------
261
+
262
+ /** Update the agent's instructions mid-session. */
263
+ async updateInstructions(instructions: string): Promise<void> {
264
+ this.instructions = instructions;
265
+ }
266
+
267
+ /** Update the agent's tool list mid-session. */
268
+ async updateTools(tools: FunctionTool[]): Promise<void> {
269
+ const record: Record<string, FunctionTool> = {};
270
+ for (const t of tools) {
271
+ record[t.name] = t;
272
+ }
273
+ this.tools = record;
274
+ }
275
+ }
276
+
277
+ // ---------------------------------------------------------------------------
278
+ // RunContext
279
+ // ---------------------------------------------------------------------------
280
+
281
+ /** Mirrors a LiveKit RunContext -- available inside tool handlers. */
282
+ export class RunContext<UserData = any> {
283
+ session?: AgentSession<UserData>;
284
+ speechHandle?: unknown;
285
+ functionCall?: unknown;
286
+
287
+ constructor(
288
+ session?: AgentSession<UserData>,
289
+ options?: { speechHandle?: unknown; functionCall?: unknown },
290
+ ) {
291
+ this.session = session;
292
+ this.speechHandle = options?.speechHandle;
293
+ this.functionCall = options?.functionCall;
294
+ }
295
+
296
+ get userData(): UserData {
297
+ return (this.session?.userData ?? {}) as UserData;
298
+ }
299
+ }
300
+
301
+ // ---------------------------------------------------------------------------
302
+ // AgentSession
303
+ // ---------------------------------------------------------------------------
304
+
305
+ /** Mirrors a LiveKit AgentSession -- binds an Agent to SignalWire. */
306
+ export class AgentSession<UserData = any> {
307
+ private _llm: any;
308
+ private _tools: FunctionTool[];
309
+ private _userData: UserData;
310
+ private _agent?: Agent<UserData>;
311
+ private _swAgent?: AgentBase;
312
+ private _allowInterruptions: boolean;
313
+ private _minInterruptionDuration: number;
314
+ private _minEndpointingDelay: number;
315
+ private _maxEndpointingDelay: number;
316
+ private _maxToolSteps: number;
317
+ private _preemptiveGeneration: boolean;
318
+ private _history: Array<Record<string, string>> = [];
319
+ private _sayQueue: string[] = [];
320
+ private noop = new NoopTracker();
321
+
322
+ constructor(options?: {
323
+ stt?: any;
324
+ tts?: any;
325
+ llm?: any;
326
+ vad?: any;
327
+ turnDetection?: any;
328
+ tools?: FunctionTool[];
329
+ mcpServers?: unknown;
330
+ userData?: UserData;
331
+ allowInterruptions?: boolean;
332
+ minInterruptionDuration?: number;
333
+ minEndpointingDelay?: number;
334
+ maxEndpointingDelay?: number;
335
+ maxToolSteps?: number;
336
+ preemptiveGeneration?: boolean;
337
+ }) {
338
+ this._llm = options?.llm;
339
+ this._tools = options?.tools ? [...options.tools] : [];
340
+ this._userData = (options?.userData ?? {}) as UserData;
341
+ this._allowInterruptions = options?.allowInterruptions ?? true;
342
+ this._minInterruptionDuration = options?.minInterruptionDuration ?? 0.5;
343
+ this._minEndpointingDelay = options?.minEndpointingDelay ?? 0.5;
344
+ this._maxEndpointingDelay = options?.maxEndpointingDelay ?? 3.0;
345
+ this._maxToolSteps = options?.maxToolSteps ?? 3;
346
+ this._preemptiveGeneration = options?.preemptiveGeneration ?? false;
347
+
348
+ if (options?.stt != null) {
349
+ this.noop.once(
350
+ 'stt',
351
+ `WithSTT("${options.stt}"): SignalWire's control plane handles speech recognition at scale — no configuration needed`,
352
+ );
353
+ }
354
+ if (options?.tts != null) {
355
+ this.noop.once(
356
+ 'tts',
357
+ `WithTTS("${options.tts}"): SignalWire's control plane handles text-to-speech at scale — no configuration needed`,
358
+ );
359
+ }
360
+ if (options?.vad != null) {
361
+ this.noop.once(
362
+ 'vad',
363
+ "WithVAD(): SignalWire's control plane handles voice activity detection at scale automatically",
364
+ );
365
+ }
366
+ if (options?.turnDetection != null) {
367
+ this.noop.once(
368
+ 'turn_detection',
369
+ `WithTurnDetection("${options.turnDetection}"): SignalWire's control plane handles turn detection at scale automatically`,
370
+ );
371
+ }
372
+ if (options?.mcpServers != null) {
373
+ this.noop.once(
374
+ 'mcp_servers',
375
+ 'AgentSession(mcpServers=...): MCP servers are not yet supported in LiveWire -- tools should be registered via tool()',
376
+ );
377
+ }
378
+ if (options?.maxToolSteps != null && options.maxToolSteps !== 3) {
379
+ this.noop.once(
380
+ 'max_tool_steps',
381
+ `AgentSession(maxToolSteps=${options.maxToolSteps}): SignalWire's control plane handles tool execution depth at scale automatically`,
382
+ );
383
+ }
384
+ }
385
+
386
+ /** Start the session by binding the agent to a SignalWire AgentBase. */
387
+ async start(params: { agent: Agent<UserData>; room?: any; record?: boolean }): Promise<void> {
388
+ this._agent = params.agent;
389
+ params.agent.session = this;
390
+
391
+ // Mirrors Python _build_sw_agent(): alias self._agent for subsequent reads
392
+ const agent = this._agent;
393
+
394
+ // Build a real SignalWire AgentBase
395
+ const swAgent = new AgentBase({
396
+ name: 'LiveWireAgent',
397
+ route: '/',
398
+ });
399
+
400
+ swAgent.setPromptText(agent.instructions);
401
+
402
+ // Map LLM model if provided (session-level takes priority, then agent-level hint)
403
+ const llmModel = this._llm ?? agent._llmHint;
404
+ if (llmModel != null) {
405
+ let model = String(llmModel);
406
+ const slashIdx = model.indexOf('/');
407
+ if (slashIdx >= 0) model = model.slice(slashIdx + 1);
408
+ swAgent.setParam('model', model);
409
+ }
410
+
411
+ // Map interruption / barge settings
412
+ let allowInterruptions = this._allowInterruptions;
413
+ if (agent._allowInterruptions != null) {
414
+ allowInterruptions = agent._allowInterruptions as boolean;
415
+ }
416
+ if (!allowInterruptions) {
417
+ swAgent.setParam('barge_confidence', 1.0);
418
+ }
419
+
420
+ // Map endpointing delays
421
+ let minEp: number = this._minEndpointingDelay;
422
+ if (agent._minEndpointingDelay != null) {
423
+ minEp = agent._minEndpointingDelay as number;
424
+ }
425
+ if (minEp > 0) {
426
+ swAgent.setParam('end_of_speech_timeout', Math.round(minEp * 1000));
427
+ }
428
+
429
+ let maxEp: number = this._maxEndpointingDelay;
430
+ if (agent._maxEndpointingDelay != null) {
431
+ maxEp = agent._maxEndpointingDelay as number;
432
+ }
433
+ if (maxEp > 0) {
434
+ swAgent.setParam('attention_timeout', Math.round(maxEp * 1000));
435
+ }
436
+
437
+ // Register all tools from the agent + session-level tools
438
+ const allTools: [string, FunctionTool][] = [
439
+ ...Object.entries(agent.tools),
440
+ ...this._tools.map((t) => [t.name, t] as [string, FunctionTool]),
441
+ ];
442
+ for (const [name, toolDef] of allTools) {
443
+ const handler: SwaigHandler = async (args, _rawData) => {
444
+ const ctx = new RunContext<UserData>(this);
445
+ const result = await toolDef.execute(args, { ctx });
446
+ if (result instanceof FunctionResult) return result;
447
+ if (typeof result === 'string') return new FunctionResult(result);
448
+ return new FunctionResult(JSON.stringify(result));
449
+ };
450
+ swAgent.defineTool({
451
+ name,
452
+ description: toolDef.description,
453
+ parameters: toolDef.parameters,
454
+ handler,
455
+ });
456
+ }
457
+
458
+ // Initial greeting (say queue)
459
+ for (const text of this._sayQueue) {
460
+ swAgent.promptAddSection('Initial Greeting', { body: text });
461
+ }
462
+
463
+ this._swAgent = swAgent;
464
+ }
465
+
466
+ /** Queue text to be spoken by the agent. */
467
+ say(text: string): void {
468
+ // If the session is already started, inject directly into the SWML flow.
469
+ // Otherwise queue the text so it is replayed when start() is called.
470
+ if (this._swAgent) {
471
+ this._swAgent.promptAddSection('Say', { body: text });
472
+ } else {
473
+ this._sayQueue.push(text);
474
+ }
475
+ }
476
+
477
+ /** Trigger the agent to generate a reply, optionally with extra instructions. */
478
+ generateReply(options?: { instructions?: string }): void {
479
+ if (options?.instructions && this._swAgent) {
480
+ this._swAgent.promptAddSection('Initial Greeting', { body: options.instructions });
481
+ }
482
+ }
483
+
484
+ /** Interrupt current speech -- noop on SignalWire (barge-in is automatic). */
485
+ interrupt(): void {
486
+ this.noop.once('interrupt', "Interrupt(): SignalWire handles barge-in automatically via its control plane");
487
+ }
488
+
489
+ /** Update the agent bound to this session. */
490
+ updateAgent(agent: Agent<UserData>): void {
491
+ this._agent = agent;
492
+ agent.session = this;
493
+ if (this._swAgent) {
494
+ this._swAgent.setPromptText(agent.instructions);
495
+ }
496
+ }
497
+
498
+ get userData(): UserData {
499
+ return this._userData;
500
+ }
501
+
502
+ set userData(val: UserData) {
503
+ this._userData = val;
504
+ }
505
+
506
+ /** Conversation history entries. */
507
+ get history(): Array<Record<string, string>> {
508
+ return this._history;
509
+ }
510
+
511
+ /** Return the underlying SignalWire AgentBase (for testing / advanced use). */
512
+ getSwAgent(): AgentBase | undefined {
513
+ return this._swAgent;
514
+ }
515
+ }
516
+
517
+ // ---------------------------------------------------------------------------
518
+ // tool()
519
+ // ---------------------------------------------------------------------------
520
+
521
+ /**
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.
525
+ */
526
+ export function tool<P = any>(options: {
527
+ description: string;
528
+ parameters?: any;
529
+ execute: (params: P, context: { ctx: RunContext }) => any;
530
+ }): FunctionTool {
531
+ // Extract JSON schema from parameters if provided
532
+ let jsonSchema: Record<string, unknown> | undefined;
533
+ if (options.parameters) {
534
+ // If it looks like a Zod schema (has a .shape or ._def), try to extract
535
+ if (typeof options.parameters === 'object' && options.parameters._def) {
536
+ // Best-effort Zod extraction -- store as-is for now
537
+ jsonSchema = options.parameters;
538
+ } else {
539
+ jsonSchema = options.parameters;
540
+ }
541
+ }
542
+
543
+ return {
544
+ name: '', // Filled in when assigned to agent.tools
545
+ description: options.description,
546
+ parameters: jsonSchema,
547
+ execute: options.execute,
548
+ };
549
+ }
550
+
551
+ // ---------------------------------------------------------------------------
552
+ // handoff()
553
+ // ---------------------------------------------------------------------------
554
+
555
+ /** Create an AgentHandoff descriptor for multi-agent scenarios. */
556
+ export function handoff(options: { agent: Agent; returns?: string }): AgentHandoff {
557
+ const h = new AgentHandoff();
558
+ h.agent = options.agent;
559
+ h.returns = options.returns;
560
+ return h;
561
+ }
562
+
563
+ // ---------------------------------------------------------------------------
564
+ // AgentHandoff / StopResponse / ToolError
565
+ // ---------------------------------------------------------------------------
566
+
567
+ /** Signals a handoff to another agent in multi-agent scenarios. */
568
+ export class AgentHandoff {
569
+ agent!: Agent;
570
+ returns?: string;
571
+ }
572
+
573
+ /** Signals that a tool should not trigger another LLM reply. */
574
+ export class StopResponse extends Error {
575
+ constructor(message?: string) {
576
+ super(message ?? 'StopResponse');
577
+ this.name = 'StopResponse';
578
+ }
579
+ }
580
+
581
+ /** Error thrown from a tool to signal failure back to the LLM. */
582
+ export class ToolError extends Error {
583
+ constructor(message: string) {
584
+ super(message);
585
+ this.name = 'ToolError';
586
+ }
587
+ }
588
+
589
+ // ---------------------------------------------------------------------------
590
+ // JobProcess
591
+ // ---------------------------------------------------------------------------
592
+
593
+ /** Mirrors a LiveKit JobProcess -- used for prewarm/setup. */
594
+ export class JobProcess {
595
+ userData: Record<string, any> = {};
596
+ }
597
+
598
+ // ---------------------------------------------------------------------------
599
+ // Room
600
+ // ---------------------------------------------------------------------------
601
+
602
+ /** Stub -- SignalWire doesn't use the LiveKit room abstraction. */
603
+ export class Room {
604
+ readonly name: string = 'livewire-room';
605
+ }
606
+
607
+ // ---------------------------------------------------------------------------
608
+ // JobContext
609
+ // ---------------------------------------------------------------------------
610
+
611
+ /** Mirrors a LiveKit JobContext -- provides room and connection info. */
612
+ export class JobContext {
613
+ room: Room;
614
+ proc: JobProcess;
615
+ /** @internal */
616
+ _swAgent?: AgentBase;
617
+
618
+ constructor() {
619
+ this.room = new Room();
620
+ this.proc = new JobProcess();
621
+ }
622
+
623
+ /** Connect is a noop on SignalWire -- the platform handles connection lifecycle. */
624
+ async connect(): Promise<void> {
625
+ globalNoop.once(
626
+ 'connect',
627
+ "JobContext.connect(): SignalWire's control plane handles connection lifecycle at scale automatically",
628
+ );
629
+ }
630
+
631
+ /** Wait for a participant -- noop on SignalWire. */
632
+ async waitForParticipant(options?: { identity?: string }): Promise<any> {
633
+ return { identity: options?.identity ?? 'caller' };
634
+ }
635
+ }
636
+
637
+ // ---------------------------------------------------------------------------
638
+ // defineAgent
639
+ // ---------------------------------------------------------------------------
640
+
641
+ /**
642
+ * Mirrors @livekit/agents defineAgent().
643
+ * Wraps an entry function (and optional prewarm) for later execution by runApp.
644
+ */
645
+ export function defineAgent(agent: {
646
+ entry: (ctx: JobContext) => Promise<void>;
647
+ prewarm?: (proc: JobProcess) => any;
648
+ }): { entry: (ctx: JobContext) => Promise<void>; prewarm?: (proc: JobProcess) => any } {
649
+ return agent;
650
+ }
651
+
652
+ // ---------------------------------------------------------------------------
653
+ // runApp
654
+ // ---------------------------------------------------------------------------
655
+
656
+ /**
657
+ * Mirrors cli.runApp() from @livekit/agents-js.
658
+ *
659
+ * 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()
665
+ */
666
+ export function runApp(options: any): void {
667
+ printBanner();
668
+
669
+ // If passed an AgentServer instance, convert it to an agentDef-compatible object
670
+ const agentDef = options instanceof AgentServer
671
+ ? options._toAgentDef()
672
+ : (options?.agent ?? options);
673
+
674
+ // Run prewarm if registered
675
+ if (agentDef?.prewarm) {
676
+ const proc = new JobProcess();
677
+ globalNoop.once(
678
+ 'prewarm',
679
+ "prewarm: Warm process pools not needed — SignalWire's control plane manages media infrastructure at scale",
680
+ );
681
+ agentDef.prewarm(proc);
682
+ }
683
+
684
+ // Create a JobContext
685
+ const ctx = new JobContext();
686
+
687
+ // Print a random tip
688
+ printTip();
689
+
690
+ // Call the entry function
691
+ const entryFn = agentDef?.entry ?? agentDef;
692
+ if (typeof entryFn === 'function') {
693
+ Promise.resolve(entryFn(ctx)).then(() => {
694
+ // After entry completes, the session should have bound a swAgent to ctx
695
+ // If someone stored it on ctx, start it
696
+ if (ctx._swAgent) {
697
+ ctx._swAgent.run().catch((err: Error) => {
698
+ process.stderr.write(`[LiveWire] agent error: ${err.message}\n`);
699
+ });
700
+ }
701
+ }).catch((err: Error) => {
702
+ process.stderr.write(`[LiveWire] entry function error: ${err.message}\n`);
703
+ });
704
+ }
705
+ }
706
+
707
+ // ---------------------------------------------------------------------------
708
+ // WorkerOptions / ServerOptions
709
+ // ---------------------------------------------------------------------------
710
+
711
+ /** Stub for LiveKit WorkerOptions. */
712
+ export class WorkerOptions {
713
+ constructor(_opts?: any) {}
714
+ }
715
+
716
+ /** Stub for LiveKit ServerOptions. */
717
+ export class ServerOptions {
718
+ constructor(_opts?: any) {}
719
+ }
720
+
721
+ // ---------------------------------------------------------------------------
722
+ // AgentServer
723
+ // ---------------------------------------------------------------------------
724
+
725
+ /**
726
+ * Mirrors a LiveKit AgentServer -- registers entrypoints and starts.
727
+ *
728
+ * Usage:
729
+ * const server = new AgentServer();
730
+ * server.setupFnc = async (proc) => { ... };
731
+ *
732
+ * // Bare decorator usage:
733
+ * server.rtcSession(myEntryFn);
734
+ *
735
+ * // Parameterized decorator usage:
736
+ * server.rtcSession({ agentName: 'myAgent' })(myEntryFn);
737
+ *
738
+ * cli.runApp(server);
739
+ */
740
+ export class AgentServer {
741
+ /** Optional prewarm hook called before the entrypoint. Mirrors Python's setup_fnc. */
742
+ setupFnc?: (proc: JobProcess) => void;
743
+
744
+ /** @internal Registered entrypoint function. */
745
+ private _entryFn?: (ctx: JobContext) => Promise<void>;
746
+
747
+ /** @internal Agent name hint registered via rtcSession(). */
748
+ private _agentName: string = '';
749
+
750
+ constructor(_opts?: any) {}
751
+
752
+ /**
753
+ * Decorator that registers the session entrypoint.
754
+ *
755
+ * Supports both bare and parameterized usage:
756
+ * server.rtcSession(fn) // bare
757
+ * server.rtcSession(fn, { agentName: 'x' }) // with opts, explicit fn
758
+ * server.rtcSession({ agentName: 'x' })(fn) // parameterized decorator
759
+ * @server.rtcSession // decorator (bare)
760
+ * @server.rtcSession({ agentName: 'x' }) // decorator (parameterized)
761
+ */
762
+ rtcSession(
763
+ fnOrOpts?:
764
+ | ((ctx: JobContext) => Promise<void>)
765
+ | {
766
+ agentName?: string;
767
+ type?: string;
768
+ onRequest?: ((...args: any[]) => any) | null;
769
+ onSessionEnd?: ((...args: any[]) => any) | null;
770
+ },
771
+ opts?: {
772
+ agentName?: string;
773
+ type?: string;
774
+ onRequest?: ((...args: any[]) => any) | null;
775
+ onSessionEnd?: ((...args: any[]) => any) | null;
776
+ },
777
+ ): ((fn: (ctx: JobContext) => Promise<void>) => (ctx: JobContext) => Promise<void>) | void {
778
+ // Determine whether first arg is a function or an options object
779
+ let fn: ((ctx: JobContext) => Promise<void>) | undefined;
780
+ let resolvedOpts: typeof opts;
781
+
782
+ if (typeof fnOrOpts === 'function') {
783
+ fn = fnOrOpts;
784
+ resolvedOpts = opts;
785
+ } else {
786
+ // fnOrOpts is an options object (or undefined) — parameterized decorator usage
787
+ resolvedOpts = fnOrOpts;
788
+ }
789
+
790
+ if (resolvedOpts?.type && resolvedOpts.type !== 'room') {
791
+ globalNoop.once(
792
+ 'server_type',
793
+ `AgentServer.rtcSession(type=${JSON.stringify(resolvedOpts.type)}): SignalWire's control plane handles server topology at scale automatically`,
794
+ );
795
+ }
796
+
797
+ const register = (entryFn: (ctx: JobContext) => Promise<void>) => {
798
+ this._entryFn = entryFn;
799
+ if (resolvedOpts?.agentName) this._agentName = resolvedOpts.agentName;
800
+ return entryFn;
801
+ };
802
+
803
+ if (fn) {
804
+ register(fn);
805
+ return;
806
+ }
807
+ return register;
808
+ }
809
+
810
+ /** @internal Extract agentDef-compatible shape for use by runApp. */
811
+ _toAgentDef(): {
812
+ entry: (ctx: JobContext) => Promise<void>;
813
+ prewarm?: (proc: JobProcess) => void;
814
+ } {
815
+ return {
816
+ entry: this._entryFn ?? (async (_ctx: JobContext) => {}),
817
+ prewarm: this.setupFnc,
818
+ };
819
+ }
820
+ }
821
+
822
+ // ---------------------------------------------------------------------------
823
+ // Plugin stubs
824
+ // ---------------------------------------------------------------------------
825
+
826
+ /** Stub providers matching common LiveKit plugin packages. */
827
+ export namespace plugins {
828
+ export class DeepgramSTT {
829
+ constructor(_opts?: any) {
830
+ globalNoop.once(
831
+ 'stt_plugin',
832
+ 'DeepgramSTT: SignalWire\'s control plane handles the full media pipeline at scale',
833
+ );
834
+ }
835
+ }
836
+
837
+ export class OpenAILLM {
838
+ model: string;
839
+ constructor(_opts?: any) {
840
+ this.model = ((_opts as any)?.model as string) ?? '';
841
+ globalNoop.once(
842
+ 'openai_llm',
843
+ 'OpenAILLM(): model selection is mapped to SignalWire AI params -- OpenAI plugin wrapper is a no-op',
844
+ );
845
+ }
846
+ }
847
+
848
+ export class CartesiaTTS {
849
+ constructor(_opts?: any) {
850
+ globalNoop.once(
851
+ 'cartesia_tts',
852
+ "CartesiaTTS: SignalWire's control plane handles the full media pipeline at scale",
853
+ );
854
+ }
855
+ }
856
+
857
+ export class ElevenLabsTTS {
858
+ constructor(_opts?: any) {
859
+ globalNoop.once(
860
+ 'elevenlabs_tts',
861
+ "ElevenLabsTTS: SignalWire's control plane handles the full media pipeline at scale",
862
+ );
863
+ }
864
+ }
865
+
866
+ export class SileroVAD {
867
+ constructor(_opts?: Record<string, unknown>) {}
868
+
869
+ static load(): SileroVAD {
870
+ globalNoop.once(
871
+ 'vad_plugin',
872
+ "SileroVAD.load(): SignalWire's control plane handles voice activity detection at scale automatically",
873
+ );
874
+ return new SileroVAD();
875
+ }
876
+ }
877
+ }
878
+
879
+ // ---------------------------------------------------------------------------
880
+ // Inference module stubs
881
+ // ---------------------------------------------------------------------------
882
+
883
+ /** Stub inference types matching LiveKit's inference namespace. */
884
+ export namespace inference {
885
+ export class STT {
886
+ model: string;
887
+ constructor(model: string = '', _opts?: any) {
888
+ this.model = model;
889
+ globalNoop.once(
890
+ 'inference_stt',
891
+ 'inference.STT: SignalWire\'s control plane handles speech recognition at scale',
892
+ );
893
+ }
894
+ }
895
+
896
+ export class LLM {
897
+ model: string;
898
+ constructor(model: string = '', _opts?: any) {
899
+ this.model = model;
900
+ }
901
+ }
902
+
903
+ export class TTS {
904
+ model: string;
905
+ constructor(model: string = '', _opts?: any) {
906
+ this.model = model;
907
+ globalNoop.once(
908
+ 'inference_tts',
909
+ 'inference.TTS: SignalWire\'s control plane handles text-to-speech at scale',
910
+ );
911
+ }
912
+ }
913
+ }
914
+
915
+ // ---------------------------------------------------------------------------
916
+ // Namespace re-exports matching @livekit/agents
917
+ // ---------------------------------------------------------------------------
918
+
919
+ /** LiveKit voice namespace equivalent. */
920
+ export const voice = {
921
+ Agent,
922
+ AgentSession,
923
+ AgentSessionEventTypes: {} as Record<string, string>,
924
+ };
925
+
926
+ /** Minimal ChatContext matching livekit ChatContext. */
927
+ export class ChatContext {
928
+ messages: Array<Record<string, string>> = [];
929
+
930
+ append(options: { role?: string; text?: string }): this {
931
+ this.messages.push({ role: options.role ?? 'user', content: options.text ?? '' });
932
+ return this;
933
+ }
934
+ }
935
+
936
+ /** LiveKit llm namespace equivalent. */
937
+ export const llm = {
938
+ tool,
939
+ handoff,
940
+ ToolError,
941
+ ChatContext,
942
+ };
943
+
944
+ /** LiveKit cli namespace equivalent. */
945
+ export const cli = {
946
+ runApp,
947
+ };
948
+
949
+ // Re-export banner/tip functions for testing
950
+ export { printBanner, printTip, banner };