@signalwire/sdk 2.0.5 → 3.6.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 (659) hide show
  1. package/CHANGELOG.md +821 -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 +510 -126
  6. package/dist/AgentBase.js +1581 -455
  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 +186 -45
  21. package/dist/DataMap.js +210 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +309 -83
  24. package/dist/FunctionResult.js +483 -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 +169 -59
  58. package/dist/SWMLService.js +456 -129
  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/SemanticGate.d.ts +183 -0
  67. package/dist/SemanticGate.js +533 -0
  68. package/dist/SemanticGate.js.map +1 -0
  69. package/dist/ServerlessAdapter.d.ts +156 -7
  70. package/dist/ServerlessAdapter.js +399 -42
  71. package/dist/ServerlessAdapter.js.map +1 -1
  72. package/dist/SessionManager.d.ts +11 -2
  73. package/dist/SessionManager.js +50 -18
  74. package/dist/SessionManager.js.map +1 -1
  75. package/dist/SslConfig.d.ts +2 -1
  76. package/dist/SslConfig.js +4 -1
  77. package/dist/SslConfig.js.map +1 -1
  78. package/dist/SwaigActions.generated.d.ts +23 -0
  79. package/dist/SwaigActions.generated.js +8 -0
  80. package/dist/SwaigActions.generated.js.map +1 -0
  81. package/dist/SwaigContracts.d.ts +15 -0
  82. package/dist/SwaigContracts.generated.d.ts +264 -0
  83. package/dist/SwaigContracts.generated.js +12 -0
  84. package/dist/SwaigContracts.generated.js.map +1 -0
  85. package/dist/SwaigContracts.js +2 -0
  86. package/dist/SwaigContracts.js.map +1 -0
  87. package/dist/SwaigFunction.d.ts +139 -7
  88. package/dist/SwaigFunction.js +170 -22
  89. package/dist/SwaigFunction.js.map +1 -1
  90. package/dist/SwmlBuilder.d.ts +68 -19
  91. package/dist/SwmlBuilder.js +74 -38
  92. package/dist/SwmlBuilder.js.map +1 -1
  93. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  94. package/dist/SwmlVerbMethods.generated.js +1 -1
  95. package/dist/TypeInference.d.ts +39 -3
  96. package/dist/TypeInference.js +256 -16
  97. package/dist/TypeInference.js.map +1 -1
  98. package/dist/WebService.d.ts +79 -11
  99. package/dist/WebService.js +320 -109
  100. package/dist/WebService.js.map +1 -1
  101. package/dist/WebhookMiddleware.d.ts +119 -0
  102. package/dist/WebhookMiddleware.js +271 -0
  103. package/dist/WebhookMiddleware.js.map +1 -0
  104. package/dist/WebhookValidator.d.ts +92 -0
  105. package/dist/WebhookValidator.js +409 -0
  106. package/dist/WebhookValidator.js.map +1 -0
  107. package/dist/agents/BedrockAgent.d.ts +162 -0
  108. package/dist/agents/BedrockAgent.js +323 -0
  109. package/dist/agents/BedrockAgent.js.map +1 -0
  110. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  111. package/dist/ai-chat/AIChatClient.js +535 -0
  112. package/dist/ai-chat/AIChatClient.js.map +1 -0
  113. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  114. package/dist/ai-chat/ChatGateway.js +747 -0
  115. package/dist/ai-chat/ChatGateway.js.map +1 -0
  116. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  117. package/dist/ai-chat/HandoffRouter.js +518 -0
  118. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  119. package/dist/ai-chat/index.d.ts +12 -0
  120. package/dist/ai-chat/index.js +10 -0
  121. package/dist/ai-chat/index.js.map +1 -0
  122. package/dist/capabilities.d.ts +64 -0
  123. package/dist/capabilities.js +95 -0
  124. package/dist/capabilities.js.map +1 -0
  125. package/dist/cli/agent-loader.d.ts +32 -6
  126. package/dist/cli/agent-loader.js +92 -33
  127. package/dist/cli/agent-loader.js.map +1 -1
  128. package/dist/cli/datamap-exec.d.ts +175 -0
  129. package/dist/cli/datamap-exec.js +1284 -0
  130. package/dist/cli/datamap-exec.js.map +1 -0
  131. package/dist/cli/function-args.d.ts +40 -0
  132. package/dist/cli/function-args.js +146 -0
  133. package/dist/cli/function-args.js.map +1 -0
  134. package/dist/cli/simulation.d.ts +99 -0
  135. package/dist/cli/simulation.js +490 -0
  136. package/dist/cli/simulation.js.map +1 -0
  137. package/dist/cli/swaig-test.d.ts +12 -25
  138. package/dist/cli/swaig-test.js +935 -371
  139. package/dist/cli/swaig-test.js.map +1 -1
  140. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  141. package/dist/cli/tsdocs/agentsNote.js +92 -0
  142. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  143. package/dist/cli/tsdocs/api-index.json +1 -0
  144. package/dist/cli/tsdocs/api.d.ts +91 -0
  145. package/dist/cli/tsdocs/api.js +372 -0
  146. package/dist/cli/tsdocs/api.js.map +1 -0
  147. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  148. package/dist/cli/tsdocs/apiTypes.js +7 -0
  149. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  150. package/dist/cli/tsdocs/bin.d.ts +6 -0
  151. package/dist/cli/tsdocs/bin.js +23 -0
  152. package/dist/cli/tsdocs/bin.js.map +1 -0
  153. package/dist/cli/tsdocs/files.d.ts +108 -0
  154. package/dist/cli/tsdocs/files.js +287 -0
  155. package/dist/cli/tsdocs/files.js.map +1 -0
  156. package/dist/cli/tsdocs/index.d.ts +28 -0
  157. package/dist/cli/tsdocs/index.js +307 -0
  158. package/dist/cli/tsdocs/index.js.map +1 -0
  159. package/dist/cli/tsdocs/live.d.ts +41 -0
  160. package/dist/cli/tsdocs/live.js +202 -0
  161. package/dist/cli/tsdocs/live.js.map +1 -0
  162. package/dist/cli/tsdocs/locate.d.ts +51 -0
  163. package/dist/cli/tsdocs/locate.js +75 -0
  164. package/dist/cli/tsdocs/locate.js.map +1 -0
  165. package/dist/cli/tsdocs/render.d.ts +75 -0
  166. package/dist/cli/tsdocs/render.js +323 -0
  167. package/dist/cli/tsdocs/render.js.map +1 -0
  168. package/dist/cli/tsdocs/topics.d.ts +43 -0
  169. package/dist/cli/tsdocs/topics.js +920 -0
  170. package/dist/cli/tsdocs/topics.js.map +1 -0
  171. package/dist/index.d.ts +49 -68
  172. package/dist/index.js +45 -73
  173. package/dist/index.js.map +1 -1
  174. package/dist/livewire/index.d.ts +229 -155
  175. package/dist/livewire/index.js +298 -195
  176. package/dist/livewire/index.js.map +1 -1
  177. package/dist/llms.txt +65 -0
  178. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  179. package/dist/prefabs/CallSessionStore.js +72 -0
  180. package/dist/prefabs/CallSessionStore.js.map +1 -0
  181. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  182. package/dist/prefabs/ConciergeAgent.js +36 -31
  183. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  184. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  185. package/dist/prefabs/FAQBotAgent.js +113 -47
  186. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  187. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  188. package/dist/prefabs/InfoGathererAgent.js +67 -58
  189. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  190. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  191. package/dist/prefabs/ReceptionistAgent.js +39 -31
  192. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  193. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  194. package/dist/prefabs/SurveyAgent.js +84 -68
  195. package/dist/prefabs/SurveyAgent.js.map +1 -1
  196. package/dist/relay/Action.d.ts +44 -21
  197. package/dist/relay/Action.js +75 -17
  198. package/dist/relay/Action.js.map +1 -1
  199. package/dist/relay/Call.d.ts +312 -47
  200. package/dist/relay/Call.js +369 -18
  201. package/dist/relay/Call.js.map +1 -1
  202. package/dist/relay/Deferred.js.map +1 -1
  203. package/dist/relay/Message.d.ts +26 -5
  204. package/dist/relay/Message.js +36 -6
  205. package/dist/relay/Message.js.map +1 -1
  206. package/dist/relay/RelayClient.d.ts +44 -17
  207. package/dist/relay/RelayClient.js +175 -65
  208. package/dist/relay/RelayClient.js.map +1 -1
  209. package/dist/relay/RelayError.d.ts +14 -0
  210. package/dist/relay/RelayError.js +15 -0
  211. package/dist/relay/RelayError.js.map +1 -1
  212. package/dist/relay/RelayEvent.d.ts +96 -65
  213. package/dist/relay/RelayEvent.js +85 -56
  214. package/dist/relay/RelayEvent.js.map +1 -1
  215. package/dist/relay/closedSets.d.ts +111 -0
  216. package/dist/relay/closedSets.js +83 -0
  217. package/dist/relay/closedSets.js.map +1 -0
  218. package/dist/relay/index.d.ts +3 -1
  219. package/dist/relay/index.js +1 -0
  220. package/dist/relay/index.js.map +1 -1
  221. package/dist/relay/normalize.js.map +1 -1
  222. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  223. package/dist/relay/protocol.types.generated.js +8 -0
  224. package/dist/relay/protocol.types.generated.js.map +1 -0
  225. package/dist/relay/types.d.ts +73 -42
  226. package/dist/rest/HttpClient.d.ts +36 -8
  227. package/dist/rest/HttpClient.js +233 -40
  228. package/dist/rest/HttpClient.js.map +1 -1
  229. package/dist/rest/RequestOptions.d.ts +110 -0
  230. package/dist/rest/RequestOptions.js +113 -0
  231. package/dist/rest/RequestOptions.js.map +1 -0
  232. package/dist/rest/RestError.d.ts +52 -6
  233. package/dist/rest/RestError.js +89 -5
  234. package/dist/rest/RestError.js.map +1 -1
  235. package/dist/rest/base/CrudResource.d.ts +16 -26
  236. package/dist/rest/base/CrudResource.js +19 -33
  237. package/dist/rest/base/CrudResource.js.map +1 -1
  238. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  239. package/dist/rest/base/CrudWithAddresses.js +2 -2
  240. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  241. package/dist/rest/base/FabricResource.d.ts +15 -0
  242. package/dist/rest/base/FabricResource.js +16 -0
  243. package/dist/rest/base/FabricResource.js.map +1 -0
  244. package/dist/rest/base/ReadResource.d.ts +62 -0
  245. package/dist/rest/base/ReadResource.js +69 -0
  246. package/dist/rest/base/ReadResource.js.map +1 -0
  247. package/dist/rest/callHandler.d.ts +5 -2
  248. package/dist/rest/callHandler.js +4 -1
  249. package/dist/rest/callHandler.js.map +1 -1
  250. package/dist/rest/index.d.ts +18 -77
  251. package/dist/rest/index.js +47 -120
  252. package/dist/rest/index.js.map +1 -1
  253. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  254. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  255. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  256. package/dist/rest/namespaces/addresses.d.ts +3 -42
  257. package/dist/rest/namespaces/addresses.js +3 -50
  258. package/dist/rest/namespaces/addresses.js.map +1 -1
  259. package/dist/rest/namespaces/calling.d.ts +6 -378
  260. package/dist/rest/namespaces/calling.js +6 -473
  261. package/dist/rest/namespaces/calling.js.map +1 -1
  262. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  263. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  264. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  265. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  266. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  267. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  268. package/dist/rest/namespaces/chat.d.ts +4 -18
  269. package/dist/rest/namespaces/chat.js +4 -21
  270. package/dist/rest/namespaces/chat.js.map +1 -1
  271. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  272. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  273. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  274. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  275. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  276. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  277. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  278. package/dist/rest/namespaces/datasphere.js +6 -72
  279. package/dist/rest/namespaces/datasphere.js.map +1 -1
  280. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  281. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  282. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  283. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  284. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  285. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  286. package/dist/rest/namespaces/fabric.d.ts +11 -327
  287. package/dist/rest/namespaces/fabric.js +14 -439
  288. package/dist/rest/namespaces/fabric.js.map +1 -1
  289. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  290. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  291. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  293. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  294. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  296. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  297. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  298. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  299. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  300. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  301. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  302. package/dist/rest/namespaces/imported-numbers.js +3 -21
  303. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  304. package/dist/rest/namespaces/logs.d.ts +10 -101
  305. package/dist/rest/namespaces/logs.js +10 -128
  306. package/dist/rest/namespaces/logs.js.map +1 -1
  307. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  308. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  309. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  310. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  311. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  312. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  313. package/dist/rest/namespaces/lookup.d.ts +3 -25
  314. package/dist/rest/namespaces/lookup.js +3 -27
  315. package/dist/rest/namespaces/lookup.js.map +1 -1
  316. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  317. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  318. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  319. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  320. package/dist/rest/namespaces/message.types.generated.js +8 -0
  321. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  323. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  324. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  325. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  326. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  327. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  328. package/dist/rest/namespaces/mfa.d.ts +3 -42
  329. package/dist/rest/namespaces/mfa.js +3 -49
  330. package/dist/rest/namespaces/mfa.js.map +1 -1
  331. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  332. package/dist/rest/namespaces/number-groups.js +3 -53
  333. package/dist/rest/namespaces/number-groups.js.map +1 -1
  334. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  335. package/dist/rest/namespaces/phone-numbers.js +8 -230
  336. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  337. package/dist/rest/namespaces/project.d.ts +6 -42
  338. package/dist/rest/namespaces/project.js +6 -51
  339. package/dist/rest/namespaces/project.js.map +1 -1
  340. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  341. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  342. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  343. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  344. package/dist/rest/namespaces/project.types.generated.js +8 -0
  345. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  347. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  348. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  349. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  350. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  351. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  352. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  353. package/dist/rest/namespaces/pubsub.js +4 -21
  354. package/dist/rest/namespaces/pubsub.js.map +1 -1
  355. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  356. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  357. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  358. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  359. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  360. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  361. package/dist/rest/namespaces/queues.d.ts +3 -38
  362. package/dist/rest/namespaces/queues.js +3 -44
  363. package/dist/rest/namespaces/queues.js.map +1 -1
  364. package/dist/rest/namespaces/recordings.d.ts +3 -34
  365. package/dist/rest/namespaces/recordings.js +3 -40
  366. package/dist/rest/namespaces/recordings.js.map +1 -1
  367. package/dist/rest/namespaces/registry.d.ts +6 -137
  368. package/dist/rest/namespaces/registry.js +6 -173
  369. package/dist/rest/namespaces/registry.js.map +1 -1
  370. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  371. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  372. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  373. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  374. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  375. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  376. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  377. package/dist/rest/namespaces/short-codes.js +3 -41
  378. package/dist/rest/namespaces/short-codes.js.map +1 -1
  379. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  380. package/dist/rest/namespaces/sip-profile.js +3 -29
  381. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  382. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  383. package/dist/rest/namespaces/verified-callers.js +3 -34
  384. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  385. package/dist/rest/namespaces/video.d.ts +10 -227
  386. package/dist/rest/namespaces/video.js +10 -288
  387. package/dist/rest/namespaces/video.js.map +1 -1
  388. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  389. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  390. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  391. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  392. package/dist/rest/namespaces/video.types.generated.js +8 -0
  393. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  395. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  396. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  397. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  398. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  399. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  400. package/dist/rest/pagination.d.ts +5 -1
  401. package/dist/rest/pagination.js +40 -20
  402. package/dist/rest/pagination.js.map +1 -1
  403. package/dist/rest/types.d.ts +21 -3
  404. package/dist/schema.json +299 -98
  405. package/dist/skills/SkillBase.d.ts +111 -21
  406. package/dist/skills/SkillBase.js +100 -17
  407. package/dist/skills/SkillBase.js.map +1 -1
  408. package/dist/skills/SkillManager.d.ts +66 -13
  409. package/dist/skills/SkillManager.js +101 -20
  410. package/dist/skills/SkillManager.js.map +1 -1
  411. package/dist/skills/SkillName.d.ts +44 -0
  412. package/dist/skills/SkillName.js +2 -0
  413. package/dist/skills/SkillName.js.map +1 -0
  414. package/dist/skills/SkillRegistry.d.ts +22 -11
  415. package/dist/skills/SkillRegistry.js +47 -17
  416. package/dist/skills/SkillRegistry.js.map +1 -1
  417. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  418. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  419. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  420. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  421. package/dist/skills/builtin/ask_claude.js +36 -14
  422. package/dist/skills/builtin/ask_claude.js.map +1 -1
  423. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  424. package/dist/skills/builtin/claude_skills.js +19 -15
  425. package/dist/skills/builtin/claude_skills.js.map +1 -1
  426. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  427. package/dist/skills/builtin/custom_skills.js +26 -9
  428. package/dist/skills/builtin/custom_skills.js.map +1 -1
  429. package/dist/skills/builtin/datasphere.d.ts +5 -3
  430. package/dist/skills/builtin/datasphere.js +21 -22
  431. package/dist/skills/builtin/datasphere.js.map +1 -1
  432. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  433. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  434. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  435. package/dist/skills/builtin/datetime.d.ts +3 -1
  436. package/dist/skills/builtin/datetime.js +11 -7
  437. package/dist/skills/builtin/datetime.js.map +1 -1
  438. package/dist/skills/builtin/google_maps.d.ts +29 -14
  439. package/dist/skills/builtin/google_maps.js +89 -269
  440. package/dist/skills/builtin/google_maps.js.map +1 -1
  441. package/dist/skills/builtin/index.d.ts +8 -6
  442. package/dist/skills/builtin/index.js +8 -6
  443. package/dist/skills/builtin/index.js.map +1 -1
  444. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  445. package/dist/skills/builtin/info_gatherer.js +20 -12
  446. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  447. package/dist/skills/builtin/joke.d.ts +16 -6
  448. package/dist/skills/builtin/joke.js +54 -37
  449. package/dist/skills/builtin/joke.js.map +1 -1
  450. package/dist/skills/builtin/math.d.ts +3 -1
  451. package/dist/skills/builtin/math.js +14 -9
  452. package/dist/skills/builtin/math.js.map +1 -1
  453. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  454. package/dist/skills/builtin/mcp_gateway.js +77 -46
  455. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  456. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  457. package/dist/skills/builtin/native_vector_search.js +179 -61
  458. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  459. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  460. package/dist/skills/builtin/play_background_file.js +43 -122
  461. package/dist/skills/builtin/play_background_file.js.map +1 -1
  462. package/dist/skills/builtin/spider.d.ts +42 -4
  463. package/dist/skills/builtin/spider.js +277 -104
  464. package/dist/skills/builtin/spider.js.map +1 -1
  465. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  466. package/dist/skills/builtin/swml_transfer.js +45 -24
  467. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  468. package/dist/skills/builtin/weather_api.d.ts +24 -13
  469. package/dist/skills/builtin/weather_api.js +38 -30
  470. package/dist/skills/builtin/weather_api.js.map +1 -1
  471. package/dist/skills/builtin/web_search.d.ts +48 -10
  472. package/dist/skills/builtin/web_search.js +294 -100
  473. package/dist/skills/builtin/web_search.js.map +1 -1
  474. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  475. package/dist/skills/builtin/wikipedia_search.js +14 -13
  476. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  477. package/dist/skills/index.d.ts +3 -2
  478. package/dist/skills/index.js +1 -1
  479. package/dist/skills/index.js.map +1 -1
  480. package/dist/swml_verbs_generated.d.ts +2824 -0
  481. package/dist/swml_verbs_generated.js +12 -0
  482. package/dist/swml_verbs_generated.js.map +1 -0
  483. package/dist/types.d.ts +59 -6
  484. package/dist/web.d.ts +27 -0
  485. package/dist/web.js +20 -0
  486. package/dist/web.js.map +1 -0
  487. package/docs/agent-guide.md +1034 -0
  488. package/docs/ai_chat.md +560 -0
  489. package/docs/api-reference.md +3641 -0
  490. package/docs/architecture.md +846 -0
  491. package/docs/bedrock_agent.md +411 -0
  492. package/docs/cli-guide.md +403 -0
  493. package/docs/cloud_functions_guide.md +399 -0
  494. package/docs/configuration.md +548 -0
  495. package/docs/contexts-guide.md +884 -0
  496. package/docs/datamap-guide.md +1207 -0
  497. package/docs/developer_pain_points.md +548 -0
  498. package/docs/llm_parameters.md +298 -0
  499. package/docs/mcp_gateway_reference.md +354 -0
  500. package/docs/mcp_integration.md +162 -0
  501. package/docs/pgi_agent_guide.md +1820 -0
  502. package/docs/prefabs-guide.md +815 -0
  503. package/docs/programmatically_governed_inference.md +301 -0
  504. package/docs/sdk_features.md +501 -0
  505. package/docs/security.md +559 -0
  506. package/docs/serverless-guide.md +520 -0
  507. package/docs/skills-guide.md +1223 -0
  508. package/docs/skills-system.md +405 -0
  509. package/docs/skills_parameter_schema.md +417 -0
  510. package/docs/swaig-reference.md +1986 -0
  511. package/docs/swml_service_guide.md +573 -0
  512. package/docs/third_party_skills.md +410 -0
  513. package/docs/web_service.md +666 -0
  514. package/examples/README.md +202 -0
  515. package/examples/advanced-datamap.ts +108 -0
  516. package/examples/advanced-dynamic-config.ts +70 -0
  517. package/examples/auto-vivified.ts +95 -0
  518. package/examples/call-flow.ts +65 -0
  519. package/examples/comprehensive-dynamic.ts +125 -0
  520. package/examples/contexts-steps.ts +65 -0
  521. package/examples/custom-path.ts +45 -0
  522. package/examples/datamap-tools.ts +51 -0
  523. package/examples/datasphere-multi-instance.ts +66 -0
  524. package/examples/datasphere-serverless-env.ts +87 -0
  525. package/examples/datasphere-webhook-env.ts +65 -0
  526. package/examples/datasphere.ts +56 -0
  527. package/examples/declarative.ts +100 -0
  528. package/examples/dynamic-config.ts +54 -0
  529. package/examples/dynamic-info-gatherer.ts +69 -0
  530. package/examples/dynamic-swml-service.ts +67 -0
  531. package/examples/gather-info.ts +95 -0
  532. package/examples/gather-per-question-functions-demo.ts +139 -0
  533. package/examples/joke-agent.ts +34 -0
  534. package/examples/kubernetes-agent.ts +45 -0
  535. package/examples/llm-params.ts +75 -0
  536. package/examples/mcp-agent.ts +89 -0
  537. package/examples/mcp-gateway.ts +81 -0
  538. package/examples/multi-agent.ts +80 -0
  539. package/examples/multi-endpoint.ts +79 -0
  540. package/examples/pgi/case-domain.ts +114 -0
  541. package/examples/pgi/serve.ts +16 -0
  542. package/examples/pgi/support-agent.ts +265 -0
  543. package/examples/pom-prompt.ts +70 -0
  544. package/examples/prefab-concierge.ts +42 -0
  545. package/examples/prefab-faq.ts +58 -0
  546. package/examples/prefab-info-gatherer.ts +33 -0
  547. package/examples/prefab-receptionist.ts +36 -0
  548. package/examples/prefab-survey.ts +69 -0
  549. package/examples/quickstart-agent.ts +29 -0
  550. package/examples/quickstart-relay.ts +25 -0
  551. package/examples/quickstart-rest.ts +25 -0
  552. package/examples/record-call.ts +65 -0
  553. package/examples/relay-demo.ts +33 -0
  554. package/examples/room-and-sip.ts +93 -0
  555. package/examples/serverless-lambda.ts +43 -0
  556. package/examples/session-state.ts +83 -0
  557. package/examples/simple-agent.ts +36 -0
  558. package/examples/simple-static.ts +29 -0
  559. package/examples/skills-demo.ts +41 -0
  560. package/examples/step-function-inheritance-demo.ts +124 -0
  561. package/examples/swaig-features.ts +193 -0
  562. package/examples/swml-service-routing.ts +66 -0
  563. package/examples/swml-service.ts +38 -0
  564. package/examples/swmlservice_ai_sidecar.ts +104 -0
  565. package/examples/swmlservice_swaig_standalone.ts +79 -0
  566. package/examples/tap.ts +67 -0
  567. package/examples/typed-tools.ts +68 -0
  568. package/examples/verb-methods.ts +45 -0
  569. package/examples/web-search-multi-instance.ts +75 -0
  570. package/examples/web-search.ts +38 -0
  571. package/examples/wikipedia.ts +36 -0
  572. package/livewire/README.md +164 -0
  573. package/livewire/docs/migration-guide.md +251 -0
  574. package/livewire/examples/livewire-basic-agent.ts +74 -0
  575. package/livewire/examples/livewire-handoff.ts +196 -0
  576. package/livewire/examples/livewire-multi-tool.ts +121 -0
  577. package/package.json +85 -13
  578. package/relay/README.md +101 -0
  579. package/relay/docs/call-methods.md +622 -0
  580. package/relay/docs/client-reference.md +281 -0
  581. package/relay/docs/events.md +193 -0
  582. package/relay/docs/getting-started.md +221 -0
  583. package/relay/docs/guide.md +386 -0
  584. package/relay/docs/messaging.md +246 -0
  585. package/relay/examples/relay-inbound.ts +66 -0
  586. package/relay/examples/relay-messaging.ts +74 -0
  587. package/relay/examples/relay-outbound.ts +76 -0
  588. package/rest/README.md +141 -0
  589. package/rest/docs/calling.md +313 -0
  590. package/rest/docs/client-reference.md +149 -0
  591. package/rest/docs/fabric.md +192 -0
  592. package/rest/docs/getting-started.md +138 -0
  593. package/rest/docs/guide.md +421 -0
  594. package/rest/docs/namespaces.md +367 -0
  595. package/rest/docs/phone-binding.md +116 -0
  596. package/rest/examples/rest-10dlc-registration.ts +177 -0
  597. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  598. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  599. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  600. package/rest/examples/rest-client.ts +59 -0
  601. package/rest/examples/rest-datasphere-search.ts +81 -0
  602. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  603. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  604. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  605. package/rest/examples/rest-manage-resources.ts +64 -0
  606. package/rest/examples/rest-phone-number-management.ts +200 -0
  607. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  608. package/rest/examples/rest-video-rooms.ts +186 -0
  609. package/tutorial/fred/fred.ts +218 -0
  610. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  611. package/tutorial/fred/tutorial/02-setup.md +304 -0
  612. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  613. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  614. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  615. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  616. package/tutorial/fred/tutorial/README.md +56 -0
  617. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  618. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  619. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  620. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  621. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  622. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  623. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  624. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  625. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  626. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  627. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  628. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  629. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  630. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  631. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  632. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  633. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  634. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  635. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  636. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  637. package/tutorial/multi_agents/README.md +175 -0
  638. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  639. package/tutorial/multi_agents/extending_agents.ts +641 -0
  640. package/tutorial/multi_agents/knowledge.ts +59 -0
  641. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  642. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  643. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  644. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  645. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  646. package/tutorial/multi_agents/pc_builder.ts +529 -0
  647. package/tutorial/multi_agents/sales_agent.ts +88 -0
  648. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  649. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  650. package/tutorial/multi_agents/support_knowledge.md +256 -0
  651. package/dist/cli/mock-data.d.ts +0 -37
  652. package/dist/cli/mock-data.js +0 -80
  653. package/dist/cli/mock-data.js.map +0 -1
  654. package/dist/generateVerbTypes.d.ts +0 -11
  655. package/dist/generateVerbTypes.js +0 -265
  656. package/dist/generateVerbTypes.js.map +0 -1
  657. package/dist/rest/namespaces/compat.d.ts +0 -585
  658. package/dist/rest/namespaces/compat.js +0 -735
  659. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,846 @@
