@signalwire/sdk 2.0.4 → 3.5.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 (656) hide show
  1. package/CHANGELOG.md +785 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +550 -163
  6. package/dist/AgentBase.js +1640 -514
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +158 -45
  21. package/dist/DataMap.js +167 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +277 -83
  24. package/dist/FunctionResult.js +444 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +163 -0
  30. package/dist/POM/PromptObjectModel.js +481 -0
  31. package/dist/POM/PromptObjectModel.js.map +1 -0
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +28 -0
  42. package/dist/PomBuilder.js +81 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +29 -1
  48. package/dist/PromptManager.js +37 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +265 -66
  58. package/dist/SWMLService.js +652 -112
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +55 -8
  64. package/dist/SecurityUtils.js +162 -49
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/ServerlessAdapter.d.ts +156 -7
  67. package/dist/ServerlessAdapter.js +399 -42
  68. package/dist/ServerlessAdapter.js.map +1 -1
  69. package/dist/SessionManager.d.ts +11 -2
  70. package/dist/SessionManager.js +50 -18
  71. package/dist/SessionManager.js.map +1 -1
  72. package/dist/SslConfig.d.ts +2 -1
  73. package/dist/SslConfig.js +4 -1
  74. package/dist/SslConfig.js.map +1 -1
  75. package/dist/SwaigActions.generated.d.ts +23 -0
  76. package/dist/SwaigActions.generated.js +8 -0
  77. package/dist/SwaigActions.generated.js.map +1 -0
  78. package/dist/SwaigContracts.d.ts +15 -0
  79. package/dist/SwaigContracts.generated.d.ts +264 -0
  80. package/dist/SwaigContracts.generated.js +12 -0
  81. package/dist/SwaigContracts.generated.js.map +1 -0
  82. package/dist/SwaigContracts.js +2 -0
  83. package/dist/SwaigContracts.js.map +1 -0
  84. package/dist/SwaigFunction.d.ts +110 -4
  85. package/dist/SwaigFunction.js +151 -19
  86. package/dist/SwaigFunction.js.map +1 -1
  87. package/dist/SwmlBuilder.d.ts +68 -19
  88. package/dist/SwmlBuilder.js +74 -38
  89. package/dist/SwmlBuilder.js.map +1 -1
  90. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  91. package/dist/SwmlVerbMethods.generated.js +1 -1
  92. package/dist/TypeInference.d.ts +39 -3
  93. package/dist/TypeInference.js +256 -16
  94. package/dist/TypeInference.js.map +1 -1
  95. package/dist/WebService.d.ts +79 -11
  96. package/dist/WebService.js +320 -109
  97. package/dist/WebService.js.map +1 -1
  98. package/dist/WebhookMiddleware.d.ts +119 -0
  99. package/dist/WebhookMiddleware.js +271 -0
  100. package/dist/WebhookMiddleware.js.map +1 -0
  101. package/dist/WebhookValidator.d.ts +92 -0
  102. package/dist/WebhookValidator.js +409 -0
  103. package/dist/WebhookValidator.js.map +1 -0
  104. package/dist/agents/BedrockAgent.d.ts +162 -0
  105. package/dist/agents/BedrockAgent.js +323 -0
  106. package/dist/agents/BedrockAgent.js.map +1 -0
  107. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  108. package/dist/ai-chat/AIChatClient.js +535 -0
  109. package/dist/ai-chat/AIChatClient.js.map +1 -0
  110. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  111. package/dist/ai-chat/ChatGateway.js +747 -0
  112. package/dist/ai-chat/ChatGateway.js.map +1 -0
  113. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  114. package/dist/ai-chat/HandoffRouter.js +518 -0
  115. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  116. package/dist/ai-chat/index.d.ts +12 -0
  117. package/dist/ai-chat/index.js +10 -0
  118. package/dist/ai-chat/index.js.map +1 -0
  119. package/dist/capabilities.d.ts +64 -0
  120. package/dist/capabilities.js +95 -0
  121. package/dist/capabilities.js.map +1 -0
  122. package/dist/cli/agent-loader.d.ts +32 -6
  123. package/dist/cli/agent-loader.js +95 -34
  124. package/dist/cli/agent-loader.js.map +1 -1
  125. package/dist/cli/datamap-exec.d.ts +175 -0
  126. package/dist/cli/datamap-exec.js +1284 -0
  127. package/dist/cli/datamap-exec.js.map +1 -0
  128. package/dist/cli/function-args.d.ts +40 -0
  129. package/dist/cli/function-args.js +146 -0
  130. package/dist/cli/function-args.js.map +1 -0
  131. package/dist/cli/simulation.d.ts +99 -0
  132. package/dist/cli/simulation.js +490 -0
  133. package/dist/cli/simulation.js.map +1 -0
  134. package/dist/cli/swaig-test.d.ts +12 -25
  135. package/dist/cli/swaig-test.js +935 -367
  136. package/dist/cli/swaig-test.js.map +1 -1
  137. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  138. package/dist/cli/tsdocs/agentsNote.js +92 -0
  139. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  140. package/dist/cli/tsdocs/api-index.json +1 -0
  141. package/dist/cli/tsdocs/api.d.ts +91 -0
  142. package/dist/cli/tsdocs/api.js +372 -0
  143. package/dist/cli/tsdocs/api.js.map +1 -0
  144. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  145. package/dist/cli/tsdocs/apiTypes.js +7 -0
  146. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  147. package/dist/cli/tsdocs/bin.d.ts +6 -0
  148. package/dist/cli/tsdocs/bin.js +23 -0
  149. package/dist/cli/tsdocs/bin.js.map +1 -0
  150. package/dist/cli/tsdocs/files.d.ts +108 -0
  151. package/dist/cli/tsdocs/files.js +287 -0
  152. package/dist/cli/tsdocs/files.js.map +1 -0
  153. package/dist/cli/tsdocs/index.d.ts +28 -0
  154. package/dist/cli/tsdocs/index.js +307 -0
  155. package/dist/cli/tsdocs/index.js.map +1 -0
  156. package/dist/cli/tsdocs/live.d.ts +41 -0
  157. package/dist/cli/tsdocs/live.js +202 -0
  158. package/dist/cli/tsdocs/live.js.map +1 -0
  159. package/dist/cli/tsdocs/locate.d.ts +51 -0
  160. package/dist/cli/tsdocs/locate.js +75 -0
  161. package/dist/cli/tsdocs/locate.js.map +1 -0
  162. package/dist/cli/tsdocs/render.d.ts +75 -0
  163. package/dist/cli/tsdocs/render.js +323 -0
  164. package/dist/cli/tsdocs/render.js.map +1 -0
  165. package/dist/cli/tsdocs/topics.d.ts +43 -0
  166. package/dist/cli/tsdocs/topics.js +916 -0
  167. package/dist/cli/tsdocs/topics.js.map +1 -0
  168. package/dist/index.d.ts +102 -39
  169. package/dist/index.js +107 -30
  170. package/dist/index.js.map +1 -1
  171. package/dist/livewire/index.d.ts +229 -155
  172. package/dist/livewire/index.js +298 -195
  173. package/dist/livewire/index.js.map +1 -1
  174. package/dist/llms.txt +65 -0
  175. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  176. package/dist/prefabs/CallSessionStore.js +72 -0
  177. package/dist/prefabs/CallSessionStore.js.map +1 -0
  178. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  179. package/dist/prefabs/ConciergeAgent.js +36 -31
  180. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  181. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  182. package/dist/prefabs/FAQBotAgent.js +113 -47
  183. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  184. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  185. package/dist/prefabs/InfoGathererAgent.js +67 -58
  186. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  187. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  188. package/dist/prefabs/ReceptionistAgent.js +39 -31
  189. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  190. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  191. package/dist/prefabs/SurveyAgent.js +84 -68
  192. package/dist/prefabs/SurveyAgent.js.map +1 -1
  193. package/dist/relay/Action.d.ts +44 -21
  194. package/dist/relay/Action.js +75 -17
  195. package/dist/relay/Action.js.map +1 -1
  196. package/dist/relay/Call.d.ts +312 -47
  197. package/dist/relay/Call.js +369 -18
  198. package/dist/relay/Call.js.map +1 -1
  199. package/dist/relay/Deferred.js.map +1 -1
  200. package/dist/relay/Message.d.ts +26 -5
  201. package/dist/relay/Message.js +36 -6
  202. package/dist/relay/Message.js.map +1 -1
  203. package/dist/relay/RelayClient.d.ts +79 -14
  204. package/dist/relay/RelayClient.js +268 -61
  205. package/dist/relay/RelayClient.js.map +1 -1
  206. package/dist/relay/RelayError.d.ts +14 -0
  207. package/dist/relay/RelayError.js +15 -0
  208. package/dist/relay/RelayError.js.map +1 -1
  209. package/dist/relay/RelayEvent.d.ts +96 -65
  210. package/dist/relay/RelayEvent.js +85 -56
  211. package/dist/relay/RelayEvent.js.map +1 -1
  212. package/dist/relay/closedSets.d.ts +111 -0
  213. package/dist/relay/closedSets.js +83 -0
  214. package/dist/relay/closedSets.js.map +1 -0
  215. package/dist/relay/index.d.ts +3 -1
  216. package/dist/relay/index.js +1 -0
  217. package/dist/relay/index.js.map +1 -1
  218. package/dist/relay/normalize.js.map +1 -1
  219. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  220. package/dist/relay/protocol.types.generated.js +8 -0
  221. package/dist/relay/protocol.types.generated.js.map +1 -0
  222. package/dist/relay/types.d.ts +81 -39
  223. package/dist/rest/HttpClient.d.ts +36 -8
  224. package/dist/rest/HttpClient.js +233 -40
  225. package/dist/rest/HttpClient.js.map +1 -1
  226. package/dist/rest/RequestOptions.d.ts +110 -0
  227. package/dist/rest/RequestOptions.js +113 -0
  228. package/dist/rest/RequestOptions.js.map +1 -0
  229. package/dist/rest/RestError.d.ts +52 -6
  230. package/dist/rest/RestError.js +89 -5
  231. package/dist/rest/RestError.js.map +1 -1
  232. package/dist/rest/base/CrudResource.d.ts +16 -26
  233. package/dist/rest/base/CrudResource.js +19 -33
  234. package/dist/rest/base/CrudResource.js.map +1 -1
  235. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  236. package/dist/rest/base/CrudWithAddresses.js +2 -2
  237. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  238. package/dist/rest/base/FabricResource.d.ts +15 -0
  239. package/dist/rest/base/FabricResource.js +16 -0
  240. package/dist/rest/base/FabricResource.js.map +1 -0
  241. package/dist/rest/base/ReadResource.d.ts +62 -0
  242. package/dist/rest/base/ReadResource.js +69 -0
  243. package/dist/rest/base/ReadResource.js.map +1 -0
  244. package/dist/rest/callHandler.d.ts +63 -0
  245. package/dist/rest/callHandler.js +62 -0
  246. package/dist/rest/callHandler.js.map +1 -0
  247. package/dist/rest/index.d.ts +19 -76
  248. package/dist/rest/index.js +49 -120
  249. package/dist/rest/index.js.map +1 -1
  250. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  251. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  252. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  253. package/dist/rest/namespaces/addresses.d.ts +3 -42
  254. package/dist/rest/namespaces/addresses.js +3 -50
  255. package/dist/rest/namespaces/addresses.js.map +1 -1
  256. package/dist/rest/namespaces/calling.d.ts +6 -378
  257. package/dist/rest/namespaces/calling.js +6 -473
  258. package/dist/rest/namespaces/calling.js.map +1 -1
  259. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  260. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  261. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  262. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  263. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  264. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  265. package/dist/rest/namespaces/chat.d.ts +4 -18
  266. package/dist/rest/namespaces/chat.js +4 -21
  267. package/dist/rest/namespaces/chat.js.map +1 -1
  268. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  269. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  270. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  271. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  272. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  273. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  274. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  275. package/dist/rest/namespaces/datasphere.js +6 -72
  276. package/dist/rest/namespaces/datasphere.js.map +1 -1
  277. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  278. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  279. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  280. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  281. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  282. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  283. package/dist/rest/namespaces/fabric.d.ts +11 -273
  284. package/dist/rest/namespaces/fabric.js +14 -363
  285. package/dist/rest/namespaces/fabric.js.map +1 -1
  286. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  287. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  288. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  289. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  290. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  291. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  293. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  294. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  296. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  297. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  298. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  299. package/dist/rest/namespaces/imported-numbers.js +3 -21
  300. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  301. package/dist/rest/namespaces/logs.d.ts +10 -101
  302. package/dist/rest/namespaces/logs.js +10 -128
  303. package/dist/rest/namespaces/logs.js.map +1 -1
  304. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  305. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  306. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  307. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  308. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  309. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  310. package/dist/rest/namespaces/lookup.d.ts +3 -25
  311. package/dist/rest/namespaces/lookup.js +3 -27
  312. package/dist/rest/namespaces/lookup.js.map +1 -1
  313. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  314. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  315. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  316. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  317. package/dist/rest/namespaces/message.types.generated.js +8 -0
  318. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  319. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  320. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  321. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  323. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  324. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  325. package/dist/rest/namespaces/mfa.d.ts +3 -42
  326. package/dist/rest/namespaces/mfa.js +3 -49
  327. package/dist/rest/namespaces/mfa.js.map +1 -1
  328. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  329. package/dist/rest/namespaces/number-groups.js +3 -53
  330. package/dist/rest/namespaces/number-groups.js.map +1 -1
  331. package/dist/rest/namespaces/phone-numbers.d.ts +9 -57
  332. package/dist/rest/namespaces/phone-numbers.js +9 -63
  333. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  334. package/dist/rest/namespaces/project.d.ts +6 -42
  335. package/dist/rest/namespaces/project.js +6 -51
  336. package/dist/rest/namespaces/project.js.map +1 -1
  337. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  338. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  339. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  340. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  341. package/dist/rest/namespaces/project.types.generated.js +8 -0
  342. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  343. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  344. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  345. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  347. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  348. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  349. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  350. package/dist/rest/namespaces/pubsub.js +4 -21
  351. package/dist/rest/namespaces/pubsub.js.map +1 -1
  352. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  353. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  354. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  355. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  356. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  357. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  358. package/dist/rest/namespaces/queues.d.ts +3 -38
  359. package/dist/rest/namespaces/queues.js +3 -44
  360. package/dist/rest/namespaces/queues.js.map +1 -1
  361. package/dist/rest/namespaces/recordings.d.ts +3 -34
  362. package/dist/rest/namespaces/recordings.js +3 -40
  363. package/dist/rest/namespaces/recordings.js.map +1 -1
  364. package/dist/rest/namespaces/registry.d.ts +6 -137
  365. package/dist/rest/namespaces/registry.js +6 -173
  366. package/dist/rest/namespaces/registry.js.map +1 -1
  367. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  368. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  369. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  370. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  371. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  372. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  373. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  374. package/dist/rest/namespaces/short-codes.js +3 -41
  375. package/dist/rest/namespaces/short-codes.js.map +1 -1
  376. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  377. package/dist/rest/namespaces/sip-profile.js +3 -29
  378. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  379. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  380. package/dist/rest/namespaces/verified-callers.js +3 -34
  381. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  382. package/dist/rest/namespaces/video.d.ts +10 -227
  383. package/dist/rest/namespaces/video.js +10 -288
  384. package/dist/rest/namespaces/video.js.map +1 -1
  385. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  386. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  387. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  388. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  389. package/dist/rest/namespaces/video.types.generated.js +8 -0
  390. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  391. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  392. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  393. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  395. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  396. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  397. package/dist/rest/pagination.d.ts +5 -1
  398. package/dist/rest/pagination.js +40 -20
  399. package/dist/rest/pagination.js.map +1 -1
  400. package/dist/rest/types.d.ts +21 -3
  401. package/dist/schema.json +299 -98
  402. package/dist/skills/SkillBase.d.ts +97 -20
  403. package/dist/skills/SkillBase.js +100 -17
  404. package/dist/skills/SkillBase.js.map +1 -1
  405. package/dist/skills/SkillManager.d.ts +66 -13
  406. package/dist/skills/SkillManager.js +101 -20
  407. package/dist/skills/SkillManager.js.map +1 -1
  408. package/dist/skills/SkillName.d.ts +44 -0
  409. package/dist/skills/SkillName.js +2 -0
  410. package/dist/skills/SkillName.js.map +1 -0
  411. package/dist/skills/SkillRegistry.d.ts +47 -7
  412. package/dist/skills/SkillRegistry.js +85 -13
  413. package/dist/skills/SkillRegistry.js.map +1 -1
  414. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  415. package/dist/skills/builtin/api_ninjas_trivia.js +24 -8
  416. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  417. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  418. package/dist/skills/builtin/ask_claude.js +36 -14
  419. package/dist/skills/builtin/ask_claude.js.map +1 -1
  420. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  421. package/dist/skills/builtin/claude_skills.js +19 -15
  422. package/dist/skills/builtin/claude_skills.js.map +1 -1
  423. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  424. package/dist/skills/builtin/custom_skills.js +26 -9
  425. package/dist/skills/builtin/custom_skills.js.map +1 -1
  426. package/dist/skills/builtin/datasphere.d.ts +5 -3
  427. package/dist/skills/builtin/datasphere.js +34 -25
  428. package/dist/skills/builtin/datasphere.js.map +1 -1
  429. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  430. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  431. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  432. package/dist/skills/builtin/datetime.d.ts +3 -1
  433. package/dist/skills/builtin/datetime.js +11 -7
  434. package/dist/skills/builtin/datetime.js.map +1 -1
  435. package/dist/skills/builtin/google_maps.d.ts +29 -14
  436. package/dist/skills/builtin/google_maps.js +89 -269
  437. package/dist/skills/builtin/google_maps.js.map +1 -1
  438. package/dist/skills/builtin/index.d.ts +8 -6
  439. package/dist/skills/builtin/index.js +8 -6
  440. package/dist/skills/builtin/index.js.map +1 -1
  441. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  442. package/dist/skills/builtin/info_gatherer.js +20 -12
  443. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  444. package/dist/skills/builtin/joke.d.ts +16 -6
  445. package/dist/skills/builtin/joke.js +54 -37
  446. package/dist/skills/builtin/joke.js.map +1 -1
  447. package/dist/skills/builtin/math.d.ts +3 -1
  448. package/dist/skills/builtin/math.js +14 -9
  449. package/dist/skills/builtin/math.js.map +1 -1
  450. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  451. package/dist/skills/builtin/mcp_gateway.js +77 -46
  452. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  453. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  454. package/dist/skills/builtin/native_vector_search.js +179 -61
  455. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  456. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  457. package/dist/skills/builtin/play_background_file.js +43 -122
  458. package/dist/skills/builtin/play_background_file.js.map +1 -1
  459. package/dist/skills/builtin/spider.d.ts +46 -1
  460. package/dist/skills/builtin/spider.js +317 -101
  461. package/dist/skills/builtin/spider.js.map +1 -1
  462. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  463. package/dist/skills/builtin/swml_transfer.js +45 -24
  464. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  465. package/dist/skills/builtin/weather_api.d.ts +24 -13
  466. package/dist/skills/builtin/weather_api.js +57 -31
  467. package/dist/skills/builtin/weather_api.js.map +1 -1
  468. package/dist/skills/builtin/web_search.d.ts +48 -10
  469. package/dist/skills/builtin/web_search.js +301 -84
  470. package/dist/skills/builtin/web_search.js.map +1 -1
  471. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  472. package/dist/skills/builtin/wikipedia_search.js +32 -14
  473. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  474. package/dist/skills/index.d.ts +3 -2
  475. package/dist/skills/index.js +1 -1
  476. package/dist/skills/index.js.map +1 -1
  477. package/dist/swml_verbs_generated.d.ts +2824 -0
  478. package/dist/swml_verbs_generated.js +12 -0
  479. package/dist/swml_verbs_generated.js.map +1 -0
  480. package/dist/types.d.ts +65 -6
  481. package/dist/web.d.ts +27 -0
  482. package/dist/web.js +20 -0
  483. package/dist/web.js.map +1 -0
  484. package/docs/agent-guide.md +1034 -0
  485. package/docs/ai_chat.md +560 -0
  486. package/docs/api-reference.md +3534 -0
  487. package/docs/architecture.md +846 -0
  488. package/docs/bedrock_agent.md +411 -0
  489. package/docs/cli-guide.md +403 -0
  490. package/docs/cloud_functions_guide.md +399 -0
  491. package/docs/configuration.md +548 -0
  492. package/docs/contexts-guide.md +884 -0
  493. package/docs/datamap-guide.md +1160 -0
  494. package/docs/developer_pain_points.md +548 -0
  495. package/docs/llm_parameters.md +298 -0
  496. package/docs/mcp_gateway_reference.md +354 -0
  497. package/docs/mcp_integration.md +162 -0
  498. package/docs/pgi_agent_guide.md +1820 -0
  499. package/docs/prefabs-guide.md +815 -0
  500. package/docs/programmatically_governed_inference.md +301 -0
  501. package/docs/sdk_features.md +501 -0
  502. package/docs/security.md +559 -0
  503. package/docs/serverless-guide.md +520 -0
  504. package/docs/skills-guide.md +1223 -0
  505. package/docs/skills-system.md +405 -0
  506. package/docs/skills_parameter_schema.md +417 -0
  507. package/docs/swaig-reference.md +1938 -0
  508. package/docs/swml_service_guide.md +573 -0
  509. package/docs/third_party_skills.md +410 -0
  510. package/docs/web_service.md +666 -0
  511. package/examples/README.md +202 -0
  512. package/examples/advanced-datamap.ts +108 -0
  513. package/examples/advanced-dynamic-config.ts +70 -0
  514. package/examples/auto-vivified.ts +95 -0
  515. package/examples/call-flow.ts +65 -0
  516. package/examples/comprehensive-dynamic.ts +125 -0
  517. package/examples/contexts-steps.ts +65 -0
  518. package/examples/custom-path.ts +45 -0
  519. package/examples/datamap-tools.ts +51 -0
  520. package/examples/datasphere-multi-instance.ts +66 -0
  521. package/examples/datasphere-serverless-env.ts +87 -0
  522. package/examples/datasphere-webhook-env.ts +65 -0
  523. package/examples/datasphere.ts +56 -0
  524. package/examples/declarative.ts +100 -0
  525. package/examples/dynamic-config.ts +54 -0
  526. package/examples/dynamic-info-gatherer.ts +69 -0
  527. package/examples/dynamic-swml-service.ts +67 -0
  528. package/examples/gather-info.ts +95 -0
  529. package/examples/gather-per-question-functions-demo.ts +139 -0
  530. package/examples/joke-agent.ts +34 -0
  531. package/examples/kubernetes-agent.ts +45 -0
  532. package/examples/llm-params.ts +75 -0
  533. package/examples/mcp-agent.ts +89 -0
  534. package/examples/mcp-gateway.ts +81 -0
  535. package/examples/multi-agent.ts +80 -0
  536. package/examples/multi-endpoint.ts +79 -0
  537. package/examples/pgi/case-domain.ts +114 -0
  538. package/examples/pgi/serve.ts +16 -0
  539. package/examples/pgi/support-agent.ts +265 -0
  540. package/examples/pom-prompt.ts +70 -0
  541. package/examples/prefab-concierge.ts +42 -0
  542. package/examples/prefab-faq.ts +58 -0
  543. package/examples/prefab-info-gatherer.ts +33 -0
  544. package/examples/prefab-receptionist.ts +36 -0
  545. package/examples/prefab-survey.ts +69 -0
  546. package/examples/quickstart-agent.ts +29 -0
  547. package/examples/quickstart-relay.ts +25 -0
  548. package/examples/quickstart-rest.ts +25 -0
  549. package/examples/record-call.ts +65 -0
  550. package/examples/relay-demo.ts +33 -0
  551. package/examples/room-and-sip.ts +93 -0
  552. package/examples/serverless-lambda.ts +43 -0
  553. package/examples/session-state.ts +83 -0
  554. package/examples/simple-agent.ts +36 -0
  555. package/examples/simple-static.ts +29 -0
  556. package/examples/skills-demo.ts +41 -0
  557. package/examples/step-function-inheritance-demo.ts +124 -0
  558. package/examples/swaig-features.ts +193 -0
  559. package/examples/swml-service-routing.ts +66 -0
  560. package/examples/swml-service.ts +38 -0
  561. package/examples/swmlservice_ai_sidecar.ts +104 -0
  562. package/examples/swmlservice_swaig_standalone.ts +79 -0
  563. package/examples/tap.ts +67 -0
  564. package/examples/typed-tools.ts +68 -0
  565. package/examples/verb-methods.ts +45 -0
  566. package/examples/web-search-multi-instance.ts +75 -0
  567. package/examples/web-search.ts +38 -0
  568. package/examples/wikipedia.ts +36 -0
  569. package/livewire/README.md +164 -0
  570. package/livewire/docs/migration-guide.md +251 -0
  571. package/livewire/examples/livewire-basic-agent.ts +74 -0
  572. package/livewire/examples/livewire-handoff.ts +196 -0
  573. package/livewire/examples/livewire-multi-tool.ts +121 -0
  574. package/package.json +88 -13
  575. package/relay/README.md +101 -0
  576. package/relay/docs/call-methods.md +622 -0
  577. package/relay/docs/client-reference.md +281 -0
  578. package/relay/docs/events.md +193 -0
  579. package/relay/docs/getting-started.md +221 -0
  580. package/relay/docs/guide.md +386 -0
  581. package/relay/docs/messaging.md +246 -0
  582. package/relay/examples/relay-inbound.ts +66 -0
  583. package/relay/examples/relay-messaging.ts +74 -0
  584. package/relay/examples/relay-outbound.ts +76 -0
  585. package/rest/README.md +141 -0
  586. package/rest/docs/calling.md +313 -0
  587. package/rest/docs/client-reference.md +149 -0
  588. package/rest/docs/fabric.md +192 -0
  589. package/rest/docs/getting-started.md +138 -0
  590. package/rest/docs/guide.md +421 -0
  591. package/rest/docs/namespaces.md +367 -0
  592. package/rest/docs/phone-binding.md +116 -0
  593. package/rest/examples/rest-10dlc-registration.ts +177 -0
  594. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  595. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  596. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  597. package/rest/examples/rest-client.ts +59 -0
  598. package/rest/examples/rest-datasphere-search.ts +81 -0
  599. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  600. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  601. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  602. package/rest/examples/rest-manage-resources.ts +64 -0
  603. package/rest/examples/rest-phone-number-management.ts +200 -0
  604. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  605. package/rest/examples/rest-video-rooms.ts +186 -0
  606. package/tutorial/fred/fred.ts +218 -0
  607. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  608. package/tutorial/fred/tutorial/02-setup.md +304 -0
  609. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  610. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  611. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  612. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  613. package/tutorial/fred/tutorial/README.md +56 -0
  614. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  615. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  616. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  617. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  618. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  619. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  620. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  621. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  622. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  623. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  624. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  625. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  626. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  627. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  628. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  629. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  630. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  631. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  632. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  633. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  634. package/tutorial/multi_agents/README.md +175 -0
  635. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  636. package/tutorial/multi_agents/extending_agents.ts +641 -0
  637. package/tutorial/multi_agents/knowledge.ts +59 -0
  638. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  639. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  640. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  641. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  642. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  643. package/tutorial/multi_agents/pc_builder.ts +529 -0
  644. package/tutorial/multi_agents/sales_agent.ts +88 -0
  645. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  646. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  647. package/tutorial/multi_agents/support_knowledge.md +256 -0
  648. package/dist/cli/mock-data.d.ts +0 -37
  649. package/dist/cli/mock-data.js +0 -80
  650. package/dist/cli/mock-data.js.map +0 -1
  651. package/dist/generateVerbTypes.d.ts +0 -11
  652. package/dist/generateVerbTypes.js +0 -265
  653. package/dist/generateVerbTypes.js.map +0 -1
  654. package/dist/rest/namespaces/compat.d.ts +0 -585
  655. package/dist/rest/namespaces/compat.js +0 -735
  656. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -1,12 +1,13 @@
