@signalwire/sdk 2.0.4 → 3.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (656) hide show
  1. package/CHANGELOG.md +785 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +550 -163
  6. package/dist/AgentBase.js +1640 -514
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +158 -45
  21. package/dist/DataMap.js +167 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +277 -83
  24. package/dist/FunctionResult.js +444 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +163 -0
  30. package/dist/POM/PromptObjectModel.js +481 -0
  31. package/dist/POM/PromptObjectModel.js.map +1 -0
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +28 -0
  42. package/dist/PomBuilder.js +81 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +29 -1
  48. package/dist/PromptManager.js +37 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +265 -66
  58. package/dist/SWMLService.js +652 -112
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +55 -8
  64. package/dist/SecurityUtils.js +162 -49
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/ServerlessAdapter.d.ts +156 -7
  67. package/dist/ServerlessAdapter.js +399 -42
  68. package/dist/ServerlessAdapter.js.map +1 -1
  69. package/dist/SessionManager.d.ts +11 -2
  70. package/dist/SessionManager.js +50 -18
  71. package/dist/SessionManager.js.map +1 -1
  72. package/dist/SslConfig.d.ts +2 -1
  73. package/dist/SslConfig.js +4 -1
  74. package/dist/SslConfig.js.map +1 -1
  75. package/dist/SwaigActions.generated.d.ts +23 -0
  76. package/dist/SwaigActions.generated.js +8 -0
  77. package/dist/SwaigActions.generated.js.map +1 -0
  78. package/dist/SwaigContracts.d.ts +15 -0
  79. package/dist/SwaigContracts.generated.d.ts +264 -0
  80. package/dist/SwaigContracts.generated.js +12 -0
  81. package/dist/SwaigContracts.generated.js.map +1 -0
  82. package/dist/SwaigContracts.js +2 -0
  83. package/dist/SwaigContracts.js.map +1 -0
  84. package/dist/SwaigFunction.d.ts +110 -4
  85. package/dist/SwaigFunction.js +151 -19
  86. package/dist/SwaigFunction.js.map +1 -1
  87. package/dist/SwmlBuilder.d.ts +68 -19
  88. package/dist/SwmlBuilder.js +74 -38
  89. package/dist/SwmlBuilder.js.map +1 -1
  90. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  91. package/dist/SwmlVerbMethods.generated.js +1 -1
  92. package/dist/TypeInference.d.ts +39 -3
  93. package/dist/TypeInference.js +256 -16
  94. package/dist/TypeInference.js.map +1 -1
  95. package/dist/WebService.d.ts +79 -11
  96. package/dist/WebService.js +320 -109
  97. package/dist/WebService.js.map +1 -1
  98. package/dist/WebhookMiddleware.d.ts +119 -0
  99. package/dist/WebhookMiddleware.js +271 -0
  100. package/dist/WebhookMiddleware.js.map +1 -0
  101. package/dist/WebhookValidator.d.ts +92 -0
  102. package/dist/WebhookValidator.js +409 -0
  103. package/dist/WebhookValidator.js.map +1 -0
  104. package/dist/agents/BedrockAgent.d.ts +162 -0
  105. package/dist/agents/BedrockAgent.js +323 -0
  106. package/dist/agents/BedrockAgent.js.map +1 -0
  107. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  108. package/dist/ai-chat/AIChatClient.js +535 -0
  109. package/dist/ai-chat/AIChatClient.js.map +1 -0
  110. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  111. package/dist/ai-chat/ChatGateway.js +747 -0
  112. package/dist/ai-chat/ChatGateway.js.map +1 -0
  113. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  114. package/dist/ai-chat/HandoffRouter.js +518 -0
  115. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  116. package/dist/ai-chat/index.d.ts +12 -0
  117. package/dist/ai-chat/index.js +10 -0
  118. package/dist/ai-chat/index.js.map +1 -0
  119. package/dist/capabilities.d.ts +64 -0
  120. package/dist/capabilities.js +95 -0
  121. package/dist/capabilities.js.map +1 -0
  122. package/dist/cli/agent-loader.d.ts +32 -6
  123. package/dist/cli/agent-loader.js +95 -34
  124. package/dist/cli/agent-loader.js.map +1 -1
  125. package/dist/cli/datamap-exec.d.ts +175 -0
  126. package/dist/cli/datamap-exec.js +1284 -0
  127. package/dist/cli/datamap-exec.js.map +1 -0
  128. package/dist/cli/function-args.d.ts +40 -0
  129. package/dist/cli/function-args.js +146 -0
  130. package/dist/cli/function-args.js.map +1 -0
  131. package/dist/cli/simulation.d.ts +99 -0
  132. package/dist/cli/simulation.js +490 -0
  133. package/dist/cli/simulation.js.map +1 -0
  134. package/dist/cli/swaig-test.d.ts +12 -25
  135. package/dist/cli/swaig-test.js +935 -367
  136. package/dist/cli/swaig-test.js.map +1 -1
  137. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  138. package/dist/cli/tsdocs/agentsNote.js +92 -0
  139. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  140. package/dist/cli/tsdocs/api-index.json +1 -0
  141. package/dist/cli/tsdocs/api.d.ts +91 -0
  142. package/dist/cli/tsdocs/api.js +372 -0
  143. package/dist/cli/tsdocs/api.js.map +1 -0
  144. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  145. package/dist/cli/tsdocs/apiTypes.js +7 -0
  146. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  147. package/dist/cli/tsdocs/bin.d.ts +6 -0
  148. package/dist/cli/tsdocs/bin.js +23 -0
  149. package/dist/cli/tsdocs/bin.js.map +1 -0
  150. package/dist/cli/tsdocs/files.d.ts +108 -0
  151. package/dist/cli/tsdocs/files.js +287 -0
  152. package/dist/cli/tsdocs/files.js.map +1 -0
  153. package/dist/cli/tsdocs/index.d.ts +28 -0
  154. package/dist/cli/tsdocs/index.js +307 -0
  155. package/dist/cli/tsdocs/index.js.map +1 -0
  156. package/dist/cli/tsdocs/live.d.ts +41 -0
  157. package/dist/cli/tsdocs/live.js +202 -0
  158. package/dist/cli/tsdocs/live.js.map +1 -0
  159. package/dist/cli/tsdocs/locate.d.ts +51 -0
  160. package/dist/cli/tsdocs/locate.js +75 -0
  161. package/dist/cli/tsdocs/locate.js.map +1 -0
  162. package/dist/cli/tsdocs/render.d.ts +75 -0
  163. package/dist/cli/tsdocs/render.js +323 -0
  164. package/dist/cli/tsdocs/render.js.map +1 -0
  165. package/dist/cli/tsdocs/topics.d.ts +43 -0
  166. package/dist/cli/tsdocs/topics.js +916 -0
  167. package/dist/cli/tsdocs/topics.js.map +1 -0
  168. package/dist/index.d.ts +102 -39
  169. package/dist/index.js +107 -30
  170. package/dist/index.js.map +1 -1
  171. package/dist/livewire/index.d.ts +229 -155
  172. package/dist/livewire/index.js +298 -195
  173. package/dist/livewire/index.js.map +1 -1
  174. package/dist/llms.txt +65 -0
  175. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  176. package/dist/prefabs/CallSessionStore.js +72 -0
  177. package/dist/prefabs/CallSessionStore.js.map +1 -0
  178. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  179. package/dist/prefabs/ConciergeAgent.js +36 -31
  180. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  181. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  182. package/dist/prefabs/FAQBotAgent.js +113 -47
  183. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  184. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  185. package/dist/prefabs/InfoGathererAgent.js +67 -58
  186. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  187. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  188. package/dist/prefabs/ReceptionistAgent.js +39 -31
  189. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  190. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  191. package/dist/prefabs/SurveyAgent.js +84 -68
  192. package/dist/prefabs/SurveyAgent.js.map +1 -1
  193. package/dist/relay/Action.d.ts +44 -21
  194. package/dist/relay/Action.js +75 -17
  195. package/dist/relay/Action.js.map +1 -1
  196. package/dist/relay/Call.d.ts +312 -47
  197. package/dist/relay/Call.js +369 -18
  198. package/dist/relay/Call.js.map +1 -1
  199. package/dist/relay/Deferred.js.map +1 -1
  200. package/dist/relay/Message.d.ts +26 -5
  201. package/dist/relay/Message.js +36 -6
  202. package/dist/relay/Message.js.map +1 -1
  203. package/dist/relay/RelayClient.d.ts +79 -14
  204. package/dist/relay/RelayClient.js +268 -61
  205. package/dist/relay/RelayClient.js.map +1 -1
  206. package/dist/relay/RelayError.d.ts +14 -0
  207. package/dist/relay/RelayError.js +15 -0
  208. package/dist/relay/RelayError.js.map +1 -1
  209. package/dist/relay/RelayEvent.d.ts +96 -65
  210. package/dist/relay/RelayEvent.js +85 -56
  211. package/dist/relay/RelayEvent.js.map +1 -1
  212. package/dist/relay/closedSets.d.ts +111 -0
  213. package/dist/relay/closedSets.js +83 -0
  214. package/dist/relay/closedSets.js.map +1 -0
  215. package/dist/relay/index.d.ts +3 -1
  216. package/dist/relay/index.js +1 -0
  217. package/dist/relay/index.js.map +1 -1
  218. package/dist/relay/normalize.js.map +1 -1
  219. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  220. package/dist/relay/protocol.types.generated.js +8 -0
  221. package/dist/relay/protocol.types.generated.js.map +1 -0
  222. package/dist/relay/types.d.ts +81 -39
  223. package/dist/rest/HttpClient.d.ts +36 -8
  224. package/dist/rest/HttpClient.js +233 -40
  225. package/dist/rest/HttpClient.js.map +1 -1
  226. package/dist/rest/RequestOptions.d.ts +110 -0
  227. package/dist/rest/RequestOptions.js +113 -0
  228. package/dist/rest/RequestOptions.js.map +1 -0
  229. package/dist/rest/RestError.d.ts +52 -6
  230. package/dist/rest/RestError.js +89 -5
  231. package/dist/rest/RestError.js.map +1 -1
  232. package/dist/rest/base/CrudResource.d.ts +16 -26
  233. package/dist/rest/base/CrudResource.js +19 -33
  234. package/dist/rest/base/CrudResource.js.map +1 -1
  235. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  236. package/dist/rest/base/CrudWithAddresses.js +2 -2
  237. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  238. package/dist/rest/base/FabricResource.d.ts +15 -0
  239. package/dist/rest/base/FabricResource.js +16 -0
  240. package/dist/rest/base/FabricResource.js.map +1 -0
  241. package/dist/rest/base/ReadResource.d.ts +62 -0
  242. package/dist/rest/base/ReadResource.js +69 -0
  243. package/dist/rest/base/ReadResource.js.map +1 -0
  244. package/dist/rest/callHandler.d.ts +63 -0
  245. package/dist/rest/callHandler.js +62 -0
  246. package/dist/rest/callHandler.js.map +1 -0
  247. package/dist/rest/index.d.ts +19 -76
  248. package/dist/rest/index.js +49 -120
  249. package/dist/rest/index.js.map +1 -1
  250. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  251. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  252. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  253. package/dist/rest/namespaces/addresses.d.ts +3 -42
  254. package/dist/rest/namespaces/addresses.js +3 -50
  255. package/dist/rest/namespaces/addresses.js.map +1 -1
  256. package/dist/rest/namespaces/calling.d.ts +6 -378
  257. package/dist/rest/namespaces/calling.js +6 -473
  258. package/dist/rest/namespaces/calling.js.map +1 -1
  259. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  260. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  261. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  262. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  263. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  264. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  265. package/dist/rest/namespaces/chat.d.ts +4 -18
  266. package/dist/rest/namespaces/chat.js +4 -21
  267. package/dist/rest/namespaces/chat.js.map +1 -1
  268. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  269. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  270. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  271. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  272. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  273. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  274. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  275. package/dist/rest/namespaces/datasphere.js +6 -72
  276. package/dist/rest/namespaces/datasphere.js.map +1 -1
  277. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  278. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  279. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  280. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  281. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  282. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  283. package/dist/rest/namespaces/fabric.d.ts +11 -273
  284. package/dist/rest/namespaces/fabric.js +14 -363
  285. package/dist/rest/namespaces/fabric.js.map +1 -1
  286. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  287. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  288. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  289. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  290. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  291. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  293. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  294. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  296. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  297. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  298. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  299. package/dist/rest/namespaces/imported-numbers.js +3 -21
  300. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  301. package/dist/rest/namespaces/logs.d.ts +10 -101
  302. package/dist/rest/namespaces/logs.js +10 -128
  303. package/dist/rest/namespaces/logs.js.map +1 -1
  304. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  305. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  306. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  307. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  308. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  309. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  310. package/dist/rest/namespaces/lookup.d.ts +3 -25
  311. package/dist/rest/namespaces/lookup.js +3 -27
  312. package/dist/rest/namespaces/lookup.js.map +1 -1
  313. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  314. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  315. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  316. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  317. package/dist/rest/namespaces/message.types.generated.js +8 -0
  318. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  319. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  320. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  321. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  323. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  324. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  325. package/dist/rest/namespaces/mfa.d.ts +3 -42
  326. package/dist/rest/namespaces/mfa.js +3 -49
  327. package/dist/rest/namespaces/mfa.js.map +1 -1
  328. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  329. package/dist/rest/namespaces/number-groups.js +3 -53
  330. package/dist/rest/namespaces/number-groups.js.map +1 -1
  331. package/dist/rest/namespaces/phone-numbers.d.ts +9 -57
  332. package/dist/rest/namespaces/phone-numbers.js +9 -63
  333. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  334. package/dist/rest/namespaces/project.d.ts +6 -42
  335. package/dist/rest/namespaces/project.js +6 -51
  336. package/dist/rest/namespaces/project.js.map +1 -1
  337. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  338. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  339. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  340. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  341. package/dist/rest/namespaces/project.types.generated.js +8 -0
  342. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  343. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  344. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  345. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  347. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  348. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  349. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  350. package/dist/rest/namespaces/pubsub.js +4 -21
  351. package/dist/rest/namespaces/pubsub.js.map +1 -1
  352. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  353. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  354. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  355. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  356. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  357. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  358. package/dist/rest/namespaces/queues.d.ts +3 -38
  359. package/dist/rest/namespaces/queues.js +3 -44
  360. package/dist/rest/namespaces/queues.js.map +1 -1
  361. package/dist/rest/namespaces/recordings.d.ts +3 -34
  362. package/dist/rest/namespaces/recordings.js +3 -40
  363. package/dist/rest/namespaces/recordings.js.map +1 -1
  364. package/dist/rest/namespaces/registry.d.ts +6 -137
  365. package/dist/rest/namespaces/registry.js +6 -173
  366. package/dist/rest/namespaces/registry.js.map +1 -1
  367. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  368. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  369. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  370. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  371. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  372. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  373. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  374. package/dist/rest/namespaces/short-codes.js +3 -41
  375. package/dist/rest/namespaces/short-codes.js.map +1 -1
  376. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  377. package/dist/rest/namespaces/sip-profile.js +3 -29
  378. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  379. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  380. package/dist/rest/namespaces/verified-callers.js +3 -34
  381. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  382. package/dist/rest/namespaces/video.d.ts +10 -227
  383. package/dist/rest/namespaces/video.js +10 -288
  384. package/dist/rest/namespaces/video.js.map +1 -1
  385. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  386. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  387. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  388. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  389. package/dist/rest/namespaces/video.types.generated.js +8 -0
  390. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  391. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  392. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  393. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  395. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  396. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  397. package/dist/rest/pagination.d.ts +5 -1
  398. package/dist/rest/pagination.js +40 -20
  399. package/dist/rest/pagination.js.map +1 -1
  400. package/dist/rest/types.d.ts +21 -3
  401. package/dist/schema.json +299 -98
  402. package/dist/skills/SkillBase.d.ts +97 -20
  403. package/dist/skills/SkillBase.js +100 -17
  404. package/dist/skills/SkillBase.js.map +1 -1
  405. package/dist/skills/SkillManager.d.ts +66 -13
  406. package/dist/skills/SkillManager.js +101 -20
  407. package/dist/skills/SkillManager.js.map +1 -1
  408. package/dist/skills/SkillName.d.ts +44 -0
  409. package/dist/skills/SkillName.js +2 -0
  410. package/dist/skills/SkillName.js.map +1 -0
  411. package/dist/skills/SkillRegistry.d.ts +47 -7
  412. package/dist/skills/SkillRegistry.js +85 -13
  413. package/dist/skills/SkillRegistry.js.map +1 -1
  414. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  415. package/dist/skills/builtin/api_ninjas_trivia.js +24 -8
  416. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  417. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  418. package/dist/skills/builtin/ask_claude.js +36 -14
  419. package/dist/skills/builtin/ask_claude.js.map +1 -1
  420. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  421. package/dist/skills/builtin/claude_skills.js +19 -15
  422. package/dist/skills/builtin/claude_skills.js.map +1 -1
  423. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  424. package/dist/skills/builtin/custom_skills.js +26 -9
  425. package/dist/skills/builtin/custom_skills.js.map +1 -1
  426. package/dist/skills/builtin/datasphere.d.ts +5 -3
  427. package/dist/skills/builtin/datasphere.js +34 -25
  428. package/dist/skills/builtin/datasphere.js.map +1 -1
  429. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  430. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  431. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  432. package/dist/skills/builtin/datetime.d.ts +3 -1
  433. package/dist/skills/builtin/datetime.js +11 -7
  434. package/dist/skills/builtin/datetime.js.map +1 -1
  435. package/dist/skills/builtin/google_maps.d.ts +29 -14
  436. package/dist/skills/builtin/google_maps.js +89 -269
  437. package/dist/skills/builtin/google_maps.js.map +1 -1
  438. package/dist/skills/builtin/index.d.ts +8 -6
  439. package/dist/skills/builtin/index.js +8 -6
  440. package/dist/skills/builtin/index.js.map +1 -1
  441. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  442. package/dist/skills/builtin/info_gatherer.js +20 -12
  443. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  444. package/dist/skills/builtin/joke.d.ts +16 -6
  445. package/dist/skills/builtin/joke.js +54 -37
  446. package/dist/skills/builtin/joke.js.map +1 -1
  447. package/dist/skills/builtin/math.d.ts +3 -1
  448. package/dist/skills/builtin/math.js +14 -9
  449. package/dist/skills/builtin/math.js.map +1 -1
  450. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  451. package/dist/skills/builtin/mcp_gateway.js +77 -46
  452. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  453. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  454. package/dist/skills/builtin/native_vector_search.js +179 -61
  455. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  456. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  457. package/dist/skills/builtin/play_background_file.js +43 -122
  458. package/dist/skills/builtin/play_background_file.js.map +1 -1
  459. package/dist/skills/builtin/spider.d.ts +46 -1
  460. package/dist/skills/builtin/spider.js +317 -101
  461. package/dist/skills/builtin/spider.js.map +1 -1
  462. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  463. package/dist/skills/builtin/swml_transfer.js +45 -24
  464. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  465. package/dist/skills/builtin/weather_api.d.ts +24 -13
  466. package/dist/skills/builtin/weather_api.js +57 -31
  467. package/dist/skills/builtin/weather_api.js.map +1 -1
  468. package/dist/skills/builtin/web_search.d.ts +48 -10
  469. package/dist/skills/builtin/web_search.js +301 -84
  470. package/dist/skills/builtin/web_search.js.map +1 -1
  471. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  472. package/dist/skills/builtin/wikipedia_search.js +32 -14
  473. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  474. package/dist/skills/index.d.ts +3 -2
  475. package/dist/skills/index.js +1 -1
  476. package/dist/skills/index.js.map +1 -1
  477. package/dist/swml_verbs_generated.d.ts +2824 -0
  478. package/dist/swml_verbs_generated.js +12 -0
  479. package/dist/swml_verbs_generated.js.map +1 -0
  480. package/dist/types.d.ts +65 -6
  481. package/dist/web.d.ts +27 -0
  482. package/dist/web.js +20 -0
  483. package/dist/web.js.map +1 -0
  484. package/docs/agent-guide.md +1034 -0
  485. package/docs/ai_chat.md +560 -0
  486. package/docs/api-reference.md +3534 -0
  487. package/docs/architecture.md +846 -0
  488. package/docs/bedrock_agent.md +411 -0
  489. package/docs/cli-guide.md +403 -0
  490. package/docs/cloud_functions_guide.md +399 -0
  491. package/docs/configuration.md +548 -0
  492. package/docs/contexts-guide.md +884 -0
  493. package/docs/datamap-guide.md +1160 -0
  494. package/docs/developer_pain_points.md +548 -0
  495. package/docs/llm_parameters.md +298 -0
  496. package/docs/mcp_gateway_reference.md +354 -0
  497. package/docs/mcp_integration.md +162 -0
  498. package/docs/pgi_agent_guide.md +1820 -0
  499. package/docs/prefabs-guide.md +815 -0
  500. package/docs/programmatically_governed_inference.md +301 -0
  501. package/docs/sdk_features.md +501 -0
  502. package/docs/security.md +559 -0
  503. package/docs/serverless-guide.md +520 -0
  504. package/docs/skills-guide.md +1223 -0
  505. package/docs/skills-system.md +405 -0
  506. package/docs/skills_parameter_schema.md +417 -0
  507. package/docs/swaig-reference.md +1938 -0
  508. package/docs/swml_service_guide.md +573 -0
  509. package/docs/third_party_skills.md +410 -0
  510. package/docs/web_service.md +666 -0
  511. package/examples/README.md +202 -0
  512. package/examples/advanced-datamap.ts +108 -0
  513. package/examples/advanced-dynamic-config.ts +70 -0
  514. package/examples/auto-vivified.ts +95 -0
  515. package/examples/call-flow.ts +65 -0
  516. package/examples/comprehensive-dynamic.ts +125 -0
  517. package/examples/contexts-steps.ts +65 -0
  518. package/examples/custom-path.ts +45 -0
  519. package/examples/datamap-tools.ts +51 -0
  520. package/examples/datasphere-multi-instance.ts +66 -0
  521. package/examples/datasphere-serverless-env.ts +87 -0
  522. package/examples/datasphere-webhook-env.ts +65 -0
  523. package/examples/datasphere.ts +56 -0
  524. package/examples/declarative.ts +100 -0
  525. package/examples/dynamic-config.ts +54 -0
  526. package/examples/dynamic-info-gatherer.ts +69 -0
  527. package/examples/dynamic-swml-service.ts +67 -0
  528. package/examples/gather-info.ts +95 -0
  529. package/examples/gather-per-question-functions-demo.ts +139 -0
  530. package/examples/joke-agent.ts +34 -0
  531. package/examples/kubernetes-agent.ts +45 -0
  532. package/examples/llm-params.ts +75 -0
  533. package/examples/mcp-agent.ts +89 -0
  534. package/examples/mcp-gateway.ts +81 -0
  535. package/examples/multi-agent.ts +80 -0
  536. package/examples/multi-endpoint.ts +79 -0
  537. package/examples/pgi/case-domain.ts +114 -0
  538. package/examples/pgi/serve.ts +16 -0
  539. package/examples/pgi/support-agent.ts +265 -0
  540. package/examples/pom-prompt.ts +70 -0
  541. package/examples/prefab-concierge.ts +42 -0
  542. package/examples/prefab-faq.ts +58 -0
  543. package/examples/prefab-info-gatherer.ts +33 -0
  544. package/examples/prefab-receptionist.ts +36 -0
  545. package/examples/prefab-survey.ts +69 -0
  546. package/examples/quickstart-agent.ts +29 -0
  547. package/examples/quickstart-relay.ts +25 -0
  548. package/examples/quickstart-rest.ts +25 -0
  549. package/examples/record-call.ts +65 -0
  550. package/examples/relay-demo.ts +33 -0
  551. package/examples/room-and-sip.ts +93 -0
  552. package/examples/serverless-lambda.ts +43 -0
  553. package/examples/session-state.ts +83 -0
  554. package/examples/simple-agent.ts +36 -0
  555. package/examples/simple-static.ts +29 -0
  556. package/examples/skills-demo.ts +41 -0
  557. package/examples/step-function-inheritance-demo.ts +124 -0
  558. package/examples/swaig-features.ts +193 -0
  559. package/examples/swml-service-routing.ts +66 -0
  560. package/examples/swml-service.ts +38 -0
  561. package/examples/swmlservice_ai_sidecar.ts +104 -0
  562. package/examples/swmlservice_swaig_standalone.ts +79 -0
  563. package/examples/tap.ts +67 -0
  564. package/examples/typed-tools.ts +68 -0
  565. package/examples/verb-methods.ts +45 -0
  566. package/examples/web-search-multi-instance.ts +75 -0
  567. package/examples/web-search.ts +38 -0
  568. package/examples/wikipedia.ts +36 -0
  569. package/livewire/README.md +164 -0
  570. package/livewire/docs/migration-guide.md +251 -0
  571. package/livewire/examples/livewire-basic-agent.ts +74 -0
  572. package/livewire/examples/livewire-handoff.ts +196 -0
  573. package/livewire/examples/livewire-multi-tool.ts +121 -0
  574. package/package.json +88 -13
  575. package/relay/README.md +101 -0
  576. package/relay/docs/call-methods.md +622 -0
  577. package/relay/docs/client-reference.md +281 -0
  578. package/relay/docs/events.md +193 -0
  579. package/relay/docs/getting-started.md +221 -0
  580. package/relay/docs/guide.md +386 -0
  581. package/relay/docs/messaging.md +246 -0
  582. package/relay/examples/relay-inbound.ts +66 -0
  583. package/relay/examples/relay-messaging.ts +74 -0
  584. package/relay/examples/relay-outbound.ts +76 -0
  585. package/rest/README.md +141 -0
  586. package/rest/docs/calling.md +313 -0
  587. package/rest/docs/client-reference.md +149 -0
  588. package/rest/docs/fabric.md +192 -0
  589. package/rest/docs/getting-started.md +138 -0
  590. package/rest/docs/guide.md +421 -0
  591. package/rest/docs/namespaces.md +367 -0
  592. package/rest/docs/phone-binding.md +116 -0
  593. package/rest/examples/rest-10dlc-registration.ts +177 -0
  594. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  595. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  596. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  597. package/rest/examples/rest-client.ts +59 -0
  598. package/rest/examples/rest-datasphere-search.ts +81 -0
  599. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  600. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  601. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  602. package/rest/examples/rest-manage-resources.ts +64 -0
  603. package/rest/examples/rest-phone-number-management.ts +200 -0
  604. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  605. package/rest/examples/rest-video-rooms.ts +186 -0
  606. package/tutorial/fred/fred.ts +218 -0
  607. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  608. package/tutorial/fred/tutorial/02-setup.md +304 -0
  609. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  610. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  611. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  612. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  613. package/tutorial/fred/tutorial/README.md +56 -0
  614. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  615. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  616. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  617. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  618. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  619. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  620. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  621. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  622. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  623. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  624. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  625. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  626. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  627. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  628. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  629. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  630. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  631. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  632. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  633. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  634. package/tutorial/multi_agents/README.md +175 -0
  635. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  636. package/tutorial/multi_agents/extending_agents.ts +641 -0
  637. package/tutorial/multi_agents/knowledge.ts +59 -0
  638. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  639. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  640. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  641. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  642. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  643. package/tutorial/multi_agents/pc_builder.ts +529 -0
  644. package/tutorial/multi_agents/sales_agent.ts +88 -0
  645. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  646. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  647. package/tutorial/multi_agents/support_knowledge.md +256 -0
  648. package/dist/cli/mock-data.d.ts +0 -37
  649. package/dist/cli/mock-data.js +0 -80
  650. package/dist/cli/mock-data.js.map +0 -1
  651. package/dist/generateVerbTypes.d.ts +0 -11
  652. package/dist/generateVerbTypes.js +0 -265
  653. package/dist/generateVerbTypes.js.map +0 -1
  654. package/dist/rest/namespaces/compat.d.ts +0 -585
  655. package/dist/rest/namespaces/compat.js +0 -735
  656. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,467 @@
