@signalwire/sdk 2.0.1 → 2.0.2

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 (610) hide show
  1. package/dist/AgentBase.d.ts +1045 -0
  2. package/dist/AgentBase.js +2375 -0
  3. package/dist/AgentBase.js.map +1 -0
  4. package/dist/AgentServer.d.ts +146 -0
  5. package/dist/AgentServer.js +388 -0
  6. package/dist/AgentServer.js.map +1 -0
  7. package/dist/AuthHandler.d.ts +127 -0
  8. package/dist/AuthHandler.js +212 -0
  9. package/dist/AuthHandler.js.map +1 -0
  10. package/dist/ConfigLoader.d.ts +170 -0
  11. package/dist/ConfigLoader.js +393 -0
  12. package/dist/ConfigLoader.js.map +1 -0
  13. package/dist/ContextBuilder.d.ts +652 -0
  14. package/dist/ContextBuilder.js +1115 -0
  15. package/dist/ContextBuilder.js.map +1 -0
  16. package/dist/DataMap.d.ts +271 -0
  17. package/dist/DataMap.js +430 -0
  18. package/dist/DataMap.js.map +1 -0
  19. package/dist/FunctionResult.d.ts +481 -0
  20. package/dist/FunctionResult.js +775 -0
  21. package/dist/FunctionResult.js.map +1 -0
  22. package/dist/Logger.d.ts +113 -0
  23. package/dist/Logger.js +320 -0
  24. package/dist/Logger.js.map +1 -0
  25. package/dist/PomBuilder.d.ts +208 -0
  26. package/dist/PomBuilder.js +409 -0
  27. package/dist/PomBuilder.js.map +1 -0
  28. package/dist/PromptManager.d.ts +85 -0
  29. package/dist/PromptManager.js +108 -0
  30. package/dist/PromptManager.js.map +1 -0
  31. package/dist/SWMLHandler.d.ts +159 -0
  32. package/dist/SWMLHandler.js +229 -0
  33. package/dist/SWMLHandler.js.map +1 -0
  34. package/dist/SWMLService.d.ts +326 -0
  35. package/dist/SWMLService.js +610 -0
  36. package/dist/SWMLService.js.map +1 -0
  37. package/dist/SchemaUtils.d.ts +108 -0
  38. package/dist/SchemaUtils.js +317 -0
  39. package/dist/SchemaUtils.js.map +1 -0
  40. package/dist/SecurityUtils.d.ts +60 -0
  41. package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
  42. package/dist/SecurityUtils.js.map +1 -0
  43. package/dist/ServerlessAdapter.d.ts +119 -0
  44. package/dist/ServerlessAdapter.js +188 -0
  45. package/dist/ServerlessAdapter.js.map +1 -0
  46. package/dist/SessionManager.d.ts +142 -0
  47. package/dist/SessionManager.js +260 -0
  48. package/dist/SessionManager.js.map +1 -0
  49. package/dist/SslConfig.d.ts +77 -0
  50. package/dist/SslConfig.js +100 -0
  51. package/dist/SslConfig.js.map +1 -0
  52. package/dist/SwaigFunction.d.ts +159 -0
  53. package/dist/SwaigFunction.js +209 -0
  54. package/dist/SwaigFunction.js.map +1 -0
  55. package/dist/SwmlBuilder.d.ts +165 -0
  56. package/dist/SwmlBuilder.js +247 -0
  57. package/dist/SwmlBuilder.js.map +1 -0
  58. package/dist/SwmlVerbMethods.generated.d.ts +254 -0
  59. package/dist/SwmlVerbMethods.generated.js +9 -0
  60. package/dist/SwmlVerbMethods.generated.js.map +1 -0
  61. package/dist/TypeInference.d.ts +71 -0
  62. package/dist/TypeInference.js +164 -0
  63. package/dist/TypeInference.js.map +1 -0
  64. package/dist/WebService.d.ts +148 -0
  65. package/dist/WebService.js +532 -0
  66. package/dist/WebService.js.map +1 -0
  67. package/dist/cli/agent-loader.d.ts +22 -0
  68. package/dist/cli/agent-loader.js +144 -0
  69. package/dist/cli/agent-loader.js.map +1 -0
  70. package/dist/cli/mock-data.d.ts +37 -0
  71. package/dist/cli/mock-data.js +80 -0
  72. package/dist/cli/mock-data.js.map +1 -0
  73. package/dist/cli/swaig-test.d.ts +32 -0
  74. package/dist/cli/swaig-test.js +418 -0
  75. package/dist/cli/swaig-test.js.map +1 -0
  76. package/dist/generateVerbTypes.d.ts +11 -0
  77. package/dist/generateVerbTypes.js +265 -0
  78. package/dist/generateVerbTypes.js.map +1 -0
  79. package/{src/index.ts → dist/index.d.ts} +13 -100
  80. package/dist/index.js +152 -0
  81. package/dist/index.js.map +1 -0
  82. package/dist/livewire/index.d.ts +653 -0
  83. package/dist/livewire/index.js +992 -0
  84. package/dist/livewire/index.js.map +1 -0
  85. package/dist/prefabs/ConciergeAgent.d.ts +89 -0
  86. package/dist/prefabs/ConciergeAgent.js +245 -0
  87. package/dist/prefabs/ConciergeAgent.js.map +1 -0
  88. package/dist/prefabs/FAQBotAgent.d.ts +113 -0
  89. package/dist/prefabs/FAQBotAgent.js +329 -0
  90. package/dist/prefabs/FAQBotAgent.js.map +1 -0
  91. package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
  92. package/dist/prefabs/InfoGathererAgent.js +287 -0
  93. package/dist/prefabs/InfoGathererAgent.js.map +1 -0
  94. package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
  95. package/dist/prefabs/ReceptionistAgent.js +303 -0
  96. package/dist/prefabs/ReceptionistAgent.js.map +1 -0
  97. package/dist/prefabs/SurveyAgent.d.ts +148 -0
  98. package/dist/prefabs/SurveyAgent.js +540 -0
  99. package/dist/prefabs/SurveyAgent.js.map +1 -0
  100. package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
  101. package/dist/prefabs/index.js +14 -0
  102. package/dist/prefabs/index.js.map +1 -0
  103. package/dist/relay/Action.d.ts +258 -0
  104. package/dist/relay/Action.js +402 -0
  105. package/dist/relay/Action.js.map +1 -0
  106. package/dist/relay/Call.d.ts +697 -0
  107. package/dist/relay/Call.js +1062 -0
  108. package/dist/relay/Call.js.map +1 -0
  109. package/dist/relay/Deferred.d.ts +44 -0
  110. package/dist/relay/Deferred.js +69 -0
  111. package/dist/relay/Deferred.js.map +1 -0
  112. package/dist/relay/Message.d.ts +103 -0
  113. package/dist/relay/Message.js +169 -0
  114. package/dist/relay/Message.js.map +1 -0
  115. package/dist/relay/RelayClient.d.ts +302 -0
  116. package/dist/relay/RelayClient.js +1019 -0
  117. package/dist/relay/RelayClient.js.map +1 -0
  118. package/dist/relay/RelayError.d.ts +15 -0
  119. package/dist/relay/RelayError.js +20 -0
  120. package/dist/relay/RelayError.js.map +1 -0
  121. package/dist/relay/RelayEvent.d.ts +254 -0
  122. package/dist/relay/RelayEvent.js +509 -0
  123. package/dist/relay/RelayEvent.js.map +1 -0
  124. package/dist/relay/constants.d.ts +90 -0
  125. package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
  126. package/dist/relay/constants.js.map +1 -0
  127. package/dist/relay/index.d.ts +16 -0
  128. package/dist/relay/index.js +18 -0
  129. package/dist/relay/index.js.map +1 -0
  130. package/dist/relay/types.d.ts +142 -0
  131. package/dist/relay/types.js +5 -0
  132. package/dist/relay/types.js.map +1 -0
  133. package/dist/rest/HttpClient.d.ts +80 -0
  134. package/dist/rest/HttpClient.js +148 -0
  135. package/dist/rest/HttpClient.js.map +1 -0
  136. package/dist/rest/RestError.d.ts +30 -0
  137. package/dist/rest/RestError.js +39 -0
  138. package/dist/rest/RestError.js.map +1 -0
  139. package/dist/rest/base/BaseResource.d.ts +24 -0
  140. package/dist/rest/base/BaseResource.js +29 -0
  141. package/dist/rest/base/BaseResource.js.map +1 -0
  142. package/dist/rest/base/CrudResource.d.ts +68 -0
  143. package/dist/rest/base/CrudResource.js +82 -0
  144. package/dist/rest/base/CrudResource.js.map +1 -0
  145. package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
  146. package/dist/rest/base/CrudWithAddresses.js +25 -0
  147. package/dist/rest/base/CrudWithAddresses.js.map +1 -0
  148. package/dist/rest/index.d.ts +131 -0
  149. package/{src/rest/index.ts → dist/rest/index.js} +101 -136
  150. package/dist/rest/index.js.map +1 -0
  151. package/dist/rest/namespaces/addresses.d.ts +46 -0
  152. package/dist/rest/namespaces/addresses.js +55 -0
  153. package/dist/rest/namespaces/addresses.js.map +1 -0
  154. package/dist/rest/namespaces/calling.d.ts +382 -0
  155. package/dist/rest/namespaces/calling.js +478 -0
  156. package/dist/rest/namespaces/calling.js.map +1 -0
  157. package/dist/rest/namespaces/chat.d.ts +22 -0
  158. package/dist/rest/namespaces/chat.js +26 -0
  159. package/dist/rest/namespaces/chat.js.map +1 -0
  160. package/dist/rest/namespaces/compat.d.ts +585 -0
  161. package/dist/rest/namespaces/compat.js +735 -0
  162. package/dist/rest/namespaces/compat.js.map +1 -0
  163. package/dist/rest/namespaces/datasphere.d.ts +66 -0
  164. package/dist/rest/namespaces/datasphere.js +77 -0
  165. package/dist/rest/namespaces/datasphere.js.map +1 -0
  166. package/dist/rest/namespaces/fabric.d.ts +282 -0
  167. package/dist/rest/namespaces/fabric.js +373 -0
  168. package/dist/rest/namespaces/fabric.js.map +1 -0
  169. package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
  170. package/dist/rest/namespaces/imported-numbers.js +26 -0
  171. package/dist/rest/namespaces/imported-numbers.js.map +1 -0
  172. package/dist/rest/namespaces/logs.d.ts +105 -0
  173. package/dist/rest/namespaces/logs.js +133 -0
  174. package/dist/rest/namespaces/logs.js.map +1 -0
  175. package/dist/rest/namespaces/lookup.d.ts +29 -0
  176. package/dist/rest/namespaces/lookup.js +32 -0
  177. package/dist/rest/namespaces/lookup.js.map +1 -0
  178. package/dist/rest/namespaces/mfa.d.ts +46 -0
  179. package/dist/rest/namespaces/mfa.js +54 -0
  180. package/dist/rest/namespaces/mfa.js.map +1 -0
  181. package/dist/rest/namespaces/number-groups.d.ts +49 -0
  182. package/dist/rest/namespaces/number-groups.js +58 -0
  183. package/dist/rest/namespaces/number-groups.js.map +1 -0
  184. package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
  185. package/dist/rest/namespaces/phone-numbers.js +67 -0
  186. package/dist/rest/namespaces/phone-numbers.js.map +1 -0
  187. package/dist/rest/namespaces/project.d.ts +46 -0
  188. package/dist/rest/namespaces/project.js +56 -0
  189. package/dist/rest/namespaces/project.js.map +1 -0
  190. package/dist/rest/namespaces/pubsub.d.ts +22 -0
  191. package/dist/rest/namespaces/pubsub.js +26 -0
  192. package/dist/rest/namespaces/pubsub.js.map +1 -0
  193. package/dist/rest/namespaces/queues.d.ts +42 -0
  194. package/dist/rest/namespaces/queues.js +49 -0
  195. package/dist/rest/namespaces/queues.js.map +1 -0
  196. package/dist/rest/namespaces/recordings.d.ts +38 -0
  197. package/dist/rest/namespaces/recordings.js +45 -0
  198. package/dist/rest/namespaces/recordings.js.map +1 -0
  199. package/dist/rest/namespaces/registry.d.ts +141 -0
  200. package/dist/rest/namespaces/registry.js +178 -0
  201. package/dist/rest/namespaces/registry.js.map +1 -0
  202. package/dist/rest/namespaces/short-codes.d.ts +39 -0
  203. package/dist/rest/namespaces/short-codes.js +46 -0
  204. package/dist/rest/namespaces/short-codes.js.map +1 -0
  205. package/dist/rest/namespaces/sip-profile.d.ts +28 -0
  206. package/dist/rest/namespaces/sip-profile.js +34 -0
  207. package/dist/rest/namespaces/sip-profile.js.map +1 -0
  208. package/dist/rest/namespaces/verified-callers.d.ts +33 -0
  209. package/dist/rest/namespaces/verified-callers.js +39 -0
  210. package/dist/rest/namespaces/verified-callers.js.map +1 -0
  211. package/dist/rest/namespaces/video.d.ts +235 -0
  212. package/dist/rest/namespaces/video.js +297 -0
  213. package/dist/rest/namespaces/video.js.map +1 -0
  214. package/{src/rest/pagination.ts → dist/rest/pagination.d.ts} +2 -61
  215. package/dist/rest/pagination.js +78 -0
  216. package/dist/rest/pagination.js.map +1 -0
  217. package/dist/rest/types.d.ts +54 -0
  218. package/dist/rest/types.js +5 -0
  219. package/dist/rest/types.js.map +1 -0
  220. package/dist/skills/SkillBase.d.ts +404 -0
  221. package/dist/skills/SkillBase.js +471 -0
  222. package/dist/skills/SkillBase.js.map +1 -0
  223. package/dist/skills/SkillManager.d.ts +195 -0
  224. package/dist/skills/SkillManager.js +378 -0
  225. package/dist/skills/SkillManager.js.map +1 -0
  226. package/dist/skills/SkillRegistry.d.ts +176 -0
  227. package/dist/skills/SkillRegistry.js +310 -0
  228. package/dist/skills/SkillRegistry.js.map +1 -0
  229. package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
  230. package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
  231. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
  232. package/dist/skills/builtin/ask_claude.d.ts +37 -0
  233. package/dist/skills/builtin/ask_claude.js +162 -0
  234. package/dist/skills/builtin/ask_claude.js.map +1 -0
  235. package/dist/skills/builtin/claude_skills.d.ts +75 -0
  236. package/dist/skills/builtin/claude_skills.js +753 -0
  237. package/dist/skills/builtin/claude_skills.js.map +1 -0
  238. package/dist/skills/builtin/custom_skills.d.ts +79 -0
  239. package/dist/skills/builtin/custom_skills.js +227 -0
  240. package/dist/skills/builtin/custom_skills.js.map +1 -0
  241. package/dist/skills/builtin/datasphere.d.ts +73 -0
  242. package/dist/skills/builtin/datasphere.js +350 -0
  243. package/dist/skills/builtin/datasphere.js.map +1 -0
  244. package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
  245. package/dist/skills/builtin/datasphere_serverless.js +291 -0
  246. package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
  247. package/dist/skills/builtin/datetime.d.ts +40 -0
  248. package/dist/skills/builtin/datetime.js +118 -0
  249. package/dist/skills/builtin/datetime.js.map +1 -0
  250. package/dist/skills/builtin/google_maps.d.ts +48 -0
  251. package/dist/skills/builtin/google_maps.js +470 -0
  252. package/dist/skills/builtin/google_maps.js.map +1 -0
  253. package/dist/skills/builtin/index.d.ts +31 -0
  254. package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
  255. package/dist/skills/builtin/index.js.map +1 -0
  256. package/dist/skills/builtin/info_gatherer.d.ts +115 -0
  257. package/dist/skills/builtin/info_gatherer.js +328 -0
  258. package/dist/skills/builtin/info_gatherer.js.map +1 -0
  259. package/dist/skills/builtin/joke.d.ts +41 -0
  260. package/dist/skills/builtin/joke.js +156 -0
  261. package/dist/skills/builtin/joke.js.map +1 -0
  262. package/dist/skills/builtin/math.d.ts +39 -0
  263. package/dist/skills/builtin/math.js +119 -0
  264. package/dist/skills/builtin/math.js.map +1 -0
  265. package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
  266. package/dist/skills/builtin/mcp_gateway.js +574 -0
  267. package/dist/skills/builtin/mcp_gateway.js.map +1 -0
  268. package/dist/skills/builtin/native_vector_search.d.ts +128 -0
  269. package/dist/skills/builtin/native_vector_search.js +752 -0
  270. package/dist/skills/builtin/native_vector_search.js.map +1 -0
  271. package/dist/skills/builtin/play_background_file.d.ts +59 -0
  272. package/dist/skills/builtin/play_background_file.js +274 -0
  273. package/dist/skills/builtin/play_background_file.js.map +1 -0
  274. package/dist/skills/builtin/spider.d.ts +91 -0
  275. package/dist/skills/builtin/spider.js +758 -0
  276. package/dist/skills/builtin/spider.js.map +1 -0
  277. package/dist/skills/builtin/swml_transfer.d.ts +66 -0
  278. package/dist/skills/builtin/swml_transfer.js +475 -0
  279. package/dist/skills/builtin/swml_transfer.js.map +1 -0
  280. package/dist/skills/builtin/weather_api.d.ts +59 -0
  281. package/dist/skills/builtin/weather_api.js +196 -0
  282. package/dist/skills/builtin/weather_api.js.map +1 -0
  283. package/dist/skills/builtin/web_search.d.ts +160 -0
  284. package/dist/skills/builtin/web_search.js +894 -0
  285. package/dist/skills/builtin/web_search.js.map +1 -0
  286. package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
  287. package/dist/skills/builtin/wikipedia_search.js +241 -0
  288. package/dist/skills/builtin/wikipedia_search.js.map +1 -0
  289. package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
  290. package/dist/skills/index.js +10 -0
  291. package/dist/skills/index.js.map +1 -0
  292. package/dist/types.d.ts +118 -0
  293. package/dist/types.js +5 -0
  294. package/dist/types.js.map +1 -0
  295. package/package.json +7 -1
  296. package/.github/workflows/publish.yml +0 -27
  297. package/.github/workflows/test.yml +0 -17
  298. package/CLAUDE.md +0 -112
  299. package/docs/MIGRATION-2.0.md +0 -81
  300. package/docs/agent-guide.md +0 -869
  301. package/docs/agent_guide.md +0 -1026
  302. package/docs/api-reference.md +0 -2420
  303. package/docs/api_reference.md +0 -1301
  304. package/docs/architecture.md +0 -843
  305. package/docs/cli-guide.md +0 -579
  306. package/docs/cli_guide.md +0 -448
  307. package/docs/cloud_functions_guide.md +0 -474
  308. package/docs/configuration.md +0 -422
  309. package/docs/contexts-guide.md +0 -787
  310. package/docs/contexts_guide.md +0 -511
  311. package/docs/datamap-guide.md +0 -1141
  312. package/docs/datamap_guide.md +0 -595
  313. package/docs/llm_parameters.md +0 -239
  314. package/docs/mcp_gateway_reference.md +0 -648
  315. package/docs/mcp_integration.md +0 -108
  316. package/docs/prefabs-guide.md +0 -800
  317. package/docs/sdk_features.md +0 -477
  318. package/docs/security.md +0 -436
  319. package/docs/serverless-guide.md +0 -513
  320. package/docs/skills-guide.md +0 -857
  321. package/docs/skills-system.md +0 -301
  322. package/docs/skills_parameter_schema.md +0 -392
  323. package/docs/skills_system.md +0 -467
  324. package/docs/swaig-reference.md +0 -1627
  325. package/docs/swaig_reference.md +0 -910
  326. package/docs/swml_service_guide.md +0 -600
  327. package/docs/third_party_skills.md +0 -533
  328. package/docs/web_service.md +0 -677
  329. package/examples/README.md +0 -131
  330. package/examples/advanced-datamap.ts +0 -100
  331. package/examples/advanced-dynamic-config.ts +0 -70
  332. package/examples/auto-vivified.ts +0 -94
  333. package/examples/call-flow.ts +0 -63
  334. package/examples/comprehensive-dynamic.ts +0 -125
  335. package/examples/contexts-steps.ts +0 -65
  336. package/examples/custom-path.ts +0 -45
  337. package/examples/datamap-tools.ts +0 -55
  338. package/examples/datasphere-multi-instance.ts +0 -63
  339. package/examples/datasphere-serverless-env.ts +0 -68
  340. package/examples/datasphere-webhook-env.ts +0 -66
  341. package/examples/datasphere.ts +0 -37
  342. package/examples/declarative.ts +0 -100
  343. package/examples/dynamic-config.ts +0 -54
  344. package/examples/dynamic-info-gatherer.ts +0 -69
  345. package/examples/dynamic-swml-service.ts +0 -67
  346. package/examples/gather-info.ts +0 -71
  347. package/examples/gather-per-question-functions-demo.ts +0 -140
  348. package/examples/joke-agent.ts +0 -34
  349. package/examples/kubernetes-agent.ts +0 -45
  350. package/examples/llm-params.ts +0 -69
  351. package/examples/mcp-agent.ts +0 -84
  352. package/examples/mcp-gateway.ts +0 -35
  353. package/examples/multi-agent.ts +0 -73
  354. package/examples/multi-endpoint.ts +0 -79
  355. package/examples/pom-prompt.ts +0 -71
  356. package/examples/prefab-concierge.ts +0 -47
  357. package/examples/prefab-faq.ts +0 -54
  358. package/examples/prefab-info-gatherer.ts +0 -33
  359. package/examples/prefab-receptionist.ts +0 -36
  360. package/examples/prefab-survey.ts +0 -68
  361. package/examples/record-call.ts +0 -67
  362. package/examples/relay-demo.ts +0 -33
  363. package/examples/room-and-sip.ts +0 -94
  364. package/examples/serverless-lambda.ts +0 -35
  365. package/examples/session-state.ts +0 -83
  366. package/examples/simple-agent.ts +0 -36
  367. package/examples/simple-static.ts +0 -29
  368. package/examples/skills-demo.ts +0 -38
  369. package/examples/step-function-inheritance-demo.ts +0 -124
  370. package/examples/swaig-features.ts +0 -187
  371. package/examples/swml-service-routing.ts +0 -66
  372. package/examples/swml-service.ts +0 -38
  373. package/examples/tap.ts +0 -68
  374. package/examples/verb-methods.ts +0 -45
  375. package/examples/web-search-multi-instance.ts +0 -72
  376. package/examples/web-search.ts +0 -38
  377. package/examples/wikipedia.ts +0 -36
  378. package/livewire/README.md +0 -140
  379. package/livewire/docs/migration-guide.md +0 -228
  380. package/livewire/examples/livewire-basic-agent.ts +0 -74
  381. package/livewire/examples/livewire-handoff.ts +0 -197
  382. package/livewire/examples/livewire-multi-tool.ts +0 -117
  383. package/relay/README.md +0 -70
  384. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
  385. package/relay/docs/call-methods.md +0 -474
  386. package/relay/docs/client-reference.md +0 -142
  387. package/relay/docs/events.md +0 -134
  388. package/relay/docs/getting-started.md +0 -134
  389. package/relay/docs/guide.md +0 -306
  390. package/relay/docs/messaging.md +0 -182
  391. package/relay/examples/relay-inbound.ts +0 -66
  392. package/relay/examples/relay-messaging.ts +0 -71
  393. package/relay/examples/relay-outbound.ts +0 -76
  394. package/rest/README.md +0 -95
  395. package/rest/docs/calling.md +0 -273
  396. package/rest/docs/client-reference.md +0 -107
  397. package/rest/docs/compat.md +0 -204
  398. package/rest/docs/fabric.md +0 -183
  399. package/rest/docs/getting-started.md +0 -110
  400. package/rest/docs/guide.md +0 -351
  401. package/rest/docs/namespaces.md +0 -285
  402. package/rest/examples/rest-10dlc-registration.ts +0 -161
  403. package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
  404. package/rest/examples/rest-calling-play-and-record.ts +0 -91
  405. package/rest/examples/rest-client.ts +0 -65
  406. package/rest/examples/rest-compat-laml.ts +0 -210
  407. package/rest/examples/rest-datasphere-search.ts +0 -82
  408. package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
  409. package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
  410. package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
  411. package/rest/examples/rest-manage-resources.ts +0 -65
  412. package/rest/examples/rest-phone-number-management.ts +0 -197
  413. package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
  414. package/rest/examples/rest-video-rooms.ts +0 -186
  415. package/src/AgentBase.ts +0 -2598
  416. package/src/AgentServer.ts +0 -442
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1181
  420. package/src/DataMap.ts +0 -477
  421. package/src/FunctionResult.ts +0 -903
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -467
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -749
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -240
  429. package/src/SessionManager.ts +0 -311
  430. package/src/SslConfig.ts +0 -118
  431. package/src/SwaigFunction.ts +0 -276
  432. package/src/SwmlBuilder.ts +0 -283
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -199
  435. package/src/WebService.ts +0 -641
  436. package/src/cli/agent-loader.ts +0 -166
  437. package/src/cli/mock-data.ts +0 -111
  438. package/src/cli/swaig-test.ts +0 -452
  439. package/src/generateVerbTypes.ts +0 -322
  440. package/src/livewire/index.ts +0 -1252
  441. package/src/prefabs/ConciergeAgent.ts +0 -309
  442. package/src/prefabs/FAQBotAgent.ts +0 -415
  443. package/src/prefabs/InfoGathererAgent.ts +0 -379
  444. package/src/prefabs/ReceptionistAgent.ts +0 -395
  445. package/src/prefabs/SurveyAgent.ts +0 -671
  446. package/src/relay/Action.ts +0 -482
  447. package/src/relay/Call.ts +0 -1270
  448. package/src/relay/Deferred.ts +0 -94
  449. package/src/relay/Message.ts +0 -199
  450. package/src/relay/RelayClient.ts +0 -1185
  451. package/src/relay/RelayError.ts +0 -20
  452. package/src/relay/RelayEvent.ts +0 -944
  453. package/src/relay/index.ts +0 -123
  454. package/src/relay/types.ts +0 -149
  455. package/src/rest/HttpClient.ts +0 -164
  456. package/src/rest/RestError.ts +0 -45
  457. package/src/rest/base/BaseResource.ts +0 -32
  458. package/src/rest/base/CrudResource.ts +0 -98
  459. package/src/rest/base/CrudWithAddresses.ts +0 -37
  460. package/src/rest/namespaces/addresses.ts +0 -64
  461. package/src/rest/namespaces/calling.ts +0 -534
  462. package/src/rest/namespaces/chat.ts +0 -31
  463. package/src/rest/namespaces/compat.ts +0 -812
  464. package/src/rest/namespaces/datasphere.ts +0 -88
  465. package/src/rest/namespaces/fabric.ts +0 -417
  466. package/src/rest/namespaces/imported-numbers.ts +0 -31
  467. package/src/rest/namespaces/logs.ts +0 -151
  468. package/src/rest/namespaces/lookup.ts +0 -38
  469. package/src/rest/namespaces/mfa.ts +0 -61
  470. package/src/rest/namespaces/number-groups.ts +0 -68
  471. package/src/rest/namespaces/phone-numbers.ts +0 -76
  472. package/src/rest/namespaces/project.ts +0 -65
  473. package/src/rest/namespaces/pubsub.ts +0 -31
  474. package/src/rest/namespaces/queues.ts +0 -58
  475. package/src/rest/namespaces/recordings.ts +0 -53
  476. package/src/rest/namespaces/registry.ts +0 -200
  477. package/src/rest/namespaces/short-codes.ts +0 -54
  478. package/src/rest/namespaces/sip-profile.ts +0 -40
  479. package/src/rest/namespaces/verified-callers.ts +0 -46
  480. package/src/rest/namespaces/video.ts +0 -332
  481. package/src/rest/types.ts +0 -61
  482. package/src/skills/SkillBase.ts +0 -582
  483. package/src/skills/SkillManager.ts +0 -419
  484. package/src/skills/SkillRegistry.ts +0 -367
  485. package/src/skills/builtin/api_ninjas_trivia.ts +0 -285
  486. package/src/skills/builtin/ask_claude.ts +0 -246
  487. package/src/skills/builtin/claude_skills.ts +0 -983
  488. package/src/skills/builtin/custom_skills.ts +0 -327
  489. package/src/skills/builtin/datasphere.ts +0 -447
  490. package/src/skills/builtin/datasphere_serverless.ts +0 -347
  491. package/src/skills/builtin/datetime.ts +0 -137
  492. package/src/skills/builtin/google_maps.ts +0 -656
  493. package/src/skills/builtin/info_gatherer.ts +0 -415
  494. package/src/skills/builtin/joke.ts +0 -196
  495. package/src/skills/builtin/math.ts +0 -149
  496. package/src/skills/builtin/mcp_gateway.ts +0 -685
  497. package/src/skills/builtin/native_vector_search.ts +0 -910
  498. package/src/skills/builtin/play_background_file.ts +0 -367
  499. package/src/skills/builtin/spider.ts +0 -874
  500. package/src/skills/builtin/swml_transfer.ts +0 -645
  501. package/src/skills/builtin/weather_api.ts +0 -255
  502. package/src/skills/builtin/web_search.ts +0 -1083
  503. package/src/skills/builtin/wikipedia_search.ts +0 -304
  504. package/src/types.ts +0 -132
  505. package/tests/AgentBase.test.ts +0 -1093
  506. package/tests/AgentServer.test.ts +0 -126
  507. package/tests/AuthHandler.test.ts +0 -133
  508. package/tests/ConfigLoader.test.ts +0 -151
  509. package/tests/ContextBuilder.test.ts +0 -108
  510. package/tests/DataMap.test.ts +0 -367
  511. package/tests/EphemeralSkillCopy.test.ts +0 -107
  512. package/tests/FunctionResult.test.ts +0 -298
  513. package/tests/GracefulShutdown.test.ts +0 -46
  514. package/tests/Logger.test.ts +0 -420
  515. package/tests/PomBuilder.test.ts +0 -228
  516. package/tests/ProxyDetection.test.ts +0 -228
  517. package/tests/SWMLService.test.ts +0 -320
  518. package/tests/SWMLVerbHandler.test.ts +0 -523
  519. package/tests/SchemaUtils.test.ts +0 -106
  520. package/tests/SchemaUtils.verb.test.ts +0 -206
  521. package/tests/SecurityUtils.test.ts +0 -192
  522. package/tests/ServerlessAdapter.test.ts +0 -222
  523. package/tests/SessionManager.test.ts +0 -257
  524. package/tests/SkillBaseFeatures.test.ts +0 -130
  525. package/tests/SkillMultiInstance.test.ts +0 -102
  526. package/tests/SkillParameterSchemas.test.ts +0 -134
  527. package/tests/SkillRegistrySchema.test.ts +0 -84
  528. package/tests/SslConfig.test.ts +0 -97
  529. package/tests/SwmlBuilder.test.ts +0 -400
  530. package/tests/TypeInference.test.ts +0 -165
  531. package/tests/VerbHandlerRegistry.test.ts +0 -128
  532. package/tests/cli/mock-data.test.ts +0 -113
  533. package/tests/cli/swaig-test.test.ts +0 -108
  534. package/tests/examples.test.ts +0 -194
  535. package/tests/fixtures/scrape-parity/README.md +0 -53
  536. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  537. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  538. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  548. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  549. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  550. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  551. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  552. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  553. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  554. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  555. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  556. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  557. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  558. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  559. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  560. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  561. package/tests/livewire/livewire.test.ts +0 -780
  562. package/tests/mcp.test.ts +0 -221
  563. package/tests/prefabs/prefabs.test.ts +0 -1093
  564. package/tests/relay/Action.test.ts +0 -392
  565. package/tests/relay/Call.test.ts +0 -535
  566. package/tests/relay/Deferred.test.ts +0 -71
  567. package/tests/relay/Message.test.ts +0 -164
  568. package/tests/relay/RelayClient.test.ts +0 -779
  569. package/tests/relay/RelayEvent.test.ts +0 -463
  570. package/tests/relay/helpers.ts +0 -79
  571. package/tests/rest/HttpClient.test.ts +0 -274
  572. package/tests/rest/RestError.test.ts +0 -53
  573. package/tests/rest/calling.test.ts +0 -156
  574. package/tests/rest/client.test.ts +0 -197
  575. package/tests/rest/compat.test.ts +0 -335
  576. package/tests/rest/datasphere.test.ts +0 -71
  577. package/tests/rest/fabric.test.ts +0 -186
  578. package/tests/rest/helpers.ts +0 -95
  579. package/tests/rest/logs.test.ts +0 -68
  580. package/tests/rest/pagination.test.ts +0 -133
  581. package/tests/rest/registry.test.ts +0 -94
  582. package/tests/rest/relay-rest.test.ts +0 -290
  583. package/tests/rest/video.test.ts +0 -173
  584. package/tests/setup.ts +0 -6
  585. package/tests/skills/SkillBase.test.ts +0 -108
  586. package/tests/skills/SkillManager.test.ts +0 -268
  587. package/tests/skills/SkillRegistry.test.ts +0 -176
  588. package/tests/skills/builtin.test.ts +0 -1472
  589. package/tests/skills/claude-skills.test.ts +0 -54
  590. package/tests/skills/custom-skills.test.ts +0 -53
  591. package/tests/skills/datasphere-serverless.test.ts +0 -70
  592. package/tests/skills/datasphere.test.ts +0 -107
  593. package/tests/skills/datetime.test.ts +0 -101
  594. package/tests/skills/google-maps.test.ts +0 -78
  595. package/tests/skills/info-gatherer.test.ts +0 -411
  596. package/tests/skills/joke.test.ts +0 -81
  597. package/tests/skills/math.test.ts +0 -68
  598. package/tests/skills/mcp-gateway.test.ts +0 -101
  599. package/tests/skills/play-background.test.ts +0 -54
  600. package/tests/skills/spider.test.ts +0 -108
  601. package/tests/skills/swml-transfer.test.ts +0 -178
  602. package/tests/skills/trivia.test.ts +0 -54
  603. package/tests/skills/vector-search.test.ts +0 -135
  604. package/tests/skills/weather-api.test.ts +0 -77
  605. package/tests/skills/web-search-parity.test.ts +0 -59
  606. package/tests/skills/web-search.test.ts +0 -103
  607. package/tests/skills/wikipedia.test.ts +0 -63
  608. package/tsconfig.json +0 -18
  609. package/vitest.config.ts +0 -9
  610. /package/{src → dist}/schema.json +0 -0
