@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
@@ -5,24 +5,33 @@
5
5
  * into a single HTTP-servable agent.
6
6
  */
7
7
  import { Hono } from 'hono';
8
+ import type { Context } from 'hono';
9
+ import type { HostAppRouter } from './web.js';
8
10
  import { PromptManager } from './PromptManager.js';
9
11
  import { PromptObjectModel } from './POM/PromptObjectModel.js';
10
12
  import { SWMLService } from './SWMLService.js';
11
- import { SwaigFunction, type SwaigHandler } from './SwaigFunction.js';
13
+ import { SwaigFunction, type SwaigErrorHandler } from './SwaigFunction.js';
14
+ import { type TypedToolHandler } from './TypeInference.js';
12
15
  import { ContextBuilder } from './ContextBuilder.js';
16
+ import { type Logger } from './Logger.js';
13
17
  import { SkillManager } from './skills/SkillManager.js';
14
18
  import type { SkillBase, SkillConfig } from './skills/SkillBase.js';
19
+ import type { SkillNameOrString } from './skills/SkillName.js';
15
20
  import { type ServerlessEvent, type ServerlessResponse } from './ServerlessAdapter.js';
16
21
  import type { AgentOptions, LanguageConfig, PronunciationRule, FunctionInclude, DynamicConfigCallback } from './types.js';
22
+ import type { SwmlRequestData } from './PlatformContracts.js';
23
+ import type { SwaigRequest, PostPrompt, PostPromptData } from './SwaigContracts.js';
17
24
  /**
18
25
  * Callback invoked at a registered routing endpoint to determine how to handle an
19
26
  * incoming request. Return a route string to redirect to that agent route, or
20
27
  * null / undefined to let normal SWML processing continue.
21
28
  *
22
- * Mirrors Python `web_mixin.register_routing_callback` callback signature (body-only
23
- * variant — Hono request object is not forwarded; use the parsed body instead).
29
+ * Mirrors Python `web_mixin.register_routing_callback` callback signature. Python
30
+ * decomposed the routing callback to `callback_fn(body, headers)` — the parsed body
31
+ * plus the request headers (the raw Hono request object is not forwarded). `headers`
32
+ * is optional so existing body-only callbacks keep working.
24
33
  */
25
- export type RoutingCallback = (body: Record<string, unknown>) => string | null | undefined | Promise<string | null | undefined>;
34
+ export type RoutingCallback = (body: SwmlRequestData, headers?: Record<string, string>) => string | null | undefined | Promise<string | null | undefined>;
26
35
  /**
27
36
  * Core agent class that composes an HTTP server, prompt management, session handling,
28
37
  * SWAIG tool registry, and 5-phase SWML rendering into a single deployable unit.
@@ -99,6 +108,7 @@ export declare class AgentBase extends SWMLService {
99
108
  private _nativeFunctions;
100
109
  private hints;
101
110
  private languages;
111
+ private multilingual;
102
112
  private pronounce;
103
113
  private params;
104
114
  private globalData;
@@ -110,11 +120,20 @@ export declare class AgentBase extends SWMLService {
110
120
  private answerConfig;
111
121
  private postAnswerVerbs;
112
122
  private postAiVerbs;
113
- private dynamicConfigCallback;
123
+ /** Per-request configuration callbacks, run in order on each request's copy. */
124
+ private perCallConfigs;
125
+ /** Set once serve() runs an HTTP server; getFullUrl then ignores serverless environments. */
126
+ private _serving;
127
+ /** Handlers registered with {@link onCallEnd}. */
128
+ private callEndHandlers;
129
+ /** Apps and routers added with {@link mount}, replayed on every app build. */
130
+ private mounts;
114
131
  private swaigQueryParams;
115
132
  private webHookUrlOverride;
116
133
  private postPromptUrlOverride;
117
134
  private contextsBuilder;
135
+ /** Contexts given as a plain object, rendered as they are. */
136
+ private _rawContexts;
118
137
  private _mcpServers;
119
138
  private _mcpServerEnabled;
120
139
  private _sipRoutingEnabled;
