@signalwire/sdk 2.0.1 → 2.0.3

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 +1026 -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,1115 @@
1
+ /**
2
+ * ContextBuilder - Contexts and Steps workflow system.
3
+ *
4
+ * Contexts contain ordered Steps, each with prompt text/POM sections,
5
+ * completion criteria, function restrictions, and navigation rules.
6
+ */
7
+ const MAX_CONTEXTS = 50;
8
+ const MAX_STEPS_PER_CONTEXT = 100;
9
+ /**
10
+ * Reserved tool names auto-injected by the runtime when contexts/steps are
11
+ * present. User-defined SWAIG tools must not collide with these names.
12
+ *
13
+ * - `next_step` / `change_context` are injected when valid_steps or
14
+ * valid_contexts is set so the model can navigate the flow.
15
+ * - `gather_submit` is injected while a step's gather_info is collecting
16
+ * answers.
17
+ *
18
+ * ContextBuilder.validate() rejects any agent that registers a user tool
19
+ * sharing one of these names — the runtime would never call the user tool
20
+ * because the native one wins.
21
+ */
22
+ export const RESERVED_NATIVE_TOOL_NAMES = new Set([
23
+ 'next_step',
24
+ 'change_context',
25
+ 'gather_submit',
26
+ ]);
27
+ // ── GatherQuestion ──────────────────────────────────────────────────
28
+ /** Represents a single question within a gather operation. */
29
+ export class GatherQuestion {
30
+ /** Unique key used to store the answer. */
31
+ key;
32
+ /** The question text presented to the user. */
33
+ question;
34
+ /** Expected answer type (e.g., "string", "number"). */
35
+ type;
36
+ /** Whether the answer requires user confirmation. */
37
+ confirm;
38
+ /** Optional additional prompt context for this question. */
39
+ prompt;
40
+ /** Optional list of SWAIG function names available during this question. */
41
+ functions;
42
+ /**
43
+ * Creates a new GatherQuestion.
44
+ * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
45
+ */
46
+ constructor(opts) {
47
+ this.key = opts.key;
48
+ this.question = opts.question;
49
+ this.type = opts.type ?? 'string';
50
+ this.confirm = opts.confirm ?? false;
51
+ this.prompt = opts.prompt;
52
+ this.functions = opts.functions;
53
+ }
54
+ /**
55
+ * Serializes this question to a plain object for SWML output.
56
+ * @returns A dictionary representation of this question.
57
+ */
58
+ toDict() {
59
+ const d = { key: this.key, question: this.question };
60
+ if (this.type !== 'string')
61
+ d['type'] = this.type;
62
+ if (this.confirm)
63
+ d['confirm'] = true;
64
+ if (this.prompt)
65
+ d['prompt'] = this.prompt;
66
+ if (this.functions)
67
+ d['functions'] = this.functions;
68
+ return d;
69
+ }
70
+ }
71
+ // ── GatherInfo ──────────────────────────────────────────────────────
72
+ /** Collects structured information from the user through a series of questions. */
73
+ export class GatherInfo {
74
+ questions = [];
75
+ outputKey;
76
+ completionAction;
77
+ prompt;
78
+ /**
79
+ * Creates a new GatherInfo.
80
+ * @param opts - Optional output key, completion action, and prompt configuration.
81
+ */
82
+ constructor(opts) {
83
+ this.outputKey = opts?.outputKey;
84
+ this.completionAction = opts?.completionAction;
85
+ this.prompt = opts?.prompt;
86
+ }
87
+ /**
88
+ * Adds a question to this gather operation.
89
+ * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
90
+ * @returns This GatherInfo for chaining.
91
+ */
92
+ addQuestion(opts) {
93
+ this.questions.push(new GatherQuestion(opts));
94
+ return this;
95
+ }
96
+ /**
97
+ * Returns all questions in this gather operation.
98
+ * @returns The array of GatherQuestion instances.
99
+ */
100
+ getQuestions() {
101
+ return this.questions;
102
+ }
103
+ /**
104
+ * Returns the completion action for this gather info.
105
+ * @internal
106
+ */
107
+ getCompletionAction() {
108
+ return this.completionAction;
109
+ }
110
+ /**
111
+ * Serializes this gather operation to a plain object for SWML output.
112
+ * @returns A dictionary representation of the gather info and its questions.
113
+ */
114
+ toDict() {
115
+ if (!this.questions.length)
116
+ throw new Error('gather_info must have at least one question');
117
+ const d = { questions: this.questions.map((q) => q.toDict()) };
118
+ if (this.prompt)
119
+ d['prompt'] = this.prompt;
120
+ if (this.outputKey)
121
+ d['output_key'] = this.outputKey;
122
+ if (this.completionAction)
123
+ d['completion_action'] = this.completionAction;
124
+ return d;
125
+ }
126
+ }
127
+ /** A single step within a context, with prompt content, criteria, function restrictions, and navigation rules. */
128
+ export class Step {
129
+ /** The unique name identifying this step within its context. */
130
+ name;
131
+ text = null;
132
+ stepCriteria = null;
133
+ functions = null;
134
+ validSteps = null;
135
+ validContexts = null;
136
+ sections = [];
137
+ gatherInfo = null;
138
+ _end = false;
139
+ skipUserTurn = false;
140
+ _skipToNextStep = false;
141
+ resetSystemPrompt = null;
142
+ resetUserPrompt = null;
143
+ resetConsolidate = false;
144
+ resetFullReset = false;
145
+ /**
146
+ * Creates a new Step.
147
+ * @param name - The unique step name.
148
+ */
149
+ constructor(name) {
150
+ this.name = name;
151
+ }
152
+ /**
153
+ * Sets raw text content for this step, mutually exclusive with POM sections.
154
+ * @param text - The raw prompt text.
155
+ * @returns This step for chaining.
156
+ */
157
+ setText(text) {
158
+ if (this.sections.length)
159
+ throw new Error('Cannot use setText() when POM sections have been added.');
160
+ this.text = text;
161
+ return this;
162
+ }
163
+ /**
164
+ * Adds a POM section with a body, mutually exclusive with raw text.
165
+ * @param title - The section heading.
166
+ * @param body - The section body text.
167
+ * @returns This step for chaining.
168
+ */
169
+ addSection(title, body) {
170
+ if (this.text !== null)
171
+ throw new Error('Cannot add POM sections when setText() has been used.');
172
+ this.sections.push({ title, body });
173
+ return this;
174
+ }
175
+ /**
176
+ * Adds a POM section with bullet points, mutually exclusive with raw text.
177
+ * @param title - The section heading.
178
+ * @param bullets - The list of bullet point strings.
179
+ * @returns This step for chaining.
180
+ */
181
+ addBullets(title, bullets) {
182
+ if (this.text !== null)
183
+ throw new Error('Cannot add POM sections when setText() has been used.');
184
+ this.sections.push({ title, bullets });
185
+ return this;
186
+ }
187
+ /**
188
+ * Sets the criteria that must be met before this step is considered complete.
189
+ * @param criteria - A description of the completion criteria.
190
+ * @returns This step for chaining.
191
+ */
192
+ setStepCriteria(criteria) {
193
+ this.stepCriteria = criteria;
194
+ return this;
195
+ }
196
+ /**
197
+ * Set which non-internal functions are callable while this step is active.
198
+ *
199
+ * IMPORTANT — inheritance behavior:
200
+ * If you do NOT call this method, the step inherits whichever function
201
+ * set was active on the previous step (or the previous context's last
202
+ * step). The server-side runtime only resets the active set when a
203
+ * step explicitly declares its `functions` field. This is by design,
204
+ * but it is the most common source of bugs in multi-step agents:
205
+ * forgetting setFunctions() on a later step lets the previous step's
206
+ * tools leak through.
207
+ *
208
+ * Best practice: call setFunctions() explicitly on every step that
209
+ * should have a different toolset than the previous one.
210
+ *
211
+ * Keep the per-step active set small: LLM tool selection accuracy
212
+ * degrades noticeably past ~7-8 simultaneously-active tools per call.
213
+ * Use per-step whitelisting to partition large tool collections.
214
+ *
215
+ * Internal functions (e.g. `startup_hook`, `hangup_hook`, `gather_submit`)
216
+ * are ALWAYS protected and cannot be deactivated by this whitelist. The
217
+ * native navigation tools `next_step` and `change_context` are injected
218
+ * automatically when validSteps/validContexts is set; they are not
219
+ * affected by this list and do not need to appear in it.
220
+ *
221
+ * @param functions - One of:
222
+ * - `string[]` — whitelist of function names allowed in this step.
223
+ * Functions not in the list become inactive.
224
+ * - `[]` — explicit disable-all (no user functions callable).
225
+ * - `"none"` — synonym for `[]`, same effect.
226
+ * @returns This step for chaining.
227
+ *
228
+ * @example
229
+ * step.setFunctions(['lookup_account', 'check_balance']); // whitelist
230
+ * step.setFunctions([]); // disable all
231
+ * step.setFunctions('none'); // disable all (alt)
232
+ */
233
+ setFunctions(functions) {
234
+ this.functions = functions;
235
+ return this;
236
+ }
237
+ /**
238
+ * Sets which steps the AI may navigate to from this step.
239
+ * @param steps - List of allowed step names.
240
+ * @returns This step for chaining.
241
+ */
242
+ setValidSteps(steps) {
243
+ this.validSteps = steps;
244
+ return this;
245
+ }
246
+ /**
247
+ * Sets which contexts the AI may navigate to from this step.
248
+ * @param contexts - List of allowed context names.
249
+ * @returns This step for chaining.
250
+ */
251
+ setValidContexts(contexts) {
252
+ this.validContexts = contexts;
253
+ return this;
254
+ }
255
+ /**
256
+ * Mark this step as terminal for the step flow.
257
+ *
258
+ * IMPORTANT: `end=true` does NOT end the conversation or hang up the
259
+ * call. It exits step mode entirely after this step executes — clearing
260
+ * the steps list, current step index, validSteps, and validContexts.
261
+ * The agent keeps running, but operates only under the base system
262
+ * prompt and the context-level prompt; no more step instructions are
263
+ * injected and no more `next_step` tool is offered.
264
+ *
265
+ * To actually end the call, call a hangup tool or define a hangup hook.
266
+ *
267
+ * @param end - True to exit step mode after this step.
268
+ * @returns This step for chaining.
269
+ */
270
+ setEnd(end) {
271
+ this._end = end;
272
+ return this;
273
+ }
274
+ /**
275
+ * Sets whether to skip waiting for user input when entering this step.
276
+ * @param skip - Whether to skip the user turn.
277
+ * @returns This step for chaining.
278
+ */
279
+ setSkipUserTurn(skip) {
280
+ this.skipUserTurn = skip;
281
+ return this;
282
+ }
283
+ /**
284
+ * Sets whether to automatically advance to the next step after this one completes.
285
+ * @param skip - Whether to skip to the next step.
286
+ * @returns This step for chaining.
287
+ */
288
+ setSkipToNextStep(skip) {
289
+ this._skipToNextStep = skip;
290
+ return this;
291
+ }
292
+ /**
293
+ * Initializes a gather info operation on this step for collecting structured data.
294
+ * @param opts - Optional output key, completion action, and prompt configuration.
295
+ * @returns This step for chaining.
296
+ */
297
+ setGatherInfo(opts) {
298
+ this.gatherInfo = new GatherInfo(opts);
299
+ return this;
300
+ }
301
+ /**
302
+ * Add a question to this step's gather_info configuration.
303
+ * setGatherInfo() must be called before this method.
304
+ *
305
+ * IMPORTANT — gather mode locks function access:
306
+ * While the model is asking gather questions, the runtime forcibly
307
+ * deactivates ALL of the step's other functions. The only callable
308
+ * tools during a gather question are:
309
+ *
310
+ * - `gather_submit` (the native answer-submission tool)
311
+ * - Whatever names you list in this question's `functions` option
312
+ *
313
+ * `next_step` and `change_context` are also filtered out — the model
314
+ * cannot navigate away until the gather completes. This is by design:
315
+ * it forces a tight ask → submit → next-question loop.
316
+ *
317
+ * If a question needs to call out to a tool (e.g. validate an email,
318
+ * geocode a ZIP), list that tool name in this question's `functions`.
319
+ * Functions listed here are active ONLY for this question.
320
+ *
321
+ * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
322
+ * @returns This step for chaining.
323
+ */
324
+ addGatherQuestion(opts) {
325
+ if (!this.gatherInfo)
326
+ throw new Error('Must call setGatherInfo() before addGatherQuestion()');
327
+ this.gatherInfo.addQuestion(opts);
328
+ return this;
329
+ }
330
+ /**
331
+ * Returns the gather info for this step, if any.
332
+ * @internal
333
+ */
334
+ getGatherInfo() {
335
+ return this.gatherInfo;
336
+ }
337
+ /**
338
+ * Returns the valid steps list for this step, if any.
339
+ * @internal
340
+ */
341
+ getValidSteps() {
342
+ return this.validSteps;
343
+ }
344
+ /**
345
+ * Returns the valid contexts list for this step, if any.
346
+ * @internal
347
+ */
348
+ getStepValidContexts() {
349
+ return this.validContexts;
350
+ }
351
+ /**
352
+ * Removes all POM sections and raw text from this step.
353
+ * @returns This step for chaining.
354
+ */
355
+ clearSections() {
356
+ this.sections = [];
357
+ this.text = null;
358
+ return this;
359
+ }
360
+ /**
361
+ * Sets the system prompt to use when resetting context at this step.
362
+ * @param systemPrompt - The replacement system prompt text.
363
+ * @returns This step for chaining.
364
+ */
365
+ setResetSystemPrompt(systemPrompt) {
366
+ this.resetSystemPrompt = systemPrompt;
367
+ return this;
368
+ }
369
+ /**
370
+ * Sets the user prompt to use when resetting context at this step.
371
+ * @param userPrompt - The replacement user prompt text.
372
+ * @returns This step for chaining.
373
+ */
374
+ setResetUserPrompt(userPrompt) {
375
+ this.resetUserPrompt = userPrompt;
376
+ return this;
377
+ }
378
+ /**
379
+ * Sets whether to consolidate conversation history when resetting at this step.
380
+ * @param consolidate - Whether to consolidate.
381
+ * @returns This step for chaining.
382
+ */
383
+ setResetConsolidate(consolidate) {
384
+ this.resetConsolidate = consolidate;
385
+ return this;
386
+ }
387
+ /**
388
+ * Sets whether to perform a full conversation reset at this step.
389
+ * @param fullReset - Whether to fully reset.
390
+ * @returns This step for chaining.
391
+ */
392
+ setResetFullReset(fullReset) {
393
+ this.resetFullReset = fullReset;
394
+ return this;
395
+ }
396
+ renderText() {
397
+ if (this.text !== null)
398
+ return this.text;
399
+ if (!this.sections.length)
400
+ throw new Error(`Step '${this.name}' has no text or POM sections defined`);
401
+ const parts = [];
402
+ for (const section of this.sections) {
403
+ parts.push(`## ${section.title}`);
404
+ if (section.bullets) {
405
+ for (const b of section.bullets)
406
+ parts.push(`- ${b}`);
407
+ }
408
+ else if (section.body) {
409
+ parts.push(section.body);
410
+ }
411
+ parts.push('');
412
+ }
413
+ return parts.join('\n').trim();
414
+ }
415
+ /**
416
+ * Serializes this step to a plain object for SWML output.
417
+ * @returns A dictionary representation of this step.
418
+ */
419
+ toDict() {
420
+ const d = { name: this.name, text: this.renderText() };
421
+ if (this.stepCriteria)
422
+ d['step_criteria'] = this.stepCriteria;
423
+ if (this.functions !== null)
424
+ d['functions'] = this.functions;
425
+ if (this.validSteps !== null)
426
+ d['valid_steps'] = this.validSteps;
427
+ if (this.validContexts !== null)
428
+ d['valid_contexts'] = this.validContexts;
429
+ if (this._end)
430
+ d['end'] = true;
431
+ if (this.skipUserTurn)
432
+ d['skip_user_turn'] = true;
433
+ if (this._skipToNextStep)
434
+ d['skip_to_next_step'] = true;
435
+ const reset = {};
436
+ if (this.resetSystemPrompt !== null)
437
+ reset['system_prompt'] = this.resetSystemPrompt;
438
+ if (this.resetUserPrompt !== null)
439
+ reset['user_prompt'] = this.resetUserPrompt;
440
+ if (this.resetConsolidate)
441
+ reset['consolidate'] = true;
442
+ if (this.resetFullReset)
443
+ reset['full_reset'] = true;
444
+ if (Object.keys(reset).length)
445
+ d['reset'] = reset;
446
+ if (this.gatherInfo)
447
+ d['gather_info'] = this.gatherInfo.toDict();
448
+ return d;
449
+ }
450
+ }
451
+ // ── Context ─────────────────────────────────────────────────────────
452
+ /** A named context containing ordered steps, prompt configuration, and navigation rules. */
453
+ export class Context {
454
+ /** The unique name identifying this context. */
455
+ name;
456
+ steps = new Map();
457
+ stepOrder = [];
458
+ _validContexts = null;
459
+ _validSteps = null;
460
+ _postPrompt = null;
461
+ _systemPrompt = null;
462
+ systemPromptSections = [];
463
+ _consolidate = false;
464
+ _fullReset = false;
465
+ _userPrompt = null;
466
+ _isolated = false;
467
+ promptText = null;
468
+ promptSections = [];
469
+ _initialStep = null;
470
+ _enterFillers = null;
471
+ _exitFillers = null;
472
+ /**
473
+ * Creates a new Context.
474
+ * @param name - The unique context name.
475
+ */
476
+ constructor(name) {
477
+ this.name = name;
478
+ }
479
+ /**
480
+ * Adds a new step to this context.
481
+ * @param name - The unique step name within this context.
482
+ * @param opts - Optional shorthand for task text, bullets, criteria, functions, and valid steps.
483
+ * @returns The newly created Step for further configuration.
484
+ */
485
+ addStep(name, opts) {
486
+ if (this.steps.size >= MAX_STEPS_PER_CONTEXT) {
487
+ throw new Error(`Maximum steps per context (${MAX_STEPS_PER_CONTEXT}) exceeded`);
488
+ }
489
+ if (this.steps.has(name))
490
+ throw new Error(`Step '${name}' already exists in context '${this.name}'`);
491
+ const step = new Step(name);
492
+ this.steps.set(name, step);
493
+ this.stepOrder.push(name);
494
+ if (opts?.task)
495
+ step.addSection('Task', opts.task);
496
+ if (opts?.bullets)
497
+ step.addBullets('Process', opts.bullets);
498
+ if (opts?.criteria)
499
+ step.setStepCriteria(opts.criteria);
500
+ if (opts?.functions)
501
+ step.setFunctions(opts.functions);
502
+ if (opts?.validSteps)
503
+ step.setValidSteps(opts.validSteps);
504
+ return step;
505
+ }
506
+ /**
507
+ * Returns a step by name.
508
+ * @param name - The step name to retrieve.
509
+ * @returns The matching Step, or undefined if not found.
510
+ */
511
+ getStep(name) {
512
+ return this.steps.get(name);
513
+ }
514
+ /**
515
+ * Removes a step from this context by name.
516
+ * @param name - The step name to remove.
517
+ * @returns This context for chaining.
518
+ */
519
+ removeStep(name) {
520
+ this.steps.delete(name);
521
+ this.stepOrder = this.stepOrder.filter((s) => s !== name);
522
+ return this;
523
+ }
524
+ /**
525
+ * Moves a step to a new position in the step order.
526
+ * @param name - The step name to move.
527
+ * @param position - The zero-based index to insert at.
528
+ * @returns This context for chaining.
529
+ */
530
+ moveStep(name, position) {
531
+ if (!this.steps.has(name))
532
+ throw new Error(`Step '${name}' not found in context '${this.name}'`);
533
+ this.stepOrder = this.stepOrder.filter((s) => s !== name);
534
+ this.stepOrder.splice(position, 0, name);
535
+ return this;
536
+ }
537
+ /**
538
+ * Sets which contexts the AI may navigate to from this context.
539
+ * @param contexts - List of allowed context names.
540
+ * @returns This context for chaining.
541
+ */
542
+ setValidContexts(contexts) {
543
+ this._validContexts = contexts;
544
+ return this;
545
+ }
546
+ /**
547
+ * Sets which steps the AI may navigate to from this context.
548
+ * @param steps - List of allowed step names.
549
+ * @returns This context for chaining.
550
+ */
551
+ setValidSteps(steps) {
552
+ this._validSteps = steps;
553
+ return this;
554
+ }
555
+ /**
556
+ * Sets the post-prompt text for this context.
557
+ * @param postPrompt - The post-prompt string.
558
+ * @returns This context for chaining.
559
+ */
560
+ setPostPrompt(postPrompt) {
561
+ this._postPrompt = postPrompt;
562
+ return this;
563
+ }
564
+ /**
565
+ * Sets raw system prompt text, mutually exclusive with system POM sections.
566
+ * @param systemPrompt - The system prompt string.
567
+ * @returns This context for chaining.
568
+ */
569
+ setSystemPrompt(systemPrompt) {
570
+ if (this.systemPromptSections.length)
571
+ throw new Error('Cannot use setSystemPrompt() when POM sections have been added.');
572
+ this._systemPrompt = systemPrompt;
573
+ return this;
574
+ }
575
+ /**
576
+ * Sets whether to consolidate conversation history when entering this context.
577
+ * @param consolidate - Whether to consolidate.
578
+ * @returns This context for chaining.
579
+ */
580
+ setConsolidate(consolidate) {
581
+ this._consolidate = consolidate;
582
+ return this;
583
+ }
584
+ /**
585
+ * Sets whether to fully reset conversation history when entering this context.
586
+ * @param fullReset - Whether to fully reset.
587
+ * @returns This context for chaining.
588
+ */
589
+ setFullReset(fullReset) {
590
+ this._fullReset = fullReset;
591
+ return this;
592
+ }
593
+ /**
594
+ * Sets the user prompt text for this context.
595
+ * @param userPrompt - The user prompt string.
596
+ * @returns This context for chaining.
597
+ */
598
+ setUserPrompt(userPrompt) {
599
+ this._userPrompt = userPrompt;
600
+ return this;
601
+ }
602
+ /**
603
+ * Set which step the context starts on when entered.
604
+ *
605
+ * By default, a context starts on its first step (index 0). Use this to
606
+ * skip a preamble step on re-entry via `change_context`.
607
+ *
608
+ * @param stepName - Name of the step to start on. Must exist in this context (validated by ContextBuilder.validate()).
609
+ * @returns This context for chaining.
610
+ */
611
+ setInitialStep(stepName) {
612
+ this._initialStep = stepName;
613
+ return this;
614
+ }
615
+ /**
616
+ * Mark this context as isolated — entering it wipes conversation history.
617
+ *
618
+ * When `isolated=true` and the context is entered via change_context, the
619
+ * runtime wipes the conversation array. The model starts fresh with only
620
+ * the new context's systemPrompt + step instructions, with no memory of
621
+ * prior turns.
622
+ *
623
+ * EXCEPTION — `reset` overrides the wipe:
624
+ * If the context also has a `reset` configuration (via consolidate or
625
+ * full_reset), the wipe is skipped in favor of the reset behavior. Use
626
+ * reset with consolidate=true to summarize prior history into a single
627
+ * message instead of dropping it entirely.
628
+ *
629
+ * Use cases:
630
+ * - Switching to a sensitive billing flow that should not see prior
631
+ * small-talk
632
+ * - Handing off to a different agent persona
633
+ * - Resetting after a long off-topic detour
634
+ *
635
+ * @param isolated - True to wipe conversation history on context entry
636
+ * (subject to the reset exception above).
637
+ * @returns This context for chaining.
638
+ */
639
+ setIsolated(isolated) {
640
+ this._isolated = isolated;
641
+ return this;
642
+ }
643
+ /**
644
+ * Adds a POM section to the system prompt, mutually exclusive with raw system prompt text.
645
+ * @param title - The section heading.
646
+ * @param body - The section body text.
647
+ * @returns This context for chaining.
648
+ */
649
+ addSystemSection(title, body) {
650
+ if (this._systemPrompt !== null)
651
+ throw new Error('Cannot add POM sections when setSystemPrompt() has been used.');
652
+ this.systemPromptSections.push({ title, body });
653
+ return this;
654
+ }
655
+ /**
656
+ * Adds a POM section with bullets to the system prompt, mutually exclusive with raw system prompt text.
657
+ * @param title - The section heading.
658
+ * @param bullets - The list of bullet point strings.
659
+ * @returns This context for chaining.
660
+ */
661
+ addSystemBullets(title, bullets) {
662
+ if (this._systemPrompt !== null)
663
+ throw new Error('Cannot add POM sections when setSystemPrompt() has been used.');
664
+ this.systemPromptSections.push({ title, bullets });
665
+ return this;
666
+ }
667
+ /**
668
+ * Sets raw prompt text for this context, mutually exclusive with POM prompt sections.
669
+ * @param prompt - The prompt string.
670
+ * @returns This context for chaining.
671
+ */
672
+ setPrompt(prompt) {
673
+ if (this.promptSections.length)
674
+ throw new Error('Cannot use setPrompt() when POM sections have been added.');
675
+ this.promptText = prompt;
676
+ return this;
677
+ }
678
+ /**
679
+ * Adds a POM section with a body to the context prompt, mutually exclusive with raw prompt text.
680
+ * @param title - The section heading.
681
+ * @param body - The section body text.
682
+ * @returns This context for chaining.
683
+ */
684
+ addSection(title, body) {
685
+ if (this.promptText !== null)
686
+ throw new Error('Cannot add POM sections when setPrompt() has been used.');
687
+ this.promptSections.push({ title, body });
688
+ return this;
689
+ }
690
+ /**
691
+ * Adds a POM section with bullets to the context prompt, mutually exclusive with raw prompt text.
692
+ * @param title - The section heading.
693
+ * @param bullets - The list of bullet point strings.
694
+ * @returns This context for chaining.
695
+ */
696
+ addBullets(title, bullets) {
697
+ if (this.promptText !== null)
698
+ throw new Error('Cannot add POM sections when setPrompt() has been used.');
699
+ this.promptSections.push({ title, bullets });
700
+ return this;
701
+ }
702
+ /**
703
+ * Sets filler phrases spoken when entering this context, keyed by language code.
704
+ * @param fillers - Map of language codes to arrays of filler phrases.
705
+ * @returns This context for chaining.
706
+ */
707
+ setEnterFillers(fillers) {
708
+ this._enterFillers = fillers;
709
+ return this;
710
+ }
711
+ /**
712
+ * Sets filler phrases spoken when exiting this context, keyed by language code.
713
+ * @param fillers - Map of language codes to arrays of filler phrases.
714
+ * @returns This context for chaining.
715
+ */
716
+ setExitFillers(fillers) {
717
+ this._exitFillers = fillers;
718
+ return this;
719
+ }
720
+ /**
721
+ * Adds enter filler phrases for a specific language.
722
+ * @param languageCode - The language code (e.g., "en-US").
723
+ * @param fillers - Array of filler phrases.
724
+ * @returns This context for chaining.
725
+ */
726
+ addEnterFiller(languageCode, fillers) {
727
+ if (!this._enterFillers)
728
+ this._enterFillers = {};
729
+ this._enterFillers[languageCode] = fillers;
730
+ return this;
731
+ }
732
+ /**
733
+ * Adds exit filler phrases for a specific language.
734
+ * @param languageCode - The language code (e.g., "en-US").
735
+ * @param fillers - Array of filler phrases.
736
+ * @returns This context for chaining.
737
+ */
738
+ addExitFiller(languageCode, fillers) {
739
+ if (!this._exitFillers)
740
+ this._exitFillers = {};
741
+ this._exitFillers[languageCode] = fillers;
742
+ return this;
743
+ }
744
+ /** @internal */
745
+ getSteps() {
746
+ return this.steps;
747
+ }
748
+ /** @internal */
749
+ getStepOrder() {
750
+ return this.stepOrder;
751
+ }
752
+ /** @internal */
753
+ getInitialStep() {
754
+ return this._initialStep;
755
+ }
756
+ /** @internal */
757
+ getValidContexts() {
758
+ return this._validContexts;
759
+ }
760
+ renderPrompt() {
761
+ if (this.promptText !== null)
762
+ return this.promptText;
763
+ if (!this.promptSections.length)
764
+ return null;
765
+ return this.renderSections(this.promptSections);
766
+ }
767
+ renderSystemPrompt() {
768
+ if (this._systemPrompt !== null)
769
+ return this._systemPrompt;
770
+ if (!this.systemPromptSections.length)
771
+ return null;
772
+ return this.renderSections(this.systemPromptSections);
773
+ }
774
+ renderSections(sections) {
775
+ const parts = [];
776
+ for (const s of sections) {
777
+ parts.push(`## ${s.title}`);
778
+ if (s.bullets)
779
+ for (const b of s.bullets)
780
+ parts.push(`- ${b}`);
781
+ else if (s.body)
782
+ parts.push(s.body);
783
+ parts.push('');
784
+ }
785
+ return parts.join('\n').trim();
786
+ }
787
+ /**
788
+ * Serializes this context and all its steps to a plain object for SWML output.
789
+ * @returns A dictionary representation of this context.
790
+ */
791
+ toDict() {
792
+ if (!this.steps.size)
793
+ throw new Error(`Context '${this.name}' has no steps defined`);
794
+ const d = {
795
+ steps: this.stepOrder.map((name) => this.steps.get(name).toDict()),
796
+ };
797
+ if (this._validContexts !== null)
798
+ d['valid_contexts'] = this._validContexts;
799
+ if (this._validSteps !== null)
800
+ d['valid_steps'] = this._validSteps;
801
+ if (this._initialStep !== null)
802
+ d['initial_step'] = this._initialStep;
803
+ if (this._postPrompt !== null)
804
+ d['post_prompt'] = this._postPrompt;
805
+ const sp = this.renderSystemPrompt();
806
+ if (sp !== null)
807
+ d['system_prompt'] = sp;
808
+ if (this._consolidate)
809
+ d['consolidate'] = true;
810
+ if (this._fullReset)
811
+ d['full_reset'] = true;
812
+ if (this._userPrompt !== null)
813
+ d['user_prompt'] = this._userPrompt;
814
+ if (this._isolated)
815
+ d['isolated'] = true;
816
+ if (this.promptSections.length) {
817
+ d['pom'] = this.promptSections;
818
+ }
819
+ else if (this.promptText !== null) {
820
+ d['prompt'] = this.promptText;
821
+ }
822
+ if (this._enterFillers)
823
+ d['enter_fillers'] = this._enterFillers;
824
+ if (this._exitFillers)
825
+ d['exit_fillers'] = this._exitFillers;
826
+ return d;
827
+ }
828
+ }
829
+ // ── ContextBuilder ──────────────────────────────────────────────────
830
+ /**
831
+ * Builder for multi-step, multi-context AI agent workflows.
832
+ *
833
+ * A ContextBuilder owns one or more Contexts; each Context owns an ordered
834
+ * list of Steps. Only one context and one step is active at a time. Per
835
+ * chat turn, the runtime injects the current step's instructions as a
836
+ * system message, then asks the LLM for a response.
837
+ *
838
+ * ## Native tools auto-injected by the runtime
839
+ *
840
+ * When a step (or its enclosing context) declares `validSteps` or
841
+ * `validContexts`, the runtime auto-injects two native tools so the model
842
+ * can navigate the flow:
843
+ *
844
+ * - `next_step(step: enum)` — present when validSteps is set
845
+ * - `change_context(context: enum)` — present when validContexts is set
846
+ *
847
+ * Their `enum` schemas are rewritten on every turn to match whatever
848
+ * validSteps / validContexts apply to the current step. You do NOT need
849
+ * to define these tools yourself; they appear automatically.
850
+ *
851
+ * A third native tool — `gather_submit` — is injected during gather_info
852
+ * questioning (see Step.setGatherInfo / addGatherQuestion).
853
+ *
854
+ * These three names — `next_step`, `change_context`, `gather_submit` —
855
+ * are reserved. ContextBuilder.validate() will reject any agent that
856
+ * defines a SWAIG tool with one of these names.
857
+ *
858
+ * ## Function whitelisting (Step.setFunctions)
859
+ *
860
+ * Each step may declare a `functions` whitelist. The whitelist is applied
861
+ * in-memory at the start of each LLM turn. CRITICALLY: if a step does NOT
862
+ * declare a `functions` field, it INHERITS the previous step's active set.
863
+ * See Step.setFunctions() for details and examples.
864
+ *
865
+ * ## Validation
866
+ *
867
+ * Call validate() (or toDict(), which calls it) to check that:
868
+ *
869
+ * - At least one context is defined
870
+ * - A single context must be named "default"
871
+ * - Every context has at least one step
872
+ * - validSteps references resolve to real step names (or "next")
873
+ * - validContexts references resolve to real context names
874
+ * - gather_info questions are non-empty and have unique keys
875
+ * - gather_info completion_action targets a reachable step
876
+ * - No user-defined SWAIG tool collides with a reserved native name
877
+ *
878
+ * @example Two-step support bot
879
+ * ```ts
880
+ * import { AgentBase, ContextBuilder } from '@signalwire/sdk';
881
+ *
882
+ * const agent = new AgentBase({ name: 'support', route: '/' });
883
+ *
884
+ * const contexts = new ContextBuilder();
885
+ * const flow = contexts.addContext('default');
886
+ *
887
+ * flow.addStep('greeting')
888
+ * .setText("Greet the caller and ask if they're an existing customer.")
889
+ * .setValidSteps(['existing', 'new']);
890
+ *
891
+ * flow.addStep('existing')
892
+ * .setText('Ask for the account number and read it back to confirm.');
893
+ *
894
+ * flow.addStep('new')
895
+ * .setText('Collect name, email, and reason for calling.');
896
+ *
897
+ * agent.defineContexts(contexts);
898
+ * ```
899
+ *
900
+ * @see {@link Context}
901
+ * @see {@link Step}
902
+ * @see {@link GatherInfo}
903
+ * @see {@link AgentBase.defineContexts}
904
+ */
905
+ export class ContextBuilder {
906
+ contexts = new Map();
907
+ contextOrder = [];
908
+ agent = null;
909
+ /**
910
+ * Attach an agent reference so validate() can check user tool names
911
+ * against reserved native tool names. Called internally by
912
+ * AgentBase.defineContexts().
913
+ * @internal
914
+ */
915
+ attachAgent(agent) {
916
+ this.agent = agent;
917
+ return this;
918
+ }
919
+ /**
920
+ * Removes all contexts, returning the builder to its initial state.
921
+ * Use this in a dynamic config callback when you need to rebuild
922
+ * contexts from scratch for a specific request.
923
+ * @returns This builder for chaining.
924
+ */
925
+ reset() {
926
+ this.contexts.clear();
927
+ this.contextOrder = [];
928
+ return this;
929
+ }
930
+ /**
931
+ * Adds a new named context to the builder.
932
+ *
933
+ * @param name - The unique context name. A single-context flow must name
934
+ * its only context `"default"`.
935
+ * @returns The newly created {@link Context} for further configuration.
936
+ * @throws {Error} When the max-context limit is exceeded or a context with
937
+ * the same name already exists.
938
+ */
939
+ addContext(name) {
940
+ if (this.contexts.size >= MAX_CONTEXTS) {
941
+ throw new Error(`Maximum number of contexts (${MAX_CONTEXTS}) exceeded`);
942
+ }
943
+ if (this.contexts.has(name))
944
+ throw new Error(`Context '${name}' already exists`);
945
+ const ctx = new Context(name);
946
+ this.contexts.set(name, ctx);
947
+ this.contextOrder.push(name);
948
+ return ctx;
949
+ }
950
+ /**
951
+ * Returns a context by name.
952
+ * @param name - The context name to retrieve.
953
+ * @returns The matching Context, or undefined if not found.
954
+ */
955
+ getContext(name) {
956
+ return this.contexts.get(name);
957
+ }
958
+ /**
959
+ * Validates that all contexts have steps, naming constraints are met, and cross-context references are valid.
960
+ * @throws Error if validation fails.
961
+ */
962
+ validate() {
963
+ if (!this.contexts.size)
964
+ throw new Error('At least one context must be defined');
965
+ if (this.contexts.size === 1) {
966
+ const name = [...this.contexts.keys()][0];
967
+ if (name !== 'default')
968
+ throw new Error("When using a single context, it must be named 'default'");
969
+ }
970
+ for (const [name, ctx] of this.contexts) {
971
+ if (!ctx.getSteps().size)
972
+ throw new Error(`Context '${name}' must have at least one step`);
973
+ }
974
+ // Validate initial_step references a real step in the context
975
+ for (const [name, ctx] of this.contexts) {
976
+ const initialStep = ctx.getInitialStep();
977
+ if (initialStep !== null && !ctx.getSteps().has(initialStep)) {
978
+ const available = [...ctx.getSteps().keys()].sort();
979
+ throw new Error(`Context '${name}' has initial_step='${initialStep}' but that step does not exist. ` +
980
+ `Available steps: [${available.map((n) => `'${n}'`).join(', ')}]`);
981
+ }
982
+ }
983
+ // Validate context references
984
+ for (const [, ctx] of this.contexts) {
985
+ const vc = ctx.getValidContexts();
986
+ if (vc) {
987
+ for (const ref of vc) {
988
+ if (!this.contexts.has(ref)) {
989
+ throw new Error(`Context '${ctx.name}' references unknown context '${ref}'`);
990
+ }
991
+ }
992
+ }
993
+ }
994
+ // Validate step references in valid_steps
995
+ for (const [ctxName, ctx] of this.contexts) {
996
+ const steps = ctx.getSteps();
997
+ for (const [stepName, step] of steps) {
998
+ const vs = step.getValidSteps();
999
+ if (vs) {
1000
+ for (const ref of vs) {
1001
+ if (ref !== 'next' && !steps.has(ref)) {
1002
+ throw new Error(`Step '${stepName}' in context '${ctxName}' references unknown step '${ref}'`);
1003
+ }
1004
+ }
1005
+ }
1006
+ }
1007
+ }
1008
+ // Validate context references in valid_contexts (step-level)
1009
+ for (const [ctxName, ctx] of this.contexts) {
1010
+ for (const [stepName, step] of ctx.getSteps()) {
1011
+ const vc = step.getStepValidContexts();
1012
+ if (vc) {
1013
+ for (const ref of vc) {
1014
+ if (!this.contexts.has(ref)) {
1015
+ throw new Error(`Step '${stepName}' in context '${ctxName}' references unknown context '${ref}'`);
1016
+ }
1017
+ }
1018
+ }
1019
+ }
1020
+ }
1021
+ // Validate gather_info: no duplicate question keys
1022
+ for (const [ctxName, ctx] of this.contexts) {
1023
+ for (const [stepName, step] of ctx.getSteps()) {
1024
+ const gi = step.getGatherInfo();
1025
+ if (!gi)
1026
+ continue;
1027
+ const keysSeen = new Set();
1028
+ for (const q of gi.getQuestions()) {
1029
+ if (keysSeen.has(q.key)) {
1030
+ throw new Error(`Step '${stepName}' in context '${ctxName}' has duplicate gather_info question key '${q.key}'`);
1031
+ }
1032
+ keysSeen.add(q.key);
1033
+ }
1034
+ }
1035
+ }
1036
+ // Validate completion_action references in gather_info
1037
+ for (const [ctxName, ctx] of this.contexts) {
1038
+ const stepOrder = ctx.getStepOrder();
1039
+ const steps = ctx.getSteps();
1040
+ for (let i = 0; i < stepOrder.length; i++) {
1041
+ const stepName = stepOrder[i];
1042
+ const step = steps.get(stepName);
1043
+ const gi = step.getGatherInfo();
1044
+ if (!gi)
1045
+ continue;
1046
+ const action = gi.getCompletionAction();
1047
+ if (!action)
1048
+ continue;
1049
+ if (action === 'next_step') {
1050
+ if (i === stepOrder.length - 1) {
1051
+ throw new Error(`Step '${stepName}' in context '${ctxName}' has gather_info ` +
1052
+ `completion_action='next_step' but it is the last step in the context. ` +
1053
+ `Either (1) add another step after '${stepName}', ` +
1054
+ `(2) set completion_action to the name of an existing step in this ` +
1055
+ `context to jump to it, or (3) omit completion_action (default) to ` +
1056
+ `stay in '${stepName}' after gathering completes.`);
1057
+ }
1058
+ }
1059
+ else if (!steps.has(action)) {
1060
+ const available = [...steps.keys()].sort();
1061
+ throw new Error(`Step '${stepName}' in context '${ctxName}' has gather_info ` +
1062
+ `completion_action='${action}' but '${action}' is not a step in this ` +
1063
+ `context. Valid options: 'next_step' (advance to the next sequential ` +
1064
+ `step), undefined (stay in the current step), or one of ` +
1065
+ `[${available.map((n) => `'${n}'`).join(', ')}].`);
1066
+ }
1067
+ }
1068
+ }
1069
+ // Validate that user-defined tools do not collide with reserved native
1070
+ // tool names. The runtime auto-injects next_step / change_context /
1071
+ // gather_submit when contexts/steps are present, so user tools sharing
1072
+ // those names would never be called.
1073
+ if (this.agent && typeof this.agent.getRegisteredTools === 'function') {
1074
+ const getRegisteredTools = this.agent.getRegisteredTools.bind(this.agent);
1075
+ const registered = getRegisteredTools();
1076
+ const colliding = [];
1077
+ for (const tool of registered) {
1078
+ if (tool && typeof tool.name === 'string' && RESERVED_NATIVE_TOOL_NAMES.has(tool.name)) {
1079
+ colliding.push(tool.name);
1080
+ }
1081
+ }
1082
+ colliding.sort();
1083
+ if (colliding.length > 0) {
1084
+ const reserved = [...RESERVED_NATIVE_TOOL_NAMES].sort();
1085
+ throw new Error(`Tool name(s) [${colliding.map((n) => `'${n}'`).join(', ')}] collide ` +
1086
+ `with reserved native tools auto-injected by contexts/steps. The ` +
1087
+ `names [${reserved.join(', ')}] are reserved and cannot be used ` +
1088
+ `for user-defined SWAIG tools when contexts/steps are in use. ` +
1089
+ `Rename your tool(s) to avoid the collision.`);
1090
+ }
1091
+ }
1092
+ }
1093
+ /**
1094
+ * Validates and serializes all contexts to a plain object for SWML output.
1095
+ * @returns A dictionary mapping context names to their serialized representations.
1096
+ */
1097
+ toDict() {
1098
+ this.validate();
1099
+ const result = {};
1100
+ for (const name of this.contextOrder) {
1101
+ result[name] = this.contexts.get(name).toDict();
1102
+ }
1103
+ return result;
1104
+ }
1105
+ }
1106
+ // ── Helper ──────────────────────────────────────────────────────────
1107
+ /**
1108
+ * Creates a standalone Context instance without a ContextBuilder.
1109
+ * @param name - The context name (defaults to "default").
1110
+ * @returns A new Context instance.
1111
+ */
1112
+ export function createSimpleContext(name = 'default') {
1113
+ return new Context(name);
1114
+ }
1115
+ //# sourceMappingURL=ContextBuilder.js.map