1
+ # SignalWire AI Agents TypeScript SDK Architecture
2
+
3
+ This page explains how the TypeScript SDK is put together. It covers the classes an agent is built from, how it renders SWML, and what happens to each request SignalWire sends it.
4
+
5
+ <!-- snippet-setup -->
6
+ ```ts
7
+ export {}; // treat each example as a module (top-level await)
8
+ declare global {
9
+ const agent: import('@signalwire/sdk').AgentBase;
10
+ const FunctionResult: typeof import('@signalwire/sdk').FunctionResult;
11
+ }
12
+ ```
13
+
14
+ ## Table of Contents
15
+
16
+ - [Overview](#overview)
17
+ - [Core Components](#core-components)
18
+ - [AgentBase](#agentbase)
19
+ - [PromptManager and PomBuilder](#promptmanager-and-pombuilder)
20
+ - [SwmlBuilder](#swmlbuilder)
21
+ - [SwaigFunction](#swaigfunction)
22
+ - [FunctionResult](#functionresult)
23
+ - [SessionManager](#sessionmanager)
24
+ - [ContextBuilder](#contextbuilder)
25
+ - [DataMap](#datamap)
26
+ - [Composition Architecture](#composition-architecture)
27
+ - [SWML Rendering Pipeline](#swml-rendering-pipeline)
28
+ - [Request Flow](#request-flow)
29
+ - [SWML Request (GET/POST /)](#swml-request-getpost-)
30
+ - [SWAIG Function Dispatch (POST /swaig)](#swaig-function-dispatch-post-swaig)
31
+ - [Post-Prompt Handler (POST /post_prompt)](#post-prompt-handler-post-post_prompt)
32
+ - [Tool System](#tool-system)
33
+ - [SwaigFunction Wrapper](#swaigfunction-wrapper)
34
+ - [Handler Signature](#handler-signature)
35
+ - [Result Serialization](#result-serialization)
36
+ - [DataMap Tools](#datamap-tools)
37
+ - [Session Management](#session-management)
38
+ - [Token Format](#token-format)
39
+ - [Token Generation](#token-generation)
40
+ - [Token Validation](#token-validation)
41
+ - [Proxy Detection](#proxy-detection)
42
+ - [Security Layers](#security-layers)
43
+ - [Basic Authentication](#basic-authentication)
44
+ - [CORS](#cors)
45
+ - [Security Headers](#security-headers)
46
+ - [Rate Limiting](#rate-limiting)
47
+ - [Allowed Hosts](#allowed-hosts)
48
+ - [Request Size Limits](#request-size-limits)
49
+ - [Webhook Signatures and TLS](#webhook-signatures-and-tls)
50
+ - [Extension Points](#extension-points)
51
+
52
+ ---
53
+
54
+ ## Overview
55
+
56
+ Each agent is an HTTP service. It serves a SWML document, the JSON call-flow instructions SignalWire runs. It also answers the SWAIG requests SignalWire sends when the model on the call uses a tool. The SDK builds on the [Hono](https://hono.dev/) web framework and uses Node.js `crypto` for its per-call tokens.
57
+
58
+ The diagram shows the parts of an agent and the requests of one call:
59
+
60
+ ```text
61
+ +--------------------------------------------------+
62
+ | AgentBase (extends SWMLService) |
63
+ | |
64
+ | +----------------+ +---------------------+ |
65
+ | | PromptManager | | SessionManager | |
66
+ | | +----------+ | | (per-call HMAC | |
67
+ | | |PomBuilder| | | tokens) | |
68
+ | | +----------+ | +---------------------+ |
69
+ | +----------------+ |
70
+ | |
71
+ | +----------------+ +---------------------+ |
72
+ | | SwmlBuilder | | Tool registry | |
73
+ | | (the SWML | | Map<name, | |
74
+ | | document) | | SwaigFunction or | |
75
+ | +----------------+ | DataMap object> | |
76
+ | +---------------------+ |
77
+ | +----------------+ +---------------------+ |
78
+ | | ContextBuilder | | SkillManager | |
79
+ | | (optional) | | | |
80
+ | +----------------+ +---------------------+ |
81
+ | |
82
+ | +--------------------------------------------+ |
83
+ | | Hono app | |
84
+ | | GET/POST {route} -> SWML | |
85
+ | | POST {route}/swaig -> tool handler | |
86
+ | | POST {route}/post_prompt -> onSummary() | |
87
+ | | GET {route}/health, /ready (no auth) | |
88
+ | +--------------------------------------------+ |
89
+ +--------------------------------------------------+
90
+
91
+ Inbound call
92
+ |
93
+ v
94
+ SignalWire --POST--> {route} (returns the SWML)
95
+ |
96
+ v
97
+ The platform runs the SWML; its ai verb starts the model
98
+ |
99
+ v
100
+ Model uses a tool --POST--> {route}/swaig (runs the handler)
101
+ |
102
+ v
103
+ Call ends --POST--> {route}/post_prompt (delivers the summary)
104
+ ```
105
+
106
+ SignalWire requests the SWML with a `POST` whose body describes the call. The agent route also answers `GET`, which is useful for testing with a browser or `curl`. `GET {route}/swaig` and `GET {route}/post_prompt` return the SWML too; only a `POST` runs a tool or delivers a summary.
107
+
108
+ ### AgentServer (Multi-Agent)
109
+
110
+ `AgentServer` hosts several agents on one port. `register(agent)` mounts the agent's route-relative router (`agent.asRouter()`) at the agent's route, so each agent's paths are its route plus the agent's own paths:
111
+
112
+ ```text
113
+ AgentServer (Hono)
114
+ |-- /sales, /sales/swaig, /sales/post_prompt -> sales agent
115
+ |-- /support, /support/swaig, /support/post_prompt -> support agent
116
+ |-- /health -> server health check
117
+ |-- /ready -> server readiness check
118
+ |-- / -> agent listing (if no agent is registered at /)
119
+ ```
120
+
121
+ `register()` copies the agent's routes when it's called. `setupSipRouting()` and `registerGlobalRoutingCallback()` can be called before or after it, even after the server has served requests: a change to the routes rebuilds the server's app, so the callback is served at the agent's route, such as `/sales/sip`.
122
+
123
+ ---
124
+
125
+ ## Core Components
126
+
127
+ ### AgentBase
128
+
129
+ **File**: `src/AgentBase.ts`
130
+
131
+ `AgentBase` extends `SWMLService` and holds the other components as fields. It's responsible for:
132
+
133
+ - **HTTP**: building the Hono app, its middleware and routes, and starting the server.
134
+ - **SWML rendering**: assembling the document from the call-flow verbs, the prompt, the tools and the AI settings.
135
+ - **Tool dispatch**: running the handler for a SWAIG request, after checking its per-call token.
136
+ - **Proxy detection**: finding the external URL for the webhook URLs in the SWML.
137
+ - **Per-request configuration**: making a per-request copy of the agent for a dynamic config callback.
138
+ - **Lifecycle hooks**: `onSummary`, `onFunctionCall`, `onSwmlRequest`, `onDebugEvent`, `onCallEnd` and `onError`.
139
+
140
+ `SWMLService` supplies the `SwmlBuilder`, the tool registry, basic-auth resolution, routing callbacks and `handleRequest()`, the framework-free request handler that the agent's SWML routes call.
141
+
142
+ ### PromptManager and PomBuilder
143
+
144
+ **Files**: `src/PromptManager.ts`, `src/PomBuilder.ts`
145
+
146
+ `PromptManager` holds the agent's prompt and post-prompt. The prompt has two forms:
147
+
148
+ 1. **Raw text**: a string set with `setPromptText()`. When set, it takes precedence over sections.
149
+ 2. **Sections (POM)**: a `PomBuilder` of sections added with `promptAddSection()`, used when the `usePom` option is `true` (the default).
150
+
151
+ Each section has a `title`, a `body`, `bullets` (optionally `numbered`) and `subsections`. The rendered SWML carries sections as a structured `prompt.pom` array. Raw text goes in `prompt.text`.
152
+
153
+ `PromptManager.getPrompt()` returns:
154
+ 1. The raw text, if set.
155
+ 2. The sections rendered as Markdown, if sections exist.
156
+ 3. An empty string otherwise.
157
+
158
+ ### SwmlBuilder
159
+
160
+ **File**: `src/SwmlBuilder.ts`
161
+
162
+ `SwmlBuilder` holds a SWML document:
163
+
164
+ ```json
165
+ {
166
+ "version": "1.0.0",
167
+ "sections": {
168
+ "main": [
169
+ { "answer": {} },
170
+ { "ai": { "prompt": { "text": "You are a support agent." } } },
171
+ { "hangup": {} }
172
+ ]
173
+ }
174
+ }
175
+ ```
176
+
177
+ It has these methods:
178
+
179
+ | Method | Description |
180
+ |--------|-------------|
181
+ | `reset()` | Replaces the document with an empty `{ version, sections: { main: [] } }`. |
182
+ | `addVerb(verbName, config)` | Validates the verb against the bundled schema, then appends `{ [verbName]: config }` to `main`. |
183
+ | `addVerbToSection(section, verb, config)` | Validates, then appends to a named section, creating it if needed. |
184
+ | `addSection(section)` | Adds an empty section. |
185
+ | `build()` | Returns the document object. |
186
+ | `render()` | Returns `JSON.stringify(document)`. |
187
+
188
+ The constructor also adds a method for each verb in the bundled schema, such as `answer()`, `play()` and `connect()`, which call `addVerb()` and return the builder. `SWML_SKIP_SCHEMA_VALIDATION=true` turns validation off.
189
+
190
+ `AgentBase.renderSwml()` calls `reset()`, adds every phase's verbs, and returns `render()`, so the builder holds only the latest render.
191
+
192
+ ### SwaigFunction
193
+
194
+ **File**: `src/SwaigFunction.ts`
195
+
196
+ `SwaigFunction` wraps a tool handler with the metadata SWAIG needs. Its main fields are:
197
+
198
+ <!-- snippet: no-compile field-shape reference for SwaigFunction; abbreviated types, not runnable -->
199
+ ```typescript
200
+ class SwaigFunction {
201
+ name: string; // Tool name, read by the model
202
+ handler: SwaigHandler; // The callback function
203
+ description: string; // Tells the model when to use the tool
204
+ parameters: Record; // JSON Schema for the arguments
205
+ secure: boolean; // Requires a per-call token (default true)
206
+ fillers?: Record; // Per-language filler phrases
207
+ waitFile?: string; // Audio to play while the tool runs
208
+ waitFileLoops?: number; // Loop count for the wait file
209
+ webhookUrl?: string; // External webhook, rendered in place of the agent's /swaig
210
+ required: string[]; // Required parameter names
211
+ extraFields: Record; // Additional SWAIG fields, merged into the definition
212
+ onError?: SwaigErrorHandler; // Per-tool error hook
213
+ errorMessage?: string; // Response when the handler throws
214
+ }
215
+ ```
216
+
217
+ `execute(args, rawData)` runs the handler and returns the result as a SWAIG response object. [Result Serialization](#result-serialization) lists how each return type is converted.
218
+
219
+ ### FunctionResult
220
+
221
+ **File**: `src/FunctionResult.ts`
222
+
223
+ `FunctionResult` is a builder for a tool's response. It carries:
224
+
225
+ - `response`: text returned to the model. It's context for the model, not speech: the model decides what to say.
226
+ - `action`: an ordered list of actions for the platform to run.
227
+ - `postProcess`: when `true`, the model gets one more turn to respond before the actions run.
228
+
229
+ A `FunctionResult` can also carry a structured response, `{ tool_result, tool_prompt }`, set with the constructor option or `setToolResponse()`. It separates the facts from the instructions for the model. `toDict()` serializes it:
230
+
231
+ <!-- snippet: no-compile method-body excerpt shown outside its class, not a standalone module -->
232
+ ```typescript
233
+ toDict(): SwaigResultDict {
234
+ const result: SwaigResultDict = {};
235
+ if (this._toolResponse && Object.keys(this._toolResponse).length > 0) {
236
+ result.response = { ...this._toolResponse };
237
+ } else if (this.response) {
238
+ result.response = this.response;
239
+ }
240
+ if (this.action.length > 0) result.action = this.action;
241
+ if (this.postProcess && this.action.length > 0) result.post_process = true;
242
+ if (Object.keys(result).length === 0) result.response = 'Action completed.';
243
+ return result;
244
+ }
245
+ ```
246
+
247
+ The fallback `"Action completed."` keeps the response from being empty.
248
+
249
+ The action methods fall into these groups:
250
+
251
+ | Category | Methods |
252
+ |----------|---------|
253
+ | Call control | `connect()`, `hangup()`, `hold()`, `stop()`, `waitForUser()` |
254
+ | Audio | `say()`, `playBackgroundFile()`, `stopBackgroundFile()` |
255
+ | Speech | `addDynamicHints()`, `clearDynamicHints()`, `setEndOfSpeechTimeout()` |
256
+ | Data | `updateGlobalData()`, `removeGlobalData()`, `setMetadata()`, `removeMetadata()` |
257
+ | SWML | `executeSwml()`, `swmlChangeStep()`, `swmlChangeContext()`, `swmlUserEvent()` |
258
+ | Context | `switchContext()` |
259
+ | Functions | `toggleFunctions()`, `enableFunctionsOnTimeout()`, `updateSettings()` |
260
+ | Comms | `sendSms()`, `recordCall()`, `stopRecordCall()`, `tap()`, `stopTap()`, `sipRefer()` |
261
+ | Rooms | `joinRoom()`, `joinConference()` |
262
+ | RPC | `executeRpc()`, `rpcDial()`, `rpcAiMessage()`, `rpcAiUnhold()` |
263
+ | Payments | `pay()` |
264
+
265
+ ### SessionManager
266
+
267
+ **File**: `src/SessionManager.ts`
268
+
269
+ `SessionManager` creates and checks the HMAC-SHA256 tokens that protect secure tools and the post-prompt URL. It stores nothing for a token: everything it needs is in the token. See [Session Management](#session-management).
270
+
271
+ ### ContextBuilder
272
+
273
+ **File**: `src/ContextBuilder.ts`
274
+
275
+ `ContextBuilder` defines multi-step conversations. It holds named contexts, each an ordered list of steps. A step has prompt content, completion criteria, the functions it allows, and the steps and contexts it can move to:
276
+
277
+ ```text
278
+ ContextBuilder
279
+ |-- Context "greeting"
280
+ | |-- Step "welcome" (text, criteria, functions)
281
+ | |-- Step "identify" (gather_info questions)
282
+ |
283
+ |-- Context "support"
284
+ |-- Step "diagnose" (POM sections, valid_steps)
285
+ |-- Step "resolve" (end: true)
286
+ ```
287
+
288
+ `defineContexts()` returns the agent's builder, creating it on first use. `renderSwml()` puts the contexts inside the `ai` verb's prompt object, as `prompt.contexts`.
289
+
290
+ ### DataMap
291
+
292
+ **File**: `src/DataMap.ts`
293
+
294
+ `DataMap` builds a tool that the SignalWire platform runs itself, without a request to the agent. A DataMap tool can have:
295
+
296
+ - **Webhooks**: HTTP requests to external APIs, with templates for the request and the output.
297
+ - **Expressions**: patterns matched against template values, each with its output.
298
+ - **Outputs**: `FunctionResult` objects, serialized as the tool's response.
299
+
300
+ DataMap tools are stored in the tool registry as plain objects, not `SwaigFunction` instances. For the template syntax, see the DataMap guide.
301
+
302
+ ---
303
+
304
+ ## Composition Architecture
305
+
306
+ The Python SDK builds `AgentBase` from several mixin classes. The TypeScript SDK has one level of inheritance, `AgentBase extends SWMLService`, and holds the rest as fields:
307
+
308
+ ```text
309
+ Python SDK TypeScript SDK
310
+ -------------------------- ---------------------------------------
311
+ class AgentBase( class SWMLService {
312
+ AuthMixin, WebMixin, swmlBuilder: SwmlBuilder
313
+ SWMLService, PromptMixin, toolRegistry: Map<...>
314
+ SkillMixin, AIConfigMixin, _app: Hono
315
+ ServerlessMixin, StateMixin, _routingCallbacks: Map<...>
316
+ MCPServerMixin) }
317
+ class AgentBase extends SWMLService {
318
+ _promptManager: PromptManager
319
+ sessionManager: SessionManager
320
+ _skillManager: SkillManager
321
+ contextsBuilder: ContextBuilder | null
322
+ perCallConfigs: DynamicConfigCallback[]
323
+ }
324
+ ```
325
+
326
+ The public methods on `AgentBase` delegate to these fields. For example, `setPromptText()` sets the prompt on the `PromptManager`. You configure an agent through its methods, and don't need to reach the fields.
327
+
328
+ The tool registry holds two kinds of entries: `SwaigFunction` instances for tools with a handler, and plain objects for DataMap tools.
329
+
330
+ A dynamic config callback, or one added with `addPerCallConfig()`, receives a per-request copy of the agent. The copy has its own prompt, tools, hints, languages, pronunciations, params, global data, call-flow verbs, contexts and routing callbacks. The callback's changes stay on that request. Skills the agent loaded are shared with the copy without running their setup again. The SWML is rendered from the copy, `/swaig` and `/post_prompt` requests run on it, and the original agent isn't modified.
331
+
332
+ ---
333
+
334
+ ## SWML Rendering Pipeline
335
+
336
+ `renderSwml(callId?, modifications?)` builds the SWML document for one call in five phases:
337
+
338
+ ```text
339
+ renderSwml(callId?, modifications?)
340
+ |
341
+ |-- defineTools() (once per agent), swmlBuilder.reset()
342
+ |-- callId: the argument, or a new random ID
343
+ |
344
+ |-- Build webhook URLs
345
+ | - base: external URL + route, with the basic-auth credentials in it
346
+ | - {base}/swaig with the SWAIG query params (defaults.web_hook_url)
347
+ | - a secure tool's URL adds __token, a token for that tool and call
348
+ | - {base}/post_prompt with a post_prompt token, if a post-prompt is set
349
+ |
350
+ |-- Build the SWAIG object
351
+ | - native_functions, includes, internal_fillers
352
+ | - functions[] from the tool registry:
353
+ | SwaigFunction: function, description, parameters,
354
+ | fillers, wait_file, wait_file_loops, web_hook_url, extra fields
355
+ | DataMap object: copied as it is
356
+ | - defaults.web_hook_url (when there are functions)
357
+ | - mcp_servers
358
+ |
359
+ |-- PHASE 1: pre-answer verbs (addPreAnswerVerb)
360
+ |-- PHASE 2: answer, if autoAnswer
361
+ |-- PHASE 3: record_call, if recordCall; post-answer verbs (addPostAnswerVerb)
362
+ |-- PHASE 4: the ai verb
363
+ | prompt: { pom: [...] } or { text: ... }, plus prompt LLM params,
364
+ | and contexts, if contexts are defined
365
+ | post_prompt, post_prompt_url
366
+ | SWAIG, hints, languages, multilingual, pronounce, params, global_data
367
+ | debug_webhook_url, debug_webhook_level, if debug events are on
368
+ | modifications from onSwmlRequest: global_data merged, other keys replaced
369
+ |-- PHASE 5: post-AI verbs (addPostAiVerb)
370
+ |
371
+ |-- Return swmlBuilder.render() (a JSON string)
372
+ ```
373
+
374
+ Verbs you add are validated against the bundled schema. The `answer`, `record_call` and `ai` verbs the agent builds itself aren't.
375
+
376
+ A document with every phase looks like this:
377
+
378
+ ```json
379
+ {
380
+ "version": "1.0.0",
381
+ "sections": {
382
+ "main": [
383
+ { "play": { "url": "https://example.com/ring.wav" } },
384
+ { "answer": {} },
385
+ { "record_call": { "format": "mp4", "stereo": true } },
386
+ {
387
+ "ai": {
388
+ "prompt": { "text": "..." },
389
+ "post_prompt": { "text": "..." },
390
+ "post_prompt_url": "https://user:pass@agents.example.com/support/post_prompt?__token=...",
391
+ "SWAIG": {
392
+ "functions": [ ... ],
393
+ "defaults": { "web_hook_url": "https://user:pass@agents.example.com/support/swaig" }
394
+ },
395
+ "hints": [ "SignalWire", "HIPAA" ],
396
+ "params": { "temperature": 0.7 },
397
+ "global_data": { "company": "Acme" }
398
+ }
399
+ },
400
+ { "hangup": {} }
401
+ ]
402
+ }
403
+ }
404
+ ```
405
+
406
+ ---
407
+
408
+ ## Request Flow
409
+
410
+ ### SWML Request (GET/POST /)
411
+
412
+ A request for the SWML goes through these steps:
413
+
414
+ ```text
415
+ Request from SignalWire (POST) or a browser (GET)
416
+ |
417
+ v
418
+ Hono middleware:
419
+ 1. Security headers (added to the response)
420
+ 2. Request size limit (SWML_MAX_REQUEST_SIZE)
421
+ 3. Allowed hosts (SWML_ALLOWED_HOSTS, if set)
422
+ 4. Rate limit (SWML_RATE_LIMIT, if set)
423
+ 5. CORS (SWML_CORS_ORIGINS)
424
+ 6. CSRF origin check (SWML_CSRF_PROTECTION, if set)
425
+ 7. Basic auth
426
+ 8. Webhook signature, for a POST (if a signing key is set)
427
+ |
428
+ v
429
+ Route handler:
430
+ 1. Proxy detection from the request headers (see Proxy Detection)
431
+ 2. Parse the JSON body (none for a GET)
432
+ |
433
+ v
434
+ handleRequest(method, url, headers, body):
435
+ 1. call_id: body.call_id or body.call.call_id for a POST; ?call_id= for a GET
436
+ 2. For a POST to a routing-callback path: run the callback;
437
+ a returned route is sent as a 307 redirect
438
+ 3. modifications = await onSwmlRequest(body, callbackPath, context)
439
+ 4. The agent to render from: a per-request copy configured by the
440
+ dynamic config callbacks, or this agent when there are none
441
+ 5. renderSwml(callId, modifications)
442
+ 6. Return 200 with the SWML
443
+ ```
444
+
445
+ ### SWAIG Function Dispatch (POST /swaig)
446
+
447
+ A tool request from SignalWire goes through these steps:
448
+
449
+ ```text
450
+ Request from SignalWire
451
+ |
452
+ v
453
+ Middleware (as for the SWML request; signature check when a signing key is set)
454
+ |
455
+ v
456
+ handleSwaig():
457
+ 1. Parse the JSON body
458
+ 2. Function name from body.function
459
+ - missing -> 400; longer than 128 characters or not an identifier -> 400
460
+ 3. The agent to run on: the per-request copy, when there are dynamic config callbacks
461
+ 4. Look the name up in that agent's tool registry
462
+ - not found, or not a SwaigFunction (a DataMap tool) -> 404 { error: "Unknown function: ..." }
463
+ 5. If the tool is secure: check __token (or token) from the URL against the
464
+ function name and body.call_id. A missing or invalid token gets a 200 response
465
+ whose text says the token is invalid or expired; the handler doesn't run.
466
+ 6. Arguments from body.argument.parsed[0], body.argument.raw, or body.arguments
467
+ 7. onFunctionCall(name, args, body): a returned value is sent instead of running the handler
468
+ 8. Run the handler with (args, body, agent), and send its result
469
+ ```
470
+
471
+ ### Post-Prompt Handler (POST /post_prompt)
472
+
473
+ The end-of-call summary goes through these steps:
474
+
475
+ ```text
476
+ Request from SignalWire at the end of the call
477
+ |
478
+ v
479
+ Middleware (as for the SWML request)
480
+ |
481
+ v
482
+ handlePostPrompt():
483
+ 1. Parse the JSON body
484
+ 2. call_id from the body, or the URL's ?call_id=; if both are present and differ -> 400
485
+ 3. Check __token for the post_prompt function and that call; missing or invalid -> 403
486
+ 4. The agent to run on: the per-request copy, when there are dynamic config callbacks
487
+ 5. findSummary(body): body.summary, else post_prompt_data.parsed[0],
488
+ else post_prompt_data.raw parsed as JSON, else the raw text, else null
489
+ 6. await onSummary(summary, body); an error it throws is logged
490
+ 7. Return { "success": true }, or onSummary's return value for a
491
+ fetch_conversation request
492
+ ```
493
+
494
+ ---
495
+
496
+ ## Tool System
497
+
498
+ ### SwaigFunction Wrapper
499
+
500
+ Each tool registered with `defineTool()` is a `SwaigFunction` in the tool registry, a `Map` keyed by name. `registerSwaigFunction()` stores a `SwaigFunction`, or a plain object for a DataMap tool:
501
+
502
+ <!-- snippet: no-compile registry illustration with `...` elision, not runnable -->
503
+ ```typescript
504
+ // Handler-based tool
505
+ toolRegistry.set('get_weather', new SwaigFunction({ name, handler, description, ... }));
506
+
507
+ // DataMap tool (plain object)
508
+ toolRegistry.set('lookup_zip', { function: 'lookup_zip', description: '...', data_map: {...} });
509
+ ```
510
+
511
+ Rendering walks the registry. A `SwaigFunction` becomes a definition with its schema and webhook URL. A plain object is copied as it is.
512
+
513
+ ### Handler Signature
514
+
515
+ A handler receives the arguments, the whole request body, and the agent the request runs on:
516
+
517
+ <!-- snippet: no-compile handler type-alias reference, not runnable code -->
518
+ ```typescript
519
+ type SwaigHandler = (
520
+ args: Record<string, unknown>, // Arguments the model supplied
521
+ rawData: SwaigRequest, // The full SWAIG request body
522
+ agent?: AgentBase, // The per-request copy, or the agent itself
523
+ ) => FunctionResult | Record<string, unknown> | string
524
+ | Promise<FunctionResult | Record<string, unknown> | string>;
525
+ ```
526
+
527
+ The third argument is the agent the request was configured on: the per-request copy when a dynamic config callback or `addPerCallConfig()` is in use. A handler that closes over the original agent sees the original, not the copy. The route awaits the handler. A synchronous or CPU-bound handler blocks Node's event loop, and every other request, until it returns.
528
+
529
+ ### Result Serialization
530
+
531
+ `SwaigFunction` converts the handler's result like this:
532
+
533
+ ```text
534
+ Handler returns:
535
+ |
536
+ |-- FunctionResult --> result.toDict()
537
+ |-- { response: ... } --> sent as it is
538
+ |-- object without response --> FunctionResult("Function completed successfully").toDict()
539
+ |-- anything else (a string) --> FunctionResult(String(value)).toDict()
540
+ |-- throws --> the tool's onError hook, then the agent's onError hook;
541
+ a FunctionResult either returns is sent. Otherwise
542
+ FunctionResult(errorMessage or the default message).toDict()
543
+ ```
544
+
545
+ `FunctionResult.toDict()` produces an object like this one:
546
+
547
+ ```json
548
+ {
549
+ "response": "The weather in Austin is 72F and sunny.",
550
+ "action": [
551
+ { "set_global_data": { "last_city": "Austin" } }
552
+ ]
553
+ }
554
+ ```
555
+
556
+ `post_process` appears only when it's `true` and there are actions. If both `response` and `action` are empty, the response is `"Action completed."`.
557
+
558
+ ### DataMap Tools
559
+
560
+ The SignalWire platform runs a DataMap tool itself, so it has a `data_map` key and no `web_hook_url`:
561
+
562
+ ```json
563
+ {
564
+ "function": "check_status",
565
+ "description": "Check order status",
566
+ "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } } },
567
+ "data_map": {
568
+ "webhooks": [
569
+ {
570
+ "url": "https://api.example.com/orders/${args.order_id}",
571
+ "method": "GET",
572
+ "output": { "response": "Order status: ${status}" }
573
+ }
574
+ ]
575
+ }
576
+ }
577
+ ```
578
+
579
+ A webhook's JSON response is read from the root of the template data (`${status}`). The URL and params read the arguments as `${args.name}`, and the webhook's output as `${input.args.name}`. A request for a DataMap tool at the agent's `/swaig` gets `404`, because the agent has no handler for it.
580
+
581
+ ---
582
+
583
+ ## Session Management
584
+
585
+ `SessionManager` creates and checks the per-call tokens for secure tools and for the post-prompt URL. It stores no state for them: a token carries everything the check needs.
586
+
587
+ ### Token Format
588
+
589
+ A token is the base64url encoding of five dot-separated fields:
590
+
591
+ ```text
592
+ base64url( callId . functionName . expiry . nonce . hmacSignature )
593
+ ```
594
+
595
+ | Field | Description |
596
+ |-------|-------------|
597
+ | `callId` | The call the token is for. |
598
+ | `functionName` | The function the token allows (`post_prompt` for the post-prompt URL). |
599
+ | `expiry` | Unix time, in seconds, when the token expires. |
600
+ | `nonce` | 16 random hex characters. |
601
+ | `hmacSignature` | The HMAC-SHA256 hex digest of `callId:functionName:expiry:nonce`. |
602
+
603
+ ### Token Generation
604
+
605
+ `generateToken()` builds the token:
606
+
607
+ <!-- snippet: no-compile method-body excerpt shown outside its class, not a standalone module -->
608
+ ```typescript
609
+ generateToken(functionName: string, callId: string): string {
610
+ const expiry = Math.floor(Date.now() / 1000) + this.tokenExpirySecs;
611
+ const nonce = randomBytes(8).toString('hex');
612
+ const message = `${callId}:${functionName}:${expiry}:${nonce}`;
613
+ const signature = createHmac('sha256', this.secretKey).update(message).digest('hex');
614
+ const token = `${callId}.${functionName}.${expiry}.${nonce}.${signature}`;
615
+ return Buffer.from(token).toString('base64url');
616
+ }
617
+ ```
618
+
619
+ The secret key is the `swaigSecret` option, else `SIGNALWIRE_SWAIG_SECRET`, else 32 random bytes generated when the agent is created. With a random key, tokens stop validating after a restart and on other replicas, so set the same secret on every replica. Tokens last `tokenExpirySecs` seconds, 3600 by default for an agent. `renderSwml()` creates them and puts them in the `__token` query parameter of each secure tool's webhook URL and of the post-prompt URL.
620
+
621
+ ### Token Validation
622
+
623
+ For each `/swaig` request for a secure tool, and each `/post_prompt` request, the agent checks the token:
624
+
625
+ 1. Decode the base64url token and split it into fields. The last four are the function, expiry, nonce and signature; the rest is the call ID, which can contain dots.
626
+ 2. Reject it if the request has no call ID.
627
+ 3. Check that the function name matches the request.
628
+ 4. Check that the expiry hasn't passed.
629
+ 5. Recompute the HMAC-SHA256 signature and compare it in constant time.
630
+ 6. Check that the call ID matches the request's.
631
+
632
+ A secure tool with a missing or failed token doesn't run. The response is `200` with a response text saying the token is invalid or expired. A `/post_prompt` request with a missing or failed token gets `403`.
633
+
634
+ ### Session Metadata
635
+
636
+ `SessionManager` also has an in-memory store keyed by session ID, in this process only:
637
+
638
+ <!-- snippet: no-compile bare method signatures shown for reference, not runnable -->
639
+ ```typescript
640
+ setSessionMetadata(sessionId: string, metadata: Record<string, unknown>): void;
641
+ getSessionMetadata(sessionId: string): Record<string, unknown>;
642
+ deleteSessionMetadata(sessionId: string): boolean;
643
+ ```
644
+
645
+ The token checks don't use it. It isn't shared between replicas, and it's lost on a restart.
646
+
647
+ ---
648
+
649
+ ## Proxy Detection
650
+
651
+ Behind a reverse proxy (nginx, a load balancer, a tunnel), the agent needs its external URL to build the webhook URLs in its SWML. It chooses the base URL like this:
652
+
653
+ 1. **`SWML_PROXY_URL_BASE`**, read when the agent is created. While it's set, request headers never change the base URL.
654
+ 2. **`manualSetProxyUrl(url)`**, which replaces the base URL from then on.
655
+ 3. **Request headers**, only with `SWML_TRUST_PROXY_HEADERS=true` and without `SWML_PROXY_URL_BASE`. On each SWML request, the agent reads, in order:
656
+ - `X-Forwarded-Host`, with `X-Forwarded-Proto` (default `https`)
657
+ - `Forwarded` (RFC 7239), its `host=` and `proto=` values
658
+ - `X-Original-Host`, with `X-Forwarded-Proto`
659
+ - `X-Forwarded-For` alone has no host; with `SWML_PROXY_DEBUG=true`, the agent logs that it can't determine the host.
660
+ 4. **Serverless**: on a detected serverless platform, the platform's URL for the function.
661
+ 5. **Fallback**: `http://{host}:{port}`, with `localhost` for the host `0.0.0.0`, and `https` when `SWML_ENFORCE_HTTPS=true`.
662
+
663
+ A base URL found from headers stays in effect for later requests until other headers replace it.
664
+
665
+ ### Webhook URL Building
666
+
667
+ `buildWebhookUrl(endpoint, extraParams?)` builds each webhook URL:
668
+
669
+ <!-- snippet: no-compile bare method signature shown for reference, not runnable -->
670
+ ```typescript
671
+ buildWebhookUrl(endpoint: string, extraParams?: Record<string, string>): string
672
+ ```
673
+
674
+ It follows these steps:
675
+
676
+ 1. Call `getFullUrl(true)` for the base URL and route, with the basic-auth credentials in it.
677
+ 2. Append the endpoint (`swaig`, `post_prompt` or `debug_events`).
678
+ 3. Append the query parameters: the SWAIG query params and, for a secure tool, `__token`.
679
+
680
+ A generated URL looks like this:
681
+
682
+ ```text
683
+ https://admin:a-long-random-password@agents.example.com/support/swaig?tenant=acme&__token=...
684
+ ```
685
+
686
+ ---
687
+
688
+ ## Security Layers
689
+
690
+ The agent's security settings are Hono middleware on its app. [Configuration](configuration.md) lists every variable.
691
+
692
+ ### Basic Authentication
693
+
694
+ Every route except `/health` and `/ready` requires HTTP Basic Authentication. The agent resolves the credentials in this order:
695
+
696
+ 1. The `basicAuth` constructor option.
697
+ 2. The config file's `security.auth.basic` (or `security.basicAuth`) password.
698
+ 3. `SWML_BASIC_AUTH_PASSWORD`, with `SWML_BASIC_AUTH_USER` or `signalwire` as the username.
699
+ 4. Generated: `SWML_BASIC_AUTH_USER` or the agent's name, and 32 random hex characters.
700
+
701
+ The credentials are in the webhook URLs of the SWML, so SignalWire authenticates when it calls the agent back. The routes check credentials through `validateBasicAuth()`, which compares them with the configured pair in constant time and which a subclass can override.
702
+
703
+ ### CORS
704
+
705
+ `SWML_CORS_ORIGINS` sets the allowed origins:
706
+
707
+ <!-- snippet: no-compile illustrative Hono middleware calls, not a standalone program -->
708
+ ```typescript
709
+ // Default: any origin, without credentials
710
+ cors({ origin: '*', credentials: false })
711
+
712
+ // SWML_CORS_ORIGINS=https://app.example.com,https://admin.example.com
713
+ cors({ origin: ['https://app.example.com', 'https://admin.example.com'], credentials: true })
714
+ ```
715
+
716
+ With `SWML_CSRF_PROTECTION=true` and a `SWML_CORS_ORIGINS` list, a `POST` whose `Origin` header isn't in the list gets `403`.
717
+
718
+ ### Security Headers
719
+
720
+ Every response from the agent's routes carries these headers:
721
+
722
+ | Header | Value |
723
+ |--------|-------|
724
+ | `X-Content-Type-Options` | `nosniff` |
725
+ | `X-Frame-Options` | `DENY` |
726
+ | `X-XSS-Protection` | `1; mode=block` |
727
+ | `Referrer-Policy` | `strict-origin-when-cross-origin` |
728
+ | `Content-Security-Policy` | `default-src 'none'; frame-ancestors 'none'` |
729
+ | `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` |
730
+
731
+ An app added with `mount()` sets its own headers and CORS, and isn't behind the agent's basic auth.
732
+
733
+ ### Rate Limiting
734
+
735
+ When `SWML_RATE_LIMIT` is set, it's the number of requests allowed per minute per client IP:
736
+
737
+ - With `SWML_TRUST_PROXY_HEADERS=true`, the IP is the first `X-Forwarded-For` entry, else `X-Real-IP`, else the connection's address. Without it, the IP is the connection's address.
738
+ - An in-memory `Map` counts requests per IP, in 60-second windows.
739
+ - A request over the limit gets `429` `{"error":"Rate limit exceeded"}`.
740
+
741
+ ### Allowed Hosts
742
+
743
+ When `SWML_ALLOWED_HOSTS` is set to a comma-separated list of host names:
744
+
745
+ - The agent reads the `Host` header, drops the port and lowercases it.
746
+ - A host not in the list gets `403`.
747
+
748
+ ### Request Size Limits
749
+
750
+ The agent checks each request's `Content-Length` against `SWML_MAX_REQUEST_SIZE`, 1048576 bytes (1 MB) by default:
751
+
752
+ - A larger or non-numeric value gets `413` `{"error":"Request too large"}`.
753
+ - A request without `Content-Length` isn't checked.
754
+
755
+ ### Webhook Signatures and TLS
756
+
757
+ A signing key comes from the `signingKey` option or `SIGNALWIRE_SIGNING_KEY`. With one, a `POST` to the agent route, `/swaig`, `/post_prompt` or a routing-callback path needs a valid SignalWire signature, or gets `403`. `GET` requests aren't checked.
758
+
759
+ `AgentBase.serve()` serves HTTPS when `SWML_SSL_ENABLED`, `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH` are set, and plain HTTP otherwise. Behind a TLS-terminating proxy, set `SWML_PROXY_URL_BASE` to its `https` URL.
760
+
761
+ ---
762
+
763
+ ## Extension Points
764
+
765
+ ### Lifecycle Hooks (Override in Subclass)
766
+
767
+ A subclass can override these methods:
768
+
769
+ | Hook | Signature | When Called |
770
+ |------|-----------|------------|
771
+ | `defineTools()` | `protected defineTools(): void` | Once, the first time tools are needed: `renderSwml()`, `getTools()`, `getApp()`/`serve()` or a SWAIG request. Register tools here with `this.defineTool()`. |
772
+ | `onSummary(summary, rawData)` | returns `void`, or a value for `fetch_conversation` | For each valid `/post_prompt` request, on the per-request copy. |
773
+ | `onFunctionCall(name, args, rawData)` | returns `void`, or a result to send instead | Before each tool handler runs at `/swaig`. |
774
+ | `onSwmlRequest(rawData, callbackPath?, context?)` | returns `void`, or modifications for the `ai` verb | On each SWML request, on the agent itself, before the per-request copy is made. `context` is the Hono context. |
775
+ | `onDebugEvent(event)` | `void \| Promise<void>` | For each `POST /debug_events`. |
776
+
777
+ These methods register handlers instead of being overridden:
778
+
779
+ - `onError(handler)`: called when a tool handler throws, after the tool's own `onError`. A `FunctionResult` it returns is sent as the response.
780
+ - `onCallEnd(handler)`: registers the reserved `hangup_hook` tool and turns on `swaig_post_conversation`, so the handler gets the call log when the call ends.
781
+
782
+ ### Dynamic Configuration Callback
783
+
784
+ `setDynamicConfigCallback()` registers a callback that configures a per-request copy of the agent:
785
+
786
+ ```typescript
787
+ agent.setDynamicConfigCallback(async (queryParams, bodyParams, headers, callAgent) => {
788
+ // Configure callAgent; the original agent is unchanged
789
+ if (queryParams['tier'] === 'gold') {
790
+ callAgent.promptAddSection('Priority', { body: 'This caller has priority support.' });
791
+ }
792
+ });
793
+ ```
794
+
795
+ The callback receives the request's query parameters, body and headers (with credential-bearing headers removed), and the copy. `addPerCallConfig()` adds another callback to the chain, and `setDynamicConfigCallback()` replaces the chain. [Composition Architecture](#composition-architecture) describes what the copy has of its own.
796
+
797
+ A field a subclass adds is shared between the copy and the agent. Assigning a new value to it on the copy is safe; changing a shared object in place affects every request.
798
+
799
+ ### Declarative PROMPT_SECTIONS
800
+
801
+ A subclass can declare its prompt sections as a static field:
802
+
803
+ <!-- snippet: no-compile bare static-field type signature shown for reference, not runnable -->
804
+ ```typescript
805
+ static PROMPT_SECTIONS?: {
806
+ title: string;
807
+ body?: string;
808
+ bullets?: string[];
809
+ numbered?: boolean;
810
+ }[];
811
+ ```
812
+
813
+ The `AgentBase` constructor adds each entry with `promptAddSection()`.
814
+
815
+ ### Skills System
816
+
817
+ Skills are packages of tools, prompt sections, hints and global data:
818
+
819
+ ```typescript
820
+ import { DateTimeSkill } from '@signalwire/sdk';
821
+
822
+ await agent.addSkill(new DateTimeSkill());
823
+ ```
824
+
825
+ `addSkill()` runs the skill's setup, which registers its tools, prompt sections, hints and global data on the agent. `addSkillByName(name, params)` creates a skill from the registry first.
826
+
827
+ ### Webhook URL Overrides
828
+
829
+ Two methods replace the webhook URLs the agent generates:
830
+
831
+ ```typescript
832
+ agent.setWebHookUrl('https://custom-swaig-endpoint.example.com/swaig');
833
+ agent.setPostPromptUrl('https://custom-endpoint.example.com/post_prompt');
834
+ ```
835
+
836
+ `setWebHookUrl()` replaces `defaults.web_hook_url`; a secure tool still gets its own URL with a token. `setPostPromptUrl()` replaces `post_prompt_url`.
837
+
838
+ ### Debug Events
839
+
840
+ `enableDebugEvents(level)` turns on debug webhooks, with level 1 by default:
841
+
842
+ ```typescript
843
+ agent.enableDebugEvents(2);
844
+ ```
845
+
846
+ The SWML then has `debug_webhook_url` (the agent's `/debug_events`) and `debug_webhook_level` in the `ai` verb. Each `POST /debug_events` calls `onDebugEvent()`.