@signalwire/sdk 2.0.4 → 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (656) hide show
  1. package/CHANGELOG.md +785 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +550 -163
  6. package/dist/AgentBase.js +1640 -514
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +158 -45
  21. package/dist/DataMap.js +167 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +277 -83
  24. package/dist/FunctionResult.js +444 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +163 -0
  30. package/dist/POM/PromptObjectModel.js +481 -0
  31. package/dist/POM/PromptObjectModel.js.map +1 -0
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +28 -0
  42. package/dist/PomBuilder.js +81 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +29 -1
  48. package/dist/PromptManager.js +37 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +265 -66
  58. package/dist/SWMLService.js +652 -112
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +55 -8
  64. package/dist/SecurityUtils.js +162 -49
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/ServerlessAdapter.d.ts +156 -7
  67. package/dist/ServerlessAdapter.js +399 -42
  68. package/dist/ServerlessAdapter.js.map +1 -1
  69. package/dist/SessionManager.d.ts +11 -2
  70. package/dist/SessionManager.js +50 -18
  71. package/dist/SessionManager.js.map +1 -1
  72. package/dist/SslConfig.d.ts +2 -1
  73. package/dist/SslConfig.js +4 -1
  74. package/dist/SslConfig.js.map +1 -1
  75. package/dist/SwaigActions.generated.d.ts +23 -0
  76. package/dist/SwaigActions.generated.js +8 -0
  77. package/dist/SwaigActions.generated.js.map +1 -0
  78. package/dist/SwaigContracts.d.ts +15 -0
  79. package/dist/SwaigContracts.generated.d.ts +264 -0
  80. package/dist/SwaigContracts.generated.js +12 -0
  81. package/dist/SwaigContracts.generated.js.map +1 -0
  82. package/dist/SwaigContracts.js +2 -0
  83. package/dist/SwaigContracts.js.map +1 -0
  84. package/dist/SwaigFunction.d.ts +110 -4
  85. package/dist/SwaigFunction.js +151 -19
  86. package/dist/SwaigFunction.js.map +1 -1
  87. package/dist/SwmlBuilder.d.ts +68 -19
  88. package/dist/SwmlBuilder.js +74 -38
  89. package/dist/SwmlBuilder.js.map +1 -1
  90. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  91. package/dist/SwmlVerbMethods.generated.js +1 -1
  92. package/dist/TypeInference.d.ts +39 -3
  93. package/dist/TypeInference.js +256 -16
  94. package/dist/TypeInference.js.map +1 -1
  95. package/dist/WebService.d.ts +79 -11
  96. package/dist/WebService.js +320 -109
  97. package/dist/WebService.js.map +1 -1
  98. package/dist/WebhookMiddleware.d.ts +119 -0
  99. package/dist/WebhookMiddleware.js +271 -0
  100. package/dist/WebhookMiddleware.js.map +1 -0
  101. package/dist/WebhookValidator.d.ts +92 -0
  102. package/dist/WebhookValidator.js +409 -0
  103. package/dist/WebhookValidator.js.map +1 -0
  104. package/dist/agents/BedrockAgent.d.ts +162 -0
  105. package/dist/agents/BedrockAgent.js +323 -0
  106. package/dist/agents/BedrockAgent.js.map +1 -0
  107. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  108. package/dist/ai-chat/AIChatClient.js +535 -0
  109. package/dist/ai-chat/AIChatClient.js.map +1 -0
  110. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  111. package/dist/ai-chat/ChatGateway.js +747 -0
  112. package/dist/ai-chat/ChatGateway.js.map +1 -0
  113. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  114. package/dist/ai-chat/HandoffRouter.js +518 -0
  115. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  116. package/dist/ai-chat/index.d.ts +12 -0
  117. package/dist/ai-chat/index.js +10 -0
  118. package/dist/ai-chat/index.js.map +1 -0
  119. package/dist/capabilities.d.ts +64 -0
  120. package/dist/capabilities.js +95 -0
  121. package/dist/capabilities.js.map +1 -0
  122. package/dist/cli/agent-loader.d.ts +32 -6
  123. package/dist/cli/agent-loader.js +95 -34
  124. package/dist/cli/agent-loader.js.map +1 -1
  125. package/dist/cli/datamap-exec.d.ts +175 -0
  126. package/dist/cli/datamap-exec.js +1284 -0
  127. package/dist/cli/datamap-exec.js.map +1 -0
  128. package/dist/cli/function-args.d.ts +40 -0
  129. package/dist/cli/function-args.js +146 -0
  130. package/dist/cli/function-args.js.map +1 -0
  131. package/dist/cli/simulation.d.ts +99 -0
  132. package/dist/cli/simulation.js +490 -0
  133. package/dist/cli/simulation.js.map +1 -0
  134. package/dist/cli/swaig-test.d.ts +12 -25
  135. package/dist/cli/swaig-test.js +935 -367
  136. package/dist/cli/swaig-test.js.map +1 -1
  137. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  138. package/dist/cli/tsdocs/agentsNote.js +92 -0
  139. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  140. package/dist/cli/tsdocs/api-index.json +1 -0
  141. package/dist/cli/tsdocs/api.d.ts +91 -0
  142. package/dist/cli/tsdocs/api.js +372 -0
  143. package/dist/cli/tsdocs/api.js.map +1 -0
  144. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  145. package/dist/cli/tsdocs/apiTypes.js +7 -0
  146. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  147. package/dist/cli/tsdocs/bin.d.ts +6 -0
  148. package/dist/cli/tsdocs/bin.js +23 -0
  149. package/dist/cli/tsdocs/bin.js.map +1 -0
  150. package/dist/cli/tsdocs/files.d.ts +108 -0
  151. package/dist/cli/tsdocs/files.js +287 -0
  152. package/dist/cli/tsdocs/files.js.map +1 -0
  153. package/dist/cli/tsdocs/index.d.ts +28 -0
  154. package/dist/cli/tsdocs/index.js +307 -0
  155. package/dist/cli/tsdocs/index.js.map +1 -0
  156. package/dist/cli/tsdocs/live.d.ts +41 -0
  157. package/dist/cli/tsdocs/live.js +202 -0
  158. package/dist/cli/tsdocs/live.js.map +1 -0
  159. package/dist/cli/tsdocs/locate.d.ts +51 -0
  160. package/dist/cli/tsdocs/locate.js +75 -0
  161. package/dist/cli/tsdocs/locate.js.map +1 -0
  162. package/dist/cli/tsdocs/render.d.ts +75 -0
  163. package/dist/cli/tsdocs/render.js +323 -0
  164. package/dist/cli/tsdocs/render.js.map +1 -0
  165. package/dist/cli/tsdocs/topics.d.ts +43 -0
  166. package/dist/cli/tsdocs/topics.js +916 -0
  167. package/dist/cli/tsdocs/topics.js.map +1 -0
  168. package/dist/index.d.ts +102 -39
  169. package/dist/index.js +107 -30
  170. package/dist/index.js.map +1 -1
  171. package/dist/livewire/index.d.ts +229 -155
  172. package/dist/livewire/index.js +298 -195
  173. package/dist/livewire/index.js.map +1 -1
  174. package/dist/llms.txt +65 -0
  175. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  176. package/dist/prefabs/CallSessionStore.js +72 -0
  177. package/dist/prefabs/CallSessionStore.js.map +1 -0
  178. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  179. package/dist/prefabs/ConciergeAgent.js +36 -31
  180. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  181. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  182. package/dist/prefabs/FAQBotAgent.js +113 -47
  183. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  184. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  185. package/dist/prefabs/InfoGathererAgent.js +67 -58
  186. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  187. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  188. package/dist/prefabs/ReceptionistAgent.js +39 -31
  189. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  190. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  191. package/dist/prefabs/SurveyAgent.js +84 -68
  192. package/dist/prefabs/SurveyAgent.js.map +1 -1
  193. package/dist/relay/Action.d.ts +44 -21
  194. package/dist/relay/Action.js +75 -17
  195. package/dist/relay/Action.js.map +1 -1
  196. package/dist/relay/Call.d.ts +312 -47
  197. package/dist/relay/Call.js +369 -18
  198. package/dist/relay/Call.js.map +1 -1
  199. package/dist/relay/Deferred.js.map +1 -1
  200. package/dist/relay/Message.d.ts +26 -5
  201. package/dist/relay/Message.js +36 -6
  202. package/dist/relay/Message.js.map +1 -1
  203. package/dist/relay/RelayClient.d.ts +79 -14
  204. package/dist/relay/RelayClient.js +268 -61
  205. package/dist/relay/RelayClient.js.map +1 -1
  206. package/dist/relay/RelayError.d.ts +14 -0
  207. package/dist/relay/RelayError.js +15 -0
  208. package/dist/relay/RelayError.js.map +1 -1
  209. package/dist/relay/RelayEvent.d.ts +96 -65
  210. package/dist/relay/RelayEvent.js +85 -56
  211. package/dist/relay/RelayEvent.js.map +1 -1
  212. package/dist/relay/closedSets.d.ts +111 -0
  213. package/dist/relay/closedSets.js +83 -0
  214. package/dist/relay/closedSets.js.map +1 -0
  215. package/dist/relay/index.d.ts +3 -1
  216. package/dist/relay/index.js +1 -0
  217. package/dist/relay/index.js.map +1 -1
  218. package/dist/relay/normalize.js.map +1 -1
  219. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  220. package/dist/relay/protocol.types.generated.js +8 -0
  221. package/dist/relay/protocol.types.generated.js.map +1 -0
  222. package/dist/relay/types.d.ts +81 -39
  223. package/dist/rest/HttpClient.d.ts +36 -8
  224. package/dist/rest/HttpClient.js +233 -40
  225. package/dist/rest/HttpClient.js.map +1 -1
  226. package/dist/rest/RequestOptions.d.ts +110 -0
  227. package/dist/rest/RequestOptions.js +113 -0
  228. package/dist/rest/RequestOptions.js.map +1 -0
  229. package/dist/rest/RestError.d.ts +52 -6
  230. package/dist/rest/RestError.js +89 -5
  231. package/dist/rest/RestError.js.map +1 -1
  232. package/dist/rest/base/CrudResource.d.ts +16 -26
  233. package/dist/rest/base/CrudResource.js +19 -33
  234. package/dist/rest/base/CrudResource.js.map +1 -1
  235. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  236. package/dist/rest/base/CrudWithAddresses.js +2 -2
  237. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  238. package/dist/rest/base/FabricResource.d.ts +15 -0
  239. package/dist/rest/base/FabricResource.js +16 -0
  240. package/dist/rest/base/FabricResource.js.map +1 -0
  241. package/dist/rest/base/ReadResource.d.ts +62 -0
  242. package/dist/rest/base/ReadResource.js +69 -0
  243. package/dist/rest/base/ReadResource.js.map +1 -0
  244. package/dist/rest/callHandler.d.ts +63 -0
  245. package/dist/rest/callHandler.js +62 -0
  246. package/dist/rest/callHandler.js.map +1 -0
  247. package/dist/rest/index.d.ts +19 -76
  248. package/dist/rest/index.js +49 -120
  249. package/dist/rest/index.js.map +1 -1
  250. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  251. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  252. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  253. package/dist/rest/namespaces/addresses.d.ts +3 -42
  254. package/dist/rest/namespaces/addresses.js +3 -50
  255. package/dist/rest/namespaces/addresses.js.map +1 -1
  256. package/dist/rest/namespaces/calling.d.ts +6 -378
  257. package/dist/rest/namespaces/calling.js +6 -473
  258. package/dist/rest/namespaces/calling.js.map +1 -1
  259. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  260. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  261. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  262. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  263. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  264. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  265. package/dist/rest/namespaces/chat.d.ts +4 -18
  266. package/dist/rest/namespaces/chat.js +4 -21
  267. package/dist/rest/namespaces/chat.js.map +1 -1
  268. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  269. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  270. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  271. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  272. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  273. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  274. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  275. package/dist/rest/namespaces/datasphere.js +6 -72
  276. package/dist/rest/namespaces/datasphere.js.map +1 -1
  277. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  278. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  279. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  280. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  281. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  282. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  283. package/dist/rest/namespaces/fabric.d.ts +11 -273
  284. package/dist/rest/namespaces/fabric.js +14 -363
  285. package/dist/rest/namespaces/fabric.js.map +1 -1
  286. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  287. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  288. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  289. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  290. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  291. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  293. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  294. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  296. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  297. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  298. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  299. package/dist/rest/namespaces/imported-numbers.js +3 -21
  300. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  301. package/dist/rest/namespaces/logs.d.ts +10 -101
  302. package/dist/rest/namespaces/logs.js +10 -128
  303. package/dist/rest/namespaces/logs.js.map +1 -1
  304. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  305. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  306. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  307. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  308. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  309. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  310. package/dist/rest/namespaces/lookup.d.ts +3 -25
  311. package/dist/rest/namespaces/lookup.js +3 -27
  312. package/dist/rest/namespaces/lookup.js.map +1 -1
  313. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  314. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  315. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  316. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  317. package/dist/rest/namespaces/message.types.generated.js +8 -0
  318. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  319. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  320. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  321. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  323. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  324. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  325. package/dist/rest/namespaces/mfa.d.ts +3 -42
  326. package/dist/rest/namespaces/mfa.js +3 -49
  327. package/dist/rest/namespaces/mfa.js.map +1 -1
  328. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  329. package/dist/rest/namespaces/number-groups.js +3 -53
  330. package/dist/rest/namespaces/number-groups.js.map +1 -1
  331. package/dist/rest/namespaces/phone-numbers.d.ts +9 -57
  332. package/dist/rest/namespaces/phone-numbers.js +9 -63
  333. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  334. package/dist/rest/namespaces/project.d.ts +6 -42
  335. package/dist/rest/namespaces/project.js +6 -51
  336. package/dist/rest/namespaces/project.js.map +1 -1
  337. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  338. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  339. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  340. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  341. package/dist/rest/namespaces/project.types.generated.js +8 -0
  342. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  343. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  344. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  345. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  347. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  348. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  349. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  350. package/dist/rest/namespaces/pubsub.js +4 -21
  351. package/dist/rest/namespaces/pubsub.js.map +1 -1
  352. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  353. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  354. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  355. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  356. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  357. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  358. package/dist/rest/namespaces/queues.d.ts +3 -38
  359. package/dist/rest/namespaces/queues.js +3 -44
  360. package/dist/rest/namespaces/queues.js.map +1 -1
  361. package/dist/rest/namespaces/recordings.d.ts +3 -34
  362. package/dist/rest/namespaces/recordings.js +3 -40
  363. package/dist/rest/namespaces/recordings.js.map +1 -1
  364. package/dist/rest/namespaces/registry.d.ts +6 -137
  365. package/dist/rest/namespaces/registry.js +6 -173
  366. package/dist/rest/namespaces/registry.js.map +1 -1
  367. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  368. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  369. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  370. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  371. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  372. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  373. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  374. package/dist/rest/namespaces/short-codes.js +3 -41
  375. package/dist/rest/namespaces/short-codes.js.map +1 -1
  376. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  377. package/dist/rest/namespaces/sip-profile.js +3 -29
  378. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  379. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  380. package/dist/rest/namespaces/verified-callers.js +3 -34
  381. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  382. package/dist/rest/namespaces/video.d.ts +10 -227
  383. package/dist/rest/namespaces/video.js +10 -288
  384. package/dist/rest/namespaces/video.js.map +1 -1
  385. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  386. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  387. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  388. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  389. package/dist/rest/namespaces/video.types.generated.js +8 -0
  390. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  391. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  392. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  393. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  395. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  396. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  397. package/dist/rest/pagination.d.ts +5 -1
  398. package/dist/rest/pagination.js +40 -20
  399. package/dist/rest/pagination.js.map +1 -1
  400. package/dist/rest/types.d.ts +21 -3
  401. package/dist/schema.json +299 -98
  402. package/dist/skills/SkillBase.d.ts +97 -20
  403. package/dist/skills/SkillBase.js +100 -17
  404. package/dist/skills/SkillBase.js.map +1 -1
  405. package/dist/skills/SkillManager.d.ts +66 -13
  406. package/dist/skills/SkillManager.js +101 -20
  407. package/dist/skills/SkillManager.js.map +1 -1
  408. package/dist/skills/SkillName.d.ts +44 -0
  409. package/dist/skills/SkillName.js +2 -0
  410. package/dist/skills/SkillName.js.map +1 -0
  411. package/dist/skills/SkillRegistry.d.ts +47 -7
  412. package/dist/skills/SkillRegistry.js +85 -13
  413. package/dist/skills/SkillRegistry.js.map +1 -1
  414. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  415. package/dist/skills/builtin/api_ninjas_trivia.js +24 -8
  416. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  417. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  418. package/dist/skills/builtin/ask_claude.js +36 -14
  419. package/dist/skills/builtin/ask_claude.js.map +1 -1
  420. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  421. package/dist/skills/builtin/claude_skills.js +19 -15
  422. package/dist/skills/builtin/claude_skills.js.map +1 -1
  423. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  424. package/dist/skills/builtin/custom_skills.js +26 -9
  425. package/dist/skills/builtin/custom_skills.js.map +1 -1
  426. package/dist/skills/builtin/datasphere.d.ts +5 -3
  427. package/dist/skills/builtin/datasphere.js +34 -25
  428. package/dist/skills/builtin/datasphere.js.map +1 -1
  429. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  430. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  431. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  432. package/dist/skills/builtin/datetime.d.ts +3 -1
  433. package/dist/skills/builtin/datetime.js +11 -7
  434. package/dist/skills/builtin/datetime.js.map +1 -1
  435. package/dist/skills/builtin/google_maps.d.ts +29 -14
  436. package/dist/skills/builtin/google_maps.js +89 -269
  437. package/dist/skills/builtin/google_maps.js.map +1 -1
  438. package/dist/skills/builtin/index.d.ts +8 -6
  439. package/dist/skills/builtin/index.js +8 -6
  440. package/dist/skills/builtin/index.js.map +1 -1
  441. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  442. package/dist/skills/builtin/info_gatherer.js +20 -12
  443. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  444. package/dist/skills/builtin/joke.d.ts +16 -6
  445. package/dist/skills/builtin/joke.js +54 -37
  446. package/dist/skills/builtin/joke.js.map +1 -1
  447. package/dist/skills/builtin/math.d.ts +3 -1
  448. package/dist/skills/builtin/math.js +14 -9
  449. package/dist/skills/builtin/math.js.map +1 -1
  450. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  451. package/dist/skills/builtin/mcp_gateway.js +77 -46
  452. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  453. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  454. package/dist/skills/builtin/native_vector_search.js +179 -61
  455. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  456. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  457. package/dist/skills/builtin/play_background_file.js +43 -122
  458. package/dist/skills/builtin/play_background_file.js.map +1 -1
  459. package/dist/skills/builtin/spider.d.ts +46 -1
  460. package/dist/skills/builtin/spider.js +317 -101
  461. package/dist/skills/builtin/spider.js.map +1 -1
  462. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  463. package/dist/skills/builtin/swml_transfer.js +45 -24
  464. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  465. package/dist/skills/builtin/weather_api.d.ts +24 -13
  466. package/dist/skills/builtin/weather_api.js +57 -31
  467. package/dist/skills/builtin/weather_api.js.map +1 -1
  468. package/dist/skills/builtin/web_search.d.ts +48 -10
  469. package/dist/skills/builtin/web_search.js +301 -84
  470. package/dist/skills/builtin/web_search.js.map +1 -1
  471. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  472. package/dist/skills/builtin/wikipedia_search.js +32 -14
  473. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  474. package/dist/skills/index.d.ts +3 -2
  475. package/dist/skills/index.js +1 -1
  476. package/dist/skills/index.js.map +1 -1
  477. package/dist/swml_verbs_generated.d.ts +2824 -0
  478. package/dist/swml_verbs_generated.js +12 -0
  479. package/dist/swml_verbs_generated.js.map +1 -0
  480. package/dist/types.d.ts +65 -6
  481. package/dist/web.d.ts +27 -0
  482. package/dist/web.js +20 -0
  483. package/dist/web.js.map +1 -0
  484. package/docs/agent-guide.md +1034 -0
  485. package/docs/ai_chat.md +560 -0
  486. package/docs/api-reference.md +3534 -0
  487. package/docs/architecture.md +846 -0
  488. package/docs/bedrock_agent.md +411 -0
  489. package/docs/cli-guide.md +403 -0
  490. package/docs/cloud_functions_guide.md +399 -0
  491. package/docs/configuration.md +548 -0
  492. package/docs/contexts-guide.md +884 -0
  493. package/docs/datamap-guide.md +1160 -0
  494. package/docs/developer_pain_points.md +548 -0
  495. package/docs/llm_parameters.md +298 -0
  496. package/docs/mcp_gateway_reference.md +354 -0
  497. package/docs/mcp_integration.md +162 -0
  498. package/docs/pgi_agent_guide.md +1820 -0
  499. package/docs/prefabs-guide.md +815 -0
  500. package/docs/programmatically_governed_inference.md +301 -0
  501. package/docs/sdk_features.md +501 -0
  502. package/docs/security.md +559 -0
  503. package/docs/serverless-guide.md +520 -0
  504. package/docs/skills-guide.md +1223 -0
  505. package/docs/skills-system.md +405 -0
  506. package/docs/skills_parameter_schema.md +417 -0
  507. package/docs/swaig-reference.md +1938 -0
  508. package/docs/swml_service_guide.md +573 -0
  509. package/docs/third_party_skills.md +410 -0
  510. package/docs/web_service.md +666 -0
  511. package/examples/README.md +202 -0
  512. package/examples/advanced-datamap.ts +108 -0
  513. package/examples/advanced-dynamic-config.ts +70 -0
  514. package/examples/auto-vivified.ts +95 -0
  515. package/examples/call-flow.ts +65 -0
  516. package/examples/comprehensive-dynamic.ts +125 -0
  517. package/examples/contexts-steps.ts +65 -0
  518. package/examples/custom-path.ts +45 -0
  519. package/examples/datamap-tools.ts +51 -0
  520. package/examples/datasphere-multi-instance.ts +66 -0
  521. package/examples/datasphere-serverless-env.ts +87 -0
  522. package/examples/datasphere-webhook-env.ts +65 -0
  523. package/examples/datasphere.ts +56 -0
  524. package/examples/declarative.ts +100 -0
  525. package/examples/dynamic-config.ts +54 -0
  526. package/examples/dynamic-info-gatherer.ts +69 -0
  527. package/examples/dynamic-swml-service.ts +67 -0
  528. package/examples/gather-info.ts +95 -0
  529. package/examples/gather-per-question-functions-demo.ts +139 -0
  530. package/examples/joke-agent.ts +34 -0
  531. package/examples/kubernetes-agent.ts +45 -0
  532. package/examples/llm-params.ts +75 -0
  533. package/examples/mcp-agent.ts +89 -0
  534. package/examples/mcp-gateway.ts +81 -0
  535. package/examples/multi-agent.ts +80 -0
  536. package/examples/multi-endpoint.ts +79 -0
  537. package/examples/pgi/case-domain.ts +114 -0
  538. package/examples/pgi/serve.ts +16 -0
  539. package/examples/pgi/support-agent.ts +265 -0
  540. package/examples/pom-prompt.ts +70 -0
  541. package/examples/prefab-concierge.ts +42 -0
  542. package/examples/prefab-faq.ts +58 -0
  543. package/examples/prefab-info-gatherer.ts +33 -0
  544. package/examples/prefab-receptionist.ts +36 -0
  545. package/examples/prefab-survey.ts +69 -0
  546. package/examples/quickstart-agent.ts +29 -0
  547. package/examples/quickstart-relay.ts +25 -0
  548. package/examples/quickstart-rest.ts +25 -0
  549. package/examples/record-call.ts +65 -0
  550. package/examples/relay-demo.ts +33 -0
  551. package/examples/room-and-sip.ts +93 -0
  552. package/examples/serverless-lambda.ts +43 -0
  553. package/examples/session-state.ts +83 -0
  554. package/examples/simple-agent.ts +36 -0
  555. package/examples/simple-static.ts +29 -0
  556. package/examples/skills-demo.ts +41 -0
  557. package/examples/step-function-inheritance-demo.ts +124 -0
  558. package/examples/swaig-features.ts +193 -0
  559. package/examples/swml-service-routing.ts +66 -0
  560. package/examples/swml-service.ts +38 -0
  561. package/examples/swmlservice_ai_sidecar.ts +104 -0
  562. package/examples/swmlservice_swaig_standalone.ts +79 -0
  563. package/examples/tap.ts +67 -0
  564. package/examples/typed-tools.ts +68 -0
  565. package/examples/verb-methods.ts +45 -0
  566. package/examples/web-search-multi-instance.ts +75 -0
  567. package/examples/web-search.ts +38 -0
  568. package/examples/wikipedia.ts +36 -0
  569. package/livewire/README.md +164 -0
  570. package/livewire/docs/migration-guide.md +251 -0
  571. package/livewire/examples/livewire-basic-agent.ts +74 -0
  572. package/livewire/examples/livewire-handoff.ts +196 -0
  573. package/livewire/examples/livewire-multi-tool.ts +121 -0
  574. package/package.json +88 -13
  575. package/relay/README.md +101 -0
  576. package/relay/docs/call-methods.md +622 -0
  577. package/relay/docs/client-reference.md +281 -0
  578. package/relay/docs/events.md +193 -0
  579. package/relay/docs/getting-started.md +221 -0
  580. package/relay/docs/guide.md +386 -0
  581. package/relay/docs/messaging.md +246 -0
  582. package/relay/examples/relay-inbound.ts +66 -0
  583. package/relay/examples/relay-messaging.ts +74 -0
  584. package/relay/examples/relay-outbound.ts +76 -0
  585. package/rest/README.md +141 -0
  586. package/rest/docs/calling.md +313 -0
  587. package/rest/docs/client-reference.md +149 -0
  588. package/rest/docs/fabric.md +192 -0
  589. package/rest/docs/getting-started.md +138 -0
  590. package/rest/docs/guide.md +421 -0
  591. package/rest/docs/namespaces.md +367 -0
  592. package/rest/docs/phone-binding.md +116 -0
  593. package/rest/examples/rest-10dlc-registration.ts +177 -0
  594. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  595. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  596. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  597. package/rest/examples/rest-client.ts +59 -0
  598. package/rest/examples/rest-datasphere-search.ts +81 -0
  599. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  600. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  601. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  602. package/rest/examples/rest-manage-resources.ts +64 -0
  603. package/rest/examples/rest-phone-number-management.ts +200 -0
  604. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  605. package/rest/examples/rest-video-rooms.ts +186 -0
  606. package/tutorial/fred/fred.ts +218 -0
  607. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  608. package/tutorial/fred/tutorial/02-setup.md +304 -0
  609. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  610. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  611. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  612. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  613. package/tutorial/fred/tutorial/README.md +56 -0
  614. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  615. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  616. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  617. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  618. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  619. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  620. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  621. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  622. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  623. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  624. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  625. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  626. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  627. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  628. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  629. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  630. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  631. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  632. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  633. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  634. package/tutorial/multi_agents/README.md +175 -0
  635. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  636. package/tutorial/multi_agents/extending_agents.ts +641 -0
  637. package/tutorial/multi_agents/knowledge.ts +59 -0
  638. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  639. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  640. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  641. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  642. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  643. package/tutorial/multi_agents/pc_builder.ts +529 -0
  644. package/tutorial/multi_agents/sales_agent.ts +88 -0
  645. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  646. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  647. package/tutorial/multi_agents/support_knowledge.md +256 -0
  648. package/dist/cli/mock-data.d.ts +0 -37
  649. package/dist/cli/mock-data.js +0 -80
  650. package/dist/cli/mock-data.js.map +0 -1
  651. package/dist/generateVerbTypes.d.ts +0 -11
  652. package/dist/generateVerbTypes.js +0 -265
  653. package/dist/generateVerbTypes.js.map +0 -1
  654. package/dist/rest/namespaces/compat.d.ts +0 -585
  655. package/dist/rest/namespaces/compat.js +0 -735
  656. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -5,22 +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
