@signalwire/sdk 2.0.5 → 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 +481 -126
  6. package/dist/AgentBase.js +1502 -438
  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 +12 -1
  30. package/dist/POM/PromptObjectModel.js +25 -9
  31. package/dist/POM/PromptObjectModel.js.map +1 -1
  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 +18 -0
  42. package/dist/PomBuilder.js +53 -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 +22 -1
  48. package/dist/PromptManager.js +28 -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 +158 -58
  58. package/dist/SWMLService.js +435 -127
  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 +49 -9
  64. package/dist/SecurityUtils.js +153 -51
  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 +92 -33
  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 -371
  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 +47 -68
  169. package/dist/index.js +44 -73
  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 +44 -17
  204. package/dist/relay/RelayClient.js +175 -65
  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 +73 -42
  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 +5 -2
  245. package/dist/rest/callHandler.js +4 -1
  246. package/dist/rest/callHandler.js.map +1 -1
  247. package/dist/rest/index.d.ts +18 -77
  248. package/dist/rest/index.js +47 -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 -327
  284. package/dist/rest/namespaces/fabric.js +14 -439
  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 +8 -196
  332. package/dist/rest/namespaces/phone-numbers.js +8 -230
  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 +22 -11
  412. package/dist/skills/SkillRegistry.js +47 -17
  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 +18 -6
  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 +21 -22
  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 +42 -4
  460. package/dist/skills/builtin/spider.js +277 -104
  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 +38 -30
  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 +294 -100
  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 +14 -13
  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 +59 -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 +85 -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
