@signalwire/sdk 2.0.5 → 3.6.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 (659) hide show
  1. package/CHANGELOG.md +821 -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 +510 -126
  6. package/dist/AgentBase.js +1581 -455
  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 +186 -45
  21. package/dist/DataMap.js +210 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +309 -83
  24. package/dist/FunctionResult.js +483 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +12 -1
  30. package/dist/POM/PromptObjectModel.js +25 -9
  31. package/dist/POM/PromptObjectModel.js.map +1 -1
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +18 -0
  42. package/dist/PomBuilder.js +53 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +22 -1
  48. package/dist/PromptManager.js +28 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +169 -59
  58. package/dist/SWMLService.js +456 -129
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +49 -9
  64. package/dist/SecurityUtils.js +153 -51
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/SemanticGate.d.ts +183 -0
  67. package/dist/SemanticGate.js +533 -0
  68. package/dist/SemanticGate.js.map +1 -0
  69. package/dist/ServerlessAdapter.d.ts +156 -7
  70. package/dist/ServerlessAdapter.js +399 -42
  71. package/dist/ServerlessAdapter.js.map +1 -1
  72. package/dist/SessionManager.d.ts +11 -2
  73. package/dist/SessionManager.js +50 -18
  74. package/dist/SessionManager.js.map +1 -1
  75. package/dist/SslConfig.d.ts +2 -1
  76. package/dist/SslConfig.js +4 -1
  77. package/dist/SslConfig.js.map +1 -1
  78. package/dist/SwaigActions.generated.d.ts +23 -0
  79. package/dist/SwaigActions.generated.js +8 -0
  80. package/dist/SwaigActions.generated.js.map +1 -0
  81. package/dist/SwaigContracts.d.ts +15 -0
  82. package/dist/SwaigContracts.generated.d.ts +264 -0
  83. package/dist/SwaigContracts.generated.js +12 -0
  84. package/dist/SwaigContracts.generated.js.map +1 -0
  85. package/dist/SwaigContracts.js +2 -0
  86. package/dist/SwaigContracts.js.map +1 -0
  87. package/dist/SwaigFunction.d.ts +139 -7
  88. package/dist/SwaigFunction.js +170 -22
  89. package/dist/SwaigFunction.js.map +1 -1
  90. package/dist/SwmlBuilder.d.ts +68 -19
  91. package/dist/SwmlBuilder.js +74 -38
  92. package/dist/SwmlBuilder.js.map +1 -1
  93. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  94. package/dist/SwmlVerbMethods.generated.js +1 -1
  95. package/dist/TypeInference.d.ts +39 -3
  96. package/dist/TypeInference.js +256 -16
  97. package/dist/TypeInference.js.map +1 -1
  98. package/dist/WebService.d.ts +79 -11
  99. package/dist/WebService.js +320 -109
  100. package/dist/WebService.js.map +1 -1
  101. package/dist/WebhookMiddleware.d.ts +119 -0
  102. package/dist/WebhookMiddleware.js +271 -0
  103. package/dist/WebhookMiddleware.js.map +1 -0
  104. package/dist/WebhookValidator.d.ts +92 -0
  105. package/dist/WebhookValidator.js +409 -0
  106. package/dist/WebhookValidator.js.map +1 -0
  107. package/dist/agents/BedrockAgent.d.ts +162 -0
  108. package/dist/agents/BedrockAgent.js +323 -0
  109. package/dist/agents/BedrockAgent.js.map +1 -0
  110. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  111. package/dist/ai-chat/AIChatClient.js +535 -0
  112. package/dist/ai-chat/AIChatClient.js.map +1 -0
  113. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  114. package/dist/ai-chat/ChatGateway.js +747 -0
  115. package/dist/ai-chat/ChatGateway.js.map +1 -0
  116. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  117. package/dist/ai-chat/HandoffRouter.js +518 -0
  118. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  119. package/dist/ai-chat/index.d.ts +12 -0
  120. package/dist/ai-chat/index.js +10 -0
  121. package/dist/ai-chat/index.js.map +1 -0
  122. package/dist/capabilities.d.ts +64 -0
  123. package/dist/capabilities.js +95 -0
  124. package/dist/capabilities.js.map +1 -0
  125. package/dist/cli/agent-loader.d.ts +32 -6
  126. package/dist/cli/agent-loader.js +92 -33
  127. package/dist/cli/agent-loader.js.map +1 -1
  128. package/dist/cli/datamap-exec.d.ts +175 -0
  129. package/dist/cli/datamap-exec.js +1284 -0
  130. package/dist/cli/datamap-exec.js.map +1 -0
  131. package/dist/cli/function-args.d.ts +40 -0
  132. package/dist/cli/function-args.js +146 -0
  133. package/dist/cli/function-args.js.map +1 -0
  134. package/dist/cli/simulation.d.ts +99 -0
  135. package/dist/cli/simulation.js +490 -0
  136. package/dist/cli/simulation.js.map +1 -0
  137. package/dist/cli/swaig-test.d.ts +12 -25
  138. package/dist/cli/swaig-test.js +935 -371
  139. package/dist/cli/swaig-test.js.map +1 -1
  140. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  141. package/dist/cli/tsdocs/agentsNote.js +92 -0
  142. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  143. package/dist/cli/tsdocs/api-index.json +1 -0
  144. package/dist/cli/tsdocs/api.d.ts +91 -0
  145. package/dist/cli/tsdocs/api.js +372 -0
  146. package/dist/cli/tsdocs/api.js.map +1 -0
  147. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  148. package/dist/cli/tsdocs/apiTypes.js +7 -0
  149. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  150. package/dist/cli/tsdocs/bin.d.ts +6 -0
  151. package/dist/cli/tsdocs/bin.js +23 -0
  152. package/dist/cli/tsdocs/bin.js.map +1 -0
  153. package/dist/cli/tsdocs/files.d.ts +108 -0
  154. package/dist/cli/tsdocs/files.js +287 -0
  155. package/dist/cli/tsdocs/files.js.map +1 -0
  156. package/dist/cli/tsdocs/index.d.ts +28 -0
  157. package/dist/cli/tsdocs/index.js +307 -0
  158. package/dist/cli/tsdocs/index.js.map +1 -0
  159. package/dist/cli/tsdocs/live.d.ts +41 -0
  160. package/dist/cli/tsdocs/live.js +202 -0
  161. package/dist/cli/tsdocs/live.js.map +1 -0
  162. package/dist/cli/tsdocs/locate.d.ts +51 -0
  163. package/dist/cli/tsdocs/locate.js +75 -0
  164. package/dist/cli/tsdocs/locate.js.map +1 -0
  165. package/dist/cli/tsdocs/render.d.ts +75 -0
  166. package/dist/cli/tsdocs/render.js +323 -0
  167. package/dist/cli/tsdocs/render.js.map +1 -0
  168. package/dist/cli/tsdocs/topics.d.ts +43 -0
  169. package/dist/cli/tsdocs/topics.js +920 -0
  170. package/dist/cli/tsdocs/topics.js.map +1 -0
  171. package/dist/index.d.ts +49 -68
  172. package/dist/index.js +45 -73
  173. package/dist/index.js.map +1 -1
  174. package/dist/livewire/index.d.ts +229 -155
  175. package/dist/livewire/index.js +298 -195
  176. package/dist/livewire/index.js.map +1 -1
  177. package/dist/llms.txt +65 -0
  178. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  179. package/dist/prefabs/CallSessionStore.js +72 -0
  180. package/dist/prefabs/CallSessionStore.js.map +1 -0
  181. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  182. package/dist/prefabs/ConciergeAgent.js +36 -31
  183. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  184. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  185. package/dist/prefabs/FAQBotAgent.js +113 -47
  186. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  187. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  188. package/dist/prefabs/InfoGathererAgent.js +67 -58
  189. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  190. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  191. package/dist/prefabs/ReceptionistAgent.js +39 -31
  192. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  193. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  194. package/dist/prefabs/SurveyAgent.js +84 -68
  195. package/dist/prefabs/SurveyAgent.js.map +1 -1
  196. package/dist/relay/Action.d.ts +44 -21
  197. package/dist/relay/Action.js +75 -17
  198. package/dist/relay/Action.js.map +1 -1
  199. package/dist/relay/Call.d.ts +312 -47
  200. package/dist/relay/Call.js +369 -18
  201. package/dist/relay/Call.js.map +1 -1
  202. package/dist/relay/Deferred.js.map +1 -1
  203. package/dist/relay/Message.d.ts +26 -5
  204. package/dist/relay/Message.js +36 -6
  205. package/dist/relay/Message.js.map +1 -1
  206. package/dist/relay/RelayClient.d.ts +44 -17
  207. package/dist/relay/RelayClient.js +175 -65
  208. package/dist/relay/RelayClient.js.map +1 -1
  209. package/dist/relay/RelayError.d.ts +14 -0
  210. package/dist/relay/RelayError.js +15 -0
  211. package/dist/relay/RelayError.js.map +1 -1
  212. package/dist/relay/RelayEvent.d.ts +96 -65
  213. package/dist/relay/RelayEvent.js +85 -56
  214. package/dist/relay/RelayEvent.js.map +1 -1
  215. package/dist/relay/closedSets.d.ts +111 -0
  216. package/dist/relay/closedSets.js +83 -0
  217. package/dist/relay/closedSets.js.map +1 -0
  218. package/dist/relay/index.d.ts +3 -1
  219. package/dist/relay/index.js +1 -0
  220. package/dist/relay/index.js.map +1 -1
  221. package/dist/relay/normalize.js.map +1 -1
  222. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  223. package/dist/relay/protocol.types.generated.js +8 -0
  224. package/dist/relay/protocol.types.generated.js.map +1 -0
  225. package/dist/relay/types.d.ts +73 -42
  226. package/dist/rest/HttpClient.d.ts +36 -8
  227. package/dist/rest/HttpClient.js +233 -40
  228. package/dist/rest/HttpClient.js.map +1 -1
  229. package/dist/rest/RequestOptions.d.ts +110 -0
  230. package/dist/rest/RequestOptions.js +113 -0
  231. package/dist/rest/RequestOptions.js.map +1 -0
  232. package/dist/rest/RestError.d.ts +52 -6
  233. package/dist/rest/RestError.js +89 -5
  234. package/dist/rest/RestError.js.map +1 -1
  235. package/dist/rest/base/CrudResource.d.ts +16 -26
  236. package/dist/rest/base/CrudResource.js +19 -33
  237. package/dist/rest/base/CrudResource.js.map +1 -1
  238. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  239. package/dist/rest/base/CrudWithAddresses.js +2 -2
  240. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  241. package/dist/rest/base/FabricResource.d.ts +15 -0
  242. package/dist/rest/base/FabricResource.js +16 -0
  243. package/dist/rest/base/FabricResource.js.map +1 -0
  244. package/dist/rest/base/ReadResource.d.ts +62 -0
  245. package/dist/rest/base/ReadResource.js +69 -0
  246. package/dist/rest/base/ReadResource.js.map +1 -0
  247. package/dist/rest/callHandler.d.ts +5 -2
  248. package/dist/rest/callHandler.js +4 -1
  249. package/dist/rest/callHandler.js.map +1 -1
  250. package/dist/rest/index.d.ts +18 -77
  251. package/dist/rest/index.js +47 -120
  252. package/dist/rest/index.js.map +1 -1
  253. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  254. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  255. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  256. package/dist/rest/namespaces/addresses.d.ts +3 -42
  257. package/dist/rest/namespaces/addresses.js +3 -50
  258. package/dist/rest/namespaces/addresses.js.map +1 -1
  259. package/dist/rest/namespaces/calling.d.ts +6 -378
  260. package/dist/rest/namespaces/calling.js +6 -473
  261. package/dist/rest/namespaces/calling.js.map +1 -1
  262. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  263. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  264. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  265. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  266. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  267. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  268. package/dist/rest/namespaces/chat.d.ts +4 -18
  269. package/dist/rest/namespaces/chat.js +4 -21
  270. package/dist/rest/namespaces/chat.js.map +1 -1
  271. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  272. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  273. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  274. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  275. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  276. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  277. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  278. package/dist/rest/namespaces/datasphere.js +6 -72
  279. package/dist/rest/namespaces/datasphere.js.map +1 -1
  280. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  281. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  282. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  283. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  284. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  285. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  286. package/dist/rest/namespaces/fabric.d.ts +11 -327
  287. package/dist/rest/namespaces/fabric.js +14 -439
  288. package/dist/rest/namespaces/fabric.js.map +1 -1
  289. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  290. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  291. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  293. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  294. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  296. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  297. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  298. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  299. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  300. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  301. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  302. package/dist/rest/namespaces/imported-numbers.js +3 -21
  303. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  304. package/dist/rest/namespaces/logs.d.ts +10 -101
  305. package/dist/rest/namespaces/logs.js +10 -128
  306. package/dist/rest/namespaces/logs.js.map +1 -1
  307. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  308. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  309. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  310. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  311. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  312. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  313. package/dist/rest/namespaces/lookup.d.ts +3 -25
  314. package/dist/rest/namespaces/lookup.js +3 -27
  315. package/dist/rest/namespaces/lookup.js.map +1 -1
  316. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  317. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  318. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  319. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  320. package/dist/rest/namespaces/message.types.generated.js +8 -0
  321. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  323. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  324. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  325. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  326. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  327. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  328. package/dist/rest/namespaces/mfa.d.ts +3 -42
  329. package/dist/rest/namespaces/mfa.js +3 -49
  330. package/dist/rest/namespaces/mfa.js.map +1 -1
  331. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  332. package/dist/rest/namespaces/number-groups.js +3 -53
  333. package/dist/rest/namespaces/number-groups.js.map +1 -1
  334. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  335. package/dist/rest/namespaces/phone-numbers.js +8 -230
  336. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  337. package/dist/rest/namespaces/project.d.ts +6 -42
  338. package/dist/rest/namespaces/project.js +6 -51
  339. package/dist/rest/namespaces/project.js.map +1 -1
  340. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  341. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  342. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  343. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  344. package/dist/rest/namespaces/project.types.generated.js +8 -0
  345. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  347. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  348. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  349. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  350. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  351. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  352. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  353. package/dist/rest/namespaces/pubsub.js +4 -21
  354. package/dist/rest/namespaces/pubsub.js.map +1 -1
  355. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  356. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  357. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  358. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  359. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  360. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  361. package/dist/rest/namespaces/queues.d.ts +3 -38
  362. package/dist/rest/namespaces/queues.js +3 -44
  363. package/dist/rest/namespaces/queues.js.map +1 -1
  364. package/dist/rest/namespaces/recordings.d.ts +3 -34
  365. package/dist/rest/namespaces/recordings.js +3 -40
  366. package/dist/rest/namespaces/recordings.js.map +1 -1
  367. package/dist/rest/namespaces/registry.d.ts +6 -137
  368. package/dist/rest/namespaces/registry.js +6 -173
  369. package/dist/rest/namespaces/registry.js.map +1 -1
  370. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  371. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  372. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  373. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  374. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  375. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  376. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  377. package/dist/rest/namespaces/short-codes.js +3 -41
  378. package/dist/rest/namespaces/short-codes.js.map +1 -1
  379. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  380. package/dist/rest/namespaces/sip-profile.js +3 -29
  381. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  382. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  383. package/dist/rest/namespaces/verified-callers.js +3 -34
  384. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  385. package/dist/rest/namespaces/video.d.ts +10 -227
  386. package/dist/rest/namespaces/video.js +10 -288
  387. package/dist/rest/namespaces/video.js.map +1 -1
  388. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  389. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  390. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  391. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  392. package/dist/rest/namespaces/video.types.generated.js +8 -0
  393. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  395. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  396. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  397. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  398. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  399. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  400. package/dist/rest/pagination.d.ts +5 -1
  401. package/dist/rest/pagination.js +40 -20
  402. package/dist/rest/pagination.js.map +1 -1
  403. package/dist/rest/types.d.ts +21 -3
  404. package/dist/schema.json +299 -98
  405. package/dist/skills/SkillBase.d.ts +111 -21
  406. package/dist/skills/SkillBase.js +100 -17
  407. package/dist/skills/SkillBase.js.map +1 -1
  408. package/dist/skills/SkillManager.d.ts +66 -13
  409. package/dist/skills/SkillManager.js +101 -20
  410. package/dist/skills/SkillManager.js.map +1 -1
  411. package/dist/skills/SkillName.d.ts +44 -0
  412. package/dist/skills/SkillName.js +2 -0
  413. package/dist/skills/SkillName.js.map +1 -0
  414. package/dist/skills/SkillRegistry.d.ts +22 -11
  415. package/dist/skills/SkillRegistry.js +47 -17
  416. package/dist/skills/SkillRegistry.js.map +1 -1
  417. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  418. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  419. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  420. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  421. package/dist/skills/builtin/ask_claude.js +36 -14
  422. package/dist/skills/builtin/ask_claude.js.map +1 -1
  423. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  424. package/dist/skills/builtin/claude_skills.js +19 -15
  425. package/dist/skills/builtin/claude_skills.js.map +1 -1
  426. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  427. package/dist/skills/builtin/custom_skills.js +26 -9
  428. package/dist/skills/builtin/custom_skills.js.map +1 -1
  429. package/dist/skills/builtin/datasphere.d.ts +5 -3
  430. package/dist/skills/builtin/datasphere.js +21 -22
  431. package/dist/skills/builtin/datasphere.js.map +1 -1
  432. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  433. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  434. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  435. package/dist/skills/builtin/datetime.d.ts +3 -1
  436. package/dist/skills/builtin/datetime.js +11 -7
  437. package/dist/skills/builtin/datetime.js.map +1 -1
  438. package/dist/skills/builtin/google_maps.d.ts +29 -14
  439. package/dist/skills/builtin/google_maps.js +89 -269
  440. package/dist/skills/builtin/google_maps.js.map +1 -1
  441. package/dist/skills/builtin/index.d.ts +8 -6
  442. package/dist/skills/builtin/index.js +8 -6
  443. package/dist/skills/builtin/index.js.map +1 -1
  444. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  445. package/dist/skills/builtin/info_gatherer.js +20 -12
  446. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  447. package/dist/skills/builtin/joke.d.ts +16 -6
  448. package/dist/skills/builtin/joke.js +54 -37
  449. package/dist/skills/builtin/joke.js.map +1 -1
  450. package/dist/skills/builtin/math.d.ts +3 -1
  451. package/dist/skills/builtin/math.js +14 -9
  452. package/dist/skills/builtin/math.js.map +1 -1
  453. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  454. package/dist/skills/builtin/mcp_gateway.js +77 -46
  455. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  456. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  457. package/dist/skills/builtin/native_vector_search.js +179 -61
  458. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  459. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  460. package/dist/skills/builtin/play_background_file.js +43 -122
  461. package/dist/skills/builtin/play_background_file.js.map +1 -1
  462. package/dist/skills/builtin/spider.d.ts +42 -4
  463. package/dist/skills/builtin/spider.js +277 -104
  464. package/dist/skills/builtin/spider.js.map +1 -1
  465. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  466. package/dist/skills/builtin/swml_transfer.js +45 -24
  467. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  468. package/dist/skills/builtin/weather_api.d.ts +24 -13
  469. package/dist/skills/builtin/weather_api.js +38 -30
  470. package/dist/skills/builtin/weather_api.js.map +1 -1
  471. package/dist/skills/builtin/web_search.d.ts +48 -10
  472. package/dist/skills/builtin/web_search.js +294 -100
  473. package/dist/skills/builtin/web_search.js.map +1 -1
  474. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  475. package/dist/skills/builtin/wikipedia_search.js +14 -13
  476. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  477. package/dist/skills/index.d.ts +3 -2
  478. package/dist/skills/index.js +1 -1
  479. package/dist/skills/index.js.map +1 -1
  480. package/dist/swml_verbs_generated.d.ts +2824 -0
  481. package/dist/swml_verbs_generated.js +12 -0
  482. package/dist/swml_verbs_generated.js.map +1 -0
  483. package/dist/types.d.ts +59 -6
  484. package/dist/web.d.ts +27 -0
  485. package/dist/web.js +20 -0
  486. package/dist/web.js.map +1 -0
  487. package/docs/agent-guide.md +1034 -0
  488. package/docs/ai_chat.md +560 -0
  489. package/docs/api-reference.md +3641 -0
  490. package/docs/architecture.md +846 -0
  491. package/docs/bedrock_agent.md +411 -0
  492. package/docs/cli-guide.md +403 -0
  493. package/docs/cloud_functions_guide.md +399 -0
  494. package/docs/configuration.md +548 -0
  495. package/docs/contexts-guide.md +884 -0
  496. package/docs/datamap-guide.md +1207 -0
  497. package/docs/developer_pain_points.md +548 -0
  498. package/docs/llm_parameters.md +298 -0
  499. package/docs/mcp_gateway_reference.md +354 -0
  500. package/docs/mcp_integration.md +162 -0
  501. package/docs/pgi_agent_guide.md +1820 -0
  502. package/docs/prefabs-guide.md +815 -0
  503. package/docs/programmatically_governed_inference.md +301 -0
  504. package/docs/sdk_features.md +501 -0
  505. package/docs/security.md +559 -0
  506. package/docs/serverless-guide.md +520 -0
  507. package/docs/skills-guide.md +1223 -0
  508. package/docs/skills-system.md +405 -0
  509. package/docs/skills_parameter_schema.md +417 -0
  510. package/docs/swaig-reference.md +1986 -0
  511. package/docs/swml_service_guide.md +573 -0
  512. package/docs/third_party_skills.md +410 -0
  513. package/docs/web_service.md +666 -0
  514. package/examples/README.md +202 -0
  515. package/examples/advanced-datamap.ts +108 -0
  516. package/examples/advanced-dynamic-config.ts +70 -0
  517. package/examples/auto-vivified.ts +95 -0
  518. package/examples/call-flow.ts +65 -0
  519. package/examples/comprehensive-dynamic.ts +125 -0
  520. package/examples/contexts-steps.ts +65 -0
  521. package/examples/custom-path.ts +45 -0
  522. package/examples/datamap-tools.ts +51 -0
  523. package/examples/datasphere-multi-instance.ts +66 -0
  524. package/examples/datasphere-serverless-env.ts +87 -0
  525. package/examples/datasphere-webhook-env.ts +65 -0
  526. package/examples/datasphere.ts +56 -0
  527. package/examples/declarative.ts +100 -0
  528. package/examples/dynamic-config.ts +54 -0
  529. package/examples/dynamic-info-gatherer.ts +69 -0
  530. package/examples/dynamic-swml-service.ts +67 -0
  531. package/examples/gather-info.ts +95 -0
  532. package/examples/gather-per-question-functions-demo.ts +139 -0
  533. package/examples/joke-agent.ts +34 -0
  534. package/examples/kubernetes-agent.ts +45 -0
  535. package/examples/llm-params.ts +75 -0
  536. package/examples/mcp-agent.ts +89 -0
  537. package/examples/mcp-gateway.ts +81 -0
  538. package/examples/multi-agent.ts +80 -0
  539. package/examples/multi-endpoint.ts +79 -0
  540. package/examples/pgi/case-domain.ts +114 -0
  541. package/examples/pgi/serve.ts +16 -0
  542. package/examples/pgi/support-agent.ts +265 -0
  543. package/examples/pom-prompt.ts +70 -0
  544. package/examples/prefab-concierge.ts +42 -0
  545. package/examples/prefab-faq.ts +58 -0
  546. package/examples/prefab-info-gatherer.ts +33 -0
  547. package/examples/prefab-receptionist.ts +36 -0
  548. package/examples/prefab-survey.ts +69 -0
  549. package/examples/quickstart-agent.ts +29 -0
  550. package/examples/quickstart-relay.ts +25 -0
  551. package/examples/quickstart-rest.ts +25 -0
  552. package/examples/record-call.ts +65 -0
  553. package/examples/relay-demo.ts +33 -0
  554. package/examples/room-and-sip.ts +93 -0
  555. package/examples/serverless-lambda.ts +43 -0
  556. package/examples/session-state.ts +83 -0
  557. package/examples/simple-agent.ts +36 -0
  558. package/examples/simple-static.ts +29 -0
  559. package/examples/skills-demo.ts +41 -0
  560. package/examples/step-function-inheritance-demo.ts +124 -0
  561. package/examples/swaig-features.ts +193 -0
  562. package/examples/swml-service-routing.ts +66 -0
  563. package/examples/swml-service.ts +38 -0
  564. package/examples/swmlservice_ai_sidecar.ts +104 -0
  565. package/examples/swmlservice_swaig_standalone.ts +79 -0
  566. package/examples/tap.ts +67 -0
  567. package/examples/typed-tools.ts +68 -0
  568. package/examples/verb-methods.ts +45 -0
  569. package/examples/web-search-multi-instance.ts +75 -0
  570. package/examples/web-search.ts +38 -0
  571. package/examples/wikipedia.ts +36 -0
  572. package/livewire/README.md +164 -0
  573. package/livewire/docs/migration-guide.md +251 -0
  574. package/livewire/examples/livewire-basic-agent.ts +74 -0
  575. package/livewire/examples/livewire-handoff.ts +196 -0
  576. package/livewire/examples/livewire-multi-tool.ts +121 -0
  577. package/package.json +85 -13
  578. package/relay/README.md +101 -0
  579. package/relay/docs/call-methods.md +622 -0
  580. package/relay/docs/client-reference.md +281 -0
  581. package/relay/docs/events.md +193 -0
  582. package/relay/docs/getting-started.md +221 -0
  583. package/relay/docs/guide.md +386 -0
  584. package/relay/docs/messaging.md +246 -0
  585. package/relay/examples/relay-inbound.ts +66 -0
  586. package/relay/examples/relay-messaging.ts +74 -0
  587. package/relay/examples/relay-outbound.ts +76 -0
  588. package/rest/README.md +141 -0
  589. package/rest/docs/calling.md +313 -0
  590. package/rest/docs/client-reference.md +149 -0
  591. package/rest/docs/fabric.md +192 -0
  592. package/rest/docs/getting-started.md +138 -0
  593. package/rest/docs/guide.md +421 -0
  594. package/rest/docs/namespaces.md +367 -0
  595. package/rest/docs/phone-binding.md +116 -0
  596. package/rest/examples/rest-10dlc-registration.ts +177 -0
  597. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  598. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  599. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  600. package/rest/examples/rest-client.ts +59 -0
  601. package/rest/examples/rest-datasphere-search.ts +81 -0
  602. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  603. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  604. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  605. package/rest/examples/rest-manage-resources.ts +64 -0
  606. package/rest/examples/rest-phone-number-management.ts +200 -0
  607. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  608. package/rest/examples/rest-video-rooms.ts +186 -0
  609. package/tutorial/fred/fred.ts +218 -0
  610. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  611. package/tutorial/fred/tutorial/02-setup.md +304 -0
  612. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  613. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  614. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  615. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  616. package/tutorial/fred/tutorial/README.md +56 -0
  617. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  618. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  619. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  620. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  621. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  622. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  623. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  624. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  625. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  626. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  627. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  628. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  629. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  630. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  631. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  632. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  633. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  634. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  635. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  636. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  637. package/tutorial/multi_agents/README.md +175 -0
  638. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  639. package/tutorial/multi_agents/extending_agents.ts +641 -0
  640. package/tutorial/multi_agents/knowledge.ts +59 -0
  641. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  642. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  643. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  644. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  645. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  646. package/tutorial/multi_agents/pc_builder.ts +529 -0
  647. package/tutorial/multi_agents/sales_agent.ts +88 -0
  648. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  649. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  650. package/tutorial/multi_agents/support_knowledge.md +256 -0
  651. package/dist/cli/mock-data.d.ts +0 -37
  652. package/dist/cli/mock-data.js +0 -80
  653. package/dist/cli/mock-data.js.map +0 -1
  654. package/dist/generateVerbTypes.d.ts +0 -11
  655. package/dist/generateVerbTypes.js +0 -265
  656. package/dist/generateVerbTypes.js.map +0 -1
  657. package/dist/rest/namespaces/compat.d.ts +0 -585
  658. package/dist/rest/namespaces/compat.js +0 -735
  659. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,191 @@