- import { SwaigFunction, type SwaigHandler } from './SwaigFunction.js';
11
+ import { PromptObjectModel } from './POM/PromptObjectModel.js';
12
+ import { SWMLService } from './SWMLService.js';
13
+ import { SwaigFunction, type SwaigErrorHandler } from './SwaigFunction.js';
14
+ import { type TypedToolHandler } from './TypeInference.js';
10
15
  import { ContextBuilder } from './ContextBuilder.js';
16
+ import { type Logger } from './Logger.js';
11
17
  import { SkillManager } from './skills/SkillManager.js';
12
18
  import type { SkillBase, SkillConfig } from './skills/SkillBase.js';
19
+ import type { SkillNameOrString } from './skills/SkillName.js';
13
20
  import { type ServerlessEvent, type ServerlessResponse } from './ServerlessAdapter.js';
14
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';
15
24
  /**
16
25
  * Callback invoked at a registered routing endpoint to determine how to handle an
17
26
  * incoming request. Return a route string to redirect to that agent route, or
18
27
  * null / undefined to let normal SWML processing continue.
19
28
  *
20
- * Mirrors Python `web_mixin.register_routing_callback` callback signature (body-only
21
- * 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.
22
33
  */
23
- 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>;
24
35
  /**
25
36
  * Core agent class that composes an HTTP server, prompt management, session handling,
26
37
  * SWAIG tool registry, and 5-phase SWML rendering into a single deployable unit.
@@ -82,21 +93,11 @@ export type RoutingCallback = (body: Record<string, unknown>) => string | null |
82
93
  * @see {@link DataMap} — server-side tools without webhooks
83
94
  * @see {@link AgentServer} — host multiple agents on one HTTP server
84
95
  */