@@ -0,0 +1,916 @@
1
+ /**
2
+ * The hand-written part of sw-tsdocs: one entry per topic.
3
+ *
4
+ * Keep each body to what a reader needs to choose an approach and avoid
5
+ * known mistakes, and point to the installed docs for the rest. Facts that
6
+ * can be read from the installed package (the version, the commands, the
7
+ * skills, the signatures) belong in the renderers, not here.
8
+ * tests/cli/tsdocs.test.ts checks that every file, example, API name and
9
+ * topic link given here exists, and that the `ts` snippets compile.
10
+ */
11
+ const QUICKSTART = {
12
+ name: 'quickstart',
13
+ title: 'Quickstart: a working agent in one file',
14
+ summary: 'The smallest complete agent, and how to run and test it',
15
+ body: `\`\`\`ts
16
+ import { AgentBase, FunctionResult } from '@signalwire/sdk';
17
+
18
+ const agent = new AgentBase({ name: 'my-agent', route: '/agent' });
19
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'inworld.Mark' });
20
+ agent.promptAddSection('Role', { body: 'You are a helpful assistant.' });
21
+
22
+ agent.defineTool({
23
+ name: 'get_time',
24
+ description: 'Get the current time',
25
+ parameters: {},
26
+ handler: () => new FunctionResult(\`The time is \${new Date().toLocaleTimeString()}.\`),
27
+ });
28
+
29
+ await agent.run();
30
+ \`\`\`
31
+
32
+ - Run it with \`npx tsx my-agent.ts\`. \`run()\` starts a web server on port
33
+ 3000 (or \`PORT\`). It serves the agent's SWML document at \`/agent\` and its
34
+ tools at \`/agent/swaig\`. On AWS Lambda, Google Cloud Functions, Azure
35
+ Functions or CGI, it handles the platform's request instead.
36
+ - Every endpoint except the \`/health\` and \`/ready\` probes needs basic auth.
37
+ Set \`SWML_BASIC_AUTH_USER\` and \`SWML_BASIC_AUTH_PASSWORD\`; otherwise the
38
+ agent generates a password, which \`agent.getBasicAuthCredentials()\`
39
+ returns.
40
+ - To take calls, SignalWire must reach the agent over HTTPS: deploy it, or use
41
+ a tunnel during development and set \`SWML_PROXY_URL_BASE\` to the public URL.
42
+ Then point a phone number's SWML webhook at
43
+ \`https://USER:PASSWORD@HOST/agent\`, in the dashboard or with the REST client
44
+ (\`rest/examples/rest-bind-phone-to-swml-webhook.ts\`).
45
+
46
+ Test it without a call:
47
+
48
+ \`\`\`bash
49
+ npx swaig-test my-agent.ts --list-tools
50
+ npx swaig-test my-agent.ts --dump-swml
51
+ npx swaig-test my-agent.ts --exec get_time
52
+ \`\`\`
53
+ `,
54
+ docs: [
55
+ ['README.md', "The SDK's overview and quickstarts for agents, RELAY and REST"],
56
+ ['docs/agent-guide.md', 'The main guide to building agents'],
57
+ ],
58
+ examples: [
59
+ 'examples/quickstart-agent.ts',
60
+ 'examples/quickstart-relay.ts',
61
+ 'examples/quickstart-rest.ts',
62
+ ],
63
+ api: ['AgentBase', 'FunctionResult', 'AgentBase.run'],
64
+ related: ['agents', 'tools', 'testing', 'deploy'],
65
+ };
66
+ const AGENTS = {
67
+ name: 'agents',
68
+ title: 'AI agents (AgentBase)',
69
+ summary: "Voice and text AI agents: how they work and how they're built",
70
+ body: `An agent is a web service, and SignalWire runs the conversation. When a call
71
+ arrives, SignalWire fetches the agent's SWML document (prompt, voice,
72
+ languages, tools, settings) and runs speech recognition, the LLM and
73
+ text-to-speech itself. When the model calls a tool, SignalWire posts the call
74
+ to the agent's \`/swaig\` endpoint, and your handler returns a
75
+ \`FunctionResult\`. Your code never handles audio.
76
+
77
+ Build one by constructing \`AgentBase\` and configuring it, or by subclassing it
78
+ (\`static PROMPT_SECTIONS\` for the prompt, and an overridden \`defineTools()\`,
79
+ which the SDK calls once, the first time the tools are needed):
80
+
81
+ - Voice and language: \`addLanguage()\`. Prompt: \`promptAddSection()\` or
82
+ \`setPromptText()\` (\`sw-tsdocs prompts\`).
83
+ - Tools: \`defineTool()\`, or DataMap tools that run on SignalWire
84
+ (\`sw-tsdocs tools\`, \`sw-tsdocs datamap\`).
85
+ - Ready-made tools: \`addSkill()\` and \`addSkillByName()\` (\`sw-tsdocs skills\`).
86
+ - Multi-step workflows: \`defineContexts()\` (\`sw-tsdocs contexts\`).
87
+ - An end-of-call summary: \`setPostPrompt()\`, received by \`onSummary()\`.
88
+
89
+ Serving: \`run()\` or \`serve()\` for one agent, \`AgentServer\` for several agents
90
+ in one process, and \`getApp()\` (a Hono app) or \`asRouter()\` to mount an agent
91
+ in an existing web app.
92
+
93
+ Per-call configuration: \`setDynamicConfigCallback()\` configures a copy of the
94
+ agent for each request, from its query parameters, body and headers, for
95
+ per-tenant prompts, voices and tools. Handlers for different calls interleave
96
+ at every \`await\`: don't keep per-caller state on the shared agent instance.
97
+ `,
98
+ docs: [
99
+ ['docs/agent-guide.md', 'The main guide: prompts, tools, skills, contexts, serving'],
100
+ ['docs/architecture.md', 'How the pieces fit: the managers AgentBase composes, request flow'],
101
+ ['docs/api-reference.md', 'Reference for AgentBase and the other public classes'],
102
+ ['docs/sdk_features.md', 'What the SDK adds over writing SWML by hand'],
103
+ ['docs/configuration.md', 'Config files and environment variables'],
104
+ ['docs/pgi_agent_guide.md', 'How to design agents that stay within their rules'],
105
+ ],
106
+ examples: [
107
+ 'examples/simple-agent.ts',
108
+ 'examples/simple-static.ts',
109
+ 'examples/declarative.ts',
110
+ 'examples/dynamic-config.ts',
111
+ 'examples/comprehensive-dynamic.ts',
112
+ 'examples/multi-agent.ts',
113
+ 'examples/custom-path.ts',
114
+ 'examples/multi-endpoint.ts',
115
+ ],
116
+ api: [
117
+ 'AgentBase',
118
+ 'AgentOptions',
119
+ 'AgentServer',
120
+ 'AgentBase.setDynamicConfigCallback',
121
+ 'AgentBase.getApp',
122
+ 'AgentBase.onSummary',
123
+ ],
124
+ related: ['prompts', 'tools', 'contexts', 'skills', 'pgi', 'deploy'],
125
+ };
126
+ const PROMPTS = {
127
+ name: 'prompts',
128
+ title: 'Prompts, voice and model settings',
129
+ summary: 'Prompt sections, post-prompt summaries, languages, voices and LLM parameters',
130
+ body: `- The Prompt Object Model builds the prompt from titled sections:
131
+ \`promptAddSection(title, { body, bullets })\`, \`promptAddSubsection()\` and
132
+ \`promptAddToSection()\`. \`setPromptText()\` sets a plain prompt instead. A
133
+ subclass's \`static PROMPT_SECTIONS\` declares the sections on the class.
134
+ - \`setPostPrompt(text)\` asks the model for a summary when the conversation
135
+ ends. \`onSummary(summary, rawData)\` receives it.
136
+ - \`addLanguage({ name, code, voice })\` sets the language and voice.
137
+ \`addHints()\` and \`addPronunciation()\` help speech recognition and
138
+ text-to-speech with your vocabulary.
139
+ - \`setParams()\` sets the platform's AI settings. \`setPromptLlmParams()\` and
140
+ \`setPostPromptLlmParams()\` set model parameters such as \`temperature\` and
141
+ \`top_p\`. Nothing is sent unless you set it.
142
+ - \`setGlobalData()\` and \`updateGlobalData()\` hold session data for the call.
143
+ It isn't a database, and the model doesn't see all of it: tools, templates
144
+ and prompts expose what they choose.
145
+
146
+ Keep prompts short and put rules that matter in code: a prompt asks, a tool
147
+ handler enforces (\`sw-tsdocs pgi\`).
148
+ `,
149
+ docs: [
150
+ ['docs/agent-guide.md', 'Prompt building, languages and voices, global data'],
151
+ ['docs/llm_parameters.md', 'Model parameters for the prompt and post-prompt'],
152
+ ],
153
+ examples: [
154
+ 'examples/declarative.ts',
155
+ 'examples/pom-prompt.ts',
156
+ 'examples/llm-params.ts',
157
+ 'examples/session-state.ts',
158
+ ],
159
+ api: [
160
+ 'AgentBase.promptAddSection',
161
+ 'AgentBase.setPromptText',
162
+ 'AgentBase.setPostPrompt',
163
+ 'AgentBase.addLanguage',
164
+ 'AgentBase.setParams',
165
+ 'AgentBase.setPromptLlmParams',
166
+ 'AgentBase.setGlobalData',
167
+ ],
168
+ related: ['agents', 'tools', 'pgi'],
169
+ };
170
+ const TOOLS = {
171
+ name: 'tools',
172
+ title: 'Tools (SWAIG functions) and FunctionResult',
173
+ summary: 'Functions the model can call, and what they return',
174
+ body: `A tool is a function the model can ask to call. SignalWire posts the call to
175
+ the agent's \`/swaig\` endpoint, and the SDK runs your handler. Handlers may be
176
+ \`async\`; while one awaits, handlers for other calls run, so guard state they
177
+ share.
178
+
179
+ Give the parameters as a flat map and list the required ones; the handler's
180
+ \`args\` are typed from them, so don't annotate or cast \`args\`:
181
+
182
+ \`\`\`ts
183
+ import { AgentBase, FunctionResult } from '@signalwire/sdk';
184
+
185
+ const orders = new Map<string, { shippedOn: string }>();
186
+ const agent = new AgentBase({ name: 'orders', route: '/orders' });
187
+
188
+ agent.defineTool({
189
+ name: 'get_order_status',
190
+ description: "Look up an order's status.",
191
+ parameters: {
192
+ order_id: { type: 'string', description: 'The order number the caller gives' },
193
+ },
194
+ required: ['order_id'],
195
+ handler: (args) => {
196
+ const order = orders.get(args.order_id); // your code decides what's true
197
+ if (!order) return new FunctionResult('No order has that number.');
198
+ return new FunctionResult({
199
+ tool_result: \`Order \${args.order_id} shipped \${order.shippedOn}.\`,
200
+ tool_prompt: 'Tell the caller when the order shipped.',
201
+ });
202
+ },
203
+ });
204
+ \`\`\`
205
+
206
+ - The description and parameter descriptions are prompt text: the model reads
207
+ them to decide when to call the tool.
208
+ - \`FunctionResult\`'s response is context for the model, not speech. Keep facts
209
+ (\`tool_result\`) apart from instructions (\`tool_prompt\`).
210
+ - Actions such as \`connect()\`, \`hangup()\`, \`hold()\`, \`sendSms()\`,
211
+ \`updateGlobalData()\` and \`swmlChangeStep()\` run on the platform. Call
212
+ \`setPostProcess(true)\` when the caller must hear something before one lands.
213
+ - The handler's second argument, \`rawData\`, is the whole request (typed
214
+ \`SwaigRequest\`), with \`call_id\` and \`global_data\`.
215
+ - Tools are secure by default: each call must carry a token minted into that
216
+ call's SWML.
217
+ - A tool call is a request from the model, not an authorization. Check
218
+ identity, state and business rules in the handler.
219
+ `,
220
+ docs: [
221
+ ['docs/swaig-reference.md', 'Every FunctionResult method and action'],
222
+ ['docs/agent-guide.md', 'Defining tools, typed parameters, secure tools'],
223
+ ['docs/pgi_agent_guide.md', 'What a tool may decide, and what code must enforce'],
224
+ ],
225
+ examples: [
226
+ 'examples/swaig-features.ts',
227
+ 'examples/typed-tools.ts',
228
+ 'examples/call-flow.ts',
229
+ 'examples/session-state.ts',
230
+ 'examples/record-call.ts',
231
+ 'examples/room-and-sip.ts',
232
+ 'examples/tap.ts',
233
+ ],
234
+ api: [
235
+ 'AgentBase.defineTool',
236
+ 'FunctionResult',
237
+ 'FunctionResult.connect',
238
+ 'FunctionResult.swmlChangeStep',
239
+ 'FunctionResult.setPostProcess',
240
+ 'SwaigRequest',
241
+ ],
242
+ related: ['datamap', 'contexts', 'skills', 'security', 'pgi'],
243
+ };
244
+ const DATAMAP = {
245
+ name: 'datamap',
246
+ title: 'DataMap: tools that run on SignalWire',
247
+ summary: "Tools that call an HTTP API from SignalWire's servers, with no webhook to your code",
248
+ body: `A DataMap tool calls an HTTP API from SignalWire's servers, or matches
249
+ patterns in its arguments, and fills the result into the model's context from
250
+ a template. Your server isn't involved when the tool runs.
251
+
252
+ \`\`\`ts
253
+ import { AgentBase, DataMap, FunctionResult } from '@signalwire/sdk';
254
+
255
+ const agent = new AgentBase({ name: 'weather', route: '/weather' });
256
+ const weather = new DataMap('get_weather')
257
+ .description('Get the current weather for a city')
258
+ .parameter('city', 'string', 'City name', { required: true })
259
+ .webhook('GET', 'https://api.example.com/weather?city=\${enc:args.city}')
260
+ .output(new FunctionResult('Weather in \${input.args.city}: \${current.summary}'));
261
+ agent.registerSwaigFunction(weather.toSwaigFunction());
262
+ \`\`\`
263
+
264
+ - The templates are plain strings, not template literals: the platform
265
+ expands them, not the SDK.
266
+ - A webhook's URL and params read the call's data: \`\${args.city}\` for an
267
+ argument. A webhook's output reads its JSON response from the root, so an
268
+ API that returns \`{"current": {...}}\` is read as \`\${current.summary}\`,
269
+ with no \`response.\` prefix; an array response is \`\${array[0].x}\`; and
270
+ the arguments there are \`\${input.args.city}\`.
271
+ - The prefix helpers \`lc:\`, \`enc:\` and \`fmt_ph:\` transform a value. The
272
+ platform applies fmt_ph, then lc, then enc, whatever order they are written
273
+ in: \`\${lc:enc:args.city}\` lowercases \`args.city\`, then URL-encodes it.
274
+ \`enc\` takes no encoding name: \`\${enc:url:args.city}\` reads the path
275
+ \`url:args.city\` and expands to nothing.
276
+ - A webhook's \`params()\` are its JSON request body.
277
+ - \`swaig-test --exec\` simulates a DataMap tool locally, including its HTTP
278
+ request.
279
+ - Use DataMap for simple lookups. Use a \`defineTool()\` handler when the result
280
+ depends on your own logic, authorization or state.
281
+ `,
282
+ docs: [['docs/datamap-guide.md', 'The DataMap builder, templates, expressions and testing']],
283
+ examples: ['examples/datamap-tools.ts', 'examples/advanced-datamap.ts', 'examples/joke-agent.ts'],
284
+ api: [
285
+ 'DataMap',
286
+ 'AgentBase.registerSwaigFunction',
287
+ 'createSimpleApiTool',
288
+ 'createExpressionTool',
289
+ ],
290
+ related: ['tools', 'testing'],
291
+ };
292
+ const CONTEXTS = {
293
+ name: 'contexts',
294
+ title: 'Contexts and steps',
295
+ summary: 'Multi-step workflows, per-step tools, and gathering answers',
296
+ body: `\`defineContexts()\` returns a \`ContextBuilder\`. Each context holds steps, and
297
+ each step has its own prompt text, its own tools and its own exits:
298
+
299
+ \`\`\`ts
300
+ import { AgentBase } from '@signalwire/sdk';
301
+
302
+ const agent = new AgentBase({ name: 'accounts', route: '/accounts' });
303
+ const ctx = agent.defineContexts().addContext('default'); // a single context must be named "default"
304
+ ctx
305
+ .addStep('identify')
306
+ .setText("Ask for the caller's account number.")
307
+ .setFunctions(['verify_account'])
308
+ .setValidSteps([]);
309
+ ctx
310
+ .addStep('help')
311
+ .setText('Help with the account.')
312
+ .setFunctions(['get_balance', 'transfer_to_agent']);
313
+ \`\`\`
314
+
315
+ - Call \`setFunctions()\` on every step. A step that doesn't set it can keep the
316
+ previous step's tools; \`setFunctions([])\` gives it none.
317
+ - \`setValidSteps()\` and \`setValidContexts()\` limit where the model may move.
318
+ To move only after your code has checked something, leave them empty and
319
+ return \`new FunctionResult().swmlChangeStep(...)\` from the handler.
320
+ - \`setStepCriteria()\` guides the model; it doesn't enforce anything.
321
+ - \`setGatherInfo()\` and \`addGatherQuestion()\` collect answers one question
322
+ at a time.
323
+ `,
324
+ docs: [
325
+ ['docs/contexts-guide.md', 'Contexts, steps, navigation, gather mode and history'],
326
+ ['docs/pgi_agent_guide.md', 'Scoping tools per step and code-owned transitions'],
327
+ ],
328
+ examples: [
329
+ 'examples/contexts-steps.ts',
330
+ 'examples/gather-info.ts',
331
+ 'examples/gather-per-question-functions-demo.ts',
332
+ 'examples/step-function-inheritance-demo.ts',
333
+ ],
334
+ api: [
335
+ 'AgentBase.defineContexts',
336
+ 'ContextBuilder',
337
+ 'Context',
338
+ 'Step',
339
+ 'Step.setFunctions',
340
+ 'Step.setGatherInfo',
341
+ 'FunctionResult.swmlChangeStep',
342
+ ],
343
+ related: ['tools', 'pgi', 'prompts'],
344
+ };
345
+ const SKILLS = {
346
+ name: 'skills',
347
+ title: 'Skills: ready-made capabilities',
348
+ summary: 'Built-in skills (web search, datetime, DataSphere, ...) and writing your own',
349
+ body: `A skill adds tools, prompt sections and hints to an agent in one call:
350
+
351
+ \`\`\`ts
352
+ import { AgentBase, DateTimeSkill } from '@signalwire/sdk';
353
+
354
+ const agent = new AgentBase({ name: 'helper', route: '/helper' });
355
+ await agent.addSkill(new DateTimeSkill());
356
+ await agent.addSkillByName('web_search', { api_key: '...', search_engine_id: '...' });
357
+ \`\`\`
358
+
359
+ - \`addSkill()\` and \`addSkillByName()\` return promises: await them before the
360
+ agent serves.
361
+ - A skill that allows several instances takes a \`tool_name\` parameter, so each
362
+ instance gets its own tool.
363
+ - \`sw-tsdocs skills <name>\` shows a skill's parameters.
364
+ - Write your own by subclassing \`SkillBase\`: set the static \`SKILL_NAME\` and
365
+ \`SKILL_DESCRIPTION\`, and return the tools from \`getTools()\` (built with
366
+ \`defineSkillTool()\`); \`setup()\`, \`getPromptSections()\` and \`getHints()\`
367
+ are optional. \`registerSkill()\` registers the class, and
368
+ \`addSkillDirectory()\` or \`SIGNALWIRE_SKILL_PATHS\` load skills from a
369
+ directory.
370
+ `,
371
+ docs: [
372
+ ['docs/skills-guide.md', 'Using the built-in skills'],
373
+ ['docs/skills-system.md', 'How skills load, and how to write one'],
374
+ ['docs/skills_parameter_schema.md', 'How skills describe their parameters'],
375
+ ['docs/third_party_skills.md', 'Packaging and loading skills from outside the SDK'],
376
+ ],
377
+ examples: [
378
+ 'examples/skills-demo.ts',
379
+ 'examples/wikipedia.ts',
380
+ 'examples/web-search.ts',
381
+ 'examples/web-search-multi-instance.ts',
382
+ 'examples/datasphere.ts',
383
+ 'examples/datasphere-multi-instance.ts',
384
+ ],
385
+ api: [
386
+ 'AgentBase.addSkill',
387
+ 'AgentBase.addSkillByName',
388
+ 'SkillBase',
389
+ 'defineSkillTool',
390
+ 'registerSkill',
391
+ 'addSkillDirectory',
392
+ ],
393
+ related: ['agents', 'mcp', 'datamap'],
394
+ live: 'skills',
395
+ };
396
+ const PREFABS = {
397
+ name: 'prefabs',
398
+ title: 'Prefab agents',
399
+ summary: 'Ready-made agents for surveys, intake, reception, FAQs and concierge',
400
+ body: `Prefabs are \`AgentBase\` subclasses for common jobs. Configure one with its
401
+ constructor options, or subclass it to change its prompt and tools.
402
+ `,
403
+ docs: [['docs/prefabs-guide.md', 'Each prefab and its options']],
404
+ examples: [
405
+ 'examples/prefab-info-gatherer.ts',
406
+ 'examples/dynamic-info-gatherer.ts',
407
+ 'examples/prefab-survey.ts',
408
+ 'examples/prefab-receptionist.ts',
409
+ 'examples/prefab-concierge.ts',
410
+ 'examples/prefab-faq.ts',
411
+ ],
412
+ api: ['InfoGathererAgent', 'SurveyAgent', 'ReceptionistAgent', 'ConciergeAgent', 'FAQBotAgent'],
413
+ related: ['agents'],
414
+ live: 'prefabs',
415
+ };
416
+ const SWML = {
417
+ name: 'swml',
418
+ title: 'SWML services: call flows without an AI agent',
419
+ summary: 'Build and serve SWML documents: IVRs, routing, recording, any verb',
420
+ body: `SWML is the JSON document that tells SignalWire what to do with a call.
421
+ \`AgentBase\` writes one with an \`ai\` verb. \`SWMLService\` builds any document,
422
+ from any verbs, and serves it the same way:
423
+
424
+ \`\`\`ts
425
+ import { SWMLService } from '@signalwire/sdk';
426
+
427
+ const service = new SWMLService({ name: 'greeter', route: '/greeter' });
428
+ service.addVerb('answer', {});
429
+ service.addVerb('play', { url: 'say:Thanks for calling.' });
430
+ service.addVerb('hangup', {});
431
+ await service.serve();
432
+ \`\`\`
433
+
434
+ - Verbs are validated against the SWML schema that ships with the package
435
+ (\`dist/schema.json\`). \`SwmlBuilder\` also has a typed method for each verb,
436
+ such as \`play()\` and \`hangup()\`.
437
+ - \`setOnRequestCallback()\` builds the document per request.
438
+ - An \`AgentBase\` adds verbs around its \`ai\` verb: \`addPreAnswerVerb()\`,
439
+ \`addPostAnswerVerb()\` and \`addPostAiVerb()\`.
440
+ `,
441
+ docs: [
442
+ ['docs/swml_service_guide.md', 'SWMLService and SwmlBuilder'],
443
+ ['docs/architecture.md', 'How SWML documents are built and served'],
444
+ ],
445
+ examples: [
446
+ 'examples/swml-service.ts',
447
+ 'examples/dynamic-swml-service.ts',
448
+ 'examples/swml-service-routing.ts',
449
+ 'examples/auto-vivified.ts',
450
+ 'examples/verb-methods.ts',
451
+ 'examples/swmlservice_swaig_standalone.ts',
452
+ 'examples/swmlservice_ai_sidecar.ts',
453
+ ],
454
+ api: ['SWMLService', 'SwmlBuilder', 'SWMLService.addVerb', 'SWMLService.setOnRequestCallback'],
455
+ related: ['agents', 'relay', 'rest'],
456
+ };
457
+ const RELAY = {
458
+ name: 'relay',
459
+ title: 'RELAY: real-time call and message control',
460
+ summary: 'Drive live calls and messages over WebSocket with async code',
461
+ body: `\`RelayClient\` holds a WebSocket connection to SignalWire. Your code answers
462
+ and places calls, and then drives them step by step: play, record, collect
463
+ digits, detect, connect, conference, transcribe, and send or receive messages.
464
+
465
+ \`\`\`ts
466
+ import { RelayClient, Call } from '@signalwire/sdk';
467
+
468
+ const client = new RelayClient({ contexts: ['default'] }); // credentials from the environment
469
+
470
+ client.onCall(async (call: Call) => {
471
+ await call.answer();
472
+ const action = await call.play([{ type: 'tts', text: 'Welcome!' }]);
473
+ await action.wait();
474
+ await call.hangup();
475
+ });
476
+
477
+ await client.run();
478
+ \`\`\`
479
+
480
+ - Credentials come from the options or from \`SIGNALWIRE_PROJECT_ID\`,
481
+ \`SIGNALWIRE_API_TOKEN\` and \`SIGNALWIRE_SPACE\`.
482
+ - Operations that take time return an action: \`await action.wait()\` for its
483
+ result.
484
+ - Choose RELAY when your code controls the call, an AI agent when the model
485
+ holds the conversation, and REST for managing resources over HTTP.
486
+ `,
487
+ docs: [
488
+ ['relay/README.md', 'Overview of the RELAY client'],
489
+ ['relay/docs/getting-started.md', 'Connecting, receiving calls, first steps'],
490
+ ['relay/docs/guide.md', 'The RELAY guide: calls, actions, events and messaging'],
491
+ ['relay/docs/client-reference.md', 'RelayClient reference'],
492
+ ['relay/docs/call-methods.md', 'Every Call method'],
493
+ ['relay/docs/events.md', 'Events and their payloads'],
494
+ ['relay/docs/messaging.md', 'Sending and receiving messages'],
495
+ ],
496
+ examples: [
497
+ 'examples/quickstart-relay.ts',
498
+ 'examples/relay-demo.ts',
499
+ 'relay/examples/relay-inbound.ts',
500
+ 'relay/examples/relay-outbound.ts',
501
+ 'relay/examples/relay-messaging.ts',
502
+ ],
503
+ api: ['RelayClient', 'Call', 'Message', 'RelayClient.onCall', 'Call.play'],
504
+ related: ['rest', 'swml', 'agents'],
505
+ };
506
+ const REST = {
507
+ name: 'rest',
508
+ title: 'REST client',
509
+ summary: 'Manage SignalWire resources over HTTP: numbers, Fabric, calls, video, messaging',
510
+ body: `\`RestClient\` is an HTTP client with one namespace per API area. Each method
511
+ returns a promise of the response's JSON:
512
+
513
+ \`\`\`ts
514
+ import { RestClient } from '@signalwire/sdk';
515
+
516
+ const client = new RestClient(); // SIGNALWIRE_PROJECT_ID, SIGNALWIRE_API_TOKEN, SIGNALWIRE_SPACE
517
+ await client.phoneNumbers.search({ areacode: '512' });
518
+ await client.fabric.aiAgents.create({ name: 'Support Bot', prompt: { text: 'You are helpful.' } });
519
+ \`\`\`
520
+
521
+ - \`client.calling\` sends commands to live calls, such as play and record.
522
+ - Errors throw \`RestError\` (\`SignalWireRestError\`), with the status code and
523
+ body.
524
+ `,
525
+ docs: [
526
+ ['rest/README.md', 'Overview of the REST client'],
527
+ ['rest/docs/getting-started.md', 'Credentials and first requests'],
528
+ ['rest/docs/guide.md', 'The REST guide: namespaces, pagination and errors'],
529
+ ['rest/docs/client-reference.md', 'RestClient reference'],
530
+ ['rest/docs/namespaces.md', 'Every namespace and its operations'],
531
+ ['rest/docs/calling.md', 'Commands for live calls'],
532
+ ['rest/docs/fabric.md', 'Fabric resources: AI agents, subscribers, SWML scripts'],
533
+ ['rest/docs/phone-binding.md', 'Pointing a phone number at an agent or a SWML script'],
534
+ ],
535
+ examples: [
536
+ 'examples/quickstart-rest.ts',
537
+ 'rest/examples/rest-client.ts',
538
+ 'rest/examples/rest-manage-resources.ts',
539
+ 'rest/examples/rest-bind-phone-to-swml-webhook.ts',
540
+ 'rest/examples/rest-phone-number-management.ts',
541
+ 'rest/examples/rest-calling-play-and-record.ts',
542
+ 'rest/examples/rest-calling-ivr-and-ai.ts',
543
+ 'rest/examples/rest-fabric-swml-and-callflows.ts',
544
+ 'rest/examples/rest-fabric-subscribers-and-sip.ts',
545
+ 'rest/examples/rest-fabric-conferences-and-routing.ts',
546
+ 'rest/examples/rest-video-rooms.ts',
547
+ 'rest/examples/rest-queues-mfa-and-recordings.ts',
548
+ 'rest/examples/rest-datasphere-search.ts',
549
+ 'rest/examples/rest-10dlc-registration.ts',
550
+ ],
551
+ api: ['RestClient', 'RestError', 'ClientOptions'],
552
+ related: ['relay', 'swml', 'deploy'],
553
+ live: 'rest',
554
+ };
555
+ const LIVEWIRE = {
556
+ name: 'livewire',
557
+ title: 'LiveWire: LiveKit Agents code on SignalWire',
558
+ summary: 'Run agents written against the LiveKit Agents API on SignalWire',
559
+ body: `\`@signalwire/sdk/livewire\` (also the \`livewire\` export of the package root)
560
+ offers the LiveKit Agents API (\`Agent\`, \`AgentSession\`, \`tool\`, \`defineAgent\`,
561
+ \`runApp\` and friends), so LiveKit agent code can run on SignalWire with a
562
+ changed import. SignalWire's platform runs speech recognition, the LLM and
563
+ text-to-speech, so the speech plugin options are accepted for compatibility
564
+ and ignored, and an LLM plugin's model name sets the model.
565
+ `,
566
+ docs: [
567
+ ['livewire/README.md', 'What LiveWire supports'],
568
+ ['livewire/docs/migration-guide.md', 'Moving a LiveKit agent to LiveWire'],
569
+ ],
570
+ examples: [
571
+ 'livewire/examples/livewire-basic-agent.ts',
572
+ 'livewire/examples/livewire-multi-tool.ts',
573
+ 'livewire/examples/livewire-handoff.ts',
574
+ ],
575
+ api: ['livewire', 'livewire.Agent', 'livewire.AgentSession', 'livewire.tool', 'livewire.runApp'],
576
+ related: ['agents'],
577
+ };
578
+ const MCP = {
579
+ name: 'mcp',
580
+ title: 'MCP: Model Context Protocol',
581
+ summary: 'Expose agent tools over MCP, call MCP servers from agents, and the MCP gateway',
582
+ body: `- An agent as an MCP server: \`enableMcpServer()\` adds an \`/mcp\` endpoint
583
+ that offers the agent's tools to MCP clients. It requires the agent's basic
584
+ auth credentials.
585
+ - MCP servers as an agent's tools: \`addMcpServer(url, { headers })\` lets the
586
+ platform discover and call a remote MCP server's tools during the call.
587
+ - MCP servers that run locally: the \`mcp_gateway\` skill connects an agent to
588
+ an MCP gateway service, which bridges them to SWAIG tools.
589
+ `,
590
+ docs: [
591
+ ['docs/mcp_integration.md', 'The /mcp endpoint and addMcpServer()'],
592
+ ['docs/mcp_gateway_reference.md', 'The MCP gateway service and skill'],
593
+ ],
594
+ examples: ['examples/mcp-agent.ts', 'examples/mcp-gateway.ts'],
595
+ api: ['AgentBase.enableMcpServer', 'AgentBase.addMcpServer', 'McpGatewaySkill'],
596
+ related: ['tools', 'skills'],
597
+ };
598
+ const CHAT = {
599
+ name: 'chat',
600
+ title: 'AI chat: client, gateway and voice handoff',
601
+ summary: 'Text chat with an agent: AIChatClient, ChatGateway for browsers, HandoffRouter',
602
+ body: `The AI Chat service runs an agent's conversation over text instead of a call.
603
+
604
+ - \`AIChatClient\` calls the service from your server with the project's
605
+ credentials: \`createConversation()\`, \`chat()\` (a full model turn, so it
606
+ takes seconds), \`log()\`, \`summarize()\` and \`end()\`.
607
+ - \`ChatGateway\` lets a web page chat without the project token, which would
608
+ let every visitor spend the project's money. Mount \`gateway.router()\` on your
609
+ app (\`agent.mount(gateway.router(), { prefix: '/chat' })\`); the browser holds
610
+ only a publishable key. Keep \`maxNewConversations\` and \`maxTurns\` set:
611
+ they're the control on a leaked key, and \`allowedOrigins\` only contains
612
+ one.
613
+ - \`HandoffRouter\` adds the routes that move a conversation between chat and a
614
+ phone call and let the page type into a live call. The browser presents a
615
+ one-time nonce, never a call id.
616
+ - The gateway's caps and the router's nonces live in the process: run one
617
+ replica, use sticky routing, or supply shared storage.
618
+ - What the browser sends (\`user_meta_data\`) is the visitor's claim, never
619
+ authority.
620
+ `,
621
+ docs: [
622
+ ['docs/ai_chat.md', 'The chat client, the gateway and the voice handoff'],
623
+ ['docs/security.md', 'Credentials and what each protection covers'],
624
+ ],
625
+ api: ['AIChatClient', 'AIChatClient.chat', 'ChatGateway', 'ChatGatewayOptions', 'HandoffRouter'],
626
+ related: ['agents', 'security'],
627
+ };
628
+ const BEDROCK = {
629
+ name: 'bedrock',
630
+ title: 'Amazon Bedrock agents',
631
+ summary: "Agents that use Amazon Bedrock's speech-to-speech model",
632
+ body: `\`BedrockAgent\` is an \`AgentBase\` that renders an \`amazon_bedrock\` verb
633
+ instead of the standard \`ai\` verb. Prompts, tools and skills work the same
634
+ way. Speech hints, languages, pronunciation rules, multilingual settings and
635
+ contexts aren't part of the Bedrock verb, so they're left out of the SWML with
636
+ a warning. \`setInferenceParams()\` sets \`temperature\`, \`top_p\` and
637
+ \`max_tokens\`, which must be numbers, and \`setVoice()\` takes one of the
638
+ voices Bedrock offers.
639
+ \`createBedrockAgent()\` is a factory for the same class.
640
+ `,
641
+ docs: [['docs/bedrock_agent.md', "BedrockAgent's options and differences"]],
642
+ api: [
643
+ 'BedrockAgent',
644
+ 'BedrockAgentConfig',
645
+ 'BedrockAgent.setInferenceParams',
646
+ 'createBedrockAgent',
647
+ ],
648
+ related: ['agents'],
649
+ };
650
+ const DEPLOY = {
651
+ name: 'deploy',
652
+ title: 'Deploying agents',
653
+ summary: 'Servers, serverless platforms, containers, public URLs and TLS',
654
+ body: `- \`run()\` works out where it's running. As a plain process or in a container,
655
+ it starts a web server. On AWS Lambda, Google Cloud Functions, Azure
656
+ Functions or CGI, it handles the platform's event; \`runServerless()\` handles
657
+ one explicitly.
658
+ - SignalWire calls back to the URLs in the agent's SWML. Behind a proxy, load
659
+ balancer or tunnel, set \`SWML_PROXY_URL_BASE\` to the public base URL.
660
+ - Serve TLS directly with \`SWML_SSL_ENABLED\`, \`SWML_SSL_CERT_PATH\` and
661
+ \`SWML_SSL_KEY_PATH\`, or terminate it in front of the agent.
662
+ - Run several agents in one process with \`AgentServer\`, or mount one in an
663
+ existing app with \`getApp()\` or \`asRouter()\`.
664
+ - With more than one replica, set \`SIGNALWIRE_SWAIG_SECRET\` to the same value
665
+ on each, so a tool token minted by one validates on another.
666
+ - The SDK needs Node.js 22 or later.
667
+ `,
668
+ docs: [
669
+ ['docs/serverless-guide.md', 'Serverless platforms: detection, handlers and URLs'],
670
+ ['docs/cloud_functions_guide.md', 'Lambda, Google Cloud Functions and Azure Functions'],
671
+ ['docs/configuration.md', 'Config files and environment variables'],
672
+ ['docs/security.md', 'Auth, signatures, tokens and TLS in production'],
673
+ ['docs/web_service.md', 'Serving static files alongside agents'],
674
+ ],
675
+ examples: [
676
+ 'examples/serverless-lambda.ts',
677
+ 'examples/kubernetes-agent.ts',
678
+ 'examples/multi-agent.ts',
679
+ ],
680
+ api: [
681
+ 'AgentBase.run',
682
+ 'AgentBase.runServerless',
683
+ 'AgentServer',
684
+ 'AgentBase.getApp',
685
+ 'ServerlessAdapter',
686
+ ],
687
+ related: ['security', 'config', 'testing'],
688
+ };
689
+ const SECURITY = {
690
+ name: 'security',
691
+ title: 'Security',
692
+ summary: 'Basic auth, webhook signatures, tool tokens and URL-fetch protection',
693
+ body: `- Basic auth protects every endpoint except the \`/health\` and \`/ready\`
694
+ probes. Set \`SWML_BASIC_AUTH_USER\` and \`SWML_BASIC_AUTH_PASSWORD\`, or pass
695
+ \`basicAuth\`; otherwise the agent generates a password.
696
+ - Webhook signatures: with \`signingKey\` (or \`SIGNALWIRE_SIGNING_KEY\`), a POST
697
+ to the SWML route, \`/swaig\`, \`/post_prompt\` or a routing callback must carry
698
+ a valid SignalWire signature. A GET for the SWML document needs only basic
699
+ auth, and so does \`/mcp\`, which checks neither signatures nor tool tokens.
700
+ - Tool tokens: a secure tool called through \`/swaig\` runs only with the token
701
+ minted into that call's SWML. \`swaigSecret\` (or \`SIGNALWIRE_SWAIG_SECRET\`)
702
+ keeps tokens valid across replicas and restarts.
703
+ - The spider and web_search skills refuse private and internal addresses in
704
+ the URLs they fetch, checking every redirect. The mcp_gateway skill and
705
+ native_vector_search's \`remote_url\` check their URL once, at setup.
706
+ \`SWML_ALLOW_PRIVATE_URLS\` allows private addresses. docs/security.md has
707
+ the details.
708
+ - Security is also a design question: what the model can see and request, and
709
+ what the handlers enforce (\`sw-tsdocs pgi\`).
710
+ `,
711
+ docs: [
712
+ ['docs/security.md', 'Every security setting and what it protects'],
713
+ ['docs/pgi_agent_guide.md', 'Keeping authority in code, not in the model'],
714
+ ],
715
+ api: ['AgentBase.getBasicAuthCredentials', 'validateRequest', 'SessionManager', 'SslConfig'],
716
+ related: ['deploy', 'config', 'pgi', 'tools'],
717
+ };
718
+ const CONFIG = {
719
+ name: 'config',
720
+ title: 'Configuration and environment variables',
721
+ summary: "Config files, precedence, and the SDK's environment variables",
722
+ body: `Settings come from constructor options, then a config file (\`configFile\`),
723
+ then environment variables, then defaults, in that order of precedence.
724
+ Logging follows \`SIGNALWIRE_LOG_LEVEL\` (debug, info, warn, error), and
725
+ \`SIGNALWIRE_LOG_MODE=off\` turns it off.
726
+ `,
727
+ docs: [
728
+ ['docs/configuration.md', 'Config file format and lookup'],
729
+ ['docs/agent-guide.md', 'The environment variables section lists the main ones'],
730
+ ['docs/security.md', 'Security-related settings'],
731
+ ],
732
+ api: ['ConfigLoader', 'AgentOptions'],
733
+ related: ['deploy', 'security'],
734
+ live: 'env',
735
+ };
736
+ const TESTING = {
737
+ name: 'testing',
738
+ title: 'Testing agents',
739
+ summary: 'Test tools and SWML locally with swaig-test, and in unit tests',
740
+ body: `\`\`\`bash
741
+ npx swaig-test agent.ts --list-tools # the tools the agent defines
742
+ npx swaig-test agent.ts --dump-swml # the SWML document it serves
743
+ npx swaig-test agent.ts --exec lookup_order --order_id 1234
744
+ npx swaig-test agent.ts --simulate-serverless lambda --dump-swml
745
+ npx swaig-test agent.ts --verbose --exec lookup_order --order_id 1234 # with logs
746
+ \`\`\`
747
+
748
+ - \`swaig-test\` sends its requests through the agent's own HTTP app, as
749
+ SignalWire would. A \`.ts\` agent file needs a Node.js that runs TypeScript
750
+ (22.18 or later), or run \`swaig-test\` under \`npx tsx\`.
751
+ - Files with several agents: pick one with \`--route\` or \`--agent-class\`.
752
+ - In unit tests, construct the agent and call \`renderSwml()\`, or test your
753
+ domain code directly. Keep business rules in plain functions so they're
754
+ testable without the SDK.
755
+ - A local test doesn't prove the voice path. Place real calls before
756
+ production.
757
+ `,
758
+ docs: [
759
+ ['docs/cli-guide.md', "swaig-test's options and simulation"],
760
+ ['docs/pgi_agent_guide.md', 'Testing levels and adversarial scenarios'],
761
+ ],
762
+ examples: ['examples/README.md'],
763
+ api: ['AgentBase.renderSwml'],
764
+ related: ['cli', 'tools', 'datamap'],
765
+ };
766
+ const TUTORIALS = {
767
+ name: 'tutorials',
768
+ title: 'Tutorials',
769
+ summary: 'Three complete agents, built lesson by lesson and tested',
770
+ body: `- Fred: a voice agent that answers questions from Wikipedia, with a
771
+ skill, custom tools, swaig-test and Docker.
772
+ - Penny: a reservation line that keeps its rules when the model
773
+ misunderstands or a caller pushes. Every step names its tools, code moves
774
+ the conversation, and the business rules live outside the SDK. A worked
775
+ example of Programmatically Governed Inference (\`sw-tsdocs pgi\`).
776
+ - Multi-agent: a sales agent with knowledge-base search, then a triage agent
777
+ that hands callers to specialists on one AgentServer.
778
+ - Each tutorial's lessons quote its real code, and its tests run in the SDK's
779
+ own test suite.
780
+ `,
781
+ docs: [
782
+ ['tutorial/fred/tutorial/README.md', 'Fred, the Wikipedia agent'],
783
+ ['tutorial/full-guardrails-agent/tutorial/README.md', 'Penny, the full-guardrails agent'],
784
+ ['tutorial/multi_agents/README.md', 'The multi-agent tutorial'],
785
+ ],
786
+ examples: [],
787
+ api: ['AgentServer'],
788
+ related: ['pgi', 'skills', 'contexts'],
789
+ };
790
+ const CLI = {
791
+ name: 'cli',
792
+ title: 'Command-line tools',
793
+ summary: 'The commands the SDK installs',
794
+ body: `Run them with \`npx\` in a project that depends on \`@signalwire/sdk\`. Each
795
+ takes \`--help\`. \`swaig-test\` is documented in the CLI guide.
796
+ `,
797
+ docs: [['docs/cli-guide.md', "swaig-test's options, actions and simulation"]],
798
+ related: ['testing'],
799
+ live: 'cli',
800
+ };
801
+ const PGI = {
802
+ name: 'pgi',
803
+ title: 'Designing agents that stay within their rules (PGI)',
804
+ summary: 'What the model decides, what code enforces: read before building a real agent',
805
+ body: `Programmatically Governed Inference (PGI): program what the model can see and
806
+ request at each stage, while software stays responsible for what actually
807
+ happens. The model interprets language and picks from the tools you expose.
808
+ Your code owns identity, authorization, business rules, state changes and
809
+ side effects.
810
+
811
+ - A tool call is a request, not an authorization. Check it in the handler.
812
+ - Expose only the tools the current step needs, and set them on every step.
813
+ - Move between steps from code (\`swmlChangeStep()\`) when a check must pass
814
+ first. A prompt, a step's criteria or a model-supplied \`approved: true\` is
815
+ never the only enforcement.
816
+ - \`global_data\` is session data, not a database. Keep per-caller state off the
817
+ shared agent instance.
818
+ - A tool's response is context for the model, not speech.
819
+ - The substitution test: if the model were replaced by a scripted UI, would
820
+ the backend still enforce the same rules?
821
+
822
+ The guide has the full rules, a capability index, a tested reference
823
+ implementation (\`examples/pgi/\`), and testing and review checklists.
824
+ `,
825
+ docs: [
826
+ ['docs/pgi_agent_guide.md', 'The PGI implementation guide for coding agents'],
827
+ [
828
+ 'docs/programmatically_governed_inference.md',
829
+ 'The discipline itself: why the model gets no authority, and the four constraint layers',
830
+ ],
831
+ [
832
+ 'docs/developer_pain_points.md',
833
+ 'The problems the guide cites, what the SDK and platform provide, and what stays yours',
834
+ ],
835
+ ],
836
+ examples: ['examples/pgi/'],
837
+ api: ['Step.setFunctions', 'FunctionResult.swmlChangeStep', 'FunctionResult'],
838
+ related: ['tools', 'contexts', 'security', 'testing'],
839
+ };
840
+ /** Every topic, in the order the index lists them. */
841
+ export const TOPICS = [
842
+ QUICKSTART,
843
+ AGENTS,
844
+ PROMPTS,
845
+ TOOLS,
846
+ DATAMAP,
847
+ CONTEXTS,
848
+ SKILLS,
849
+ PREFABS,
850
+ PGI,
851
+ SWML,
852
+ RELAY,
853
+ REST,
854
+ LIVEWIRE,
855
+ MCP,
856
+ CHAT,
857
+ BEDROCK,
858
+ DEPLOY,
859
+ SECURITY,
860
+ CONFIG,
861
+ TESTING,
862
+ TUTORIALS,
863
+ CLI,
864
+ ];
865
+ /** The topics by name. */
866
+ export const TOPICS_BY_NAME = new Map(TOPICS.map((t) => [t.name, t]));
867
+ /** How the index groups the topics. */
868
+ export const TOPIC_GROUPS = [
869
+ [
870
+ 'Build AI agents',
871
+ [
872
+ 'quickstart',
873
+ 'agents',
874
+ 'prompts',
875
+ 'tools',
876
+ 'datamap',
877
+ 'contexts',
878
+ 'skills',
879
+ 'prefabs',
880
+ 'pgi',
881
+ 'tutorials',
882
+ ],
883
+ ],
884
+ ['Call control and APIs', ['swml', 'relay', 'rest']],
885
+ ['Integrations', ['livewire', 'mcp', 'chat', 'bedrock']],
886
+ ['Run and test', ['deploy', 'security', 'config', 'testing', 'cli']],
887
+ ];
888
+ /** The index's "start here" rows: what you want to do, and the topics to read. */
889
+ export const START_HERE = [
890
+ ['Answer calls with an AI agent', ['quickstart', 'agents']],
891
+ ['Design an agent that takes real actions safely', ['pgi']],
892
+ ['Learn by building a complete agent', ['tutorials']],
893
+ ['Give an agent tools', ['tools', 'datamap', 'skills']],
894
+ ['Build a multi-step workflow', ['contexts']],
895
+ ['Control live calls from code', ['relay']],
896
+ ['Manage numbers and resources', ['rest']],
897
+ ['Route calls without AI', ['swml']],
898
+ ['Chat with an agent from a web page', ['chat']],
899
+ ['Deploy', ['deploy', 'security']],
900
+ ['Test without a phone call', ['testing']],
901
+ ];
902
+ /** The index's short list of rules that prevent the most common mistakes. */
903
+ export const RULES_OF_THUMB = [
904
+ 'Check names and signatures with `sw-tsdocs api` instead of recalling them: ' +
905
+ 'the API changes between versions, and it differs from the Python SDK (camelCase, options objects).',
906
+ 'A tool call is a request from the model, not an authorization. Enforce ' +
907
+ 'identity, state and business rules in the handler.',
908
+ "A tool's response is context for the model, not speech. Keep facts " +
909
+ '(`tool_result`) apart from instructions (`tool_prompt`).',
910
+ 'Set the tools on every step of a workflow, and move between steps from code ' +
911
+ 'when a check must pass first.',
912
+ 'Keep per-caller state off the shared agent instance. `global_data` lasts for ' +
913
+ 'the call; anything durable belongs in your own storage.',
914
+ 'Test with `swaig-test` before a live call, and with a live call before production.',
915
+ ];
916
+ //# sourceMappingURL=topics.js.map