@@ -0,0 +1,1045 @@
1
+ /**
2
+ * AgentBase - Core agent class with Hono HTTP server and 5-phase SWML rendering.
3
+ *
4
+ * Composes PromptManager, SessionManager, SwmlBuilder, and a tool registry
5
+ * into a single HTTP-servable agent.
6
+ */
7
+ import { Hono } from 'hono';
8
+ import { PromptManager } from './PromptManager.js';
9
+ import { SwaigFunction, type SwaigHandler } from './SwaigFunction.js';
10
+ import { ContextBuilder } from './ContextBuilder.js';
11
+ import { SkillManager } from './skills/SkillManager.js';
12
+ import type { SkillBase, SkillConfig } from './skills/SkillBase.js';
13
+ import { type ServerlessEvent, type ServerlessResponse } from './ServerlessAdapter.js';
14
+ import type { AgentOptions, LanguageConfig, PronunciationRule, FunctionInclude, DynamicConfigCallback } from './types.js';
15
+ /**
16
+ * Callback invoked at a registered routing endpoint to determine how to handle an
17
+ * incoming request. Return a route string to redirect to that agent route, or
18
+ * null / undefined to let normal SWML processing continue.
19
+ *
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).
22
+ */
23
+ export type RoutingCallback = (body: Record<string, unknown>) => string | null | undefined | Promise<string | null | undefined>;
24
+ /**
25
+ * Core agent class that composes an HTTP server, prompt management, session handling,
26
+ * SWAIG tool registry, and 5-phase SWML rendering into a single deployable unit.
27
+ *
28
+ * A single `AgentBase` is one HTTP-servable voice agent:
29
+ *
30
+ * - `GET /` returns the SWML call-flow document
31
+ * - `POST /swaig` dispatches SWAIG function calls to registered tool handlers
32
+ * - `POST /post_prompt` receives the end-of-call summary and invokes {@link onSummary}
33
+ *
34
+ * Most user agents either (a) subclass `AgentBase` and override `defineTools()` / `onSummary()`
35
+ * or (b) use one of the {@link ./prefabs/index.js | prefab agents} (e.g. `ReceptionistAgent`).
36
+ *
37
+ * @example Subclass with a custom tool
38
+ * ```ts
39
+ * import { AgentBase, FunctionResult } from '@signalwire/sdk';
40
+ *
41
+ * class WeatherAgent extends AgentBase {
42
+ * static override PROMPT_SECTIONS = [
43
+ * { title: 'Role', body: 'You are a weather assistant.' },
44
+ * ];
45
+ *
46
+ * protected override defineTools(): void {
47
+ * this.defineTool({
48
+ * name: 'get_forecast',
49
+ * description: 'Return the forecast for a city.',
50
+ * parameters: {
51
+ * type: 'object',
52
+ * properties: { city: { type: 'string' } },
53
+ * required: ['city'],
54
+ * },
55
+ * handler: async ({ city }) => {
56
+ * const forecast = await fetchForecast(city as string);
57
+ * return new FunctionResult(forecast);
58
+ * },
59
+ * });
60
+ * }
61
+ * }
62
+ *
63
+ * const agent = new WeatherAgent({ name: 'weather', route: '/' });
64
+ * await agent.serve({ port: 3000 });
65
+ * ```
66
+ *
67
+ * @example Imperative usage (no subclass)
68
+ * ```ts
69
+ * const agent = new AgentBase({ name: 'hello', route: '/' });
70
+ * agent.setPromptText('You are a friendly greeter.');
71
+ * agent.defineTool({
72
+ * name: 'say_hi',
73
+ * description: 'Respond with a greeting.',
74
+ * parameters: { type: 'object', properties: {} },
75
+ * handler: () => new FunctionResult('Hello from SignalWire!'),
76
+ * });
77
+ * await agent.serve();
78
+ * ```
79
+ *
80
+ * @see {@link FunctionResult} — builder for tool handler responses
81
+ * @see {@link ContextBuilder} — multi-step conversation state machines
82
+ * @see {@link DataMap} — server-side tools without webhooks
83
+ * @see {@link AgentServer} — host multiple agents on one HTTP server
84
+ */
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;
94
+ /** Unique identifier for this agent instance. */
95
+ agentId: string;
96
+ private _promptManager;
97
+ private sessionManager;
98
+ private swmlBuilder;
99
+ private toolRegistry;
100
+ private basicAuthCreds;
101
+ private basicAuthSource;
102
+ private autoAnswer;
103
+ private _recordCall;
104
+ private recordFormat;
105
+ private recordStereo;
106
+ private defaultWebhookUrl;
107
+ private _nativeFunctions;
108
+ private hints;
109
+ private languages;
110
+ private pronounce;
111
+ private params;
112
+ private globalData;
113
+ private functionIncludes;
114
+ private promptLlmParams;
115
+ private postPromptLlmParams;
116
+ private internalFillers;
117
+ private preAnswerVerbs;
118
+ private answerConfig;
119
+ private postAnswerVerbs;
120
+ private postAiVerbs;
121
+ private dynamicConfigCallback;
122
+ private swaigQueryParams;
123
+ private webHookUrlOverride;
124
+ private postPromptUrlOverride;
125
+ private contextsBuilder;
126
+ private _mcpServers;
127
+ private _mcpServerEnabled;
128
+ private _sipRoutingEnabled;
129
+ private _sipRoute;
130
+ private _sipAutoMap;
131
+ private _sipUsernames;
132
+ private debugEventsEnabled;
133
+ private debugEventsLevel;
134
+ private _proxyUrlBase;
135
+ private _proxyUrlBaseFromEnv;
136
+ private _proxyDebug;
137
+ private _trustProxyHeaders;
138
+ private _enforceHttps;
139
+ /** Structured logger instance for this agent, configurable via SIGNALWIRE_LOG_LEVEL. */
140
+ log: import("./Logger.js").Logger;
141
+ private _skillManager;
142
+ private _enablePostPromptOverride;
143
+ private _checkForInputOverride;
144
+ private _schemaValidation;
145
+ private _configFile;
146
+ private _schemaPath;
147
+ private _routingCallbacks;
148
+ private _app;
149
+ /**
150
+ * Create a new AgentBase instance.
151
+ * @param opts - Agent configuration options including name, route, auth, and call settings.
152
+ */
153
+ constructor(opts: AgentOptions);
154
+ /**
155
+ * Static prompt sections: subclasses can define these declaratively.
156
+ * Each entry is applied via promptAddSection() in the constructor.
157
+ */
158
+ static PROMPT_SECTIONS?: {
159
+ title: string;
160
+ body?: string;
161
+ bullets?: string[];
162
+ numbered?: boolean;
163
+ }[];
164
+ /**
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.
168
+ */
169
+ protected defineTools(): void;
170
+ /**
171
+ * Public access to the list of registered tools.
172
+ *
173
+ * In Python, `define_tools()` is public and returns `List[SWAIGFunction]`.
174
+ * In TypeScript, `defineTools()` is a protected setup hook (void). This
175
+ * method provides the equivalent public "get all tools" capability.
176
+ * @returns Array of all registered SwaigFunction instances.
177
+ */
178
+ getTools(): SwaigFunction[];
179
+ /**
180
+ * Public accessor for the PromptManager (POM).
181
+ *
182
+ * Python exposes `self.pom` as a public attribute. This getter
183
+ * provides equivalent access for direct POM manipulation.
184
+ */
185
+ get promptManager(): PromptManager;
186
+ /**
187
+ * Public accessor for the native functions list.
188
+ *
189
+ * Python exposes `self.native_functions` as a public read/write attribute.
190
+ * @returns A copy of the native functions list.
191
+ */
192
+ get nativeFunctions(): string[];
193
+ /** Set the native functions list. */
194
+ set nativeFunctions(fns: string[]);
195
+ /**
196
+ * Public read-only accessor for the SkillManager.
197
+ *
198
+ * Python exposes `self.skill_manager` as a public attribute. This getter
199
+ * provides equivalent read access.
200
+ */
201
+ get skillManager(): SkillManager;
202
+ /**
203
+ * Set the main system prompt text for the AI.
204
+ * @param text - The prompt text to use.
205
+ * @returns This agent instance for chaining.
206
+ */
207
+ setPromptText(text: string): this;
208
+ /**
209
+ * Set the post-prompt text evaluated after the call ends.
210
+ * @param text - The post-prompt text to use.
211
+ * @returns This agent instance for chaining.
212
+ */
213
+ setPostPrompt(text: string): this;
214
+ /**
215
+ * Add a new section to the prompt with optional body, bullets, and subsections.
216
+ * @param title - Section heading.
217
+ * @param opts - Optional section content including body text, bullet points, and subsections.
218
+ * @returns This agent instance for chaining.
219
+ */
220
+ promptAddSection(title: string, opts?: {
221
+ body?: string;
222
+ bullets?: string[];
223
+ numbered?: boolean;
224
+ numberedBullets?: boolean;
225
+ subsections?: {
226
+ title: string;
227
+ body?: string;
228
+ bullets?: string[];
229
+ }[];
230
+ }): this;
231
+ /**
232
+ * Append content to an existing prompt section.
233
+ * @param title - Title of the section to append to.
234
+ * @param opts - Content to add: body text, a single bullet, or multiple bullets.
235
+ * @returns This agent instance for chaining.
236
+ */
237
+ promptAddToSection(title: string, opts?: {
238
+ body?: string;
239
+ bullet?: string;
240
+ bullets?: string[];
241
+ }): this;
242
+ /**
243
+ * Add a subsection under an existing prompt section.
244
+ * @param parentTitle - Title of the parent section.
245
+ * @param title - Title of the new subsection.
246
+ * @param opts - Optional body text and bullet points for the subsection.
247
+ * @returns This agent instance for chaining.
248
+ */
249
+ promptAddSubsection(parentTitle: string, title: string, opts?: {
250
+ body?: string;
251
+ bullets?: string[];
252
+ }): this;
253
+ /**
254
+ * Check whether a prompt section with the given title exists.
255
+ * @param title - Section title to look for.
256
+ * @returns True if the section exists.
257
+ */
258
+ promptHasSection(title: string): boolean;
259
+ /**
260
+ * Get the fully rendered main prompt text.
261
+ * @returns The assembled prompt string.
262
+ */
263
+ getPrompt(): string;
264
+ /**
265
+ * Get the raw POM (Prompt Object Model) structure as an array of section data objects,
266
+ * when the agent is in POM mode and has at least one section.
267
+ *
268
+ * Matches Python `get_prompt()` which returns `Union[str, List[Dict]]` — a raw list when
269
+ * in POM mode (via `pom.to_list()` / `pom.render_dict()`), or a string otherwise.
270
+ * The TS `getPrompt()` always returns a string (rendered Markdown), so this companion
271
+ * method exposes the raw POM structure for callers that need it for serialisation or
272
+ * inspection (e.g. skills that inspect prompt sections).
273
+ *
274
+ * @returns An array of POM section data objects, or null if not in POM mode or POM is empty.
275
+ */
276
+ getPromptPom(): Record<string, unknown>[] | null;
277
+ /**
278
+ * Get the post-prompt text, if one has been set.
279
+ * @returns The post-prompt string, or null if not configured.
280
+ */
281
+ getPostPrompt(): string | null;
282
+ /**
283
+ * Set the prompt as a POM (Prompt Object Model) dictionary.
284
+ *
285
+ * Replaces the current POM sections with the provided structured data.
286
+ * Each entry should have `title`, and optionally `body`, `bullets`,
287
+ * `numbered`, `numberedBullets`, and `subsections`.
288
+ *
289
+ * @param pom - Array of POM section dictionaries.
290
+ * @returns This agent instance for chaining.
291
+ * @throws Error if POM mode is not enabled (`usePom: false`).
292
+ */
293
+ setPromptPom(pom: Record<string, unknown>[]): this;
294
+ /**
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.
298
+ */
299
+ defineContexts(contexts?: ContextBuilder | Record<string, unknown>): ContextBuilder;
300
+ /**
301
+ * Remove all contexts, returning the agent to a no-contexts state.
302
+ *
303
+ * This is a convenience wrapper around `defineContexts().reset()`.
304
+ * Use it in a dynamic config callback when you need to rebuild
305
+ * contexts from scratch for a specific request.
306
+ *
307
+ * @returns This agent instance for chaining.
308
+ */
309
+ resetContexts(): this;
310
+ /**
311
+ * Add a single speech-recognition hint.
312
+ * @param hint - Word or phrase to boost in speech recognition.
313
+ * @returns This agent instance for chaining.
314
+ */
315
+ addHint(hint: string): this;
316
+ /**
317
+ * Add multiple speech-recognition hints at once.
318
+ * @param hints - Array of words or phrases to boost.
319
+ * @returns This agent instance for chaining.
320
+ */
321
+ addHints(hints: string[]): this;
322
+ /**
323
+ * Add a pattern-based speech-recognition hint with find-and-replace behavior.
324
+ * @param opts - Pattern hint configuration with a descriptive hint label,
325
+ * regex pattern, replacement string, and optional case-insensitive flag.
326
+ * @returns This agent instance for chaining.
327
+ */
328
+ addPatternHint(opts: {
329
+ hint: string;
330
+ pattern: string;
331
+ replace: string;
332
+ ignoreCase?: boolean;
333
+ }): this;
334
+ /**
335
+ * Add a supported language to the AI configuration.
336
+ * @param config - Language configuration including name, code, voice, and optional fillers.
337
+ * @returns This agent instance for chaining.
338
+ */
339
+ addLanguage(config: LanguageConfig): this;
340
+ /**
341
+ * Replace all configured languages with a new list.
342
+ * @param languages - Array of language configurations.
343
+ * @returns This agent instance for chaining.
344
+ */
345
+ setLanguages(languages: LanguageConfig[]): this;
346
+ /**
347
+ * Add a pronunciation override rule for the TTS engine.
348
+ * @param rule - Pronunciation rule specifying the text to replace and its substitute.
349
+ * @returns This agent instance for chaining.
350
+ */
351
+ addPronunciation(rule: PronunciationRule): this;
352
+ /**
353
+ * Replace all pronunciation rules with a new list.
354
+ * @param rules - Array of pronunciation rule objects.
355
+ * @returns This agent instance for chaining.
356
+ */
357
+ setPronunciations(rules: PronunciationRule[]): this;
358
+ /**
359
+ * Set a single AI parameter (e.g. "temperature", "top_p").
360
+ * @param key - Parameter name.
361
+ * @param value - Parameter value.
362
+ * @returns This agent instance for chaining.
363
+ */
364
+ setParam(key: string, value: unknown): this;
365
+ /**
366
+ * Merge multiple AI parameters into the existing params object.
367
+ * @param params - Key-value pairs to merge.
368
+ * @returns This agent instance for chaining.
369
+ */
370
+ setParams(params: Record<string, unknown>): this;
371
+ /**
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.
377
+ *
378
+ * If you need to replace the entire object, assign a new agent instance or use
379
+ * `Object.assign(agent.globalData, {})` to clear first.
380
+ *
381
+ * @param data - Key-value pairs to merge into global data.
382
+ * @returns This agent instance for chaining.
383
+ */
384
+ setGlobalData(data: Record<string, unknown>): this;
385
+ /**
386
+ * Merge additional entries into the existing global_data object.
387
+ * @param data - Key-value pairs to merge into global data.
388
+ * @returns This agent instance for chaining.
389
+ */
390
+ updateGlobalData(data: Record<string, unknown>): this;
391
+ /**
392
+ * Set the list of native SWAIG function names (built-in platform functions).
393
+ * @param funcs - Array of native function names.
394
+ * @returns This agent instance for chaining.
395
+ */
396
+ setNativeFunctions(funcs: string[]): this;
397
+ /**
398
+ * The complete set of internal SWAIG function names that accept fillers,
399
+ * matching the SWAIGInternalFiller schema definition. Any name outside
400
+ * this set is silently ignored by the runtime — addInternalFiller /
401
+ * setInternalFillers warn if you pass an unknown name.
402
+ */
403
+ static readonly SUPPORTED_INTERNAL_FILLER_NAMES: ReadonlySet<string>;
404
+ /**
405
+ * Set internal fillers for native SWAIG functions.
406
+ *
407
+ * Internal fillers are short phrases the AI agent speaks (via TTS) while
408
+ * an internal/native function is running, so the caller doesn't hear
409
+ * dead air during transitions or background work.
410
+ *
411
+ * Supported function names (matches the SWAIGInternalFiller schema):
412
+ *
413
+ * hangup — when the agent is hanging up
414
+ * check_time — when checking the time
415
+ * wait_for_user — when waiting for user input
416
+ * wait_seconds — during deliberate pauses
417
+ * adjust_response_latency — when adjusting response timing
418
+ * next_step — transitioning between steps in prompt.contexts
419
+ * change_context — switching between contexts in prompt.contexts
420
+ * get_visual_input — processing visual input (enable_vision=true)
421
+ * get_ideal_strategy — thinking (enable_thinking=true)
422
+ *
423
+ * Notably NOT supported: change_step, gather_submit, or arbitrary
424
+ * user-defined SWAIG function names. The runtime only honors fillers
425
+ * for the names listed above; everything else is silently ignored at
426
+ * the SWML level. This method warns at registration time if you pass
427
+ * an unknown name so you catch the typo early.
428
+ *
429
+ * @param internalFillers - Map of function name to language-keyed filler phrases.
430
+ * @returns This agent instance for chaining.
431
+ *
432
+ * @example
433
+ * agent.setInternalFillers({
434
+ * next_step: {
435
+ * 'en-US': ['Moving to the next step...', 'Great, let us continue...'],
436
+ * 'es': ['Pasando al siguiente paso...']
437
+ * },
438
+ * check_time: {
439
+ * 'en-US': ['Let me check the time...']
440
+ * }
441
+ * });
442
+ */
443
+ setInternalFillers(internalFillers: Record<string, Record<string, string[]>>): this;
444
+ /**
445
+ * Add internal filler phrases for a single internal function and language.
446
+ *
447
+ * See {@link setInternalFillers} for the complete list of supported
448
+ * functionName values and an explanation of what fillers do.
449
+ *
450
+ * @param functionName - One of the supported internal function names
451
+ * (see SUPPORTED_INTERNAL_FILLER_NAMES). Names outside the supported
452
+ * set log a warning and are ignored by the runtime.
453
+ * @param languageCode - BCP-47 language code for the fillers (e.g. 'en-US').
454
+ * @param fillers - Array of filler phrases.
455
+ * @returns This agent instance for chaining.
456
+ */
457
+ addInternalFiller(functionName: string, languageCode: string, fillers: string[]): this;
458
+ /**
459
+ * Add a remote SWAIG function include reference.
460
+ * @param url - URL of the remote SWAIG endpoint.
461
+ * @param functions - Function names available at that endpoint.
462
+ * @param metaData - Optional metadata to attach to the include.
463
+ * @returns This agent instance for chaining.
464
+ */
465
+ addFunctionInclude(url: string, functions: string[], metaData?: Record<string, unknown>): this;
466
+ /**
467
+ * Replace the entire list of function includes.
468
+ * Each include must have a `url` and `functions` array.
469
+ * @param includes - Array of function include objects.
470
+ * @returns This agent instance for chaining.
471
+ */
472
+ setFunctionIncludes(includes: FunctionInclude[]): this;
473
+ /**
474
+ * Merge LLM-specific parameters into the main prompt configuration (e.g. model, temperature).
475
+ * @param params - Key-value LLM parameters to merge.
476
+ * @returns This agent instance for chaining.
477
+ */
478
+ setPromptLlmParams(params: Record<string, unknown>): this;
479
+ /**
480
+ * Merge LLM-specific parameters into the post-prompt configuration.
481
+ * @param params - Key-value LLM parameters to merge.
482
+ * @returns This agent instance for chaining.
483
+ */
484
+ setPostPromptLlmParams(params: Record<string, unknown>): this;
485
+ /**
486
+ * Enable debug event webhooks for this agent.
487
+ * @param level - Debug verbosity level (defaults to 1).
488
+ * @returns This agent instance for chaining.
489
+ */
490
+ enableDebugEvents(level?: number): this;
491
+ /**
492
+ * Enable SIP routing for this agent.
493
+ * @param autoMap - When true, automatically map SIP usernames to the agent route (defaults to true).
494
+ * @param path - HTTP path for the SIP routing endpoint (defaults to '/sip').
495
+ * @returns This agent instance for chaining.
496
+ */
497
+ enableSipRouting(autoMap?: boolean, path?: string): this;
498
+ /**
499
+ * Register a SIP username to route to this agent.
500
+ * @param username - The SIP username to register.
501
+ * @returns This agent instance for chaining.
502
+ */
503
+ registerSipUsername(username: string): this;
504
+ /**
505
+ * Automatically register common SIP usernames based on this agent's
506
+ * name and route. Derives cleaned variants (alphanumeric + underscore)
507
+ * and registers each via `registerSipUsername()`.
508
+ *
509
+ * Port of Python's `auto_map_sip_usernames()`:
510
+ * - Registers a cleaned version of the agent name
511
+ * - Registers a cleaned version of the route (if different from name)
512
+ * - For names longer than 3 characters, also registers a vowel-stripped variant
513
+ *
514
+ * @returns This agent instance for chaining.
515
+ */
516
+ autoMapSipUsernames(): this;
517
+ /**
518
+ * Register a callback at a specific HTTP path that decides how to route an
519
+ * incoming request.
520
+ *
521
+ * When called, the endpoint at `path` will invoke `callback` with the parsed
522
+ * 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
525
+ * agent's own SWML is returned instead (normal processing).
526
+ *
527
+ * Mirrors Python `swml_service.register_routing_callback` /
528
+ * `web_mixin.register_routing_callback`.
529
+ *
530
+ * @param callback - Function receiving the parsed request body and returning a
531
+ * route string to redirect, or null/undefined for normal processing.
532
+ * @param path - HTTP path where this callback endpoint is registered
533
+ * (default: '/sip').
534
+ * @returns This agent instance for chaining.
535
+ */
536
+ registerRoutingCallback(callback: RoutingCallback, path?: string): this;
537
+ /**
538
+ * Extract the SIP username from a request body's call.to field.
539
+ * @param requestBody - The parsed request body containing call information.
540
+ * @returns The extracted SIP username, or null if not found.
541
+ */
542
+ static extractSipUsername(requestBody: Record<string, unknown>): string | null;
543
+ /**
544
+ * Add an external MCP server for tool discovery and invocation.
545
+ * Tools are discovered via MCP protocol at session start and added to the AI's tool list.
546
+ * @param url - MCP server HTTP endpoint URL
547
+ * @param opts - Optional configuration: headers, resources, resourceVars
548
+ * @returns This agent instance for chaining
549
+ */
550
+ addMcpServer(url: string, opts?: {
551
+ headers?: Record<string, string>;
552
+ resources?: boolean;
553
+ resourceVars?: Record<string, string>;
554
+ }): this;
555
+ /**
556
+ * Expose this agent's tools as an MCP server endpoint at /mcp.
557
+ * Adds a JSON-RPC 2.0 endpoint that MCP clients (Claude Desktop, other agents) can connect to.
558
+ * @returns This agent instance for chaining
559
+ */
560
+ enableMcpServer(): this;
561
+ /** Check if MCP server endpoint is enabled. */
562
+ isMcpServerEnabled(): boolean;
563
+ /** Get configured MCP servers (read-only copy). */
564
+ getMcpServers(): Record<string, unknown>[];
565
+ /** Build MCP tool list from registered tools. */
566
+ private buildMcpToolList;
567
+ /** Handle an MCP JSON-RPC 2.0 request. Returns the response object. */
568
+ 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
+ /**
642
+ * Register a SWAIG tool with a typed handler that receives named parameters
643
+ * instead of the standard `(args, rawData)` convention.
644
+ *
645
+ * The SDK wraps the handler to unpack the args dict into positional params.
646
+ * If no `parameters` schema is provided, one is inferred from the handler's
647
+ * source code (parameter names and default values).
648
+ *
649
+ * @param opts - Tool definition with a typed handler function.
650
+ * @returns This agent instance for chaining.
651
+ */
652
+ defineTypedTool(opts: {
653
+ name: string;
654
+ description: string;
655
+ parameters?: Record<string, unknown>;
656
+ handler: Function;
657
+ secure?: boolean;
658
+ fillers?: Record<string, string[]>;
659
+ waitFile?: string;
660
+ waitFileLoops?: number;
661
+ required?: string[];
662
+ }): 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
+ /**
685
+ * Validate a tool-call token for the given function.
686
+ *
687
+ * Mirrors Python reference `core/mixins/state_mixin.py validate_tool_token`:
688
+ * 1. Unknown function → `false`.
689
+ * 2. Registered but non-secure → `true` without consulting SessionManager
690
+ * (non-secure tools never require a token).
691
+ * 3. Raw-dict descriptors (e.g. DataMap) are treated as secure, matching
692
+ * Python's `isinstance(func, dict) → is_secure = True` branch.
693
+ * 4. Missing token on a secure tool → `false`.
694
+ * 5. Otherwise delegate to `SessionManager.validateToolToken`.
695
+ *
696
+ * Divergences from the Python reference:
697
+ * - No debug-logging branch: `AgentBase` does not expose an agent-level
698
+ * debug-mode flag, so the per-call debug telemetry Python emits is
699
+ * omitted. `SessionManager` still logs its own validation outcomes.
700
+ * - No token-derived call-id fallback: `SessionManager.debugToken`
701
+ * truncates the embedded call-id for log safety, so an extracted value
702
+ * cannot be round-tripped back through `validateToolToken`. The caller
703
+ * is expected to supply a non-empty `callId`; an empty one is forwarded
704
+ * unchanged and the underlying validator will reject it.
705
+ */
706
+ validateToolToken(functionName: string, token: string, callId: string): boolean;
707
+ /**
708
+ * Add a SWML verb to execute before the answer phase (phase 1).
709
+ * @param verbName - Name of the SWML verb (e.g. "play", "record").
710
+ * @param config - Verb configuration object.
711
+ * @returns This agent instance for chaining.
712
+ */
713
+ addPreAnswerVerb(verbName: string, config: Record<string, unknown>): this;
714
+ /**
715
+ * Configure the answer verb (phase 2) with optional settings.
716
+ * @param config - Optional answer verb configuration.
717
+ * @returns This agent instance for chaining.
718
+ */
719
+ addAnswerVerb(config?: Record<string, unknown>): this;
720
+ /**
721
+ * Add a SWML verb to execute after the answer phase but before the AI verb (phase 3).
722
+ * @param verbName - Name of the SWML verb.
723
+ * @param config - Verb configuration object.
724
+ * @returns This agent instance for chaining.
725
+ */
726
+ addPostAnswerVerb(verbName: string, config: Record<string, unknown>): this;
727
+ /**
728
+ * Add a SWML verb to execute after the AI verb (phase 5).
729
+ * @param verbName - Name of the SWML verb.
730
+ * @param config - Verb configuration object.
731
+ * @returns This agent instance for chaining.
732
+ */
733
+ addPostAiVerb(verbName: string, config: Record<string, unknown>): this;
734
+ /**
735
+ * Remove all pre-answer verbs.
736
+ * @returns This agent instance for chaining.
737
+ */
738
+ clearPreAnswerVerbs(): this;
739
+ /**
740
+ * Remove all post-answer verbs.
741
+ * @returns This agent instance for chaining.
742
+ */
743
+ clearPostAnswerVerbs(): this;
744
+ /**
745
+ * Remove all post-AI verbs.
746
+ * @returns This agent instance for chaining.
747
+ */
748
+ clearPostAiVerbs(): this;
749
+ /**
750
+ * Get the agent's display name.
751
+ * @returns The agent name string.
752
+ */
753
+ getName(): string;
754
+ /**
755
+ * Add a skill to this agent, registering its tools, prompt sections, hints, and global data.
756
+ * @param skill - The skill instance to add.
757
+ * @returns This agent instance for chaining.
758
+ */
759
+ addSkill(skill: SkillBase): Promise<this>;
760
+ /**
761
+ * Add a skill by its registered name, looking it up in the global SkillRegistry.
762
+ *
763
+ * Matches Python's `add_skill(skill_name, params)` which loads skills by string
764
+ * name via the SkillManager registry. Throws a `ValueError`-equivalent if the
765
+ * skill name is not found in the registry.
766
+ *
767
+ * @param skillName - The name the skill was registered under in the SkillRegistry.
768
+ * @param params - Optional configuration parameters forwarded to the skill factory.
769
+ * @returns This agent instance for chaining.
770
+ * @throws Error if no skill with the given name is registered.
771
+ */
772
+ addSkillByName(skillName: string, params?: SkillConfig): Promise<this>;
773
+ /**
774
+ * Remove a previously added skill by its instance ID.
775
+ * @param instanceId - The unique instance ID of the skill to remove.
776
+ * @returns True if the skill was found and removed.
777
+ */
778
+ removeSkill(instanceId: string): Promise<boolean>;
779
+ /**
780
+ * List all registered skills with their names, instance IDs, and initialization status.
781
+ * @returns Array of skill descriptors.
782
+ */
783
+ listSkills(): {
784
+ name: string;
785
+ instanceId: string;
786
+ initialized: boolean;
787
+ }[];
788
+ /**
789
+ * Check whether a skill with the given name is registered.
790
+ * @param skillName - The skill name to check.
791
+ * @returns True if a skill with that name exists.
792
+ */
793
+ hasSkill(skillName: string): boolean;
794
+ /**
795
+ * Remove a skill by its name (Python parity).
796
+ *
797
+ * Python's `remove_skill(skill_name)` removes by skill name.
798
+ * The existing `removeSkill(instanceId)` removes by instance ID.
799
+ * This method provides name-based removal for cross-SDK parity.
800
+ *
801
+ * @param skillName - The skill name to remove.
802
+ * @returns True if a skill with that name was found and removed.
803
+ */
804
+ removeSkillByName(skillName: string): Promise<boolean>;
805
+ /**
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.
811
+ *
812
+ * @param cb - Callback receiving `(queryParams, bodyParams, headers, agent)` where
813
+ * `agent` is the ephemeral `AgentBase` copy to mutate. May be async.
814
+ * @returns This agent instance for chaining.
815
+ *
816
+ * @example
817
+ * ```ts
818
+ * agent.setDynamicConfigCallback((query, body, headers, agent) => {
819
+ * const lang = query.lang ?? 'en';
820
+ * if (lang === 'es') {
821
+ * (agent as AgentBase).setPromptText('Eres un asistente útil.');
822
+ * }
823
+ * });
824
+ * ```
825
+ */
826
+ setDynamicConfigCallback(cb: DynamicConfigCallback): this;
827
+ /**
828
+ * Add extra query parameters appended to all SWAIG webhook URLs.
829
+ * @param params - Key-value pairs to append as query parameters.
830
+ * @returns This agent instance for chaining.
831
+ */
832
+ addSwaigQueryParams(params: Record<string, string>): this;
833
+ /**
834
+ * Clear all SWAIG query parameters.
835
+ * @returns This agent instance for chaining.
836
+ */
837
+ clearSwaigQueryParams(): this;
838
+ /**
839
+ * Manually set the proxy base URL used for webhook URL generation.
840
+ * @param url - The external-facing base URL (trailing slashes are stripped).
841
+ * @returns This agent instance for chaining.
842
+ */
843
+ manualSetProxyUrl(url: string): this;
844
+ /**
845
+ * Register a callback function that determines routing based on POST data.
846
+ *
847
+ * When a routing callback is registered, an endpoint at the specified path
848
+ * is created in `getApp()`. The callback receives the request body and returns
849
+ * Enable debug routes for testing and development.
850
+ *
851
+ * This is a backward-compatibility stub matching the Python SDK.
852
+ * In the TypeScript SDK, debug routes (health, ready, debug_events)
853
+ * are automatically registered in `getApp()`.
854
+ *
855
+ * @returns This agent instance for chaining.
856
+ */
857
+ enableDebugRoutes(): this;
858
+ private detectProxyFromRequest;
859
+ /**
860
+ * Override the default SWAIG webhook URL with a custom one.
861
+ * @param url - The custom webhook URL.
862
+ * @returns This agent instance for chaining.
863
+ */
864
+ setWebHookUrl(url: string): this;
865
+ /**
866
+ * Override the default post-prompt webhook URL with a custom one.
867
+ * @param url - The custom post-prompt URL.
868
+ * @returns This agent instance for chaining.
869
+ */
870
+ setPostPromptUrl(url: string): this;
871
+ /**
872
+ * Get the full external URL of this agent, using the proxy base URL if available.
873
+ * @param includeAuth - Whether to embed basic-auth credentials in the URL (defaults to false).
874
+ * @returns The fully-qualified URL string.
875
+ */
876
+ getFullUrl(includeAuth?: boolean): string;
877
+ private insertAuth;
878
+ private buildWebhookUrl;
879
+ /**
880
+ * Lifecycle hook called when a post-prompt summary is received. Override in subclasses.
881
+ *
882
+ * 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
884
+ * call data, notify other systems, or trigger follow-up workflows.
885
+ *
886
+ * @param _summary - Parsed summary object (JSON when the post-prompt requests
887
+ * structured output), or `null` if extraction/parsing failed.
888
+ * @param _rawData - Full raw post-prompt payload received from the platform,
889
+ * including call metadata, conversation history, and the summary text.
890
+ *
891
+ * @example
892
+ * ```ts
893
+ * class MyAgent extends AgentBase {
894
+ * async onSummary(summary, rawData) {
895
+ * if (!summary) return;
896
+ * await db.calls.insert({
897
+ * callSid: rawData.call_id,
898
+ * summary,
899
+ * endedAt: new Date(),
900
+ * });
901
+ * }
902
+ * }
903
+ * ```
904
+ */
905
+ onSummary(_summary: Record<string, unknown> | null, _rawData: Record<string, unknown>): void | Promise<void>;
906
+ /**
907
+ * Lifecycle hook called on every SWML request before rendering. Override in subclasses.
908
+ *
909
+ * May optionally return a modification dict that will be merged into the
910
+ * rendered SWML document (matching Python's `Optional[dict]` return type).
911
+ *
912
+ * Matches Python `on_swml_request(request_data, callback_path, request)` — the third
913
+ * parameter is the FastAPI `Request` in Python; here it is the raw Hono context object
914
+ * so that subclasses can access query parameters (`context.req.query()`), raw request
915
+ * headers (`context.req.raw.headers`), etc.
916
+ *
917
+ * @param _rawData - The parsed request body.
918
+ * @param _callbackPath - Optional callback path from the request.
919
+ * @param _context - The raw Hono context object (c), providing access to headers and query params.
920
+ * @returns Optionally a dict of SWML modifications, or void.
921
+ */
922
+ onSwmlRequest(_rawData: Record<string, unknown>, _callbackPath?: string, _context?: any): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
923
+ /**
924
+ * Lifecycle hook called when a debug event webhook is received. Override in subclasses.
925
+ * @param _event - The debug event payload.
926
+ */
927
+ onDebugEvent(_event: Record<string, unknown>): void | Promise<void>;
928
+ /**
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.
932
+ * @returns True if the credentials are valid; false to reject the request.
933
+ */
934
+ validateBasicAuth(_username: string, _password: string): boolean | Promise<boolean>;
935
+ /**
936
+ * Hook called before each SWAIG function execution. Override in subclasses.
937
+ *
938
+ * **Behavioral note:** In the Python SDK, `on_function_call` IS the dispatcher
939
+ * — it retrieves and executes the function, returning the result. In TypeScript,
940
+ * `fn.execute()` is called separately after this hook. However, if this method
941
+ * returns a non-void value, it is used as the result and the default execution
942
+ * is skipped, enabling dispatch interception parity with Python.
943
+ *
944
+ * @param _name - Name of the function about to execute.
945
+ * @param _args - Parsed arguments for the function.
946
+ * @param _rawData - The full raw SWAIG request payload.
947
+ * @returns Optionally a result dict to short-circuit default execution,
948
+ * or void/undefined to proceed normally.
949
+ */
950
+ onFunctionCall(_name: string, _args: Record<string, unknown>, _rawData: Record<string, unknown>): Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
951
+ /**
952
+ * Render the complete SWML document by assembling all 5 phases: pre-answer, answer,
953
+ * post-answer, AI, and post-AI verbs.
954
+ *
955
+ * @param callId - Optional call ID to use for session tokens; auto-generated if omitted.
956
+ * @param modifications - Optional dict returned from `onSwmlRequest` to merge into the AI
957
+ * verb config before rendering. Matches Python's `_render_swml(modifications)` semantics:
958
+ * `global_data` is deep-merged; all other keys override the AI config directly.
959
+ * @returns The rendered SWML document as a JSON string.
960
+ */
961
+ renderSwml(callId?: string, modifications?: Record<string, unknown>): string;
962
+ private createEphemeralCopy;
963
+ /**
964
+ * Get or lazily create the Hono HTTP application with all routes, middleware, auth, and CORS.
965
+ * @returns The configured Hono application instance.
966
+ */
967
+ getApp(): Hono;
968
+ /**
969
+ * Return this agent's Hono app for mounting as a sub-router in an AgentServer.
970
+ * @returns The Hono application instance.
971
+ */
972
+ asRouter(): Hono;
973
+ /**
974
+ * Start the HTTP server and begin listening for requests.
975
+ *
976
+ * Uses `@hono/node-server` under the hood. When run in CLI mode
977
+ * (`SWAIG_CLI_MODE=true`, set automatically by `npx swaig-test`), this is a
978
+ * no-op so agent config can be inspected without starting a server.
979
+ *
980
+ * @param opts - Optional host/port overrides. Defaults to the values provided
981
+ * in the constructor options or the `PORT` environment variable.
982
+ * @returns A promise that resolves once the server has begun listening.
983
+ *
984
+ * @example
985
+ * ```ts
986
+ * const agent = new AgentBase({ name: 'demo', port: 3000 });
987
+ * await agent.serve();
988
+ * // Or override at runtime:
989
+ * await agent.serve({ port: 8080, host: '127.0.0.1' });
990
+ * ```
991
+ */
992
+ serve(opts?: {
993
+ host?: string;
994
+ port?: number;
995
+ }): Promise<void>;
996
+ /**
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.
1000
+ */
1001
+ run(opts?: {
1002
+ host?: string;
1003
+ port?: number;
1004
+ }): Promise<void>;
1005
+ /**
1006
+ * Handle a single serverless invocation (AWS Lambda, Google Cloud Functions, Azure Functions, or CGI).
1007
+ *
1008
+ * Matches Python `run(event, context)` when executed in a serverless environment. Python's
1009
+ * `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.
1012
+ *
1013
+ * Platform detection follows the same environment-variable heuristics as Python's
1014
+ * `ServerlessMixin`: `AWS_LAMBDA_FUNCTION_NAME` → Lambda, `K_SERVICE` → GCF,
1015
+ * `FUNCTIONS_WORKER_RUNTIME` → Azure, `GATEWAY_INTERFACE` → CGI.
1016
+ *
1017
+ * Usage in a Lambda handler file:
1018
+ * ```ts
1019
+ * export const handler = (event: any, context: any) => agent.runServerless(event, context);
1020
+ * ```
1021
+ *
1022
+ * @param event - The serverless event payload (Lambda event, GCF request body, etc.).
1023
+ * @param context - The serverless context object (Lambda context, Azure context, etc.).
1024
+ * @param platform - Optional platform override; defaults to 'auto' (environment detection).
1025
+ * @returns The normalized serverless response object.
1026
+ */
1027
+ runServerless(event: ServerlessEvent, context?: unknown, platform?: 'lambda' | 'gcf' | 'azure' | 'cgi' | 'auto'): Promise<ServerlessResponse>;
1028
+ private static _shutdownRegistered;
1029
+ /**
1030
+ * Register process signal handlers for clean Kubernetes/Docker shutdown.
1031
+ * Handles SIGTERM and SIGINT, waits for a timeout, then exits.
1032
+ * @param opts - Optional timeout in milliseconds (default 5000).
1033
+ */
1034
+ static setupGracefulShutdown(opts?: {
1035
+ timeout?: number;
1036
+ }): void;
1037
+ private findSummary;
1038
+ /**
1039
+ * Get the basic-auth credentials used by this agent.
1040
+ * @param includeSource - When true, a third element indicating the credential source is appended.
1041
+ * @returns A tuple of [username, password] or [username, password, source].
1042
+ */
1043
+ getBasicAuthCredentials(includeSource?: false): [string, string];
1044
+ getBasicAuthCredentials(includeSource: true): [string, string, 'provided' | 'environment' | 'auto-generated'];
1045
+ }