1
+ # Appendix B: Deployment
2
+
3
+ In production, Penny needs four things: its secrets, a public HTTPS address, somewhere safe to keep the reservation book, and a process manager to keep it running.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [Settings](#settings)
8
+ 2. [Secrets](#secrets)
9
+ 3. [Running in Docker](#running-in-docker)
10
+ 4. [The Management Script](#the-management-script)
11
+ 5. [One Reservation Book](#one-reservation-book)
12
+ 6. [Before You Go Live](#before-you-go-live)
13
+
14
+ ---
15
+
16
+ ## Settings
17
+
18
+ Penny reads everything from environment variables. `penny.sh` loads them from `.env`, and Docker takes them with `--env-file`.
19
+
20
+ | Variable | Required | Default | What it does |
21
+ |---|---|---|---|
22
+ | `SWML_BASIC_AUTH_USER` | Yes | | The user SignalWire presents to fetch SWML and call tools |
23
+ | `SWML_BASIC_AUTH_PASSWORD` | Yes | | Its password |
24
+ | `SIGNALWIRE_SIGNING_KEY` | In production | | Your project's signing key. When it's set, the SDK checks that SignalWire sent each request. |
25
+ | `SIGNALWIRE_SWAIG_SECRET` | Yes | | The secret behind the per-call tool tokens |
26
+ | `PENNY_DB_PATH` | No | `penny.sqlite3` next to `penny.ts` | Where the reservation book lives. The Docker image sets `/data/penny.sqlite3`. |
27
+ | `PENNY_DEMO_DATA` | No | off | `1` adds the demo reservation to an empty book. Never in production. |
28
+ | `PENNY_HOST_NUMBER` | No | empty | Where "talk to a person" goes. Empty means Penny always takes a message. |
29
+ | `PENNY_SMS_FROM` | No | empty | Your SignalWire number for confirmation texts. Empty turns texting off. |
30
+ | `PORT` | No | `3000` | The port Penny listens on |
31
+ | `SWML_PROXY_URL_BASE` | Behind a proxy | | The public URL SignalWire reaches Penny at |
32
+ | `PENNY_AI_MODEL` | No | `gpt-4.1-mini` | The model |
33
+ | `PENNY_VOICE` | No | `inworld.Sarah` | The voice |
34
+ | `PENNY_DEBUG_EVENTS` | No | off | `1` logs the platform's debug events for each call |
35
+
36
+ `SWML_PROXY_URL_BASE` matters more than it looks. The SWML Penny serves includes the address SignalWire calls back for every tool. Behind a proxy or a tunnel, that address must be the public one, or the model's tool calls go nowhere.
37
+
38
+ ## Secrets
39
+
40
+ Generate the password and the tool-token secret, rather than inventing them. This prints a random 32-byte value:
41
+
42
+ ```bash
43
+ node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"
44
+ ```
45
+
46
+ Three more rules apply to secrets:
47
+
48
+ - `SIGNALWIRE_SIGNING_KEY` isn't something you generate. It's your project's signing key from the SignalWire dashboard.
49
+ - Use the same `SIGNALWIRE_SWAIG_SECRET` on every server, so a tool call is accepted by whichever server receives it
50
+ - Keep `.env` out of version control. The tutorial's `.gitignore` already does.
51
+
52
+ ## Running in Docker
53
+
54
+ The tutorial's `Dockerfile` builds an image for Penny:
55
+
56
+ <!-- quote: tutorial/full-guardrails-agent/Dockerfile -->
57
+ ```dockerfile
58
+ FROM node:24-slim
59
+
60
+ WORKDIR /app
61
+ COPY package.json package-lock.json ./
62
+ RUN npm ci --omit=dev
63
+ COPY reservations.ts workflow.ts handlers.ts penny.ts ./
64
+
65
+ # Run as the image's unprivileged node user, and keep the reservation book on a volume.
66
+ RUN mkdir -p /data && chown node /data
67
+ USER node
68
+ ENV PENNY_DB_PATH=/data/penny.sqlite3
69
+ VOLUME /data
70
+
71
+ EXPOSE 3000
72
+ HEALTHCHECK --interval=30s --timeout=5s \
73
+ CMD node -e "fetch('http://localhost:' + (process.env.PORT || 3000) + '/penny/health').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"
74
+ CMD ["node", "--import", "tsx", "penny.ts"]
75
+ ```
76
+
77
+ The image runs Penny with Node.js 24 as the image's unprivileged `node` user. It keeps the reservation book on a volume at `/data`, and asks Penny's `/penny/health` route whether it's up every 30 seconds. The check exits with an error unless the route answers with a success status, so Docker marks a broken Penny unhealthy.
78
+
79
+ `npm ci` installs exactly what `package-lock.json` lists, so the build needs that file. Build the image from your own copy of the directory, outside this repository. Run `npm install` there once to write `package-lock.json`, then build and run the image:
80
+
81
+ ```bash
82
+ docker build -t penny .
83
+ docker run -d --name penny --env-file .env -p 3000:3000 -v penny-data:/data penny
84
+ ```
85
+
86
+ If you change `PORT`, change the `-p` mapping to match. `docker inspect --format '{{.State.Health.Status}}' penny` shows the health Docker reports.
87
+
88
+ This Dockerfile was built and run while writing this tutorial, with the SDK installed from a local package of this repository. Penny answered on `/penny/health`, kept its book in `/data`, and Docker reported it `healthy`.
89
+
90
+ ## The Management Script
91
+
92
+ `penny.sh` starts, stops and checks Penny on your own machine:
93
+
94
+ <!-- quote: tutorial/full-guardrails-agent/penny.sh -->
95
+ ```bash
96
+ #!/usr/bin/env bash
97
+ # Start, stop and check Penny. Reads settings from .env next to this script.
98
+ #
99
+ # ./penny.sh start | stop | restart | status | logs | test
100
+ set -euo pipefail
101
+ cd "$(dirname "$0")"
102
+
103
+ PID_FILE=penny.pid
104
+ LOG_FILE=penny.log
105
+
106
+ load_env() {
107
+ if [[ -f .env ]]; then
108
+ set -a
109
+ # shellcheck disable=SC1091
110
+ source .env
111
+ set +a
112
+ fi
113
+ }
114
+
115
+ running() {
116
+ [[ -f $PID_FILE ]] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null
117
+ }
118
+
119
+ case "${1:-}" in
120
+ start)
121
+ if running; then echo "Penny is already running (pid $(cat "$PID_FILE"))."; exit 0; fi
122
+ load_env
123
+ nohup node --import tsx penny.ts >"$LOG_FILE" 2>&1 &
124
+ echo $! >"$PID_FILE"
125
+ sleep 2
126
+ if running; then
127
+ echo "Penny started (pid $(cat "$PID_FILE")). Logs: ./penny.sh logs"
128
+ else
129
+ echo "Penny failed to start:"; tail -n 20 "$LOG_FILE"; rm -f "$PID_FILE"; exit 1
130
+ fi
131
+ ;;
132
+ stop)
133
+ if ! running; then echo "Penny is not running."; rm -f "$PID_FILE"; exit 0; fi
134
+ kill "$(cat "$PID_FILE")"
135
+ for _ in 1 2 3 4 5; do running || break; sleep 1; done
136
+ if running; then kill -9 "$(cat "$PID_FILE")"; fi
137
+ rm -f "$PID_FILE"
138
+ echo "Penny stopped."
139
+ ;;
140
+ restart)
141
+ "$0" stop
142
+ "$0" start
143
+ ;;
144
+ status)
145
+ if running; then echo "Penny is running (pid $(cat "$PID_FILE"))."; else echo "Penny is not running."; fi
146
+ ;;
147
+ logs)
148
+ tail -f "$LOG_FILE"
149
+ ;;
150
+ test)
151
+ # The tests live with the SDK's other tests, two directories up.
152
+ cd ../.. && npx vitest run tests/tutorial/penny
153
+ ;;
154
+ *)
155
+ echo "usage: $0 start|stop|restart|status|logs|test"; exit 2
156
+ ;;
157
+ esac
158
+ ```
159
+
160
+ The script runs Penny with `node --import tsx`, which loads TypeScript files as they are. The `test` command runs the tests from the repository root, two directories up, so it works only inside this repository.
161
+
162
+ The script doesn't restart Penny after a crash or a reboot. In production, use Docker, systemd, or your platform's process manager instead.
163
+
164
+ ## One Reservation Book
165
+
166
+ Penny keeps all its state in one SQLite file:
167
+
168
+ - Every write is a short transaction that starts with `BEGIN IMMEDIATE`, so requests arriving together are handled one at a time. `books once when four threads confirm at the same moment` checks that four confirms racing on worker threads, each with its own connection, book one table.
169
+ - The state is keyed by call, not held in memory, so restarting Penny between two turns of a call loses nothing.
170
+ - Back up the file while Penny runs with `sqlite3 penny.sqlite3 ".backup penny-backup.sqlite3"`.
171
+ - The restaurant's time zone is set in `reservations.ts`, not taken from the server, so "tonight" means the restaurant's tonight wherever Penny runs.
172
+
173
+ One SQLite file suits one restaurant on one server. Don't put it on a network file system, where SQLite's locking can't be trusted. To run Penny on more than one server, move `ReservationStore` to a shared database such as PostgreSQL, through an asynchronous driver. Every rule lives in that one class, so nothing outside `reservations.ts` needs to change except the handlers, which would await its methods.
174
+
175
+ ## Before You Go Live
176
+
177
+ Check each item before Penny takes real calls:
178
+
179
+ - [ ] The three required secrets are real values, `SIGNALWIRE_SIGNING_KEY` is set, and `PENNY_DEMO_DATA` is `0`
180
+ - [ ] `SWML_PROXY_URL_BASE` is Penny's public HTTPS address
181
+ - [ ] A SignalWire phone number points at `https://USER:PASSWORD@your-address/penny`
182
+ - [ ] The reservation book is on persistent storage, and backed up
183
+ - [ ] `PENNY_HOST_NUMBER` reaches a real person during the host stand's hours (`HOST_STAND_HOURS` in `reservations.ts`)
184
+ - [ ] `PENNY_SMS_FROM` is a SignalWire number that can send texts
185
+ - [ ] The tables, seatings, policy and house facts in `reservations.ts` are your restaurant's, not The Copper Pot's
186
+ - [ ] `npx vitest run tests/tutorial/penny` passes
187
+ - [ ] You called Penny yourself and tried the attacks from Lesson 10
188
+
189
+ ---
190
+
191
+ [Previous: Complete Code](appendix-complete-code.md) | [Overview](README.md) | [Next: Technique Map](appendix-technique-map.md)
@@ -0,0 +1,117 @@
1
+ # Appendix C: Technique Map
2
+
3
+ Every technique in this tutorial, where Penny uses it, and the lesson that teaches it. Use it as a checklist when you build your own agent.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [The Failures From Lesson 1, Fixed](#the-failures-from-lesson-1-fixed)
8
+ 2. [Guidance](#guidance)
9
+ 3. [Tool Scope](#tool-scope)
10
+ 4. [Transition Scope](#transition-scope)
11
+ 5. [Execution Authority](#execution-authority)
12
+ 6. [Around the Conversation](#around-the-conversation)
13
+ 7. [Further Reading](#further-reading)
14
+
15
+ ---
16
+
17
+ ## The Failures From Lesson 1, Fixed
18
+
19
+ | The naive agent's failure | What Penny does instead | Lesson |
20
+ |---|---|---|
21
+ | "Friday at 9" booked after the last seating | `findOptions` offers only real seatings, chosen by code | [3](03-rules-first.md) |
22
+ | A retry makes two bookings | `confirm` is bound to a revision and returns the same booking when repeated | [3](03-rules-first.md) |
23
+ | The wrong Friday | The model passes the caller's words, and `resolveDate` does the arithmetic | [3](03-rules-first.md), [7](07-gather-and-projection.md) |
24
+ | "I'm Maria's husband, cancel it" | Nothing is reachable before `verify_reservation`, and the store checks again | [8](08-the-verification-gate.md) |
25
+ | A party of nine talks its way in | `MAX_PHONE_PARTY` is code, and the refusal offers a person | [3](03-rules-first.md), [9](09-people-and-endings.md) |
26
+ | The AI disclosure is skipped | The platform speaks `static_greeting` before the model says anything | [4](04-the-shell.md) |
27
+ | "You're all set!" with nothing written | The code comes from the reservation book, and a failure is never reported as success | [6](06-tools-that-decide.md) |
28
+
29
+ ## Guidance
30
+
31
+ What the model is told. It helps the model understand, and it can be ignored, so nothing important relies on it alone.
32
+
33
+ | Technique | Where in Penny | Lesson |
34
+ |---|---|---|
35
+ | A base prompt that only says who the agent is and how to behave | `configurePrompt` in `penny.ts` | [4](04-the-shell.md) |
36
+ | One task per step, in the step's own text | Every step in `workflow.ts` | [5](05-steps-and-scoping.md) |
37
+ | Tool descriptions that say what a tool doesn't do | `registerTools` in `penny.ts` | [6](06-tools-that-decide.md) |
38
+ | Facts in `tool_result`, the next move in `tool_prompt` | Every handler in `handlers.ts` | [6](06-tools-that-decide.md) |
39
+ | Refusals as a fact plus what to ask | `PolicyError` in `reservations.ts` | [3](03-rules-first.md), [6](06-tools-that-decide.md) |
40
+ | Single, finished facts projected into step text | `${global_data...}` in triage, `booked` and `details` | [7](07-gather-and-projection.md) |
41
+ | Hiding earlier dialogue, and projecting back what's needed | The `'hide'` history mode on `details` | [7](07-gather-and-projection.md), [8](08-the-verification-gate.md) |
42
+ | Hints and pronunciations for the voice | `configureVoice` in `penny.ts` | [4](04-the-shell.md) |
43
+
44
+ ## Tool Scope
45
+
46
+ What the model can ask for. A tool that isn't offered can't be called.
47
+
48
+ | Technique | Where in Penny | Lesson |
49
+ |---|---|---|
50
+ | Register every tool once, and offer a few per step | `registerTools`, then `scoped` | [5](05-steps-and-scoping.md) |
51
+ | Write `[]` for no tools, never leave the list out | `scoped` in `workflow.ts` | [5](05-steps-and-scoping.md) |
52
+ | Each consequential tool in exactly one step | `confirm_booking` only in `review`, and so on | [5](05-steps-and-scoping.md) |
53
+ | Gather mode, with the tools each question allows | `collect` and `take_message` | [7](07-gather-and-projection.md) |
54
+ | A gate built from missing tools | The `verify` step | [8](08-the-verification-gate.md) |
55
+ | Destinations the model can't name | `request_human` and `send_confirmation_text` take no parameters | [9](09-people-and-endings.md) |
56
+
57
+ ## Transition Scope
58
+
59
+ Who moves the conversation. In Penny, never the model.
60
+
61
+ | Technique | Where in Penny | Lesson |
62
+ |---|---|---|
63
+ | Empty `valid_steps` and `valid_contexts` on every step | `scoped` in `workflow.ts` | [5](05-steps-and-scoping.md) |
64
+ | Router tools that move the conversation and reset what comes next | `start_booking`, `manage_booking` | [5](05-steps-and-scoping.md), [6](06-tools-that-decide.md) |
65
+ | Step changes returned by handlers after they check the real state | `swmlChangeStep()` in `handlers.ts` | [6](06-tools-that-decide.md) |
66
+ | Gather mode moving on when the last answer is in | `completionAction` on `collect` and `take_message` | [7](07-gather-and-projection.md) |
67
+ | A lockout step with only a person or goodbye | `locked` | [8](08-the-verification-gate.md) |
68
+ | Endings as actions, not `setEnd()` | `finish` and `request_human` | [5](05-steps-and-scoping.md), [9](09-people-and-endings.md) |
69
+
70
+ ## Execution Authority
71
+
72
+ What actually happens. The model can ask, and code decides.
73
+
74
+ | Technique | Where in Penny | Lesson |
75
+ |---|---|---|
76
+ | Every rule in a module with no SignalWire import | `reservations.ts` | [3](03-rules-first.md) |
77
+ | Internal IDs never leave code | Tables become option numbers in `findOptions` | [3](03-rules-first.md) |
78
+ | Holds that expire and keep other callers out | `holdOption` and `tableFree` | [3](03-rules-first.md) |
79
+ | Commits bound to the revision the caller heard, and safe to repeat | `confirm`, `confirmCancel` | [3](03-rules-first.md), [8](08-the-verification-gate.md) |
80
+ | State keyed by call ID in a database, not in the conversation | `ReservationStore` | [3](03-rules-first.md) |
81
+ | Corrections kept in a per-call draft, even after a refused search | `updateDraft` | [6](06-tools-that-decide.md) |
82
+ | Verification bound to this call, and checked by every operation | `verify` and `verified` | [8](08-the-verification-gate.md) |
83
+ | Misses that don't say which half was wrong, counted after commit | `verify` | [8](08-the-verification-gate.md) |
84
+ | Two steps for anything destructive | `requestCancel`, then `confirmCancel` | [8](08-the-verification-gate.md) |
85
+ | Repeats that change nothing, and a cap on side effects | `requestSms` for texts, and one message per call in `saveMessage` | [9](09-people-and-endings.md) |
86
+ | Live facts checked when the tool runs | `hostStandOpen` in `request_human` | [9](09-people-and-endings.md) |
87
+ | A crash is never reported as success | `guarded` in `handlers.ts` | [6](06-tools-that-decide.md) |
88
+ | Records written from the system of record | `captureCall`, registered with `onCallEnd()` | [9](09-people-and-endings.md) |
89
+
90
+ ## Around the Conversation
91
+
92
+ | Technique | Where in Penny | Lesson |
93
+ |---|---|---|
94
+ | Refuse to start without real secrets | `REQUIRED_ENV` in `penny.ts` | [4](04-the-shell.md) |
95
+ | A disclosure the platform speaks, word for word | `static_greeting` | [4](04-the-shell.md) |
96
+ | Per-call facts written to the per-request copy, never to `this` | `projectCallFacts`, registered with `addPerCallConfig()` | [7](07-gather-and-projection.md) |
97
+ | UI events for a screen, alongside speech | `swmlUserEvent()` in the handlers | [6](06-tools-that-decide.md) |
98
+ | Debug events to see which step the model was in | `PENNY_DEBUG_EVENTS` | [9](09-people-and-endings.md) |
99
+ | Tests in layers, with a clock the tests control | `tests/tutorial/penny-*.test.ts` | [10](10-testing-and-running.md) |
100
+ | Tests against the app you serve | `servedSwml` and `Call` in `penny-helpers.ts` | [10](10-testing-and-running.md) |
101
+ | Breaking each guardrail on purpose once | The table in Lesson 10 | [10](10-testing-and-running.md) |
102
+ | Lessons checked against the code | Include markers and `penny-docs.test.ts` | [10](10-testing-and-running.md) |
103
+
104
+ ## Further Reading
105
+
106
+ The SDK's guides cover each technique in more depth:
107
+
108
+ - [Contexts guide](../../../docs/contexts-guide.md): contexts, steps, gather mode and navigation
109
+ - [SWAIG reference](../../../docs/swaig-reference.md): tools, `FunctionResult` and its actions
110
+ - [Security](../../../docs/security.md): basic auth, request signatures and tool tokens
111
+ - [Agent guide](../../../docs/agent-guide.md): prompts, parameters, pronunciation and debug events
112
+ - [PGI agent guide](../../../docs/pgi_agent_guide.md): the design method behind Penny, with a tested reference agent
113
+ - [CLI guide](../../../docs/cli-guide.md): `swaig-test`
114
+
115
+ ---
116
+
117
+ [Previous: Deployment](appendix-deployment.md) | [Overview](README.md)
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Penny's conversation, as configuration: which task is active, and what the
3
+ * model may do while it is.
4
+ *
5
+ * Two rules hold for every step, and both are enforced by `scoped`:
6
+ *
7
+ * 1. The step names its tools explicitly. A step that names none would inherit
8
+ * the previous step's tools, so "no tools" is written `[]`, never omitted.
9
+ * 2. The model cannot navigate. `valid_steps` and `valid_contexts` are empty,
10
+ * so the only way from one step to the next is a tool handler that has
11
+ * checked the real state and returned `swmlChangeStep`/`swmlChangeContext`.
12
+ *
13
+ * Copyright (c) 2025 SignalWire. Licensed under the MIT License.
14
+ * See LICENSE file in the project root for full license information.
15
+ */
16
+
17
+ import type { ContextBuilder, Step } from '@signalwire/sdk';
18
+
19
+ // Tools most steps offer. Reading house facts or asking for a person can never
20
+ // change a booking, so offering them widely is safe.
21
+ export const LOOKUPS = ['house_info', 'request_human'];
22
+
23
+ // region: scoped
24
+ /** Give a step its task, its tools, and no way to leave on its own. */
25
+ export function scoped(step: Step, text: string, tools: string[], history = 'default'): Step {
26
+ return step
27
+ .setText(text)
28
+ .setFunctions(tools)
29
+ .setValidSteps([])
30
+ .setValidContexts([])
31
+ .setHistory(history);
32
+ }
33
+ // endregion: scoped
34
+
35
+ /** Add Penny's four contexts to `builder` and validate them. */
36
+ export function configureWorkflow(builder: ContextBuilder): ContextBuilder {
37
+ addTriage(builder);
38
+ addBooking(builder);
39
+ addManage(builder);
40
+ addHelp(builder);
41
+ builder.validate();
42
+ return builder;
43
+ }
44
+
45
+ // region: triage
46
+ function addTriage(builder: ContextBuilder): void {
47
+ const ctx = builder.addContext('default');
48
+ scoped(
49
+ ctx.addStep('triage'),
50
+ "The greeting has already been played; don't repeat it. The host stand is " +
51
+ '${global_data.host_stand} right now. As soon as the caller says what they want, ' +
52
+ 'act on it without asking again: for a new reservation call start_booking; to ' +
53
+ 'check, change or cancel one they already have, call manage_booking. Answer ' +
54
+ 'general questions with house_info. If they ask for a person, call ' +
55
+ "request_human. If they're done, call finish.",
56
+ ['start_booking', 'manage_booking', ...LOOKUPS, 'finish'],
57
+ );
58
+ ctx.setInitialStep('triage');
59
+ }
60
+ // endregion: triage
61
+
62
+ function addBooking(builder: ContextBuilder): void {
63
+ const ctx = builder.addContext('booking');
64
+
65
+ // region: collect
66
+ // Gather mode asks one question at a time and stores the answers under
67
+ // global_data.booking_request. While it runs, the only tools are
68
+ // gather_submit and the tools each question lists.
69
+ const collect = scoped(ctx.addStep('collect'), 'Take the reservation details.', []);
70
+ collect.setGatherInfo({
71
+ outputKey: 'booking_request',
72
+ completionAction: 'search',
73
+ prompt: "You're taking a reservation. Ask each question in turn, briefly.",
74
+ });
75
+ collect.addGatherQuestion({
76
+ key: 'party_size',
77
+ question: 'How many people will be dining?',
78
+ type: 'integer',
79
+ functions: LOOKUPS,
80
+ });
81
+ collect.addGatherQuestion({
82
+ key: 'date',
83
+ question: 'What date would you like?',
84
+ functions: LOOKUPS,
85
+ prompt:
86
+ "Submit the caller's own words for the date, such as 'Friday' or " +
87
+ "'the 26th'. Do not turn it into a calendar date yourself.",
88
+ });
89
+ collect.addGatherQuestion({
90
+ key: 'time',
91
+ question: 'What time would you like?',
92
+ functions: LOOKUPS,
93
+ prompt: "Submit the time in digits, such as '7:30 PM'.",
94
+ });
95
+ collect.addGatherQuestion({
96
+ key: 'name',
97
+ question: 'What name should the reservation be under?',
98
+ confirm: true,
99
+ functions: LOOKUPS,
100
+ });
101
+ // endregion: collect
102
+
103
+ // region: booking-steps
104
+ scoped(
105
+ ctx.addStep('search'),
106
+ 'The details are collected. Call find_tables now. Say nothing about ' +
107
+ 'availability until it returns. If the caller changes a detail, pass only ' +
108
+ 'that detail to find_tables.',
109
+ ['find_tables', ...LOOKUPS],
110
+ );
111
+ scoped(
112
+ ctx.addStep('choose'),
113
+ 'Offer the options from the last find_tables result by number, and nothing ' +
114
+ 'else. When the caller picks one, call hold_table with its number. If they ' +
115
+ 'want a different time, date or party size, call find_tables with only what ' +
116
+ 'changed.',
117
+ ['hold_table', 'find_tables', ...LOOKUPS],
118
+ );
119
+ scoped(
120
+ ctx.addStep('review'),
121
+ 'A table is on hold. Read the proposal back as the last tool result gave it ' +
122
+ 'and ask the caller to confirm. Only if they clearly say yes, call ' +
123
+ "confirm_booking with the proposal's revision number. If they want a change, " +
124
+ 'call find_tables with only what changed.',
125
+ ['confirm_booking', 'find_tables', ...LOOKUPS],
126
+ );
127
+ scoped(
128
+ ctx.addStep('booked'),
129
+ 'The reservation is confirmed: ${global_data.booking.summary}. The ' +
130
+ 'confirmation code is ${global_data.booking.code_spoken}. Make sure the caller ' +
131
+ 'has the code, offer to text the details with send_confirmation_text, and ' +
132
+ "answer last questions with house_info. When they're done, call finish.",
133
+ ['send_confirmation_text', 'house_info', 'finish'],
134
+ );
135
+ ctx.setInitialStep('collect');
136
+ // endregion: booking-steps
137
+ }
138
+
139
+ // region: manage
140
+ function addManage(builder: ContextBuilder): void {
141
+ const ctx = builder.addContext('manage');
142
+ scoped(
143
+ ctx.addStep('verify'),
144
+ 'Ask for the six-character confirmation code and the last name on the ' +
145
+ 'reservation, then call verify_reservation. There is no other way to see a ' +
146
+ 'reservation, and you must not describe one before it is verified.',
147
+ ['verify_reservation', ...LOOKUPS],
148
+ );
149
+ // "hide" drops the verification back-and-forth from the model's view; the one
150
+ // thing this step needs is projected into its text instead.
151
+ scoped(
152
+ ctx.addStep('details'),
153
+ 'The caller verified this reservation: ${global_data.manage.summary}, status ' +
154
+ '${global_data.manage.status}. Tell them the details. If they want to cancel, ' +
155
+ 'call request_cancel. To change a reservation, they can cancel it and book a ' +
156
+ "new one. When they're done, call finish.",
157
+ ['request_cancel', ...LOOKUPS, 'finish'],
158
+ 'hide',
159
+ );
160
+ scoped(
161
+ ctx.addStep('confirm_cancel'),
162
+ "Read back the cancellation as the last tool result gave it and ask if they're " +
163
+ 'sure. Only if they clearly say yes, call confirm_cancel with its revision ' +
164
+ 'number. If they change their mind, call keep_reservation.',
165
+ ['confirm_cancel', 'keep_reservation', ...LOOKUPS],
166
+ );
167
+ scoped(
168
+ ctx.addStep('cancelled'),
169
+ 'The reservation is cancelled. Answer last questions with house_info, then call finish.',
170
+ ['house_info', 'finish'],
171
+ );
172
+ scoped(
173
+ ctx.addStep('locked'),
174
+ "Reservation lookups are locked for the rest of this call. Ask if they'd like " +
175
+ 'to speak with a person. Only if they say yes, call request_human; otherwise, ' +
176
+ 'call finish.',
177
+ ['request_human', 'finish'],
178
+ );
179
+ ctx.setInitialStep('verify');
180
+ }
181
+ // endregion: manage
182
+
183
+ // region: help
184
+ function addHelp(builder: ContextBuilder): void {
185
+ const ctx = builder.addContext('help');
186
+ const take = scoped(ctx.addStep('take_message'), 'Take a message for the host stand.', []);
187
+ take.setGatherInfo({
188
+ outputKey: 'message',
189
+ completionAction: 'save_message',
190
+ prompt: "Nobody is at the host stand, so you're taking a message for them.",
191
+ });
192
+ take.addGatherQuestion({ key: 'name', question: "What's your name?", functions: ['finish'] });
193
+ take.addGatherQuestion({
194
+ key: 'callback',
195
+ question: "What's the best number to call you back on?",
196
+ confirm: true,
197
+ functions: ['finish'],
198
+ });
199
+ take.addGatherQuestion({
200
+ key: 'body',
201
+ question: 'What would you like me to pass along?',
202
+ functions: ['finish'],
203
+ });
204
+
205
+ scoped(
206
+ ctx.addStep('save_message'),
207
+ "Call save_message now. Don't tell the caller it's saved until it returns. If " +
208
+ 'it asks for a correction, ask the caller and pass only the corrected detail.',
209
+ ['save_message'],
210
+ );
211
+ scoped(
212
+ ctx.addStep('message_saved'),
213
+ 'The message is saved. Tell the caller the host stand will call them back, ' +
214
+ 'answer last questions with house_info, then call finish.',
215
+ ['house_info', 'finish'],
216
+ );
217
+ ctx.setInitialStep('take_message');
218
+ }
219
+ // endregion: help