1
+ # Lesson 6: Tools That Decide
2
+
3
+ The steps decide what the model can ask for. The handlers in `handlers.ts` decide what actually happens. Each one asks the reservation book to do something, then reports back to two different audiences.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [Tool Descriptions Are Prompts](#tool-descriptions-are-prompts)
8
+ 2. [Two Audiences: the Model and the Platform](#two-audiences-the-model-and-the-platform)
9
+ 3. [A Guard Around Every Handler](#a-guard-around-every-handler)
10
+ 4. [Router Tools](#router-tools)
11
+ 5. [Finding, Holding and Confirming](#finding-holding-and-confirming)
12
+ 6. [The Rules for `global_data`](#the-rules-for-global_data)
13
+ 7. [Try It: a Booking From the Command Line](#try-it-a-booking-from-the-command-line)
14
+
15
+ ---
16
+
17
+ ## Tool Descriptions Are Prompts
18
+
19
+ Every tool is registered once, in `registerTools` in `penny.ts`:
20
+
21
+ <!-- include: tutorial/full-guardrails-agent/penny.ts#tools --> <!-- snippet: no-compile a method of Penny, excerpted from penny.ts -->
22
+ ```typescript
23
+ /** Every tool the agent has. Which ones the model sees is decided per step. */
24
+ private registerTools(h: PennyHandlers): void {
25
+ const revision = {
26
+ type: 'integer',
27
+ minimum: 1,
28
+ description: 'The revision number from the proposal the caller agreed to.',
29
+ };
30
+ const checking = { 'en-US': ['Let me check the book.', 'One moment while I look.'] };
31
+
32
+ this.defineTool({
33
+ name: 'start_booking',
34
+ description: 'Start taking a new reservation.',
35
+ handler: h.startBooking,
36
+ });
37
+ this.defineTool({
38
+ name: 'manage_booking',
39
+ description:
40
+ "Start looking up the caller's existing reservation. It does not " +
41
+ 'reveal anything until the caller verifies it.',
42
+ handler: h.manageBooking,
43
+ });
44
+ this.defineTool({
45
+ name: 'house_info',
46
+ description: 'Look up a fact about the restaurant.',
47
+ parameters: { topic: { type: 'string', enum: Object.keys(HOUSE_FACTS).sort() } },
48
+ required: ['topic'],
49
+ handler: h.houseInfo,
50
+ });
51
+ this.defineTool({
52
+ name: 'find_tables',
53
+ description:
54
+ 'Check which seatings are free, using the details the caller already gave. ' +
55
+ 'Pass only a detail the caller has changed. Holds and books nothing.',
56
+ parameters: {
57
+ party_size: {
58
+ type: 'integer',
59
+ minimum: 1,
60
+ maximum: 20,
61
+ description: 'Only if the caller changed the party size.',
62
+ },
63
+ date: {
64
+ type: 'string',
65
+ description: "Only if the caller changed the date, in their own words, e.g. 'Saturday'.",
66
+ },
67
+ time: {
68
+ type: 'string',
69
+ description: "Only if the caller changed the time, e.g. '8:00 PM'.",
70
+ },
71
+ name: { type: 'string', description: 'Only if the caller changed the name.' },
72
+ },
73
+ fillers: checking,
74
+ handler: h.findTables,
75
+ });
76
+ this.defineTool({
77
+ name: 'hold_table',
78
+ description: 'Hold the option the caller picked for five minutes. Does not book it.',
79
+ parameters: {
80
+ option: {
81
+ type: 'integer',
82
+ minimum: 1,
83
+ maximum: 3,
84
+ description: 'The option number the caller chose.',
85
+ },
86
+ },
87
+ required: ['option'],
88
+ handler: h.holdTable,
89
+ });
90
+ this.defineTool({
91
+ name: 'confirm_booking',
92
+ description:
93
+ 'Book the table on hold, only after the caller agreed to the proposal you read back.',
94
+ parameters: { revision },
95
+ required: ['revision'],
96
+ fillers: checking,
97
+ handler: h.confirmBooking,
98
+ });
99
+ this.defineTool({
100
+ name: 'send_confirmation_text',
101
+ description: 'Text the confirmed reservation to the number this call comes from.',
102
+ handler: h.sendConfirmationText,
103
+ });
104
+ this.defineTool({
105
+ name: 'verify_reservation',
106
+ description: 'Check a confirmation code and last name. Only a match unlocks the reservation.',
107
+ parameters: {
108
+ confirmation_code: {
109
+ type: 'string',
110
+ description: 'The six characters the caller read out.',
111
+ },
112
+ last_name: { type: 'string', description: "The caller's last name." },
113
+ },
114
+ required: ['confirmation_code', 'last_name'],
115
+ fillers: checking,
116
+ handler: h.verifyReservation,
117
+ });
118
+ this.defineTool({
119
+ name: 'request_cancel',
120
+ description: 'Prepare to cancel the verified reservation. Cancels nothing yet.',
121
+ handler: h.requestCancel,
122
+ });
123
+ this.defineTool({
124
+ name: 'confirm_cancel',
125
+ description:
126
+ 'Cancel the verified reservation, only after the caller said yes to ' +
127
+ 'the cancellation you read back.',
128
+ parameters: { revision },
129
+ required: ['revision'],
130
+ handler: h.confirmCancel,
131
+ });
132
+ this.defineTool({
133
+ name: 'keep_reservation',
134
+ description: 'Abandon the cancellation and keep the reservation.',
135
+ handler: h.keepReservation,
136
+ });
137
+ this.defineTool({
138
+ name: 'request_human',
139
+ description:
140
+ 'Connect the caller with a person at the host stand, or take a message ' +
141
+ 'if nobody is there.',
142
+ handler: h.requestHuman,
143
+ });
144
+ this.defineTool({
145
+ name: 'save_message',
146
+ description:
147
+ 'Save the message just taken for the host stand. Pass a detail only to correct it.',
148
+ parameters: {
149
+ name: { type: 'string' },
150
+ callback: { type: 'string' },
151
+ body: { type: 'string' },
152
+ },
153
+ handler: h.saveMessage,
154
+ });
155
+ this.defineTool({
156
+ name: 'finish',
157
+ description: 'Say goodbye and end the call.',
158
+ handler: h.finish,
159
+ });
160
+ }
161
+ ```
162
+
163
+ Each `defineTool()` call names the tool the model sees, in snake case, and the handler that runs it. `parameters` holds each argument's JSON Schema, and `required` lists the ones the model must pass.
164
+
165
+ The platform sends each tool's description and parameters to the model on every turn. That makes them prompt text, and three habits keep them accurate:
166
+
167
+ - **Say what the tool doesn't do.** `find_tables` "holds and books nothing". `hold_table` "does not book it". `request_cancel` "cancels nothing yet". A model that knows a tool is harmless won't hesitate to use it, and won't mistake it for the final step.
168
+ - **Constrain arguments in the schema.** `house_info` takes a `topic` from a fixed `enum`, and `hold_table` takes an option from 1 to 3.
169
+ - **Cover the wait with fillers.** `find_tables`, `confirm_booking` and `verify_reservation` have short phrases the platform can say while the handler works, so the caller doesn't hear silence.
170
+
171
+ A schema limit helps the model ask correctly. It is not a check. Every handler validates its arguments again, because schemas are guidance too.
172
+
173
+ ## Two Audiences: the Model and the Platform
174
+
175
+ A `FunctionResult` reaches two audiences, the model and the platform, through three parts:
176
+
177
+ | Part | Audience | Penny uses it for |
178
+ |---|---|---|
179
+ | `tool_result` | The model | What is true: "On hold for five minutes: a table for 4 on Friday, October 2 at 7:30 PM..." |
180
+ | `tool_prompt` | The model | What to do now: "Read the proposal back and ask the caller to confirm it." |
181
+ | Actions | The platform | What happens regardless of what the model says: change step, update session data, send UI events, say, transfer, hang up |
182
+
183
+ Penny passes the first two to the constructor as one object, `new FunctionResult({ tool_result, tool_prompt })`, and chains the actions after it. Keeping the parts separate matters. If the facts and the instructions share one string, the model may read the instructions aloud, or treat the facts as a suggestion. Actions don't rely on the model at all: when `confirm_booking` returns `swmlChangeStep('booked')`, the conversation moves whether or not the model mentions it.
184
+
185
+ ## A Guard Around Every Handler
186
+
187
+ Every handler is wrapped in `guarded`:
188
+
189
+ <!-- include: tutorial/full-guardrails-agent/handlers.ts#guarded --> <!-- snippet: no-compile an excerpt of handlers.ts that uses its own types and log -->
190
+ ```typescript
191
+ /** Turn refusals into facts for the model, and never let a crash sound like success. */
192
+ export function guarded(name: string, handler: Handler): Handler {
193
+ return (args, rawData) => {
194
+ try {
195
+ if (!isObject(args) || !isObject(rawData)) {
196
+ throw new PolicyError('The request was malformed.', 'Ask the caller to say that again.');
197
+ }
198
+ return handler(args, rawData);
199
+ } catch (err) {
200
+ if (err instanceof PolicyError) {
201
+ return new FunctionResult({ tool_result: err.fact, tool_prompt: err.ask });
202
+ }
203
+ if (err instanceof MissingCallContext) {
204
+ return new FunctionResult({
205
+ tool_result: 'Nothing was done: the request had no call context.',
206
+ tool_prompt: 'Apologize and offer to take a message.',
207
+ });
208
+ }
209
+ log.error(`tool ${name} failed: ${err instanceof Error ? err.stack : String(err)}`);
210
+ return new FunctionResult({
211
+ tool_result: "The system couldn't finish that, so the outcome is unknown.",
212
+ tool_prompt: "Don't say it worked. Apologize and offer to try again.",
213
+ });
214
+ }
215
+ };
216
+ }
217
+ ```
218
+
219
+ It enforces three failure rules:
220
+
221
+ - **A refusal is a fact, not an error.** A `PolicyError` from the reservation book becomes `tool_result` and `tool_prompt`, with no actions attached.
222
+ - **No call context, no action.** A request without a `call_id` can't be tied to a session, so nothing happens.
223
+ - **A crash is never success.** Anything unexpected becomes "the outcome is unknown", with the instruction "Don't say it worked." The worst failure for a booking system is an agent telling the caller "you're all set" when nothing was saved.
224
+
225
+ The SDK catches a handler that throws, too, and answers with a generic apology. `guarded` replaces that with words written for this agent, and logs the stack under the tool's name.
226
+
227
+ TypeScript has no decorators on plain functions, so `guarded` is a function that takes a handler and returns a guarded one. Each handler is a class field built with it, such as `readonly findTables = guarded('find_tables', ...)`. An arrow function in a class field keeps `this`, so `registerTools` can pass `h.findTables` to `defineTool()` as it is.
228
+
229
+ ## Router Tools
230
+
231
+ `start_booking` is the router tool for a new reservation:
232
+
233
+ <!-- include: tutorial/full-guardrails-agent/handlers.ts#start-booking --> <!-- snippet: no-compile a class field of PennyHandlers, excerpted from handlers.ts -->
234
+ ```typescript
235
+ readonly startBooking = guarded('start_booking', (_args, rawData) => {
236
+ this.store.resetRequest(callIdOf(rawData));
237
+ return new FunctionResult({
238
+ tool_result: 'A new reservation has been started.',
239
+ tool_prompt: "Tell the caller you'll take a few details.",
240
+ })
241
+ .updateGlobalData({ booking: {}, booking_request: {} })
242
+ .swmlChangeContext('booking');
243
+ });
244
+ ```
245
+
246
+ A router tool moves the conversation and resets what the next context depends on. Here, `resetRequest` clears the call's draft, offers and holds in the reservation book. The `updateGlobalData()` action clears the booking projection and the gathered answers, so a new booking starts clean.
247
+
248
+ ## Finding, Holding and Confirming
249
+
250
+ `find_tables` applies any correction to the call's booking request, then asks the reservation book for numbered options:
251
+
252
+ <!-- include: tutorial/full-guardrails-agent/handlers.ts#find-tables --> <!-- snippet: no-compile a class field of PennyHandlers, excerpted from handlers.ts -->
253
+ ```typescript
254
+ readonly findTables = guarded('find_tables', (args, rawData) => {
255
+ const callId = callIdOf(rawData);
256
+ // What the caller has asked for: gather's answers, changed by every
257
+ // correction since. A correction passed as an argument changes only
258
+ // that detail, even if the last search was refused.
259
+ const draft = this.store.updateDraft(callId, args, gathered(rawData, 'booking_request'));
260
+ let request, options;
261
+ try {
262
+ [request, options] = this.store.findOptions(
263
+ callId,
264
+ draft.party_size,
265
+ draft.date,
266
+ draft.time,
267
+ draft.name,
268
+ );
269
+ } catch (err) {
270
+ if (!(err instanceof LargePartyError)) throw err;
271
+ return new FunctionResult({ tool_result: err.fact, tool_prompt: err.ask });
272
+ }
273
+
274
+ let result: FunctionResult;
275
+ if (options.length > 0) {
276
+ const listed = options.map((option) => option.spoken()).join('; ');
277
+ result = new FunctionResult({
278
+ tool_result: `Open for ${request.partySize} on ${spokenDate(request.day)}: ${listed}.`,
279
+ tool_prompt:
280
+ 'Offer these options by number. When the caller picks one, ' +
281
+ 'call hold_table with its number.',
282
+ });
283
+ } else {
284
+ result = new FunctionResult({
285
+ tool_result:
286
+ `Nothing is open for ${request.partySize} on ${spokenDate(request.day)} ` +
287
+ `within an hour of ${spokenTime(request.start)}. Seatings run 5 PM to 8:30 PM.`,
288
+ tool_prompt:
289
+ 'Say so, and ask whether another time or date would work. ' +
290
+ 'Then call find_tables with only what changed.',
291
+ });
292
+ }
293
+ return result
294
+ .updateGlobalData({ booking: { request: request.spoken() } })
295
+ .swmlChangeStep('choose')
296
+ .swmlUserEvent({
297
+ type: 'options_offered',
298
+ day: request.day,
299
+ options: options.map((o) => ({ number: o.number, time: spokenTime(o.start) })),
300
+ });
301
+ });
302
+ ```
303
+
304
+ Three details matter:
305
+
306
+ - **A correction changes one detail.** If the caller says "actually, make it 8", the model passes only `time`. Everything else stays as the caller last gave it, even after a refused search.
307
+ - **The large-party refusal carries no step change.** The model stays put and offers a person, which is the refusal's `ask`.
308
+ - **The model sees option numbers and times, never tables.** The UI event carries the same.
309
+
310
+ The reservation book keeps the request as a draft for each call:
311
+
312
+ <!-- include: tutorial/full-guardrails-agent/reservations.ts#update-draft --> <!-- snippet: no-compile a method of ReservationStore, excerpted from reservations.ts -->
313
+ ```typescript
314
+ /**
315
+ * Apply a correction to what this call has asked for, and return the result.
316
+ *
317
+ * The draft is kept whether or not a search passes the rules, so a correction
318
+ * to a refused search isn't lost. The first search starts from `gathered`.
319
+ */
320
+ updateDraft(
321
+ callId: string,
322
+ changes: Record<string, unknown>,
323
+ gathered: Record<string, unknown>,
324
+ ): Draft {
325
+ return this.tx((db) => {
326
+ let draft = JSON.parse(this.session(db, callId).draft) as Draft;
327
+ if (Object.keys(draft).length === 0) {
328
+ draft = Object.fromEntries(DRAFT_KEYS.map((key) => [key, gathered[key] ?? null])) as Draft;
329
+ }
330
+ for (const key of DRAFT_KEYS) {
331
+ if (!isBlank(changes[key])) draft[key] = changes[key];
332
+ }
333
+ db.prepare('UPDATE sessions SET draft=? WHERE call_id=?').run(JSON.stringify(draft), callId);
334
+ return draft;
335
+ });
336
+ }
337
+ ```
338
+
339
+ The first search starts from the gathered answers, and each correction updates the draft. The draft is saved before the search checks the rules, so a refused search doesn't lose the correction. Suppose gather collected a party of eight for Monday. The caller changes it to four, hears that the restaurant is closed on Mondays, and says "Friday, then". The next search is for four on Friday, not eight.
340
+
341
+ `hold_table` turns an option into a numbered proposal:
342
+
343
+ <!-- include: tutorial/full-guardrails-agent/handlers.ts#hold-table --> <!-- snippet: no-compile a class field of PennyHandlers, excerpted from handlers.ts -->
344
+ ```typescript
345
+ readonly holdTable = guarded('hold_table', (args, rawData) => {
346
+ const callId = callIdOf(rawData);
347
+ const proposal = this.store.holdOption(callId, args['option']);
348
+ return new FunctionResult({
349
+ tool_result:
350
+ `On hold for five minutes: ${proposal.spoken()}. ` +
351
+ `This is proposal revision ${proposal.revision}.`,
352
+ tool_prompt:
353
+ 'Read the proposal back and ask the caller to confirm it. ' +
354
+ `If they clearly say yes, call confirm_booking with revision ${proposal.revision}. ` +
355
+ 'If they want a change, call find_tables with only what changed.',
356
+ })
357
+ .updateGlobalData({
358
+ booking: { proposal: proposal.spoken(), revision: proposal.revision },
359
+ })
360
+ .swmlChangeStep('review')
361
+ .swmlUserEvent({
362
+ type: 'table_held',
363
+ revision: proposal.revision,
364
+ day: proposal.day,
365
+ time: spokenTime(proposal.start),
366
+ party_size: proposal.partySize,
367
+ });
368
+ });
369
+ ```
370
+
371
+ The revision number goes to the model in both `tool_result` and `tool_prompt`, so it has the exact number to pass to `confirm_booking`.
372
+
373
+ `confirm_booking` commits the proposal:
374
+
375
+ <!-- include: tutorial/full-guardrails-agent/handlers.ts#confirm-booking --> <!-- snippet: no-compile a class field of PennyHandlers, excerpted from handlers.ts -->
376
+ ```typescript
377
+ readonly confirmBooking = guarded('confirm_booking', (args, rawData) => {
378
+ const callId = callIdOf(rawData);
379
+ const booking = this.store.confirm(callId, args['revision']);
380
+ const code = spokenCode(booking.code);
381
+ return new FunctionResult({
382
+ tool_result: `Confirmed: ${booking.spoken()}. Confirmation code: ${code}.`,
383
+ tool_prompt:
384
+ "Tell the caller it's booked and read the confirmation code " +
385
+ 'slowly, one character at a time. Then offer to text the details.',
386
+ })
387
+ .updateGlobalData({ booking: { summary: booking.spoken(), code_spoken: code } })
388
+ .swmlChangeStep('booked')
389
+ .swmlUserEvent({
390
+ type: 'booking_confirmed',
391
+ code: booking.code,
392
+ day: booking.day,
393
+ time: spokenTime(booking.start),
394
+ party_size: booking.partySize,
395
+ });
396
+ });
397
+ ```
398
+
399
+ The confirmation code comes from the reservation book. Code spells it out ("K 7 Q P 4 M") so the voice reads one character at a time. The code is also projected into the `booked` step's text, so it's still there after the conversation moves on.
400
+
401
+ ## The Rules for `global_data`
402
+
403
+ Penny's handlers follow four rules for session data:
404
+
405
+ 1. **It's a projection, not the truth.** The reservation book holds the truth. `global_data` holds the few finished facts a step's text needs, like the booking summary and the spoken code.
406
+ 2. **Write whole namespaces.** `updateGlobalData()` merges keys at the top level. Each handler writes its whole `booking` or `manage` object, never a piece of one, so the value is always complete and self-consistent.
407
+ 3. **Gathered answers are caller input.** What gather mode stores is what the caller said, and it's validated like any other input.
408
+ 4. **Don't rely on another tool's write in the same turn.** Two tools called in one turn start from the same snapshot, so a handler can't see what another tool wrote in that turn.
409
+
410
+ UI events are another projection, for a screen instead of the model. Penny emits `options_offered`, `table_held`, `booking_confirmed`, `reservation_verified`, `reservation_cancelled` and `message_taken`. A web page can react to them without parsing speech.
411
+
412
+ ## Try It: a Booking From the Command Line
413
+
414
+ `swaig-test` runs a tool handler directly, with no call. Because Penny keeps its state in the reservation book, keyed by call ID, you can walk through a whole booking in separate commands. Keep the variables from Lesson 4 exported, and put this walkthrough's book in its own file:
415
+
416
+ ```bash
417
+ export PENNY_DB_PATH=tutorial/full-guardrails-agent/walkthrough.sqlite3
418
+ npx tsx src/cli/swaig-test.ts tutorial/full-guardrails-agent/penny.ts --call-id demo-1 --exec find_tables --party_size 4 --date Friday --time "7:30 PM" --name "Maria Rivera"
419
+ npx tsx src/cli/swaig-test.ts tutorial/full-guardrails-agent/penny.ts --call-id demo-1 --exec hold_table --option 1
420
+ npx tsx src/cli/swaig-test.ts tutorial/full-guardrails-agent/penny.ts --call-id demo-1 --exec confirm_booking --revision 1
421
+ ```
422
+
423
+ Each command prints the response, then the actions. These are the three responses. Your dates will follow your calendar, and your confirmation code will differ:
424
+
425
+ ```text
426
+ Response: {"tool_result":"Open for 4 on Friday, October 2: option 1, 7:30 PM; option 2, 7 PM; option 3, 8 PM.","tool_prompt":"Offer these options by number. When the caller picks one, call hold_table with its number."}
427
+ Response: {"tool_result":"On hold for five minutes: a table for 4 on Friday, October 2 at 7:30 PM, under Maria Rivera. This is proposal revision 1.","tool_prompt":"Read the proposal back and ask the caller to confirm it. If they clearly say yes, call confirm_booking with revision 1. If they want a change, call find_tables with only what changed."}
428
+ Response: {"tool_result":"Confirmed: a table for 4 on Friday, October 2 at 7:30 PM, under Maria Rivera. Confirmation code: Q V C A 4 R.","tool_prompt":"Tell the caller it's booked and read the confirmation code slowly, one character at a time. Then offer to text the details."}
429
+ ```
430
+
431
+ Now try the things a confused model might do:
432
+
433
+ ```bash
434
+ # Confirm again: the same booking comes back, and no second one is made
435
+ npx tsx src/cli/swaig-test.ts tutorial/full-guardrails-agent/penny.ts --call-id demo-1 --exec confirm_booking --revision 1
436
+ # Confirm from a different call: that call holds nothing
437
+ npx tsx src/cli/swaig-test.ts tutorial/full-guardrails-agent/penny.ts --call-id demo-2 --exec confirm_booking --revision 1
438
+ ```
439
+
440
+ The first repeats the confirmation with the same code. The second gets a refusal and no actions:
441
+
442
+ ```text
443
+ Response: {"tool_result":"No table is on hold.","tool_prompt":"Check availability again."}
444
+ ```
445
+
446
+ A call can only confirm its own proposal.
447
+
448
+ ## Key Takeaways
449
+
450
+ - Tool descriptions are prompts: say what each tool does *not* do
451
+ - Keep facts (`tool_result`), instructions (`tool_prompt`) and actions separate
452
+ - Guard every handler: refusals are facts, and failures are never success
453
+ - `global_data` is a projection. The reservation book is the truth.
454
+
455
+ ## Review Questions
456
+
457
+ 1. Why does `confirm_booking` change the step with an action instead of telling the model to move on?
458
+ 2. What does the caller hear if the database is down when they confirm?
459
+ 3. Why does `find_tables` let arguments override the gathered answers?
460
+
461
+ ## Next Steps
462
+
463
+ The `search` step expects gathered answers to be waiting. Next, build the step that gathers them, and see how facts reach the model's instructions. Continue with [Lesson 7: Gather Mode and Projection](07-gather-and-projection.md).
464
+
465
+ ---
466
+
467
+ [Previous: Steps and Scoping](05-steps-and-scoping.md) | [Overview](README.md) | [Next: Gather Mode and Projection](07-gather-and-projection.md)
@@ -0,0 +1,160 @@
1
+ # Lesson 7: Gather Mode and Projection
2
+
3
+ This lesson covers two techniques. **Gather mode** collects structured details one question at a time, without the model skipping, reordering or inventing answers. **Projection** puts exactly the facts a step needs into its instructions, and nothing else.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [Why Use Gather Mode](#why-use-gather-mode)
8
+ 2. [The Booking Gather](#the-booking-gather)
9
+ 3. [What Gather Mode Locks Down](#what-gather-mode-locks-down)
10
+ 4. [Gathered Answers Are Still Caller Input](#gathered-answers-are-still-caller-input)
11
+ 5. [Projecting Facts Per Call](#projecting-facts-per-call)
12
+ 6. [Projecting Facts Into a Step](#projecting-facts-into-a-step)
13
+ 7. [How Much History the Model Sees](#how-much-history-the-model-sees)
14
+
15
+ ---
16
+
17
+ ## Why Use Gather Mode
18
+
19
+ A step that says "get the party size, date, time and name" invites trouble. The model might ask all four at once, skip one it thinks it can infer, or fill in "tonight" because the caller mentioned dinner. Each answer would also arrive as a tool call, cluttering the history the model reasons from.
20
+
21
+ Gather mode avoids these problems. The platform presents one question at a time, and the model submits each answer with a built-in `gather_submit` tool before it sees the next question.
22
+
23
+ ## The Booking Gather
24
+
25
+ This is the `collect` step from `workflow.ts`:
26
+
27
+ <!-- include: tutorial/full-guardrails-agent/workflow.ts#collect --> <!-- snippet: no-compile an excerpt of addBooking in workflow.ts -->
28
+ ```typescript
29
+ // Gather mode asks one question at a time and stores the answers under
30
+ // global_data.booking_request. While it runs, the only tools are
31
+ // gather_submit and the tools each question lists.
32
+ const collect = scoped(ctx.addStep('collect'), 'Take the reservation details.', []);
33
+ collect.setGatherInfo({
34
+ outputKey: 'booking_request',
35
+ completionAction: 'search',
36
+ prompt: "You're taking a reservation. Ask each question in turn, briefly.",
37
+ });
38
+ collect.addGatherQuestion({
39
+ key: 'party_size',
40
+ question: 'How many people will be dining?',
41
+ type: 'integer',
42
+ functions: LOOKUPS,
43
+ });
44
+ collect.addGatherQuestion({
45
+ key: 'date',
46
+ question: 'What date would you like?',
47
+ functions: LOOKUPS,
48
+ prompt:
49
+ "Submit the caller's own words for the date, such as 'Friday' or " +
50
+ "'the 26th'. Do not turn it into a calendar date yourself.",
51
+ });
52
+ collect.addGatherQuestion({
53
+ key: 'time',
54
+ question: 'What time would you like?',
55
+ functions: LOOKUPS,
56
+ prompt: "Submit the time in digits, such as '7:30 PM'.",
57
+ });
58
+ collect.addGatherQuestion({
59
+ key: 'name',
60
+ question: 'What name should the reservation be under?',
61
+ confirm: true,
62
+ functions: LOOKUPS,
63
+ });
64
+ ```
65
+
66
+ Six settings do the work:
67
+
68
+ - **`outputKey`**: the answers are stored in `global_data.booking_request`, where `find_tables` reads them
69
+ - **`completionAction`**: when the last answer is in, the platform moves to the `search` step. No tool is needed and the model doesn't choose.
70
+ - **`type: 'integer'`**: the party size is submitted as a number
71
+ - **`prompt` on a question**: extra instruction for that question only. The date question tells the model to pass along the caller's own words, and code resolves them (Lesson 3).
72
+ - **`confirm: true`**: the model must read the name back and get a yes before submitting it
73
+ - **`functions`**: the only tools available *during* that question
74
+
75
+ In a live test, the model asked these four questions one at a time and read the name back ("You said Daniel Chen, is that correct?"). It then called `find_tables` on its own as soon as `search` became the active step.
76
+
77
+ ## What Gather Mode Locks Down
78
+
79
+ While a question is being asked, the platform turns off every other tool on the step, and navigation too. The model can submit the answer, or use the tools that question lists. That's why each question lists the tools a caller may need partway through:
80
+
81
+ - In `collect`, every question offers `house_info` and `request_human`, so "What time do you close?" or "Can I talk to someone?" still work mid-gather
82
+ - In `take_message` (Lesson 9), each question offers `finish`, for a caller who decides not to leave a message after all
83
+
84
+ A tool listed on the step but not on the question is unavailable during the question. If a question needs a tool, list it on that question.
85
+
86
+ ## Gathered Answers Are Still Caller Input
87
+
88
+ Gather mode structures the conversation, but what gets submitted is still what the caller said, typed in by the model. So `find_tables` treats it exactly like tool arguments:
89
+
90
+ - The party size is checked to be a positive number within policy
91
+ - The date is resolved and checked against the calendar, the booking window and closed days
92
+ - The time must parse and land near a real seating
93
+ - The name is cleaned and length-limited
94
+
95
+ If an answer fails a check, the refusal's `ask` tells the model what to ask again. The correction comes back as an argument to `find_tables`, which updates that one detail of the request (Lesson 6). Gather mode has already finished, so a correction never restarts it.
96
+
97
+ ## Projecting Facts Per Call
98
+
99
+ Some facts depend on when the call arrives. Is anyone at the host stand right now? Penny works that out each time the platform requests its SWML, using a per-call configuration callback:
100
+
101
+ <!-- include: tutorial/full-guardrails-agent/penny.ts#project-call-facts --> <!-- snippet: no-compile a method of Penny, excerpted from penny.ts -->
102
+ ```typescript
103
+ /**
104
+ * Per call, on a per-request copy of the agent: facts the triage step may mention.
105
+ *
106
+ * `agent` is that copy. Changing `this` here would leak one caller's
107
+ * values into the next caller's call.
108
+ */
109
+ private projectCallFacts(agent: AgentBase): void {
110
+ agent.updateGlobalData({
111
+ host_stand: this.store.hostStandOpen() ? 'open' : 'closed',
112
+ });
113
+ }
114
+ ```
115
+
116
+ The constructor (Lesson 4) registers it with `addPerCallConfig()`, which runs a callback on every SWML request. The SDK passes the callback the request's query parameters, body and headers, and a per-request copy of the agent. Penny's callback passes only the copy to `projectCallFacts`.
117
+
118
+ The important detail is the `agent` argument. It's a per-request copy of Penny, made for this one request. Writing to `agent` affects only this call. Writing to `this` would change the shared agent that every caller uses, and one caller's values would leak into the next caller's conversation. `addPerCallConfig()` also composes: a second callback adds to the first instead of replacing it. `setDynamicConfigCallback()`, the other form, replaces every callback set before it.
119
+
120
+ ## Projecting Facts Into a Step
121
+
122
+ The triage step's text includes `${global_data.host_stand}`, and the platform fills it in when the step runs. In the live test, which ran in the early afternoon, the model's instructions read "The host stand is closed right now."
123
+
124
+ The same technique carries the confirmation code into the `booked` step: `confirm_booking` writes `booking.code_spoken` and `booking.summary` (Lesson 6), and the step's text includes both. In the live test, the `booked` step's instructions began: "The reservation is confirmed: a table for 4 on Friday, October 2 at 7:30 PM, under Daniel Chen." The next sentence gave the code as "6 A Q N C K". Whatever happens to the conversation history, the step's own instructions contain the code.
125
+
126
+ A projection is a single, finished fact. It isn't the reservation record, the customer file, or everything the model might conceivably need. Every field you project is a field the model can repeat, so project what the step needs and nothing more.
127
+
128
+ ## How Much History the Model Sees
129
+
130
+ Each step chooses how much of the earlier conversation the model keeps:
131
+
132
+ | Mode | Earlier instructions | Earlier dialogue |
133
+ |---|---|---|
134
+ | `keep` | Kept | Kept |
135
+ | `default` | Hidden | Kept |
136
+ | `hide` | Hidden | Hidden. Bring facts back with a projection. |
137
+
138
+ Most of Penny's steps use `default`: each step starts with fresh instructions, and the caller doesn't have to repeat themselves. One step uses `hide`, deliberately, and Lesson 8 explains why. Hidden turns disappear only from the model's view. The call log still has every word.
139
+
140
+ ## Key Takeaways
141
+
142
+ - Use gather mode for structured details: one question at a time, typed, optionally confirmed
143
+ - List the tools a caller may need mid-question on the question itself
144
+ - Treat gathered answers as caller input, and accept corrections as tool arguments
145
+ - Project per-call facts onto the per-request copy, never onto `this`
146
+ - Project single, finished facts into step text, and only the ones the step needs
147
+
148
+ ## Review Questions
149
+
150
+ 1. Why does `find_tables` still validate the party size when gather mode typed it as an integer?
151
+ 2. What would happen if `projectCallFacts` wrote to `this` instead of `agent`?
152
+ 3. During the date question, why can the model call `house_info` but not `find_tables`?
153
+
154
+ ## Next Steps
155
+
156
+ Projection carries facts forward from one step to the next. Next, `hide` and projection work together in the most important guardrail in Penny. Continue with [Lesson 8: The Verification Gate](08-the-verification-gate.md).
157
+
158
+ ---
159
+
160
+ [Previous: Tools That Decide](06-tools-that-decide.md) | [Overview](README.md) | [Next: The Verification Gate](08-the-verification-gate.md)