1
1
  /**
2
- * LiveWire -- LiveKit-compatible agents powered by SignalWire.
2
+ * LiveWire: LiveKit-compatible agents powered by SignalWire.
3
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.
4
+ * Provides the same class and function names as @livekit/agents-js, so
5
+ * developers can change their import path and run on SignalWire. SignalWire's
6
+ * control plane runs STT, TTS, VAD, LLM orchestration and call control. The
7
+ * pipeline options LiveWire ignores are accepted, and each logs a message
8
+ * once, so existing code keeps compiling.
9
9
  */
10
+ import { AsyncLocalStorage } from 'node:async_hooks';
10
11
  import { AgentBase } from '../AgentBase.js';
11
12
  import { FunctionResult } from '../FunctionResult.js';
12
13
  // ---------------------------------------------------------------------------
@@ -34,24 +35,24 @@ function printBanner() {
34
35
  // "Did You Know?" Tips
35
36
  // ---------------------------------------------------------------------------
36
37
  /**
37
- * Rotating "Did you know?" tips printed to stderr by the LiveWire banner.
38
- * Exported for tests; reorder or extend to change what's displayed.
38
+ * "Did you know?" tips. `runApp()` prints one, chosen at random, to stderr.
39
+ * Exported for tests; edit the list to change what's displayed.
39
40
  */
40
41
  export const tips = [
41
- "SignalWire agents support DataMap tools that execute server-side — no webhook infrastructure needed. See: docs/datamap-guide.md",
42
- "SignalWire Contexts & Steps give you mechanical state control over conversations — no prompt engineering needed. See: docs/contexts-guide.md",
43
- "SignalWire agents can transfer calls between agents with a single SwmlTransfer() action",
44
- "SignalWire handles 18 built-in skills (datetime, math, web search, etc.) with one-liner integration via agent.addSkill()",
45
- "SignalWire agents support SMS, conferencing, call recording, and SIP — all from the same agent",
46
- "Your agent's entire AI pipeline (STT, LLM, TTS, VAD) runs in SignalWire's cloud — zero infrastructure to manage",
47
- "SignalWire prefab agents (Survey, Receptionist, FAQ, Concierge) give you production patterns in 10 lines of code",
48
- "SignalWire's RELAY client gives you real-time WebSocket call control with 57+ methods — play, record, detect, conference, and more",
49
- "SignalWire agents auto-generate SWML documents — the platform handles media, turn detection, and barge-in for you",
50
- "You can host multiple agents on one server with AgentServer — each with its own route, prompt, and tools",
42
+ 'SignalWire agents support DataMap tools, which the platform runs server-side, so you host no webhook for them. See: docs/datamap-guide.md',
43
+ 'SignalWire Contexts & Steps control which step a conversation is in and which tools each step allows. See: docs/contexts-guide.md',
44
+ 'SignalWire agents can transfer a call to another agent with one FunctionResult action: swmlTransfer()',
45
+ "SignalWire built-in skills (datetime, math, web_search and more) add tools to an agent in one call: agent.addSkillByName('datetime')",
46
+ 'SignalWire agents can send SMS, join conferences, record calls and use SIP, all from the same agent',
47
+ "Your agent's AI pipeline (STT, LLM, TTS, VAD) runs in SignalWire's cloud, so you don't run those services yourself",
48
+ 'SignalWire prefab agents (InfoGathererAgent, SurveyAgent, ReceptionistAgent, FAQBotAgent, ConciergeAgent) give you ready-made agents for common call flows',
49
+ "SignalWire's RELAY client gives you real-time call control over WebSocket: play, record, detect, conference and more",
50
+ 'SignalWire agents generate SWML documents, and the platform handles media, turn detection and barge-in',
51
+ 'You can host multiple agents on one server with AgentServer, each with its own route, prompt and tools',
51
52
  ];
52
53
  function printTip() {
53
54
  const tip = tips[Math.floor(Math.random() * tips.length)];
54
- process.stderr.write(`\n\u{1f4a1} Did you know? ${tip}\n\n`);
55
+ process.stderr.write(`\nDid you know? ${tip}\n\n`);
55
56
  }
56
57
  // ---------------------------------------------------------------------------
57
58
  // Noop logging helpers
@@ -86,16 +87,32 @@ class NoopTracker {
86
87
  const globalNoop = new NoopTracker();
87
88
  // Re-export for testing
88
89
  export { NoopTracker, globalNoop };
90
+ /**
91
+ * Normalize a tool list to `[name, tool]` pairs. Accepts Python's list shape
92
+ * (each tool carries its `name`) and the name-keyed object that LiveKit
93
+ * agents-js uses (`tools: { getWeather }`), where the key is the tool name.
94
+ */
95
+ function toolEntries(tools) {
96
+ if (!tools)
97
+ return [];
98
+ if (Array.isArray(tools))
99
+ return tools.map((t) => [t.name, t]);
100
+ return Object.entries(tools).map(([name, t]) => [name, { ...t, name }]);
101
+ }
89
102
  // ---------------------------------------------------------------------------
90
103
  // Agent
91
104
  // ---------------------------------------------------------------------------
92
105
  /**
93
- * Mirrors a LiveKit `voice.Agent` — holds instructions and tool definitions.
106
+ * Mirrors a LiveKit `voice.Agent`, and holds instructions and tool definitions.
94
107
  *
95
- * Pipeline options (`stt`, `tts`, `vad`, `llm`, `turnDetection`) are accepted
96
- * for API parity but are **no-ops** — SignalWire's control plane handles the
97
- * entire AI pipeline server-side. Set instructions and tools; everything else
98
- * just logs once and continues.
108
+ * The `stt`, `tts`, `vad`, `turnDetection` and `mcpServers` options are accepted
109
+ * for API compatibility and ignored, because SignalWire's control plane runs the
110
+ * AI pipeline. Each one logs a message once. `llm` sets the model, and
111
+ * `allowInterruptions` and the endpointing delays map to AI params when
112
+ * {@link AgentSession.start} builds the agent.
113
+ *
114
+ * `tools` takes an object keyed by tool name, as LiveKit agents-js does, or
115
+ * an array of tools that each have a `name`, as the Python SDK does.
99
116
  *
100
117
  * @example Minimal LiveKit-compatible agent
101
118
  * ```ts
@@ -108,7 +125,7 @@ export { NoopTracker, globalNoop };
108
125
  *
109
126
  * const agent = new livewire.Agent({
110
127
  * instructions: 'You are a friendly helper.',
111
- * tools: [{ ...timeTool, name: 'time' }],
128
+ * tools: { time: timeTool },
112
129
  * });
113
130
  *
114
131
  * const session = new livewire.AgentSession();
@@ -133,34 +150,25 @@ export class Agent {
133
150
  _session;
134
151
  constructor(options) {
135
152
  this.instructions = options?.instructions ?? '';
136
- // Mirror Python: tools is Optional[List[Any]], stored internally as a name-keyed map.
137
- // Build the record from the array using the same pattern as updateTools().
138
- if (options?.tools) {
139
- const record = {};
140
- for (const t of options.tools) {
141
- record[t.name] = t;
142
- }
143
- this.tools = record;
144
- }
145
- else {
146
- this.tools = {};
147
- }
153
+ // Python takes a list; LiveKit agents-js takes a name-keyed object. Both
154
+ // are stored as a name-keyed map.
155
+ this.tools = Object.fromEntries(toolEntries(options?.tools));
148
156
  this.userData = options?.userData;
149
157
  // Pipeline noop advisories (matching Python behavior)
150
158
  if (options?.stt != null) {
151
- globalNoop.once('agent_stt', "Agent(stt=...): SignalWire's control plane handles speech recognition at scale -- no configuration needed");
159
+ globalNoop.once('agent_stt', "Agent({ stt }): ignored. SignalWire's control plane handles speech recognition.");
152
160
  }
153
161
  if (options?.tts != null) {
154
- globalNoop.once('agent_tts', "Agent(tts=...): SignalWire's control plane handles text-to-speech at scale -- no configuration needed");
162
+ globalNoop.once('agent_tts', "Agent({ tts }): ignored. SignalWire's control plane handles text-to-speech.");
155
163
  }
156
164
  if (options?.vad != null) {
157
- globalNoop.once('agent_vad', "Agent(vad=...): SignalWire's control plane handles voice activity detection at scale automatically");
165
+ globalNoop.once('agent_vad', "Agent({ vad }): ignored. SignalWire's control plane handles voice activity detection.");
158
166
  }
159
167
  if (options?.turnDetection != null) {
160
- globalNoop.once('agent_turn_detection', "Agent(turnDetection=...): SignalWire's control plane handles turn detection at scale automatically");
168
+ globalNoop.once('agent_turn_detection', "Agent({ turnDetection }): ignored. SignalWire's control plane handles turn detection.");
161
169
  }
162
170
  if (options?.mcpServers != null) {
163
- globalNoop.once('agent_mcp_servers', 'Agent(mcpServers=...): MCP servers are not yet supported in LiveWire -- tools should be registered via tool()');
171
+ globalNoop.once('agent_mcp_servers', "Agent({ mcpServers }): ignored. LiveWire doesn't support MCP servers; register tools with tool().");
164
172
  }
165
173
  // Store pipeline hints for later mapping (used by AgentSession.start)
166
174
  this._llmHint = options?.llm;
@@ -182,63 +190,66 @@ export class Agent {
182
190
  // Lifecycle hooks (override in subclass)
183
191
  // ------------------------------------------------------------------
184
192
  /**
185
- * Lifecycle hook called when the agent enters an active call.
186
- * Override in a subclass to run setup logic — the default is a no-op.
193
+ * LiveKit lifecycle hook, kept for API compatibility. LiveWire doesn't call
194
+ * it, so an override doesn't run. The default does nothing.
187
195
  */
188
196
  async onEnter() { }
189
197
  /**
190
- * Lifecycle hook called when the agent exits (call ended or handoff).
191
- * Override in a subclass to run teardown logic — the default is a no-op.
198
+ * LiveKit lifecycle hook, kept for API compatibility. LiveWire doesn't call
199
+ * it, so an override doesn't run. The default does nothing.
192
200
  */
193
201
  async onExit() { }
194
202
  /**
195
- * Lifecycle hook called when the user finishes speaking.
196
- * Override in a subclass to inspect / mutate the turn context before the
197
- * LLM responds — the default is a no-op.
203
+ * LiveKit lifecycle hook, kept for API compatibility. LiveWire doesn't call
204
+ * it, so an override doesn't run. The default does nothing.
198
205
  *
199
206
  * @param _turnCtx - Turn context (LiveKit shape; passed through opaquely).
200
207
  * @param _newMessage - Newly-captured user message.
201
208
  */
202
209
  async onUserTurnCompleted(_turnCtx, _newMessage) { }
203
210
  // ------------------------------------------------------------------
204
- // Pipeline nodes -- all noop + log (SignalWire handles these)
211
+ // Pipeline nodes: each does nothing and logs once (SignalWire handles these)
205
212
  // ------------------------------------------------------------------
206
213
  /**
207
- * LiveKit-compatible STT node. **No-op** on SignalWire — the control plane
208
- * handles speech recognition server-side.
214
+ * LiveKit-compatible STT node. Does nothing on SignalWire, where the control
215
+ * plane handles speech recognition. Logs a message once.
209
216
  *
210
217
  * @param _audio - Audio input (ignored).
211
218
  * @param _modelSettings - Model settings (ignored).
212
219
  */
213
220
  async sttNode(_audio, _modelSettings) {
214
- globalNoop.once('stt_node', "Agent.sttNode(): SignalWire's control plane handles speech recognition -- this node is a no-op");
221
+ globalNoop.once('stt_node', "Agent.sttNode(): does nothing. SignalWire's control plane handles speech recognition.");
215
222
  }
216
223
  /**
217
- * LiveKit-compatible LLM node. **No-op** on SignalWire — the control plane
218
- * handles LLM inference server-side.
224
+ * LiveKit-compatible LLM node. Does nothing on SignalWire, where the control
225
+ * plane handles LLM inference. Logs a message once.
219
226
  *
220
227
  * @param _chatCtx - Chat context (ignored).
221
228
  * @param _tools - Tool list (ignored).
222
229
  * @param _modelSettings - Model settings (ignored).
223
230
  */
224
231
  async llmNode(_chatCtx, _tools, _modelSettings) {
225
- globalNoop.once('llm_node', "Agent.llmNode(): SignalWire's control plane handles LLM inference -- this node is a no-op");
232
+ globalNoop.once('llm_node', "Agent.llmNode(): does nothing. SignalWire's control plane handles LLM inference.");
226
233
  }
227
234
  /**
228
- * LiveKit-compatible TTS node. **No-op** on SignalWire — the control plane
229
- * handles text-to-speech server-side.
235
+ * LiveKit-compatible TTS node. Does nothing on SignalWire, where the control
236
+ * plane handles text-to-speech. Logs a message once.
230
237
  *
231
238
  * @param _text - Text to synthesise (ignored).
232
239
  * @param _modelSettings - Model settings (ignored).
233
240
  */
234
241
  async ttsNode(_text, _modelSettings) {
235
- globalNoop.once('tts_node', "Agent.ttsNode(): SignalWire's control plane handles text-to-speech -- this node is a no-op");
242
+ globalNoop.once('tts_node', "Agent.ttsNode(): does nothing. SignalWire's control plane handles text-to-speech.");
236
243
  }
237
244
  // ------------------------------------------------------------------
238
245
  // Dynamic updates
239
246
  // ------------------------------------------------------------------
240
247
  /**
241
- * Update the agent's instructions mid-session.
248
+ * Replace the agent's instructions.
249
+ *
250
+ * This changes the `Agent` object only. A session that has already started
251
+ * keeps the prompt it built; {@link AgentSession.updateAgent} replaces that
252
+ * prompt.
242
253
  *
243
254
  * @param instructions - New system-instructions string for the agent.
244
255
  */
@@ -246,29 +257,27 @@ export class Agent {
246
257
  this.instructions = instructions;
247
258
  }
248
259
  /**
249
- * Update the agent's tool list mid-session.
260
+ * Replace the agent's tool list.
250
261
  *
251
- * Replaces the current tool record with one built from the given array,
252
- * keyed by `tool.name`. Useful for dynamic tool injection based on
253
- * conversation state.
262
+ * Replaces the current tool record with one built from the given tools.
263
+ * This changes the `Agent` object only: tools are registered when
264
+ * {@link AgentSession.start} runs, so a session that has already started
265
+ * keeps its tools.
254
266
  *
255
- * @param tools - Ordered array of {@link FunctionTool} definitions. Each
256
- * tool's `name` is used as its map key.
267
+ * @param tools - An array of {@link FunctionTool} definitions, each keyed
268
+ * by its `name`, or an object keyed by tool name (the LiveKit agents-js
269
+ * shape), whose keys become the tool names.
257
270
  */
258
271
  async updateTools(tools) {
259
- const record = {};
260
- for (const t of tools) {
261
- record[t.name] = t;
262
- }
263
- this.tools = record;
272
+ this.tools = Object.fromEntries(toolEntries(tools));
264
273
  }
265
274
  }
266
275
  // ---------------------------------------------------------------------------
267
276
  // RunContext
268
277
  // ---------------------------------------------------------------------------
269
278
  /**
270
- * Mirrors a LiveKit `RunContext` — passed to tool handlers so they can
271
- * read the current session, call handle, and user data.
279
+ * Mirrors a LiveKit `RunContext`. Tool handlers receive one as `context.ctx`,
280
+ * and read the session and its user data from it.
272
281
  */
273
282
  export class RunContext {
274
283
  /** The owning {@link AgentSession}, when one is bound. */
@@ -301,11 +310,14 @@ export class RunContext {
301
310
  // AgentSession
302
311
  // ---------------------------------------------------------------------------
303
312
  /**
304
- * Mirrors a LiveKit `AgentSession` — binds an {@link Agent} to SignalWire.
313
+ * Mirrors a LiveKit `AgentSession`, and binds an {@link Agent} to SignalWire.
305
314
  *
306
- * Call {@link AgentSession.start} with an `Agent` to construct an internal
307
- * {@link AgentBase} and begin serving SWML. Pipeline-related options are
308
- * accepted for API parity but are no-ops server-side.
315
+ * Call {@link AgentSession.start} with an `Agent` to build an internal
316
+ * {@link AgentBase}. The `stt`, `tts`, `vad`, `turnDetection` and `mcpServers`
317
+ * options are accepted for API compatibility and ignored; each logs a message
318
+ * once. `llm`, `allowInterruptions` and the endpointing delays map to AI
319
+ * params. `minInterruptionDuration` and `preemptiveGeneration` are stored and
320
+ * not used.
309
321
  */
310
322
  export class AgentSession {
311
323
  _llm;
@@ -324,7 +336,7 @@ export class AgentSession {
324
336
  noop = new NoopTracker();
325
337
  constructor(options) {
326
338
  this._llm = options?.llm;
327
- this._tools = options?.tools ? [...options.tools] : [];
339
+ this._tools = toolEntries(options?.tools);
328
340
  this._userData = (options?.userData ?? {});
329
341
  this._allowInterruptions = options?.allowInterruptions ?? true;
330
342
  this._minInterruptionDuration = options?.minInterruptionDuration ?? 0.5;
@@ -333,31 +345,43 @@ export class AgentSession {
333
345
  this._maxToolSteps = options?.maxToolSteps ?? 3;
334
346
  this._preemptiveGeneration = options?.preemptiveGeneration ?? false;
335
347
  if (options?.stt != null) {
336
- this.noop.once('stt', `WithSTT("${options.stt}"): SignalWire's control plane handles speech recognition at scale — no configuration needed`);
348
+ this.noop.once('stt', `AgentSession({ stt: "${options.stt}" }): ignored. SignalWire's control plane handles speech recognition.`);
337
349
  }
338
350
  if (options?.tts != null) {
339
- this.noop.once('tts', `WithTTS("${options.tts}"): SignalWire's control plane handles text-to-speech at scale — no configuration needed`);
351
+ this.noop.once('tts', `AgentSession({ tts: "${options.tts}" }): ignored. SignalWire's control plane handles text-to-speech.`);
340
352
  }
341
353
  if (options?.vad != null) {
342
- this.noop.once('vad', "WithVAD(): SignalWire's control plane handles voice activity detection at scale automatically");
354
+ this.noop.once('vad', "AgentSession({ vad }): ignored. SignalWire's control plane handles voice activity detection.");
343
355
  }
344
356
  if (options?.turnDetection != null) {
345
- this.noop.once('turn_detection', `WithTurnDetection("${options.turnDetection}"): SignalWire's control plane handles turn detection at scale automatically`);
357
+ this.noop.once('turn_detection', `AgentSession({ turnDetection: "${options.turnDetection}" }): ignored. SignalWire's control plane handles turn detection.`);
346
358
  }
347
359
  if (options?.mcpServers != null) {
348
- this.noop.once('mcp_servers', 'AgentSession(mcpServers=...): MCP servers are not yet supported in LiveWire -- tools should be registered via tool()');
360
+ this.noop.once('mcp_servers', "AgentSession({ mcpServers }): ignored. LiveWire doesn't support MCP servers; register tools with tool().");
349
361
  }
350
362
  if (options?.maxToolSteps != null && options.maxToolSteps !== 3) {
351
- this.noop.once('max_tool_steps', `AgentSession(maxToolSteps=${options.maxToolSteps}): SignalWire's control plane handles tool execution depth at scale automatically`);
363
+ this.noop.once('max_tool_steps', `AgentSession({ maxToolSteps: ${options.maxToolSteps} }): ignored. SignalWire's control plane handles tool execution depth.`);
352
364
  }
353
365
  }
354
366
  /**
355
- * Start the session by binding the agent to a freshly-constructed
356
- * {@link AgentBase}, mapping LiveKit-style options onto SignalWire AI params.
367
+ * Start the session by binding the agent to a new {@link AgentBase}, and map
368
+ * LiveKit-style options onto SignalWire AI params.
357
369
  *
358
- * Must be called before any other method on this session. The underlying
359
- * `AgentBase` is not started here — use {@link runApp} or an `AgentServer`
360
- * to serve it.
370
+ * The `AgentBase` gets the agent's instructions as its prompt, and a tool for
371
+ * each entry in the agent's and the session's tool lists. The `llm` value,
372
+ * a model name or an LLM plugin object such as `plugins.OpenAILLM` whose
373
+ * `model` is used, sets the `model` param, with any `provider/` prefix
374
+ * removed.
375
+ * `allowInterruptions: false` sets the `enable_barge` param to `false`, which
376
+ * turns barge-in off. The minimum and
377
+ * maximum endpointing delays, in seconds, set `end_of_speech_timeout` and
378
+ * `attention_timeout` in milliseconds. Text queued with {@link say} becomes
379
+ * an "Initial Greeting" prompt section.
380
+ *
381
+ * This method doesn't start an HTTP server. Called from an entry function
382
+ * that {@link runApp} runs, it hands the built `AgentBase` to that job, and
383
+ * `runApp()` serves it once the entry function returns. {@link getSwAgent}
384
+ * returns the built `AgentBase`.
361
385
  *
362
386
  * @param params - Start parameters.
363
387
  * @param params.agent - The {@link Agent} to bind.
@@ -376,10 +400,18 @@ export class AgentSession {
376
400
  route: '/',
377
401
  });
378
402
  swAgent.setPromptText(agent.instructions);
379
- // Map LLM model if provided (session-level takes priority, then agent-level hint)
403
+ // Map LLM model if provided (session-level takes priority, then agent-level hint).
404
+ // An LLM plugin object (plugins.OpenAILLM, inference.LLM) carries its
405
+ // model name in `model`.
380
406
  const llmModel = this._llm ?? agent._llmHint;
381
- if (llmModel != null) {
382
- let model = String(llmModel);
407
+ let model;
408
+ if (typeof llmModel === 'string') {
409
+ model = llmModel;
410
+ }
411
+ else if (llmModel != null && typeof llmModel.model === 'string') {
412
+ model = llmModel.model;
413
+ }
414
+ if (model) {
383
415
  const slashIdx = model.indexOf('/');
384
416
  if (slashIdx >= 0)
385
417
  model = model.slice(slashIdx + 1);
@@ -391,7 +423,8 @@ export class AgentSession {
391
423
  allowInterruptions = agent._allowInterruptions;
392
424
  }
393
425
  if (!allowInterruptions) {
394
- swAgent.setParam('barge_confidence', 1.0);
426
+ // The platform's switch for barge-in; barge_confidence does nothing
427
+ swAgent.setParam('enable_barge', false);
395
428
  }
396
429
  // Map endpointing delays
397
430
  let minEp = this._minEndpointingDelay;
@@ -409,10 +442,7 @@ export class AgentSession {
409
442
  swAgent.setParam('attention_timeout', Math.round(maxEp * 1000));
410
443
  }
411
444
  // Register all tools from the agent + session-level tools
412
- const allTools = [
413
- ...Object.entries(agent.tools),
414
- ...this._tools.map((t) => [t.name, t]),
415
- ];
445
+ const allTools = [...Object.entries(agent.tools), ...this._tools];
416
446
  for (const [name, toolDef] of allTools) {
417
447
  const handler = async (args, _rawData) => {
418
448
  const ctx = new RunContext(this);
@@ -435,19 +465,24 @@ export class AgentSession {
435
465
  swAgent.promptAddSection('Initial Greeting', { body: text });
436
466
  }
437
467
  this._swAgent = swAgent;
468
+ // Inside a runApp() entry function, hand the agent to that job, which
469
+ // serves it once the entry function returns.
470
+ const job = currentJob.getStore();
471
+ if (job)
472
+ job._swAgent = swAgent;
438
473
  }
439
474
  /**
440
- * Queue text to be spoken by the agent.
475
+ * Add text to the agent's prompt, for the model to use in what it says.
441
476
  *
442
- * Before {@link start} is called, text is buffered and injected at start
443
- * time as the agent's initial greeting. After start, text is added as an
444
- * additional prompt section.
477
+ * The text isn't spoken verbatim. Before {@link start}, it's queued and added
478
+ * as an "Initial Greeting" prompt section at start time. After start, it's
479
+ * added as a "Say" prompt section.
445
480
  *
446
- * @param text - Line for the agent to speak.
481
+ * @param text - Text to add to the prompt.
447
482
  */
448
483
  say(text) {
449
- // If the session is already started, inject directly into the SWML flow.
450
- // Otherwise queue the text so it is replayed when start() is called.
484
+ // If the session has started, add a prompt section now. Otherwise queue
485
+ // the text so start() adds it.
451
486
  if (this._swAgent) {
452
487
  this._swAgent.promptAddSection('Say', { body: text });
453
488
  }
@@ -456,11 +491,14 @@ export class AgentSession {
456
491
  }
457
492
  }
458
493
  /**
459
- * Trigger the agent to generate a reply, optionally with extra instructions.
494
+ * Add instructions for the agent's reply to its prompt.
495
+ *
496
+ * After {@link start}, `options.instructions` is added as an "Initial
497
+ * Greeting" prompt section. Before start, or without instructions, the call
498
+ * does nothing. It doesn't make the agent speak by itself.
460
499
  *
461
500
  * @param options - Generation options.
462
- * @param options.instructions - Extra instructions injected as a new prompt
463
- * section before the next LLM turn.
501
+ * @param options.instructions - Instructions added as a prompt section.
464
502
  */
465
503
  generateReply(options) {
466
504
  if (options?.instructions && this._swAgent) {
@@ -468,17 +506,18 @@ export class AgentSession {
468
506
  }
469
507
  }
470
508
  /**
471
- * Interrupt current speech. **No-op** on SignalWire — barge-in is handled
472
- * automatically by the control plane.
509
+ * Interrupt current speech. Does nothing on SignalWire, where the control
510
+ * plane handles barge-in. Logs a message once.
473
511
  */
474
512
  interrupt() {
475
- this.noop.once('interrupt', "Interrupt(): SignalWire handles barge-in automatically via its control plane");
513
+ this.noop.once('interrupt', "AgentSession.interrupt(): does nothing. SignalWire's control plane handles barge-in.");
476
514
  }
477
515
  /**
478
516
  * Swap the {@link Agent} bound to this session.
479
517
  *
480
- * Preserves the underlying `AgentBase` but replaces its prompt with the new
481
- * agent's instructions.
518
+ * Keeps the underlying `AgentBase` and replaces its prompt with the new
519
+ * agent's instructions. The new agent's tools aren't registered; the tools
520
+ * from {@link start} stay.
482
521
  *
483
522
  * @param agent - Replacement agent.
484
523
  */
@@ -496,13 +535,16 @@ export class AgentSession {
496
535
  set userData(val) {
497
536
  this._userData = val;
498
537
  }
499
- /** Conversation history entries captured over the session's lifetime. */
538
+ /**
539
+ * Conversation history, kept for API compatibility. LiveWire doesn't record
540
+ * turns, so the array stays empty.
541
+ */
500
542
  get history() {
501
543
  return this._history;
502
544
  }
503
545
  /**
504
- * Return the underlying SignalWire {@link AgentBase}. Useful for tests and
505
- * advanced use cases that need to reach past the LiveKit facade.
546
+ * Return the underlying SignalWire {@link AgentBase}, for tests and for code
547
+ * that needs the full SignalWire API.
506
548
  *
507
549
  * @returns The wrapped `AgentBase`, or `undefined` before {@link start}.
508
550
  */
@@ -514,15 +556,22 @@ export class AgentSession {
514
556
  // tool()
515
557
  // ---------------------------------------------------------------------------
516
558
  /**
517
- * Create a tool definition — mirrors `llm.tool()` from `@livekit/agents-js`.
559
+ * Create a tool definition. Mirrors `llm.tool()` from `@livekit/agents-js`.
560
+ *
561
+ * The returned tool has an empty `name`. It gets its name from its key when
562
+ * you add it to an agent's `tools` object (see the {@link Agent} example), or
563
+ * from the `name` you set when you pass `tools` as an array.
518
564
  *
519
- * The returned tool has an empty `name` — the caller assigns it when the tool
520
- * is attached to an agent's tools map (see the {@link Agent} example).
565
+ * `parameters` is stored as given and sent as the tool's SWAIG parameters, so
566
+ * pass a JSON Schema object. A Zod schema isn't converted to JSON Schema.
567
+ *
568
+ * The handler's return value becomes the tool result: a `FunctionResult` as is,
569
+ * a string as the response text, and any other value as JSON text.
521
570
  *
522
571
  * @typeParam P - Parameter type passed into `execute`.
523
572
  * @param options - Tool configuration.
524
573
  * @param options.description - Human-readable tool description exposed to the LLM.
525
- * @param options.parameters - JSON Schema or Zod schema describing the tool's inputs.
574
+ * @param options.parameters - JSON Schema object describing the tool's inputs.
526
575
  * @param options.execute - Handler invoked when the LLM calls the tool.
527
576
  * @returns A {@link FunctionTool} ready to be attached to an agent.
528
577
  */
@@ -531,8 +580,8 @@ export function tool(options) {
531
580
  let jsonSchema;
532
581
  if (options.parameters) {
533
582
  // If it looks like a Zod schema (has a .shape or ._def), try to extract
534
- if (typeof options.parameters === 'object' && options.parameters._def) {
535
- // Best-effort Zod extraction -- store as-is for now
583
+ if (typeof options.parameters === 'object' && '_def' in options.parameters) {
584
+ // A Zod schema is stored as is; it isn't converted to JSON Schema.
536
585
  jsonSchema = options.parameters;
537
586
  }
538
587
  else {
@@ -543,6 +592,9 @@ export function tool(options) {
543
592
  name: '', // Filled in when assigned to agent.tools
544
593
  description: options.description,
545
594
  parameters: jsonSchema,
595
+ // The generic `P` is caller-facing sugar; FunctionTool stores the handler
596
+ // with an `unknown` param. At runtime the platform forwards parsed args
597
+ // verbatim, so widening the param type here is provably safe.
546
598
  execute: options.execute,
547
599
  };
548
600
  }
@@ -550,7 +602,10 @@ export function tool(options) {
550
602
  // handoff()
551
603
  // ---------------------------------------------------------------------------
552
604
  /**
553
- * Create an {@link AgentHandoff} descriptor for multi-agent scenarios.
605
+ * Create an {@link AgentHandoff} descriptor, for LiveKit API compatibility.
606
+ *
607
+ * LiveWire doesn't act on a returned descriptor: the session keeps its agent.
608
+ * To switch agents, call {@link AgentSession.updateAgent}.
554
609
  *
555
610
  * @param options - Handoff parameters.
556
611
  * @param options.agent - Agent to transfer control to.
@@ -567,14 +622,18 @@ export function handoff(options) {
567
622
  // ---------------------------------------------------------------------------
568
623
  // AgentHandoff / StopResponse / ToolError
569
624
  // ---------------------------------------------------------------------------
570
- /** Signals a handoff to another agent in multi-agent scenarios. */
625
+ /** A handoff to another agent. LiveWire doesn't act on it; see {@link handoff}. */
571
626
  export class AgentHandoff {
572
627
  /** Target agent that should take over the conversation. */
573
628
  agent;
574
629
  /** Optional return value surfaced when the handoff completes. */
575
630
  returns;
576
631
  }
577
- /** Signals that a tool should not trigger another LLM reply. */
632
+ /**
633
+ * LiveKit's signal that a tool shouldn't trigger another LLM reply. LiveWire
634
+ * doesn't handle it specially: a tool that throws it gets the SDK's generic
635
+ * tool error response, like any other exception.
636
+ */
578
637
  export class StopResponse extends Error {
579
638
  /**
580
639
  * @param message - Optional error message. Defaults to `"StopResponse"`.
@@ -584,10 +643,14 @@ export class StopResponse extends Error {
584
643
  this.name = 'StopResponse';
585
644
  }
586
645
  }
587
- /** Error thrown from a tool to signal failure back to the LLM. */
646
+ /**
647
+ * LiveKit's error for a failed tool. LiveWire doesn't handle it specially: a
648
+ * tool that throws it gets the SDK's generic tool error response, and the
649
+ * message isn't sent to the model.
650
+ */
588
651
  export class ToolError extends Error {
589
652
  /**
590
- * @param message - Error message surfaced to the LLM.
653
+ * @param message - Error message (logged; not sent to the model).
591
654
  */
592
655
  constructor(message) {
593
656
  super(message);
@@ -598,58 +661,61 @@ export class ToolError extends Error {
598
661
  // JobProcess
599
662
  // ---------------------------------------------------------------------------
600
663
  /**
601
- * Mirrors a LiveKit `JobProcess` — placeholder for prewarm / setup hooks.
664
+ * Mirrors a LiveKit `JobProcess`, passed to the prewarm hook.
602
665
  *
603
- * On SignalWire the control plane pre-warms infrastructure at scale, so this
604
- * class carries no real state beyond the LiveKit-compatible `userData` bag.
666
+ * SignalWire has no worker processes to prewarm, so this class holds only
667
+ * the LiveKit-compatible `userData` object.
605
668
  */
606
669
  export class JobProcess {
607
- /** Mutable bag shared across prewarm and entry-point callbacks. */
670
+ /** Mutable object for data passed between callbacks. */
608
671
  userData = {};
609
672
  }
610
673
  // ---------------------------------------------------------------------------
611
674
  // Room
612
675
  // ---------------------------------------------------------------------------
613
676
  /**
614
- * Stub `Room` — SignalWire does not use the LiveKit room abstraction.
677
+ * Stub `Room`. SignalWire doesn't use the LiveKit room abstraction.
615
678
  *
616
- * Present purely for API parity so LiveKit-shaped code compiles; its only
617
- * meaningful attribute is the constant name.
679
+ * It exists for API compatibility, so LiveKit-shaped code compiles. Its only
680
+ * attribute is a constant name.
618
681
  */
619
682
  export class Room {
620
- /** Always `"livewire-room"` — SignalWire has no per-call room identity. */
683
+ /** Always `"livewire-room"`; SignalWire has no per-call room identity. */
621
684
  name = 'livewire-room';
622
685
  }
623
686
  // ---------------------------------------------------------------------------
624
687
  // JobContext
625
688
  // ---------------------------------------------------------------------------
626
689
  /**
627
- * Mirrors a LiveKit `JobContext` — provides room and connection info to the
628
- * entry-point callback registered via {@link defineAgent}.
690
+ * Mirrors a LiveKit `JobContext`, passed to the entry function that
691
+ * {@link runApp} calls.
629
692
  */
630
693
  export class JobContext {
631
694
  /** Placeholder {@link Room} (see class docs). */
632
695
  room;
633
- /** Shared {@link JobProcess} instance for prewarm-to-entry data passing. */
696
+ /** A {@link JobProcess}. `runApp()` creates it separately from the one passed to prewarm. */
634
697
  proc;
635
- /** @internal */
698
+ /**
699
+ * @internal The `AgentBase` of the last session started while this job's
700
+ * entry function ran; `runApp()` serves it.
701
+ */
636
702
  _swAgent;
637
703
  constructor() {
638
704
  this.room = new Room();
639
705
  this.proc = new JobProcess();
640
706
  }
641
707
  /**
642
- * Connect to the platform. **No-op** on SignalWire — the control plane
643
- * manages connection lifecycle automatically.
708
+ * Connect to the platform. Does nothing on SignalWire, where the platform
709
+ * connects when it requests the agent's SWML. Logs a message once.
644
710
  *
645
711
  * @returns Resolves immediately.
646
712
  */
647
713
  async connect() {
648
- globalNoop.once('connect', "JobContext.connect(): SignalWire's control plane handles connection lifecycle at scale automatically");
714
+ globalNoop.once('connect', "JobContext.connect(): does nothing. SignalWire connects when it requests the agent's SWML.");
649
715
  }
650
716
  /**
651
- * Wait for a participant to join. **No-op** on SignalWire — returns an
652
- * immediate stub participant.
717
+ * Wait for a participant to join. On SignalWire it returns a stub
718
+ * participant at once.
653
719
  *
654
720
  * @param options - Participant match options.
655
721
  * @param options.identity - Requested identity; echoed back in the stub.
@@ -660,21 +726,24 @@ export class JobContext {
660
726
  return { identity: options?.identity ?? 'caller' };
661
727
  }
662
728
  }
663
- // ---------------------------------------------------------------------------
664
- // defineAgent
665
- // ---------------------------------------------------------------------------
729
+ /**
730
+ * The {@link JobContext} whose entry function is running, so that
731
+ * {@link AgentSession.start} can hand its agent to the job for
732
+ * {@link runApp} to serve.
733
+ */
734
+ const currentJob = new AsyncLocalStorage();
666
735
  /**
667
736
  * Mirrors `@livekit/agents.defineAgent()`.
668
737
  *
669
- * Packages an entry function (plus an optional prewarm hook) for later
670
- * execution by {@link runApp}. Pass-through — no side effects.
738
+ * Packages an entry function, and an optional prewarm hook, for
739
+ * {@link runApp}. It returns its argument unchanged.
671
740
  *
672
741
  * @param agent - Entry and (optional) prewarm functions.
673
742
  * @param agent.entry - Main callback invoked with a {@link JobContext} when
674
743
  * the agent runs.
675
744
  * @param agent.prewarm - Optional prewarm callback invoked with a
676
745
  * {@link JobProcess} before `entry`.
677
- * @returns The same record (pass-through), typed consistently.
746
+ * @returns The same object.
678
747
  */
679
748
  export function defineAgent(agent) {
680
749
  return agent;
@@ -685,47 +754,74 @@ export function defineAgent(agent) {
685
754
  /**
686
755
  * Mirrors `cli.runApp()` from `@livekit/agents-js`.
687
756
  *
757
+ * It takes these steps:
758
+ *
688
759
  * 1. Prints the LiveWire banner
689
- * 2. Runs the registered prewarm callback (if any) with a fresh {@link JobProcess}
690
- * 3. Creates a fresh {@link JobContext}
760
+ * 2. Runs the prewarm callback, if any, with a new {@link JobProcess}
761
+ * 3. Creates a new {@link JobContext}
691
762
  * 4. Prints a random tip
692
- * 5. Invokes the entry function with the context
693
- * 6. Starts the underlying SignalWire `AgentBase` once the entry function
694
- * binds one (via an `AgentSession.start()` call)
763
+ * 5. Calls the entry function with the context
764
+ * 6. When the entry function resolves, serves the `AgentBase` of the last
765
+ * {@link AgentSession} the entry function started, by calling its
766
+ * `serve()`. The server listens on `PORT` (default 3000), with the route
767
+ * `/`, and runs until the process exits.
695
768
  *
696
- * Accepts either an object `{ entry, prewarm? }`, a bare entry function, or
697
- * an {@link AgentServer} instance.
769
+ * It accepts an object `{ entry, prewarm? }`, a bare entry function, or an
770
+ * {@link AgentServer} instance. Errors from the entry function are written to
771
+ * stderr, as is a message when the entry function starts no session.
772
+ *
773
+ * When `SWAIG_CLI_MODE=true` is set as `runApp()` is called (the `swaig-test`
774
+ * CLI sets it while it imports an agent file), the entry function runs and
775
+ * nothing is served.
698
776
  *
699
777
  * @param options - Agent descriptor, entry function, or `AgentServer`.
700
778
  */
701
779
  export function runApp(options) {
702
780
  printBanner();
703
- // If passed an AgentServer instance, convert it to an agentDef-compatible object
781
+ // If passed an AgentServer instance, convert it to an agentDef-compatible object.
782
+ // Otherwise the value is an AgentDefinition, a bare entry function, or a
783
+ // wrapper carrying `.agent`, each detected by its shape.
704
784
  const agentDef = options instanceof AgentServer
705
785
  ? options._toAgentDef()
706
786
  : (options?.agent ?? options);
707
787
  // Run prewarm if registered
708
- if (agentDef?.prewarm) {
788
+ const def = agentDef;
789
+ if (def?.prewarm) {
709
790
  const proc = new JobProcess();
710
- globalNoop.once('prewarm', "prewarm: Warm process pools not needed — SignalWire's control plane manages media infrastructure at scale");
711
- agentDef.prewarm(proc);
791
+ globalNoop.once('prewarm', "prewarm: the callback runs, but SignalWire's control plane manages media infrastructure, so there are no worker processes to prewarm.");
792
+ def.prewarm(proc);
712
793
  }
713
794
  // Create a JobContext
714
795
  const ctx = new JobContext();
715
796
  // Print a random tip
716
797
  printTip();
717
- // Call the entry function
718
- const entryFn = agentDef?.entry ?? agentDef;
798
+ // Read now: swaig-test sets SWAIG_CLI_MODE only while it imports the agent
799
+ // file, and the entry function's session is built after that.
800
+ const cliMode = process.env['SWAIG_CLI_MODE'] === 'true';
801
+ // Call the entry function. A session started inside it hands its agent to
802
+ // ctx (see AgentSession.start).
803
+ const entryFn = def?.entry ?? agentDef;
719
804
  if (typeof entryFn === 'function') {
720
- Promise.resolve(entryFn(ctx)).then(() => {
721
- // After entry completes, the session should have bound a swAgent to ctx
722
- // If someone stored it on ctx, start it
723
- if (ctx._swAgent) {
724
- ctx._swAgent.run().catch((err) => {
805
+ let result;
806
+ try {
807
+ result = currentJob.run(ctx, () => entryFn(ctx));
808
+ }
809
+ catch (err) {
810
+ result = Promise.reject(err);
811
+ }
812
+ Promise.resolve(result)
813
+ .then(() => {
814
+ // After entry completes, serve the AgentBase stored on ctx, if any.
815
+ if (!ctx._swAgent) {
816
+ process.stderr.write('[LiveWire] no agent was started: call session.start({ agent }) in the entry function.\n');
817
+ }
818
+ else if (!cliMode) {
819
+ ctx._swAgent.serve().catch((err) => {
725
820
  process.stderr.write(`[LiveWire] agent error: ${err.message}\n`);
726
821
  });
727
822
  }
728
- }).catch((err) => {
823
+ })
824
+ .catch((err) => {
729
825
  process.stderr.write(`[LiveWire] entry function error: ${err.message}\n`);
730
826
  });
731
827
  }
@@ -736,7 +832,7 @@ export function runApp(options) {
736
832
  /**
737
833
  * Stub class mirroring LiveKit's `WorkerOptions`.
738
834
  *
739
- * Accepts any configuration for source-compatibility with LiveKit code;
835
+ * Accepts any configuration, for source compatibility with LiveKit code.
740
836
  * SignalWire ignores these settings.
741
837
  */
742
838
  export class WorkerOptions {
@@ -746,7 +842,7 @@ export class WorkerOptions {
746
842
  /**
747
843
  * Stub class mirroring LiveKit's `ServerOptions`.
748
844
  *
749
- * Accepts any configuration for source-compatibility with LiveKit code;
845
+ * Accepts any configuration, for source compatibility with LiveKit code.
750
846
  * SignalWire ignores these settings.
751
847
  */
752
848
  export class ServerOptions {
@@ -757,7 +853,8 @@ export class ServerOptions {
757
853
  // AgentServer
758
854
  // ---------------------------------------------------------------------------
759
855
  /**
760
- * Mirrors a LiveKit AgentServer -- registers entrypoints and starts.
856
+ * Mirrors a LiveKit AgentServer: registers an entry function for
857
+ * {@link runApp}.
761
858
  *
762
859
  * Usage:
763
860
  * const server = new AgentServer();
@@ -772,7 +869,7 @@ export class ServerOptions {
772
869
  * cli.runApp(server);
773
870
  */
774
871
  export class AgentServer {
775
- /** Optional prewarm hook called before the entrypoint. Mirrors Python's setup_fnc. */
872
+ /** Optional prewarm hook, called before the entry function. Mirrors Python's `setup_fnc`. */
776
873
  setupFnc;
777
874
  /** @internal Registered entrypoint function. */
778
875
  _entryFn;
@@ -798,11 +895,11 @@ export class AgentServer {
798
895
  resolvedOpts = opts;
799
896
  }
800
897
  else {
801
- // fnOrOpts is an options object (or undefined) — parameterized decorator usage
898
+ // fnOrOpts is an options object (or undefined): parameterized decorator usage
802
899
  resolvedOpts = fnOrOpts;
803
900
  }
804
901
  if (resolvedOpts?.type && resolvedOpts.type !== 'room') {
805
- globalNoop.once('server_type', `AgentServer.rtcSession(type=${JSON.stringify(resolvedOpts.type)}): SignalWire's control plane handles server topology at scale automatically`);
902
+ globalNoop.once('server_type', `AgentServer.rtcSession({ type: ${JSON.stringify(resolvedOpts.type)} }): ignored. SignalWire's control plane handles server topology.`);
806
903
  }
807
904
  const register = (entryFn) => {
808
905
  this._entryFn = entryFn;
@@ -830,25 +927,27 @@ export class AgentServer {
830
927
  /**
831
928
  * Stub providers matching common LiveKit plugin packages.
832
929
  *
833
- * None of these do anything — they exist so LiveKit code that imports and
930
+ * None of these do anything. They exist so LiveKit code that imports and
834
931
  * constructs these classes still compiles and runs under SignalWire. The
835
- * first construction of each logs an advisory to stderr.
932
+ * first construction of most of them logs a message to stderr.
836
933
  */
934
+ // eslint-disable-next-line @typescript-eslint/no-namespace -- LiveKit-compat namespace; preserves the exact public API shape (value + type access for `plugins.X`)
837
935
  export var plugins;
838
936
  (function (plugins) {
839
- /** LiveKit Deepgram-STT plugin stub. No-op on SignalWire. */
937
+ /** LiveKit Deepgram-STT plugin stub. Does nothing on SignalWire. */
840
938
  class DeepgramSTT {
841
939
  /** @param _opts - Deepgram options (ignored). */
842
940
  constructor(_opts) {
843
- globalNoop.once('stt_plugin', 'DeepgramSTT: SignalWire\'s control plane handles the full media pipeline at scale');
941
+ globalNoop.once('stt_plugin', "DeepgramSTT: ignored. SignalWire's control plane handles speech recognition.");
844
942
  }
845
943
  }
846
944
  plugins.DeepgramSTT = DeepgramSTT;
847
945
  /**
848
946
  * LiveKit OpenAI-LLM plugin stub.
849
947
  *
850
- * The `model` string is captured and mapped to the SignalWire AI `model`
851
- * param by {@link AgentSession.start}. Other options are ignored.
948
+ * Captures the `model` string. Passed as the `llm` option of
949
+ * `AgentSession` or `Agent`, it sets the `model` AI param. Other options
950
+ * are ignored.
852
951
  */
853
952
  class OpenAILLM {
854
953
  /** Model identifier captured from the constructor options. */
@@ -856,40 +955,40 @@ export var plugins;
856
955
  /** @param _opts - OpenAI options. `_opts.model` is captured; everything else ignored. */
857
956
  constructor(_opts) {
858
957
  this.model = _opts?.model ?? '';
859
- globalNoop.once('openai_llm', 'OpenAILLM(): model selection is mapped to SignalWire AI params -- OpenAI plugin wrapper is a no-op');
958
+ globalNoop.once('openai_llm', "OpenAILLM(): only its model option is used, to set the model AI param. SignalWire's control plane runs the LLM.");
860
959
  }
861
960
  }
862
961
  plugins.OpenAILLM = OpenAILLM;
863
- /** LiveKit Cartesia-TTS plugin stub. No-op on SignalWire. */
962
+ /** LiveKit Cartesia-TTS plugin stub. Does nothing on SignalWire. */
864
963
  class CartesiaTTS {
865
964
  /** @param _opts - Cartesia options (ignored). */
866
965
  constructor(_opts) {
867
- globalNoop.once('cartesia_tts', "CartesiaTTS: SignalWire's control plane handles the full media pipeline at scale");
966
+ globalNoop.once('cartesia_tts', "CartesiaTTS: ignored. SignalWire's control plane handles text-to-speech.");
868
967
  }
869
968
  }
870
969
  plugins.CartesiaTTS = CartesiaTTS;
871
- /** LiveKit ElevenLabs-TTS plugin stub. No-op on SignalWire. */
970
+ /** LiveKit ElevenLabs-TTS plugin stub. Does nothing on SignalWire. */
872
971
  class ElevenLabsTTS {
873
972
  /** @param _opts - ElevenLabs options (ignored). */
874
973
  constructor(_opts) {
875
- globalNoop.once('elevenlabs_tts', "ElevenLabsTTS: SignalWire's control plane handles the full media pipeline at scale");
974
+ globalNoop.once('elevenlabs_tts', "ElevenLabsTTS: ignored. SignalWire's control plane handles text-to-speech.");
876
975
  }
877
976
  }
878
977
  plugins.ElevenLabsTTS = ElevenLabsTTS;
879
- /** LiveKit Silero-VAD plugin stub. No-op on SignalWire. */
978
+ /** LiveKit Silero-VAD plugin stub. Does nothing on SignalWire. */
880
979
  class SileroVAD {
881
980
  /** @param _opts - Silero VAD options (ignored). */
882
981
  constructor(_opts) { }
883
982
  /**
884
983
  * Load a Silero VAD model.
885
984
  *
886
- * **No-op** on SignalWire — returns a fresh stub instance and emits a
887
- * one-time advisory to stderr.
985
+ * Does nothing on SignalWire: returns a new stub instance, and logs a
986
+ * message to stderr once.
888
987
  *
889
988
  * @returns A new `SileroVAD` stub.
890
989
  */
891
990
  static load() {
892
- globalNoop.once('vad_plugin', "SileroVAD.load(): SignalWire's control plane handles voice activity detection at scale automatically");
991
+ globalNoop.once('vad_plugin', "SileroVAD.load(): ignored. SignalWire's control plane handles voice activity detection.");
893
992
  return new SileroVAD();
894
993
  }
895
994
  }
@@ -901,10 +1000,11 @@ export var plugins;
901
1000
  /**
902
1001
  * Stub inference types matching LiveKit's `inference` namespace.
903
1002
  *
904
- * None of these run inference on the client — SignalWire performs STT / LLM /
905
- * TTS in its control plane. These classes exist so LiveKit code that imports
906
- * and instantiates them still compiles.
1003
+ * None of these run inference on the client. SignalWire runs STT, LLM and TTS
1004
+ * in its control plane. These classes exist so LiveKit code that imports and
1005
+ * constructs them still compiles.
907
1006
  */
1007
+ // eslint-disable-next-line @typescript-eslint/no-namespace -- LiveKit-compat namespace; preserves the exact public API shape (value + type access for `inference.X`)
908
1008
  export var inference;
909
1009
  (function (inference) {
910
1010
  /** LiveKit inference-STT stub. Captures the model name; runs no inference locally. */
@@ -917,11 +1017,14 @@ export var inference;
917
1017
  */
918
1018
  constructor(model = '', _opts) {
919
1019
  this.model = model;
920
- globalNoop.once('inference_stt', 'inference.STT: SignalWire\'s control plane handles speech recognition at scale');
1020
+ globalNoop.once('inference_stt', "inference.STT: ignored. SignalWire's control plane handles speech recognition.");
921
1021
  }
922
1022
  }
923
1023
  inference.STT = STT;
924
- /** LiveKit inference-LLM stub. Captures the model name; runs no inference locally. */
1024
+ /**
1025
+ * LiveKit inference-LLM stub. Captures the model name; runs no inference
1026
+ * locally. Passed as the `llm` option, it sets the `model` AI param.
1027
+ */
925
1028
  class LLM {
926
1029
  /** Model identifier captured from the constructor. */
927
1030
  model;
@@ -944,7 +1047,7 @@ export var inference;
944
1047
  */
945
1048
  constructor(model = '', _opts) {
946
1049
  this.model = model;
947
- globalNoop.once('inference_tts', 'inference.TTS: SignalWire\'s control plane handles text-to-speech at scale');
1050
+ globalNoop.once('inference_tts', "inference.TTS: ignored. SignalWire's control plane handles text-to-speech.");
948
1051
  }
949
1052
  }
950
1053
  inference.TTS = TTS;