85
- export declare class AgentBase {
86
- /** Display name of this agent. */
87
- name: string;
88
- /** HTTP route path this agent listens on. */
89
- route: string;
90
- /** Hostname the HTTP server binds to. */
91
- host: string;
92
- /** Port number the HTTP server listens on. */
93
- port: number;
96
+ export declare class AgentBase extends SWMLService {
94
97
  /** Unique identifier for this agent instance. */
95
98
  agentId: string;
96
99
  private _promptManager;
97
100
  private sessionManager;
98
- private swmlBuilder;
99
- private toolRegistry;
100
101
  private basicAuthCreds;
101
102
  private basicAuthSource;
102
103
  private autoAnswer;
@@ -107,6 +108,7 @@ export declare class AgentBase {
107
108
  private _nativeFunctions;
108
109
  private hints;
109
110
  private languages;
111
+ private multilingual;
110
112
  private pronounce;
111
113
  private params;
112
114
  private globalData;
@@ -118,11 +120,20 @@ export declare class AgentBase {
118
120
  private answerConfig;
119
121
  private postAnswerVerbs;
120
122
  private postAiVerbs;
121
- 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;
122
131
  private swaigQueryParams;
123
132
  private webHookUrlOverride;
124
133
  private postPromptUrlOverride;
125
134
  private contextsBuilder;
135
+ /** Contexts given as a plain object, rendered as they are. */
136
+ private _rawContexts;
126
137
  private _mcpServers;
127
138
  private _mcpServerEnabled;
128
139
  private _sipRoutingEnabled;
@@ -131,21 +142,49 @@ export declare class AgentBase {
131
142
  private _sipUsernames;
132
143
  private debugEventsEnabled;
133
144
  private debugEventsLevel;
134
- private _proxyUrlBase;
135
- private _proxyUrlBaseFromEnv;
136
145
  private _proxyDebug;
137
146
  private _trustProxyHeaders;
138
147
  private _enforceHttps;
139
- /** Structured logger instance for this agent, configurable via SIGNALWIRE_LOG_LEVEL. */
140
- log: import("./Logger.js").Logger;
148
+ /** Structured logger instance for this agent. Override the inherited
149
+ * SWMLService logger with an AgentBase-tagged one. */
150
+ log: Logger;
141
151
  private _skillManager;
142
152
  private _enablePostPromptOverride;
143
153
  private _checkForInputOverride;
144
154
  private _schemaValidation;
145
155
  private _configFile;
146
156
  private _schemaPath;
147
- private _routingCallbacks;
148
- private _app;
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;
187
+ private _appBuiltByAgent;
149
188
  /**
150
189
  * Create a new AgentBase instance.
151
190
  * @param opts - Agent configuration options including name, route, auth, and call settings.
@@ -161,12 +200,45 @@ export declare class AgentBase {
161
200
  bullets?: string[];
162
201
  numbered?: boolean;
163
202
  }[];
203
+ /** Guards {@link ensureToolsDefined} so `defineTools()` runs at most once. */
204
+ private _toolsDefined;
164
205
  /**
165
- * Lifecycle method to register tools. Subclasses should call this at the
166
- * end of their own constructor (after all fields are initialized).
167
- * 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.
168
219
  */
169
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;
170
242
  /**
171
243
  * Public access to the list of registered tools.
172
244
  *
@@ -183,6 +255,24 @@ export declare class AgentBase {
183
255
  * provides equivalent access for direct POM manipulation.
184
256
  */
185
257
  get promptManager(): PromptManager;
258
+ /**
259
+ * Public accessor for the agent's POM as a {@link PromptObjectModel} instance.
260
+ *
261
+ * Python equivalent: ``agent.pom`` instance attribute (agent_base.py line 209)
262
+ * is a ``signalwire.pom.pom.PromptObjectModel`` when ``use_pom=True``,
263
+ * or ``None`` otherwise. This getter returns the equivalent TypeScript
264
+ * ``PromptObjectModel`` instance — callers can use ``addSection``,
265
+ * ``findSection``, ``renderMarkdown``, ``renderXml``, ``toJson``, ``toYaml``
266
+ * exactly as in Python.
267
+ *
268
+ * The instance returned is a fresh snapshot built from the current
269
+ * ``PomBuilder`` state, so mutating it does not feed back into the agent's
270
+ * internal builder. To mutate the agent's prompt, use
271
+ * ``promptAddSection`` / ``promptAddToSection`` / ``promptAddSubsection``.
272
+ *
273
+ * @returns A `PromptObjectModel` populated with the agent's sections, or `null` when POM mode is off.
274
+ */
275
+ get pom(): PromptObjectModel | null;
186
276
  /**
187
277
  * Public accessor for the native functions list.
188
278
  *
@@ -279,6 +369,17 @@ export declare class AgentBase {
279
369
  * @returns The post-prompt string, or null if not configured.
280
370
  */
281
371
  getPostPrompt(): string | null;
372
+ /**
373
+ * Get the raw prompt text whatever `setPromptText` stored, or null when
374
+ * no raw prompt has been set.
375
+ *
376
+ * Matches Python `PromptManager.get_raw_prompt()` which returns the raw
377
+ * stored string or `None`. Use this instead of `getPrompt()` when you
378
+ * need the unrendered text rather than the POM-rendered Markdown.
379
+ *
380
+ * @returns The raw prompt string, or null if not set.
381
+ */
382
+ getRawPrompt(): string | null;
282
383
  /**
283
384
  * Set the prompt as a POM (Prompt Object Model) dictionary.
284
385
  *
@@ -292,11 +393,20 @@ export declare class AgentBase {
292
393
  */
293
394
  setPromptPom(pom: Record<string, unknown>[]): this;
294
395
  /**
295
- * Define or replace the contexts configuration for the AI verb.
296
- * @param contexts - An existing ContextBuilder instance or a plain object; a new ContextBuilder is created if omitted.
297
- * @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.
298
407
  */
299
- defineContexts(contexts?: ContextBuilder | Record<string, unknown>): ContextBuilder;
408
+ defineContexts(contexts?: ContextBuilder): ContextBuilder;
409
+ defineContexts(contexts: Record<string, unknown>): this;
300
410
  /**
301
411
  * Remove all contexts, returning the agent to a no-contexts state.
302
412
  *
@@ -307,6 +417,16 @@ export declare class AgentBase {
307
417
  * @returns This agent instance for chaining.
308
418
  */
309
419
  resetContexts(): this;
420
+ /**
421
+ * Get the contexts dictionary as serialised SWML, or null when no
422
+ * contexts have been defined yet.
423
+ *
424
+ * Matches Python `PromptManager.get_contexts()` which returns the
425
+ * contexts dict or `None`.
426
+ *
427
+ * @returns Contexts dict, or null when no contexts are defined.
428
+ */
429
+ getContexts(): Record<string, unknown> | null;
310
430
  /**
311
431
  * Add a single speech-recognition hint.
312
432
  * @param hint - Word or phrase to boost in speech recognition.
@@ -334,6 +454,10 @@ export declare class AgentBase {
334
454
  /**
335
455
  * Add a supported language to the AI configuration.
336
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`).
337
461
  * @returns This agent instance for chaining.
338
462
  */
339
463
  addLanguage(config: LanguageConfig): this;
@@ -343,6 +467,44 @@ export declare class AgentBase {
343
467
  * @returns This agent instance for chaining.
344
468
  */
345
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;
346
508
  /**
347
509
  * Add a pronunciation override rule for the TTS engine.
348
510
  * @param rule - Pronunciation rule specifying the text to replace and its substitute.
@@ -369,25 +531,55 @@ export declare class AgentBase {
369
531
  */
370
532
  setParams(params: Record<string, unknown>): this;
371
533
  /**
372
- * Merge data into the global_data object passed into the AI configuration.
373
- *
374
- * Matches Python `set_global_data` which calls `.update()` on the internal dict —
375
- * existing keys are preserved; incoming keys overwrite on collision. Skills and
376
- * 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.
377
541
  *
378
- * If you need to replace the entire object, assign a new agent instance or use
379
- * `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}.
380
546
  *
381
547
  * @param data - Key-value pairs to merge into global data.
382
548
  * @returns This agent instance for chaining.
549
+ * @see updateGlobalData - explicit merge alias.
550
+ * @see replaceGlobalData - true replace semantics.
383
551
  */
384
552
  setGlobalData(data: Record<string, unknown>): this;
385
553
  /**
386
- * 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
+ *
387
559
  * @param data - Key-value pairs to merge into global data.
388
560
  * @returns This agent instance for chaining.
561
+ * @see replaceGlobalData - to clear prior keys instead of merging.
389
562
  */
390
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;
391
583
  /**
392
584
  * Set the list of native SWAIG function names (built-in platform functions).
393
585
  * @param funcs - Array of native function names.
@@ -520,8 +712,8 @@ export declare class AgentBase {
520
712
  *
521
713
  * When called, the endpoint at `path` will invoke `callback` with the parsed
522
714
  * request body. If `callback` returns a non-empty route string the server
523
- * responds with `{ action: "redirect", route }` so the platform can forward the
524
- * 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
525
717
  * agent's own SWML is returned instead (normal processing).
526
718
  *
527
719
  * Mirrors Python `swml_service.register_routing_callback` /
@@ -539,7 +731,7 @@ export declare class AgentBase {
539
731
  * @param requestBody - The parsed request body containing call information.
540
732
  * @returns The extracted SIP username, or null if not found.
541
733
  */
542
- static extractSipUsername(requestBody: Record<string, unknown>): string | null;
734
+ static extractSipUsername(requestBody: SwmlRequestData): string | null;
543
735
  /**
544
736
  * Add an external MCP server for tool discovery and invocation.
545
737
  * Tools are discovered via MCP protocol at session start and added to the AI's tool list.
@@ -555,6 +747,8 @@ export declare class AgentBase {
555
747
  /**
556
748
  * Expose this agent's tools as an MCP server endpoint at /mcp.
557
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).
558
752
  * @returns This agent instance for chaining
559
753
  */
560
754
  enableMcpServer(): this;
@@ -562,82 +756,16 @@ export declare class AgentBase {
562
756
  isMcpServerEnabled(): boolean;
563
757
  /** Get configured MCP servers (read-only copy). */
564
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;
565
765
  /** Build MCP tool list from registered tools. */
566
766
  private buildMcpToolList;
567
767
  /** Handle an MCP JSON-RPC 2.0 request. Returns the response object. */
568
768
  handleMcpRequest(body: Record<string, unknown>): Promise<Record<string, unknown>>;
569
- /**
570
- * Register a SWAIG tool (function) that the AI can invoke during a call.
571
- *
572
- * ## How this becomes a tool the model sees
573
- *
574
- * A SWAIG function is **exactly the same concept** as a "tool" in
575
- * native OpenAI / Anthropic tool calling. On every LLM turn, the SDK
576
- * renders each registered SWAIG function into the OpenAI tool schema:
577
- *
578
- * ```json
579
- * {
580
- * "type": "function",
581
- * "function": {
582
- * "name": "your_name_here",
583
- * "description": "your description text",
584
- * "parameters": { /* your JSON schema *\/ }
585
- * }
586
- * }
587
- * ```
588
- *
589
- * That schema goes to the model in the same API call that produces
590
- * the next assistant message. The model reads:
591
- *
592
- * - the **function `description`** to decide WHEN to call this tool
593
- * - each **parameter `description`** (inside the JSON schema) to
594
- * decide HOW to fill in each argument
595
- *
596
- * This means **descriptions are prompt engineering**, not developer
597
- * comments. A vague description is the #1 cause of "the model has the
598
- * right tool but doesn't call it" failures.
599
- *
600
- * ### Bad vs good descriptions
601
- *
602
- * ```text
603
- * BAD : description: 'Lookup function'
604
- * GOOD: description: 'Look up a customer's account details by account
605
- * number. Use this BEFORE quoting any account-specific info
606
- * (balance, plan, status). Do not use for general product
607
- * questions.'
608
- *
609
- * BAD : parameters: { id: { type: 'string', description: 'the id' } }
610
- * GOOD: parameters: { account_number: { type: 'string', description:
611
- * 'The customer's 8-digit account number, no dashes or spaces.
612
- * Ask the user if they don't provide it.' } }
613
- * ```
614
- *
615
- * ### Tool count matters
616
- *
617
- * LLM tool selection accuracy degrades past ~7-8 simultaneously-active
618
- * tools per call. Use Step.setFunctions() to partition tools across
619
- * steps so only the relevant subset is active at any moment.
620
- *
621
- * @param opts - Tool definition including name, description, parameter
622
- * schema, and handler callback. `description` and per-parameter
623
- * `description` strings are LLM-facing prompt engineering.
624
- * @returns This agent instance for chaining.
625
- */
626
- defineTool(opts: {
627
- name: string;
628
- description: string;
629
- parameters?: Record<string, unknown>;
630
- handler: SwaigHandler;
631
- secure?: boolean;
632
- fillers?: Record<string, string[]>;
633
- waitFile?: string;
634
- waitFileLoops?: number;
635
- required?: string[];
636
- /** External webhook URL; makes this an externally-hosted tool. */
637
- webhookUrl?: string;
638
- /** Additional fields to pass through to the SWAIG function definition (Python `**swaig_fields` equivalent). */
639
- extraFields?: Record<string, unknown>;
640
- }): this;
641
769
  /**
642
770
  * Register a SWAIG tool with a typed handler that receives named parameters
643
771
  * instead of the standard `(args, rawData)` convention.
@@ -653,34 +781,20 @@ export declare class AgentBase {
653
781
  name: string;
654
782
  description: string;
655
783
  parameters?: Record<string, unknown>;
656
- 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;
657
792
  secure?: boolean;
658
793
  fillers?: Record<string, string[]>;
659
794
  waitFile?: string;
660
795
  waitFileLoops?: number;
661
796
  required?: string[];
662
797
  }): this;
663
- /**
664
- * Get a summary of all registered tools with their names, descriptions, and parameter schemas.
665
- * @returns Array of tool descriptors.
666
- */
667
- getRegisteredTools(): {
668
- name: string;
669
- description: string;
670
- parameters: Record<string, unknown>;
671
- }[];
672
- /**
673
- * Look up a registered SwaigFunction by name.
674
- * @param name - The tool name to search for.
675
- * @returns The SwaigFunction instance, or undefined if not found or not a SwaigFunction.
676
- */
677
- getTool(name: string): SwaigFunction | undefined;
678
- /**
679
- * Register a pre-built SwaigFunction instance or a raw function descriptor (e.g. DataMap).
680
- * @param fn - A SwaigFunction instance or a plain object with a "function" key.
681
- * @returns This agent instance for chaining.
682
- */
683
- registerSwaigFunction(fn: SwaigFunction | Record<string, unknown>): this;
684
798
  /**
685
799
  * Validate a tool-call token for the given function.
686
800
  *
@@ -704,13 +818,21 @@ export declare class AgentBase {
704
818
  * unchanged and the underlying validator will reject it.
705
819
  */
706
820
  validateToolToken(functionName: string, token: string, callId: string): boolean;
821
+ /**
822
+ * Mint a per-call SWAIG-function token via the agent's SessionManager.
823
+ *
824
+ * Mirrors Python reference `core/mixins/state_mixin.py _create_tool_token`:
825
+ * delegates to `SessionManager.createToolToken` and returns an empty
826
+ * string on any failure (Python catches all exceptions and returns "").
827
+ */
828
+ createToolToken(toolName: string, callId: string): string;
707
829
  /**
708
830
  * Add a SWML verb to execute before the answer phase (phase 1).
709
831
  * @param verbName - Name of the SWML verb (e.g. "play", "record").
710
832
  * @param config - Verb configuration object.
711
833
  * @returns This agent instance for chaining.
712
834
  */
713
- addPreAnswerVerb(verbName: string, config: Record<string, unknown>): this;
835
+ addPreAnswerVerb(verbName: string, config: Record<string, unknown> | number): this;
714
836
  /**
715
837
  * Configure the answer verb (phase 2) with optional settings.
716
838
  * @param config - Optional answer verb configuration.
@@ -723,7 +845,7 @@ export declare class AgentBase {
723
845
  * @param config - Verb configuration object.
724
846
  * @returns This agent instance for chaining.
725
847
  */
726
- addPostAnswerVerb(verbName: string, config: Record<string, unknown>): this;
848
+ addPostAnswerVerb(verbName: string, config: Record<string, unknown> | number): this;
727
849
  /**
728
850
  * Add a SWML verb to execute after the AI verb (phase 5).
729
851
  * @param verbName - Name of the SWML verb.
@@ -764,12 +886,19 @@ export declare class AgentBase {
764
886
  * name via the SkillManager registry. Throws a `ValueError`-equivalent if the
765
887
  * skill name is not found in the registry.
766
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
+ *
767
896
  * @param skillName - The name the skill was registered under in the SkillRegistry.
768
897
  * @param params - Optional configuration parameters forwarded to the skill factory.
769
898
  * @returns This agent instance for chaining.
770
899
  * @throws Error if no skill with the given name is registered.
771
900
  */
772
- addSkillByName(skillName: string, params?: SkillConfig): Promise<this>;
901
+ addSkillByName(skillName: SkillNameOrString, params?: SkillConfig): Promise<this>;
773
902
  /**
774
903
  * Remove a previously added skill by its instance ID.
775
904
  * @param instanceId - The unique instance ID of the skill to remove.
@@ -787,27 +916,59 @@ export declare class AgentBase {
787
916
  }[];
788
917
  /**
789
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
+ *
790
924
  * @param skillName - The skill name to check.
791
925
  * @returns True if a skill with that name exists.
792
926
  */
793
- hasSkill(skillName: string): boolean;
927
+ hasSkill(skillName: SkillNameOrString): boolean;
794
928
  /**
795
- * Remove a skill by its name (Python parity).
929
+ * Remove a skill by its name (matches the Python SDK).
796
930
  *
797
931
  * Python's `remove_skill(skill_name)` removes by skill name.
798
932
  * The existing `removeSkill(instanceId)` removes by instance ID.
799
- * This method provides name-based removal for cross-SDK parity.
933
+ * This method provides name-based removal to match the Python SDK.
800
934
  *
801
935
  * @param skillName - The skill name to remove.
802
936
  * @returns True if a skill with that name was found and removed.
803
937
  */
804
938
  removeSkillByName(skillName: string): Promise<boolean>;
805
939
  /**
806
- * Set a callback invoked on each SWML request to dynamically modify an ephemeral agent copy.
807
- *
808
- * The callback receives a clone of this agent — mutations apply only to the current
809
- * request, so you can vary prompt, tools, languages, params, or global data per call
810
- * 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.
811
972
  *
812
973
  * @param cb - Callback receiving `(queryParams, bodyParams, headers, agent)` where
813
974
  * `agent` is the ephemeral `AgentBase` copy to mutate. May be async.
@@ -824,6 +985,80 @@ export declare class AgentBase {
824
985
  * ```
825
986
  */
826
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;
827
1062
  /**
828
1063
  * Add extra query parameters appended to all SWAIG webhook URLs.
829
1064
  * @param params - Key-value pairs to append as query parameters.
@@ -874,13 +1109,18 @@ export declare class AgentBase {
874
1109
  * @returns The fully-qualified URL string.
875
1110
  */
876
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;
877
1117
  private insertAuth;
878
1118
  private buildWebhookUrl;
879
1119
  /**
880
1120
  * Lifecycle hook called when a post-prompt summary is received. Override in subclasses.
881
1121
  *
882
1122
  * Invoked once at the end of a call when the AI has produced a structured summary
883
- * (configured via `setPostPrompt()` / `setPostPromptJson()`). Use this hook to persist
1123
+ * (configured via `setPostPrompt()`). Use this hook to persist
884
1124
  * call data, notify other systems, or trigger follow-up workflows.
885
1125
  *
886
1126
  * @param _summary - Parsed summary object (JSON when the post-prompt requests
@@ -888,6 +1128,12 @@ export declare class AgentBase {
888
1128
  * @param _rawData - Full raw post-prompt payload received from the platform,
889
1129
  * including call metadata, conversation history, and the summary text.
890
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
+ *
891
1137
  * @example
892
1138
  * ```ts
893
1139
  * class MyAgent extends AgentBase {
@@ -902,7 +1148,23 @@ export declare class AgentBase {
902
1148
  * }
903
1149
  * ```
904
1150
  */
905
- 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>>;
1152
+ /**
1153
+ * Lifecycle hook called when SWML is requested. Default delegates to
1154
+ * {@link onSwmlRequest} and returns its result. Subclasses typically
1155
+ * override `onSwmlRequest` rather than this method.
1156
+ *
1157
+ * Matches Python `WebMixin.on_request(request_data, callback_path)`. The
1158
+ * cross-language API is the two-arg form; the Hono `context` argument is
1159
+ * a TypeScript-side extra preserved for callers that already have it but
1160
+ * is not part of the audited surface.
1161
+ *
1162
+ * @param requestData - The parsed request body.
1163
+ * @param callbackPath - Optional callback path from the request.
1164
+ * @returns Optionally a dict of SWML modifications, or undefined for
1165
+ * default rendering.
1166
+ */
1167
+ onRequest(requestData?: SwmlRequestData | null, callbackPath?: string | null): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
906
1168
  /**
907
1169
  * Lifecycle hook called on every SWML request before rendering. Override in subclasses.
908
1170
  *
@@ -919,19 +1181,54 @@ export declare class AgentBase {
919
1181
  * @param _context - The raw Hono context object (c), providing access to headers and query params.
920
1182
  * @returns Optionally a dict of SWML modifications, or void.
921
1183
  */
922
- 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;
923
1216
  /**
924
1217
  * Lifecycle hook called when a debug event webhook is received. Override in subclasses.
925
1218
  * @param _event - The debug event payload.
926
1219
  */
927
1220
  onDebugEvent(_event: Record<string, unknown>): void | Promise<void>;
928
1221
  /**
929
- * Override to add custom basic-auth validation logic beyond credential matching.
930
- * @param _username - The username from the request.
931
- * @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.
932
1229
  * @returns True if the credentials are valid; false to reject the request.
933
1230
  */
934
- validateBasicAuth(_username: string, _password: string): boolean | Promise<boolean>;
1231
+ validateBasicAuth(username: string, password: string): boolean | Promise<boolean>;
935
1232
  /**
936
1233
  * Hook called before each SWAIG function execution. Override in subclasses.
937
1234
  *
@@ -939,7 +1236,7 @@ export declare class AgentBase {
939
1236
  * — it retrieves and executes the function, returning the result. In TypeScript,
940
1237
  * `fn.execute()` is called separately after this hook. However, if this method
941
1238
  * returns a non-void value, it is used as the result and the default execution
942
- * is skipped, enabling dispatch interception parity with Python.
1239
+ * is skipped, enabling dispatch interception matching the Python SDK.
943
1240
  *
944
1241
  * @param _name - Name of the function about to execute.
945
1242
  * @param _args - Parsed arguments for the function.
@@ -948,6 +1245,36 @@ export declare class AgentBase {
948
1245
  * or void/undefined to proceed normally.
949
1246
  */
950
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;
951
1278
  /**
952
1279
  * Render the complete SWML document by assembling all 5 phases: pre-answer, answer,
953
1280
  * post-answer, AI, and post-AI verbs.
@@ -960,16 +1287,62 @@ export declare class AgentBase {
960
1287
  */
961
1288
  renderSwml(callId?: string, modifications?: Record<string, unknown>): string;
962
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;
963
1304
  /**
964
1305
  * Get or lazily create the Hono HTTP application with all routes, middleware, auth, and CORS.
965
1306
  * @returns The configured Hono application instance.
966
1307
  */
967
1308
  getApp(): Hono;
968
1309
  /**
969
- * Return this agent's Hono app for mounting as a sub-router in an AgentServer.
970
- * @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.
971
1317
  */
972
- 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;
973
1346
  /**
974
1347
  * Start the HTTP server and begin listening for requests.
975
1348
  *
@@ -994,21 +1367,35 @@ export declare class AgentBase {
994
1367
  port?: number;
995
1368
  }): Promise<void>;
996
1369
  /**
997
- * Alias for {@link serve}. Starts the HTTP server.
998
- * @param opts - Optional host and port overrides.
999
- * @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.
1000
1384
  */
1001
1385
  run(opts?: {
1002
1386
  host?: string;
1003
1387
  port?: number;
1004
- }): Promise<void>;
1388
+ event?: ServerlessEvent;
1389
+ context?: unknown;
1390
+ platform?: 'lambda' | 'gcf' | 'azure' | 'cgi' | 'auto';
1391
+ }): Promise<void | ServerlessResponse>;
1005
1392
  /**
1006
1393
  * Handle a single serverless invocation (AWS Lambda, Google Cloud Functions, Azure Functions, or CGI).
1007
1394
  *
1008
1395
  * Matches Python `run(event, context)` when executed in a serverless environment. Python's
1009
1396
  * `run()` auto-detects the platform via `get_execution_mode()` and dispatches accordingly;
1010
- * in TypeScript the serverless path is an **explicit** method so that `run()` keeps its
1011
- * 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).
1012
1399
  *
1013
1400
  * Platform detection follows the same environment-variable heuristics as Python's
1014
1401
  * `ServerlessMixin`: `AWS_LAMBDA_FUNCTION_NAME` → Lambda, `K_SERVICE` → GCF,
@@ -1041,5 +1428,5 @@ export declare class AgentBase {
1041
1428
  * @returns A tuple of [username, password] or [username, password, source].
1042
1429
  */
1043
1430
  getBasicAuthCredentials(includeSource?: false): [string, string];
1044
- getBasicAuthCredentials(includeSource: true): [string, string, 'provided' | 'environment' | 'auto-generated'];
1431
+ getBasicAuthCredentials(includeSource: true): [string, string, 'provided' | 'environment' | 'config file' | 'generated'];
1045
1432
  }