@@ -128,13 +147,43 @@ export declare class AgentBase extends SWMLService {
128
147
  private _enforceHttps;
129
148
  /** Structured logger instance for this agent. Override the inherited
130
149
  * SWMLService logger with an AgentBase-tagged one. */
131
- log: import("./Logger.js").Logger;
150
+ log: Logger;
132
151
  private _skillManager;
133
152
  private _enablePostPromptOverride;
134
153
  private _checkForInputOverride;
135
154
  private _schemaValidation;
136
155
  private _configFile;
137
156
  private _schemaPath;
157
+ /**
158
+ * Resolved SignalWire Signing Key. Source of truth for the
159
+ * webhook-validation middleware mounted on POST /, /swaig, /post_prompt.
160
+ * Resolved from constructor opts, falling back to
161
+ * ``SIGNALWIRE_SIGNING_KEY``. When ``null``, signature validation is
162
+ * disabled.
163
+ *
164
+ * NEVER logged. NEVER serialized. Not included in any SWML/SWAIG render or
165
+ * state dump.
166
+ *
167
+ * READABLE, matching the reference's public `self.signing_key`
168
+ * (`core/agent_base.py:253`) and java's `getSigningKey()`. The value came FROM the
169
+ * caller (an explicit `signingKey` option or `SIGNALWIRE_SIGNING_KEY`), so a
170
+ * caller who supplied it must be able to read back which key the agent resolved —
171
+ * the same posture as `getBasicAuthCredentials()`, which already returns the auth
172
+ * secret. Withholding it hides configuration from its own owner without hiding it
173
+ * from anything else (the process already holds it).
174
+ */
175
+ private _signingKey;
176
+ /**
177
+ * The resolved SignalWire Signing Key, or `null` when signature validation is
178
+ * disabled — the reference's public `self.signing_key`.
179
+ *
180
+ * Read-only: the resolution order (explicit option → `SIGNALWIRE_SIGNING_KEY` →
181
+ * `null`) runs once at construction and the middleware is mounted against it, so a
182
+ * post-construction write would not take effect.
183
+ */
184
+ get signingKey(): string | null;
185
+ /** Whether to honor X-Forwarded-* headers when reconstructing the URL. */
186
+ private _webhookTrustProxy;
138
187
  private _appBuiltByAgent;
139
188
  /**
140
189
  * Create a new AgentBase instance.
@@ -151,12 +200,45 @@ export declare class AgentBase extends SWMLService {
151
200
  bullets?: string[];
152
201
  numbered?: boolean;
153
202
  }[];
203
+ /** Guards {@link ensureToolsDefined} so `defineTools()` runs at most once. */
204
+ private _toolsDefined;
154
205
  /**
155
- * Lifecycle method to register tools. Subclasses should call this at the
156
- * end of their own constructor (after all fields are initialized).
157
- * Not called automatically — call `this.defineTools()` explicitly.
206
+ * Lifecycle hook for subclasses to register their SWAIG tools. Override it
207
+ * and call `this.defineTool(...)` inside.
208
+ *
209
+ * You do **not** need to call this yourself — the base class invokes it
210
+ * automatically (exactly once) the first time tools are needed: on
211
+ * {@link renderSwml}, {@link getTools}, {@link serve}/{@link run}, or SWAIG
212
+ * dispatch. It runs lazily rather than from the base constructor because in
213
+ * JS/TS `super()` runs *before* a subclass's field initializers, so a
214
+ * base-constructor call would see `undefined` fields. Deferring to first use
215
+ * guarantees all subclass fields are initialized.
216
+ *
217
+ * Calling `this.defineTools()` manually (the old convention) still works and
218
+ * is safe — the call is idempotent, so it will not double-register tools.
158
219
  */
159
220
  protected defineTools(): void;
221
+ /**
222
+ * Run {@link defineTools} exactly once. Idempotent: safe to call from any
223
+ * tool-consumption entry point and from a subclass constructor. This is how
224
+ * `defineTools()` gets auto-invoked without falling into the JS field-init
225
+ * ordering trap (see {@link defineTools}).
226
+ */
227
+ protected ensureToolsDefined(): void;
228
+ /** Agent-level SWAIG error hook; see {@link onError}. */
229
+ private _onError?;
230
+ /**
231
+ * Register an agent-level error hook invoked when any SWAIG tool handler
232
+ * throws. It runs after a tool's own `onError` (if any) and lets you report
233
+ * failures (Sentry/Datadog/logging) and optionally control the user-facing
234
+ * response — return a {@link FunctionResult} to override it, or nothing to
235
+ * fall back to the default message. The error is always contained, so a
236
+ * thrown handler never breaks the live call.
237
+ *
238
+ * @param handler - The error hook, or `undefined` to clear it.
239
+ * @returns `this`, for chaining.
240
+ */
241
+ onError(handler: SwaigErrorHandler | undefined): this;
160
242
  /**
161
243
  * Public access to the list of registered tools.
162
244
  *
@@ -176,7 +258,7 @@ export declare class AgentBase extends SWMLService {
176
258
  /**
177
259
  * Public accessor for the agent's POM as a {@link PromptObjectModel} instance.
178
260
  *
179
- * Python parity: ``agent.pom`` instance attribute (agent_base.py line 209)
261
+ * Python equivalent: ``agent.pom`` instance attribute (agent_base.py line 209)
180
262
  * is a ``signalwire.pom.pom.PromptObjectModel`` when ``use_pom=True``,
181
263
  * or ``None`` otherwise. This getter returns the equivalent TypeScript
182
264
  * ``PromptObjectModel`` instance — callers can use ``addSection``,
@@ -311,11 +393,20 @@ export declare class AgentBase extends SWMLService {
311
393
  */
312
394
  setPromptPom(pom: Record<string, unknown>[]): this;
313
395
  /**
314
- * Define or replace the contexts configuration for the AI verb.
315
- * @param contexts - An existing ContextBuilder instance or a plain object; a new ContextBuilder is created if omitted.
316
- * @returns The active ContextBuilder for further configuration.
396
+ * Get the agent's contexts builder, creating it on first use, or replace it.
397
+ *
398
+ * Called with no argument, it returns the builder the agent already has, so
399
+ * calling it again adds to the same workflow, as in the Python SDK.
400
+ *
401
+ * Given a plain object, it uses that object as the contexts, rendered as it
402
+ * is, and returns the agent, as the Python SDK does with a dict.
403
+ *
404
+ * @param contexts - A ContextBuilder to use in place of the current one, or
405
+ * the contexts as a plain object.
406
+ * @returns The active ContextBuilder, or the agent when given an object.
317
407
  */
318
- defineContexts(contexts?: ContextBuilder | Record<string, unknown>): ContextBuilder;
408
+ defineContexts(contexts?: ContextBuilder): ContextBuilder;
409
+ defineContexts(contexts: Record<string, unknown>): this;
319
410
  /**
320
411
  * Remove all contexts, returning the agent to a no-contexts state.
321
412
  *
@@ -363,6 +454,10 @@ export declare class AgentBase extends SWMLService {
363
454
  /**
364
455
  * Add a supported language to the AI configuration.
365
456
  * @param config - Language configuration including name, code, voice, and optional fillers.
457
+ * `params` may be set to attach engine-specific tuning (voice stability,
458
+ * similarity boost, model knobs, etc.); only emitted into SWML when
459
+ * non-empty so existing entries stay byte-identical when no params are
460
+ * passed (Python ai_config_mixin.py `add_language`).
366
461
  * @returns This agent instance for chaining.
367
462
  */
368
463
  addLanguage(config: LanguageConfig): this;
@@ -372,6 +467,44 @@ export declare class AgentBase extends SWMLService {
372
467
  * @returns This agent instance for chaining.
373
468
  */
374
469
  setLanguages(languages: LanguageConfig[]): this;
470
+ /**
471
+ * Configure ASR-driven multilingual mode (Mode B).
472
+ *
473
+ * Emits a top-level `multilingual` object on the AI verb. The recognizer runs
474
+ * in code-switching mode and the agent answers in whatever language the caller
475
+ * actually spoke — the model does not pick the language. Mutually exclusive
476
+ * with {@link setLanguages}; if both are set the server uses `multilingual` and
477
+ * ignores `languages`.
478
+ *
479
+ * @param config - The multilingual config object (languages, allowed,
480
+ * start_language, min_switch_words, fillers, etc.).
481
+ * @returns This agent instance for chaining.
482
+ */
483
+ setMultilingual(config: Record<string, unknown>): this;
484
+ /**
485
+ * Set (or replace) the per-language `params` dict on an already-added
486
+ * language. Useful when language entries are built up via {@link addLanguage}
487
+ * first and engine-specific tuning is added later (e.g., from a config
488
+ * loader).
489
+ *
490
+ * Python equivalent: `set_language_params(code, params)`. Passing an empty
491
+ * object removes the `params` key entirely. Unknown codes are a no-op.
492
+ *
493
+ * @param code - Language code as previously passed to {@link addLanguage} (e.g. `"en-US"`).
494
+ * @param params - Engine-specific params dict to attach. Empty object removes the key.
495
+ * @returns This agent instance for chaining.
496
+ */
497
+ setLanguageParams(code: string, params: Record<string, unknown>): this;
498
+ /**
499
+ * Read the per-language `params` dict for a previously-added language.
500
+ *
501
+ * Python equivalent: `get_language_params(code)`. Returns `undefined` if the
502
+ * code is unknown or the language has no params set — no exception path.
503
+ *
504
+ * @param code - Language code as previously passed to {@link addLanguage}.
505
+ * @returns The params dict if set, `undefined` otherwise (including when the code is unknown).
506
+ */
507
+ getLanguageParams(code: string): Record<string, unknown> | undefined;
375
508
  /**
376
509
  * Add a pronunciation override rule for the TTS engine.
377
510
  * @param rule - Pronunciation rule specifying the text to replace and its substitute.
@@ -398,25 +531,55 @@ export declare class AgentBase extends SWMLService {
398
531
  */
399
532
  setParams(params: Record<string, unknown>): this;
400
533
  /**
401
- * Merge data into the global_data object passed into the AI configuration.
402
- *
403
- * Matches Python `set_global_data` which calls `.update()` on the internal dict —
404
- * existing keys are preserved; incoming keys overwrite on collision. Skills and
405
- * other callers can each contribute keys without clobbering one another.
534
+ * **MERGES** `data` into the global_data object passed into the AI
535
+ * configuration. **Despite the name, this does NOT replace** the existing
536
+ * object — existing keys are preserved and incoming keys overwrite only on
537
+ * collision (it calls `.update()`-style merge, matching Python
538
+ * `set_global_data`). This is intentional: skills and other callers each
539
+ * contribute keys via {@link updateGlobalData}, and a replacing
540
+ * `setGlobalData` would silently clobber their contributions.
406
541
  *
407
- * If you need to replace the entire object, assign a new agent instance or use
408
- * `Object.assign(agent.globalData, {})` to clear first.
542
+ * - To **add/override** keys while keeping the rest: this method or the
543
+ * identical {@link updateGlobalData}.
544
+ * - To **fully replace** global_data (clearing every prior key, including
545
+ * skill-contributed ones): use {@link replaceGlobalData}.
409
546
  *
410
547
  * @param data - Key-value pairs to merge into global data.
411
548
  * @returns This agent instance for chaining.
549
+ * @see updateGlobalData - explicit merge alias.
550
+ * @see replaceGlobalData - true replace semantics.
412
551
  */
413
552
  setGlobalData(data: Record<string, unknown>): this;
414
553
  /**
415
- * Merge additional entries into the existing global_data object.
554
+ * Merge additional entries into the existing global_data object. Identical in
555
+ * behavior to {@link setGlobalData} (both merge); use this name when the
556
+ * intent is explicitly "add to" rather than "set". Skills register their
557
+ * global data through this path.
558
+ *
416
559
  * @param data - Key-value pairs to merge into global data.
417
560
  * @returns This agent instance for chaining.
561
+ * @see replaceGlobalData - to clear prior keys instead of merging.
418
562
  */
419
563
  updateGlobalData(data: Record<string, unknown>): this;
564
+ /**
565
+ * **REPLACES** the entire global_data object: every previously-set key
566
+ * (including skill-contributed keys) is cleared, and `data` becomes the new
567
+ * global_data. Use this when you genuinely want a fresh object — the
568
+ * unambiguous counterpart to the merging {@link setGlobalData} /
569
+ * {@link updateGlobalData}.
570
+ *
571
+ * A shallow copy of `data` is stored, so later mutations of the caller's
572
+ * object do not leak into the agent.
573
+ *
574
+ * TS-native addition: Python's reference SDK has no replace path (its
575
+ * `set_global_data` only merges), so this has no Python counterpart — see
576
+ * `PORT_ADDITIONS.md`.
577
+ *
578
+ * @param data - The new global_data object (replaces all prior keys).
579
+ * @returns This agent instance for chaining.
580
+ * @see setGlobalData - the merging counterpart (does NOT clear prior keys).
581
+ */
582
+ replaceGlobalData(data: Record<string, unknown>): this;
420
583
  /**
421
584
  * Set the list of native SWAIG function names (built-in platform functions).
422
585
  * @param funcs - Array of native function names.
@@ -549,8 +712,8 @@ export declare class AgentBase extends SWMLService {
549
712
  *
550
713
  * When called, the endpoint at `path` will invoke `callback` with the parsed
551
714
  * request body. If `callback` returns a non-empty route string the server
552
- * responds with `{ action: "redirect", route }` so the platform can forward the
553
- * request to the right agent. If `callback` returns `null` / `undefined` the
715
+ * responds with a `307` redirect to it (`Location: <route>`), so the
716
+ * request goes to the right agent. If `callback` returns `null` / `undefined` the
554
717
  * agent's own SWML is returned instead (normal processing).
555
718
  *
556
719
  * Mirrors Python `swml_service.register_routing_callback` /
@@ -568,7 +731,7 @@ export declare class AgentBase extends SWMLService {
568
731
  * @param requestBody - The parsed request body containing call information.
569
732
  * @returns The extracted SIP username, or null if not found.
570
733
  */
571
- static extractSipUsername(requestBody: Record<string, unknown>): string | null;
734
+ static extractSipUsername(requestBody: SwmlRequestData): string | null;
572
735
  /**
573
736
  * Add an external MCP server for tool discovery and invocation.
574
737
  * Tools are discovered via MCP protocol at session start and added to the AI's tool list.
@@ -584,6 +747,8 @@ export declare class AgentBase extends SWMLService {
584
747
  /**
585
748
  * Expose this agent's tools as an MCP server endpoint at /mcp.
586
749
  * Adds a JSON-RPC 2.0 endpoint that MCP clients (Claude Desktop, other agents) can connect to.
750
+ * The endpoint requires the agent's basic auth credentials, and lists and
751
+ * calls only the tools the agent runs itself (not DataMap or external webhook tools).
587
752
  * @returns This agent instance for chaining
588
753
  */
589
754
  enableMcpServer(): this;
@@ -591,82 +756,16 @@ export declare class AgentBase extends SWMLService {
591
756
  isMcpServerEnabled(): boolean;
592
757
  /** Get configured MCP servers (read-only copy). */
593
758
  getMcpServers(): Record<string, unknown>[];
759
+ /**
760
+ * Whether the /mcp endpoint may list and call this tool: only tools this
761
+ * agent runs itself. DataMap tools run on SignalWire and external webhook
762
+ * tools run on another server, so neither has a handler here.
763
+ */
764
+ private isMcpCallable;
594
765
  /** Build MCP tool list from registered tools. */
595
766
  private buildMcpToolList;
596
767
  /** Handle an MCP JSON-RPC 2.0 request. Returns the response object. */
597
768
  handleMcpRequest(body: Record<string, unknown>): Promise<Record<string, unknown>>;
598
- /**
599
- * Register a SWAIG tool (function) that the AI can invoke during a call.
600
- *
601
- * ## How this becomes a tool the model sees
602
- *
603
- * A SWAIG function is **exactly the same concept** as a "tool" in
604
- * native OpenAI / Anthropic tool calling. On every LLM turn, the SDK
605
- * renders each registered SWAIG function into the OpenAI tool schema:
606
- *
607
- * ```json
608
- * {
609
- * "type": "function",
610
- * "function": {
611
- * "name": "your_name_here",
612
- * "description": "your description text",
613
- * "parameters": { /* your JSON schema *\/ }
614
- * }
615
- * }
616
- * ```
617
- *
618
- * That schema goes to the model in the same API call that produces
619
- * the next assistant message. The model reads:
620
- *
621
- * - the **function `description`** to decide WHEN to call this tool
622
- * - each **parameter `description`** (inside the JSON schema) to
623
- * decide HOW to fill in each argument
624
- *
625
- * This means **descriptions are prompt engineering**, not developer
626
- * comments. A vague description is the #1 cause of "the model has the
627
- * right tool but doesn't call it" failures.
628
- *
629
- * ### Bad vs good descriptions
630
- *
631
- * ```text
632
- * BAD : description: 'Lookup function'
633
- * GOOD: description: 'Look up a customer's account details by account
634
- * number. Use this BEFORE quoting any account-specific info
635
- * (balance, plan, status). Do not use for general product
636
- * questions.'
637
- *
638
- * BAD : parameters: { id: { type: 'string', description: 'the id' } }
639
- * GOOD: parameters: { account_number: { type: 'string', description:
640
- * 'The customer's 8-digit account number, no dashes or spaces.
641
- * Ask the user if they don't provide it.' } }
642
- * ```
643
- *
644
- * ### Tool count matters
645
- *
646
- * LLM tool selection accuracy degrades past ~7-8 simultaneously-active
647
- * tools per call. Use Step.setFunctions() to partition tools across
648
- * steps so only the relevant subset is active at any moment.
649
- *
650
- * @param opts - Tool definition including name, description, parameter
651
- * schema, and handler callback. `description` and per-parameter
652
- * `description` strings are LLM-facing prompt engineering.
653
- * @returns This agent instance for chaining.
654
- */
655
- defineTool(opts: {
656
- name: string;
657
- description: string;
658
- parameters?: Record<string, unknown>;
659
- handler: SwaigHandler;
660
- secure?: boolean;
661
- fillers?: Record<string, string[]>;
662
- waitFile?: string;
663
- waitFileLoops?: number;
664
- required?: string[];
665
- /** External webhook URL; makes this an externally-hosted tool. */
666
- webhookUrl?: string;
667
- /** Additional fields to pass through to the SWAIG function definition (Python `**swaig_fields` equivalent). */
668
- extraFields?: Record<string, unknown>;
669
- }): this;
670
769
  /**
671
770
  * Register a SWAIG tool with a typed handler that receives named parameters
672
771
  * instead of the standard `(args, rawData)` convention.
@@ -682,7 +781,14 @@ export declare class AgentBase extends SWMLService {
682
781
  name: string;
683
782
  description: string;
684
783
  parameters?: Record<string, unknown>;
685
- handler: Function;
784
+ /**
785
+ * The typed handler. Receives the AI-extracted arguments as named
786
+ * positional parameters (in declaration order), optionally with a trailing
787
+ * `rawData` record, and returns a SWAIG result. Precisely typed as
788
+ * {@link TypedToolHandler} rather than the bare `Function` so a non-callable
789
+ * — or a callable that returns nothing usable — is a compile-time error.
790
+ */
791
+ handler: TypedToolHandler;
686
792
  secure?: boolean;
687
793
  fillers?: Record<string, string[]>;
688
794
  waitFile?: string;
@@ -780,12 +886,19 @@ export declare class AgentBase extends SWMLService {
780
886
  * name via the SkillManager registry. Throws a `ValueError`-equivalent if the
781
887
  * skill name is not found in the registry.
782
888
  *
889
+ * Accepts a typed {@link SkillNameOrString}: one of the built-in
890
+ * {@link SkillName} values (autocompleted) or any other string for custom
891
+ * and third-party skills. Because any string is accepted, a misspelled name
892
+ * compiles, and this rejects at runtime because it isn't registered. The value is
893
+ * forwarded to the registry unchanged — the typing is erased at runtime, so
894
+ * this matches Python's bare-`str` `add_skill(skill_name, params)`.
895
+ *
783
896
  * @param skillName - The name the skill was registered under in the SkillRegistry.
784
897
  * @param params - Optional configuration parameters forwarded to the skill factory.
785
898
  * @returns This agent instance for chaining.
786
899
  * @throws Error if no skill with the given name is registered.
787
900
  */
788
- addSkillByName(skillName: string, params?: SkillConfig): Promise<this>;
901
+ addSkillByName(skillName: SkillNameOrString, params?: SkillConfig): Promise<this>;
789
902
  /**
790
903
  * Remove a previously added skill by its instance ID.
791
904
  * @param instanceId - The unique instance ID of the skill to remove.
@@ -803,27 +916,59 @@ export declare class AgentBase extends SWMLService {
803
916
  }[];
804
917
  /**
805
918
  * Check whether a skill with the given name is registered.
919
+ *
920
+ * Accepts a typed {@link SkillNameOrString} so built-in names autocomplete;
921
+ * any other string is accepted too (custom skills, matching Python's
922
+ * bare-`str` `has_skill`), so a misspelled name compiles and returns false.
923
+ *
806
924
  * @param skillName - The skill name to check.
807
925
  * @returns True if a skill with that name exists.
808
926
  */
809
- hasSkill(skillName: string): boolean;
927
+ hasSkill(skillName: SkillNameOrString): boolean;
810
928
  /**
811
- * Remove a skill by its name (Python parity).
929
+ * Remove a skill by its name (matches the Python SDK).
812
930
  *
813
931
  * Python's `remove_skill(skill_name)` removes by skill name.
814
932
  * The existing `removeSkill(instanceId)` removes by instance ID.
815
- * This method provides name-based removal for cross-SDK parity.
933
+ * This method provides name-based removal to match the Python SDK.
816
934
  *
817
935
  * @param skillName - The skill name to remove.
818
936
  * @returns True if a skill with that name was found and removed.
819
937
  */
820
938
  removeSkillByName(skillName: string): Promise<boolean>;
821
939
  /**
822
- * Set a callback invoked on each SWML request to dynamically modify an ephemeral agent copy.
823
- *
824
- * The callback receives a clone of this agent — mutations apply only to the current
825
- * request, so you can vary prompt, tools, languages, params, or global data per call
826
- * without affecting the long-lived agent instance.
940
+ * A tool handler that calls `fn` with the agent running the call: with a
941
+ * dynamic config callback, the request's configured copy (so the handler
942
+ * sees what the callback configured), otherwise this agent. For handlers
943
+ * that read the agent's own state; the SDK's prefabs register theirs this
944
+ * way. A plain handler gets the same agent as its third argument.
945
+ * @internal
946
+ */
947
+ protected _onCallAgent<A, R>(fn: (self: this, args: A, rawData: SwaigRequest) => R): (args: A, rawData: SwaigRequest, agent?: AgentBase) => R;
948
+ /**
949
+ * Set a callback that configures a per-request copy of this agent.
950
+ *
951
+ * On each request that renders SWML, runs a SWAIG function or delivers a
952
+ * summary, the SDK makes a copy of this agent, calls the callback with the
953
+ * request's query parameters, body and headers (credential-bearing headers
954
+ * removed) and the copy, and handles the request with the copy. Tool
955
+ * handlers get the copy as their third argument, and `onSummary` runs on it.
956
+ *
957
+ * The copy has its own prompt, tools, skills list, hints, languages,
958
+ * pronunciations, params, global data, function includes, LLM params,
959
+ * fillers, call-flow verbs, SWAIG query params, native functions, MCP
960
+ * servers, SIP usernames, routing callbacks and contexts, so changing any of
961
+ * them with the agent's methods affects only this request. Anything else is
962
+ * shared with this agent and every request in flight: a field a subclass
963
+ * adds, a skill instance, or an object inside the configuration that isn't
964
+ * plain data (a `URL`, a class instance). Assigning a new value to such a
965
+ * field on the copy is safe; mutating a shared object in place is not.
966
+ *
967
+ * A handler that captured this agent (an arrow function, or a method passed
968
+ * with `.bind(this)`) still sees this agent, not the copy: read per-call
969
+ * configuration from the handler's third argument. A subclass's JavaScript
970
+ * `#private` fields aren't on the copy, so its methods that read them
971
+ * throw there; use TypeScript `private` fields.
827
972
  *
828
973
  * @param cb - Callback receiving `(queryParams, bodyParams, headers, agent)` where
829
974
  * `agent` is the ephemeral `AgentBase` copy to mutate. May be async.
@@ -840,6 +985,80 @@ export declare class AgentBase extends SWMLService {
840
985
  * ```
841
986
  */
842
987
  setDynamicConfigCallback(cb: DynamicConfigCallback): this;
988
+ /**
989
+ * Register a per-request configuration callback, keeping any already set.
990
+ *
991
+ * Same signature and contract as {@link setDynamicConfigCallback}, except
992
+ * that callbacks accumulate instead of replacing each other. They run in
993
+ * registration order on the same per-request copy, so a later one sees what
994
+ * an earlier one configured. This is the composable form: a base class and a
995
+ * subclass, or an agent and a helper, can each register what they own
996
+ * without knowing about each other. `setDynamicConfigCallback` replaces
997
+ * every callback registered so far.
998
+ *
999
+ * @param cb - Callback receiving `(queryParams, bodyParams, headers, agent)`,
1000
+ * where `agent` is the per-request copy. Configure that, never the agent
1001
+ * itself, or the configuration leaks across callers. May be async.
1002
+ * @returns This agent instance for chaining.
1003
+ */
1004
+ addPerCallConfig(cb: DynamicConfigCallback): this;
1005
+ /**
1006
+ * Register a handler that runs when the call ends, with the transcript.
1007
+ *
1008
+ * Handlers run in registration order with `(callLog, rawData)`: the
1009
+ * conversation as the platform recorded it, and the whole SWAIG request
1010
+ * (with `global_data` and `call_id`). This wraps the platform's reserved
1011
+ * `hangup_hook` function, which fires on hangup and is never offered to the
1012
+ * model, so it can't be called early or skipped.
1013
+ *
1014
+ * Registering a handler also turns on the `swaig_post_conversation`
1015
+ * parameter: without it the hook still fires, but carries no transcript,
1016
+ * and the handler gets an empty list with nothing to say why. If that
1017
+ * parameter is explicitly `false`, it's left alone and a warning is logged.
1018
+ *
1019
+ * A handler's return value is ignored (the call is over), and an exception
1020
+ * is logged, not raised, so a failing handler doesn't stop the others.
1021
+ *
1022
+ * @param handler - Called with `(callLog, rawData)`; may be async.
1023
+ * @returns The handler.
1024
+ *
1025
+ * @example
1026
+ * ```ts
1027
+ * agent.onCallEnd((callLog, rawData) => {
1028
+ * archive(rawData.global_data?.['conversation_id'], callLog);
1029
+ * });
1030
+ * ```
1031
+ */
1032
+ onCallEnd(handler: (callLog: Record<string, unknown>[], rawData: SwaigRequest) => void | Promise<void>): (callLog: Record<string, unknown>[], rawData: SwaigRequest) => void | Promise<void>;
1033
+ /** Register the reserved hangup_hook tool once, and turn on its transcript. */
1034
+ private ensureCallEndHook;
1035
+ /**
1036
+ * Mount an extra Hono app, or a fetch handler, alongside this agent's routes.
1037
+ *
1038
+ * Use this instead of adding routes to {@link getApp}'s app by hand: the
1039
+ * agent rebuilds its app when its routes change (a routing callback, say),
1040
+ * and a mount is replayed on every build. A mounted app answers its own
1041
+ * CORS preflights (the agent's CORS and CSRF middleware don't apply to it),
1042
+ * sets its own security headers, and isn't behind the agent's basic auth.
1043
+ * Mount before calling `serve()`.
1044
+ *
1045
+ * @param appOrRouter - A Hono app (its routes are added under `prefix`) or a
1046
+ * fetch handler `(request) => Response` (mounted at `prefix`, which it
1047
+ * doesn't see).
1048
+ * @param opts - `prefix`: the path to mount at, from the host root (a
1049
+ * trailing slash is dropped; default the root). `name`: accepted so
1050
+ * code written for the Python SDK works; it has no effect here.
1051
+ * @returns This agent instance for chaining.
1052
+ *
1053
+ * @example
1054
+ * ```ts
1055
+ * agent.mount(gateway.router(), { prefix: '/chat' });
1056
+ * ```
1057
+ */
1058
+ mount(appOrRouter: Hono | ((req: Request) => Response | Promise<Response>), opts?: {
1059
+ prefix?: string;
1060
+ name?: string;
1061
+ }): this;
843
1062
  /**
844
1063
  * Add extra query parameters appended to all SWAIG webhook URLs.
845
1064
  * @param params - Key-value pairs to append as query parameters.
@@ -890,13 +1109,18 @@ export declare class AgentBase extends SWMLService {
890
1109
  * @returns The fully-qualified URL string.
891
1110
  */
892
1111
  getFullUrl(includeAuth?: boolean): string;
1112
+ /**
1113
+ * Whether serve() serves HTTPS: SSL enabled with a certificate and key that
1114
+ * exist. getFullUrl() uses the same check, so the webhook URLs match.
1115
+ */
1116
+ private _servesTls;
893
1117
  private insertAuth;
894
1118
  private buildWebhookUrl;
895
1119
  /**
896
1120
  * Lifecycle hook called when a post-prompt summary is received. Override in subclasses.
897
1121
  *
898
1122
  * Invoked once at the end of a call when the AI has produced a structured summary
899
- * (configured via `setPostPrompt()` / `setPostPromptJson()`). Use this hook to persist
1123
+ * (configured via `setPostPrompt()`). Use this hook to persist
900
1124
  * call data, notify other systems, or trigger follow-up workflows.
901
1125
  *
902
1126
  * @param _summary - Parsed summary object (JSON when the post-prompt requests
@@ -904,6 +1128,12 @@ export declare class AgentBase extends SWMLService {
904
1128
  * @param _rawData - Full raw post-prompt payload received from the platform,
905
1129
  * including call metadata, conversation history, and the summary text.
906
1130
  *
1131
+ * With a dynamic config callback set, this runs on the request's configured
1132
+ * copy of the agent. For a request whose `action` is `fetch_conversation`,
1133
+ * an override may return the conversation (for example
1134
+ * `{ conversation_summary: '...' }`); the post-prompt endpoint sends that
1135
+ * back instead of `{ success: true }`.
1136
+ *
907
1137
  * @example
908
1138
  * ```ts
909
1139
  * class MyAgent extends AgentBase {
@@ -918,7 +1148,7 @@ export declare class AgentBase extends SWMLService {
918
1148
  * }
919
1149
  * ```
920
1150
  */
921
- onSummary(_summary: Record<string, unknown> | null, _rawData: Record<string, unknown>): void | Promise<void>;
1151
+ onSummary(_summary: PostPromptData | null, _rawData: PostPrompt): void | Record<string, unknown> | Promise<void | Record<string, unknown>>;
922
1152
  /**
923
1153
  * Lifecycle hook called when SWML is requested. Default delegates to
924
1154
  * {@link onSwmlRequest} and returns its result. Subclasses typically
@@ -934,7 +1164,7 @@ export declare class AgentBase extends SWMLService {
934
1164
  * @returns Optionally a dict of SWML modifications, or undefined for
935
1165
  * default rendering.
936
1166
  */
937
- onRequest(requestData?: Record<string, unknown> | null, callbackPath?: string | null): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
1167
+ onRequest(requestData?: SwmlRequestData | null, callbackPath?: string | null): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
938
1168
  /**
939
1169
  * Lifecycle hook called on every SWML request before rendering. Override in subclasses.
940
1170
  *
@@ -951,19 +1181,54 @@ export declare class AgentBase extends SWMLService {
951
1181
  * @param _context - The raw Hono context object (c), providing access to headers and query params.
952
1182
  * @returns Optionally a dict of SWML modifications, or void.
953
1183
  */
954
- onSwmlRequest(_rawData: Record<string, unknown>, _callbackPath?: string, _context?: any): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
1184
+ onSwmlRequest(_rawData: SwmlRequestData, _callbackPath?: string, _context?: Context): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
1185
+ /**
1186
+ * Framework-free request-dispatch core for AgentBase.
1187
+ *
1188
+ * Overrides {@link SWMLService.handleRequest} so the primitive dispatch surface
1189
+ * renders SWML via AgentBase's {@link renderSwml} (mirroring the Hono root path)
1190
+ * instead of the base `renderDocument`. Performs basic-auth, the routing-callback
1191
+ * check `(body, headers)`, and `onSwmlRequest` modification over plain
1192
+ * primitives, returning a `[status, headers, bodyString]` triple with the
1193
+ * 401-auth and 307-redirect behavior preserved. Mirrors Python's
1194
+ * `AgentBase.handle_request(method, url, headers, body)`.
1195
+ *
1196
+ * @param method HTTP method, e.g. `"GET"` or `"POST"`.
1197
+ * @param url The full request URL.
1198
+ * @param headers Request headers as a plain dict.
1199
+ * @param body The already-parsed JSON body for POST requests, or `undefined`.
1200
+ * @returns A `[statusCode, responseHeaders, bodyString]` triple.
1201
+ */
1202
+ handleRequest(method: string, url: string, headers: Record<string, string>, body?: Record<string, unknown> | null): Promise<[number, Record<string, string>, string]>;
1203
+ /**
1204
+ * The agent a request runs on: this agent, or, when a dynamic config
1205
+ * callback is set, a per-request copy that the callback configured from the
1206
+ * request's query parameters, body and headers (credential-bearing headers
1207
+ * removed). Rendering SWML, running a SWAIG function and delivering a
1208
+ * summary all use it, so a tool the callback registers or secures is the one
1209
+ * that runs, and is checked, when the call invokes it. Mirrors the
1210
+ * reference's `_per_call_agent`.
1211
+ */
1212
+ private perCallAgent;
1213
+ /** Validate basic-auth from a plain headers dict (the primitive analog of
1214
+ * the Hono `basicAuth` middleware), through {@link validateBasicAuth}. */
1215
+ private checkAgentBasicAuth;
955
1216
  /**
956
1217
  * Lifecycle hook called when a debug event webhook is received. Override in subclasses.
957
1218
  * @param _event - The debug event payload.
958
1219
  */
959
1220
  onDebugEvent(_event: Record<string, unknown>): void | Promise<void>;
960
1221
  /**
961
- * Override to add custom basic-auth validation logic beyond credential matching.
962
- * @param _username - The username from the request.
963
- * @param _password - The password from the request.
1222
+ * Check a request's basic-auth credentials. Every route that requires
1223
+ * basic auth calls it. The default compares them with the agent's
1224
+ * credentials in constant time; override it to check credentials another
1225
+ * way, as the Python SDK's `validate_basic_auth` allows. An override
1226
+ * replaces the comparison, so call `super.validateBasicAuth()` to keep it.
1227
+ * @param username - The username from the request.
1228
+ * @param password - The password from the request.
964
1229
  * @returns True if the credentials are valid; false to reject the request.
965
1230
  */
966
- validateBasicAuth(_username: string, _password: string): boolean | Promise<boolean>;
1231
+ validateBasicAuth(username: string, password: string): boolean | Promise<boolean>;
967
1232
  /**
968
1233
  * Hook called before each SWAIG function execution. Override in subclasses.
969
1234
  *
@@ -971,7 +1236,7 @@ export declare class AgentBase extends SWMLService {
971
1236
  * — it retrieves and executes the function, returning the result. In TypeScript,
972
1237
  * `fn.execute()` is called separately after this hook. However, if this method
973
1238
  * returns a non-void value, it is used as the result and the default execution
974
- * is skipped, enabling dispatch interception parity with Python.
1239
+ * is skipped, enabling dispatch interception matching the Python SDK.
975
1240
  *
976
1241
  * @param _name - Name of the function about to execute.
977
1242
  * @param _args - Parsed arguments for the function.
@@ -980,6 +1245,36 @@ export declare class AgentBase extends SWMLService {
980
1245
  * or void/undefined to proceed normally.
981
1246
  */
982
1247
  onFunctionCall(_name: string, _args: Record<string, unknown>, _rawData: Record<string, unknown>): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
1248
+ /**
1249
+ * Extract the tool-call arguments from a SWAIG request body.
1250
+ *
1251
+ * The real platform (mod_openai) POSTs a tool call with the args nested under
1252
+ * the platform envelope `{"argument": {"parsed": [{...args...}], "raw": "..."}}`
1253
+ * — NOT flat. Reading `body.argument` directly hands the handler the WHOLE
1254
+ * envelope (`{parsed, raw}`) instead of the args, so a real platform call
1255
+ * arrives with EMPTY args. This unwraps `argument.parsed[0]` first, falls back
1256
+ * to parsing `argument.raw` JSON, and finally accepts the flat
1257
+ * `{"arguments": {...}}` shape some external integrations send — matching the
1258
+ * Python reference (`core/swml_service.py:836-851`).
1259
+ *
1260
+ * @param body - The parsed SWAIG request body.
1261
+ * @param reqLog - Request-scoped logger for the raw-parse-error path.
1262
+ * @returns The extracted argument object (empty object when none present).
1263
+ */
1264
+ /**
1265
+ * Check a SWAIG request's token before a function runs.
1266
+ *
1267
+ * A secure function runs only with a valid token minted for that function
1268
+ * and call. The token is in the `web_hook_url` the agent rendered, so a
1269
+ * request without one didn't come from that SWML: a missing token, or a
1270
+ * missing `call_id`, is refused like a wrong token. A non-secure function
1271
+ * runs without a token.
1272
+ *
1273
+ * @returns The SWAIG response to send instead of running the function, or
1274
+ * `null` when the function may run.
1275
+ */
1276
+ private swaigTokenRefusal;
1277
+ private extractSwaigArgs;
983
1278
  /**
984
1279
  * Render the complete SWML document by assembling all 5 phases: pre-answer, answer,
985
1280
  * post-answer, AI, and post-AI verbs.
@@ -992,16 +1287,62 @@ export declare class AgentBase extends SWMLService {
992
1287
  */
993
1288
  renderSwml(callId?: string, modifications?: Record<string, unknown>): string;
994
1289
  private createEphemeralCopy;
1290
+ /**
1291
+ * Thin Hono adapter over the decomposed {@link handleRequest} core. Extracts
1292
+ * `(method, url, headers, body)` primitives from the Hono `Context`, delegates
1293
+ * the auth / routing-callback / render DECISION to `handleRequest`, and
1294
+ * marshals the returned `[status, headers, body]` triple back into a Hono
1295
+ * `Response` — including the routing-callback **307** (`Location`) and the
1296
+ * **401** (`WWW-Authenticate`). This is what routes serve()/asRouter() through
1297
+ * the same core the primitive path uses, instead of a parallel inline
1298
+ * auth/render/redirect path (mirrors the rust/dotnet/php served path).
1299
+ *
1300
+ * Proxy detection stays here as framework plumbing (it needs the raw request);
1301
+ * everything else comes from `handleRequest`.
1302
+ */
1303
+ private serveViaHandleRequest;
995
1304
  /**
996
1305
  * Get or lazily create the Hono HTTP application with all routes, middleware, auth, and CORS.
997
1306
  * @returns The configured Hono application instance.
998
1307
  */
999
1308
  getApp(): Hono;
1000
1309
  /**
1001
- * Return this agent's Hono app for mounting as a sub-router in an AgentServer.
1002
- * @returns The Hono application instance.
1310
+ * Build the Hono app serving this agent's routes under `basePath` ('' for
1311
+ * route-relative routes, as {@link asRouter} returns them).
1312
+ *
1313
+ * Paths are matched without regard to a trailing slash or repeated slashes
1314
+ * (`/agent/swaig/`, `/agent//swaig`), as the reference's router and
1315
+ * catch-all routes accept them; the signature check still covers the URL
1316
+ * as the request spelled it.
1003
1317
  */
1004
- asRouter(): Hono;
1318
+ private buildApp;
1319
+ /** The route-relative app {@link asRouter} returns, built on first use. */
1320
+ private _routerApp;
1321
+ /**
1322
+ * Get a router to embed this agent's routes in a host web app.
1323
+ *
1324
+ * Returns a Hono sub-app with this agent's routes relative to its root
1325
+ * (`/`, `/swaig`, `/post_prompt`, plus any routing callbacks), for the host
1326
+ * to mount under the agent's route: `hostApp.route(agent.route,
1327
+ * agent.asRouter())`. This is the TypeScript realization of Python's
1328
+ * `as_router()`, which is route-relative the same way; the named
1329
+ * {@link HostAppRouter} type is the cross-port "embed my routes in a host
1330
+ * app" contract. {@link getApp} serves the same routes under the agent's
1331
+ * route.
1332
+ *
1333
+ * @returns A mountable Hono sub-app carrying this agent's routes.
1334
+ */
1335
+ asRouter(): HostAppRouter;
1336
+ /**
1337
+ * Whether a request path is served by an app added with {@link mount}
1338
+ * rather than by the agent's own routes, so the agent's security headers,
1339
+ * CORS and CSRF handling should leave it alone. Internal; AgentServer uses
1340
+ * it for the agents it serves.
1341
+ *
1342
+ * @param path - The path relative to the agent's route-relative router.
1343
+ * @param method - The request's method.
1344
+ */
1345
+ _servedByMount(path: string, method?: string): boolean;
1005
1346
  /**
1006
1347
  * Start the HTTP server and begin listening for requests.
1007
1348
  *
@@ -1026,21 +1367,35 @@ export declare class AgentBase extends SWMLService {
1026
1367
  port?: number;
1027
1368
  }): Promise<void>;
1028
1369
  /**
1029
- * Alias for {@link serve}. Starts the HTTP server.
1030
- * @param opts - Optional host and port overrides.
1031
- * @returns A promise that resolves once the server is running.
1370
+ * Smart entry point matching Python's `WebMixin.run()`: auto-detects the
1371
+ * execution environment and dispatches accordingly. When a serverless event
1372
+ * is supplied, or a serverless platform is detected from the environment
1373
+ * (`AWS_LAMBDA_FUNCTION_NAME`/`_HANDLER`, `FUNCTION_TARGET`,
1374
+ * `FUNCTIONS_WORKER_RUNTIME`, `GATEWAY_INTERFACE`), it dispatches to
1375
+ * {@link runServerless}; otherwise it starts the HTTP server via {@link serve}.
1376
+ * Cloud Run sets `K_SERVICE` but not `FUNCTION_TARGET`, so there it serves.
1377
+ *
1378
+ * For deterministic behavior, call {@link serve} (server) or
1379
+ * {@link runServerless} (serverless) directly.
1380
+ *
1381
+ * @param opts - Either server host/port overrides, or a serverless
1382
+ * `{ event, context, platform }` payload.
1383
+ * @returns `void` for server mode, or the serverless response object.
1032
1384
  */
1033
1385
  run(opts?: {
1034
1386
  host?: string;
1035
1387
  port?: number;
1036
- }): Promise<void>;
1388
+ event?: ServerlessEvent;
1389
+ context?: unknown;
1390
+ platform?: 'lambda' | 'gcf' | 'azure' | 'cgi' | 'auto';
1391
+ }): Promise<void | ServerlessResponse>;
1037
1392
  /**
1038
1393
  * Handle a single serverless invocation (AWS Lambda, Google Cloud Functions, Azure Functions, or CGI).
1039
1394
  *
1040
1395
  * Matches Python `run(event, context)` when executed in a serverless environment. Python's
1041
1396
  * `run()` auto-detects the platform via `get_execution_mode()` and dispatches accordingly;
1042
- * in TypeScript the serverless path is an **explicit** method so that `run()` keeps its
1043
- * HTTP-server semantics and callers opt in to serverless dispatch deliberately.
1397
+ * `runServerless` is the **explicit** serverless path so callers can opt in deliberately
1398
+ * (the polymorphic {@link run} dispatches here when a serverless env/event is detected).
1044
1399
  *
1045
1400
  * Platform detection follows the same environment-variable heuristics as Python's
1046
1401
  * `ServerlessMixin`: `AWS_LAMBDA_FUNCTION_NAME` → Lambda, `K_SERVICE` → GCF,
@@ -1073,5 +1428,5 @@ export declare class AgentBase extends SWMLService {
1073
1428
  * @returns A tuple of [username, password] or [username, password, source].
1074
1429
  */
1075
1430
  getBasicAuthCredentials(includeSource?: false): [string, string];
1076
- getBasicAuthCredentials(includeSource: true): [string, string, 'provided' | 'environment' | 'generated'];
1431
+ getBasicAuthCredentials(includeSource: true): [string, string, 'provided' | 'environment' | 'config file' | 'generated'];
1077
1432
  }