@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
@@ -6,11 +6,17 @@
6
6
  * variables, or the equivalent config params. Uses the Google Custom Search
7
7
  * JSON API to perform web searches and return formatted results.
8
8
  */
9
- import { SkillBase } from '../SkillBase.js';
9
+ import { SkillBase, defineSkillTool } from '../SkillBase.js';
10
10
  import { FunctionResult } from '../../FunctionResult.js';
11
+ import { _publicFetch } from '../../PublicFetch.js';
11
12
  import { MAX_SKILL_INPUT_LENGTH, validateUrl } from '../../SecurityUtils.js';
12
13
  import { getLogger } from '../../Logger.js';
13
- import * as cheerio from 'cheerio';
14
+ // cheerio is an OPTIONAL dependency (only the web_search / spider scraping
15
+ // skills use it). Import the TYPES statically (erased at compile time, zero
16
+ // runtime cost) and load the VALUE lazily via `await import('cheerio')` at the
17
+ // point of use — mirroring how RelayClient lazy-loads `ws`. A consumer who
18
+ // never scrapes never loads cheerio; if it is absent, `validatePackages()`
19
+ // (REQUIRED_PACKAGES below) reports it cleanly instead of crashing.
14
20
  const log = getLogger('WebSearchSkill');
15
21
  const DEFAULT_NO_RESULTS_MESSAGE = "I couldn't find quality results for '{query}'. " +
16
22
  'The search returned only low-quality or inaccessible pages. ' +
@@ -78,13 +84,14 @@ const UNWANTED_PATTERNS = [
78
84
  * {@link UNWANTED_PATTERNS} on either `class` or `id` (case-insensitive).
79
85
  * 5. Collapse whitespace and trim.
80
86
  *
81
- * Exported so `tests/skills/web-search-parity.test.ts` can verify byte-
82
- * identical behavior against Python BeautifulSoup fixtures; not re-exported
87
+ * Exported so the skill's test suite can verify byte-identical
88
+ * behavior against Python BeautifulSoup fixtures; not re-exported
83
89
  * from the skills barrel, so this stays internal to the skill module.
84
90
  *
85
91
  * @internal
86
92
  */
87
- export function extractTextFromHtml(html) {
93
+ export async function extractTextFromHtml(html) {
94
+ const cheerio = await import('cheerio');
88
95
  const normalized = html.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, content) => content);
89
96
  const $ = cheerio.load(normalized);
90
97
  let pickedHtml = '';
@@ -136,11 +143,17 @@ export function extractTextFromHtml(html) {
136
143
  *
137
144
  * Supported config: `tool_name`, `num_results`, `no_results_message`,
138
145
  * `safe_search`, `delay`, `max_content_length`, `oversample_factor`,
139
- * `min_quality_score`.
146
+ * `min_quality_score`, `response_prefix`, `response_postfix`, and the
147
+ * latency-control params `per_page_timeout`, `overall_deadline`,
148
+ * `parallel_scrape`, `snippets_only` (Python skill.py commits 51101da +
149
+ * 295745b). When the overall deadline fires or no scraped page meets the
150
+ * quality threshold, the handler falls back to formatting the CSE snippets.
140
151
  *
141
152
  * @example
142
153
  * ```ts
143
- * agent.addSkill('web_search', {
154
+ * import { AgentBase } from '@signalwire/sdk';
155
+ * const agent = new AgentBase({ name: 'demo', route: '/' });
156
+ * await agent.addSkillByName('web_search', {
144
157
  * api_key: process.env.GOOGLE_SEARCH_API_KEY,
145
158
  * search_engine_id: process.env.GOOGLE_CSE_ID,
146
159
  * num_results: 3,
@@ -149,11 +162,13 @@ export function extractTextFromHtml(html) {
149
162
  */
150
163
  export class WebSearchSkill extends SkillBase {
151
164
  // Python ground truth: skills/web_search/skill.py:559-567
152
- // REQUIRED_PACKAGES = ["bs4", "requests"] in Python; TS uses cheerio + fetch so [].
165
+ // REQUIRED_PACKAGES = ["bs4", "requests"] in Python; TS uses cheerio (optional
166
+ // dependency) + the built-in fetch. cheerio is declared so validatePackages()
167
+ // reports it cleanly if a consumer installed the SDK without the optional dep.
168
+ static REQUIRED_PACKAGES = ['cheerio'];
153
169
  static SKILL_NAME = 'web_search';
154
170
  static SKILL_DESCRIPTION = 'Search the web for information using Google Custom Search API';
155
171
  static SKILL_VERSION = '2.0.0';
156
- static REQUIRED_PACKAGES = [];
157
172
  static REQUIRED_ENV_VARS = [];
158
173
  static SUPPORTS_MULTIPLE_INSTANCES = true;
159
174
  static getParameterSchema() {
@@ -222,6 +237,48 @@ export class WebSearchSkill extends SkillBase {
222
237
  default: DEFAULT_NO_RESULTS_MESSAGE,
223
238
  required: false,
224
239
  },
240
+ // Latency-control params — Python skill.py:855-895 (commit 295745b).
241
+ // The SignalWire kernel times out webhook responses around 55s, so the
242
+ // handler MUST finish under that. These bound per-page and whole-call
243
+ // latency and offer a sub-second snippets-only mode.
244
+ per_page_timeout: {
245
+ type: 'number',
246
+ description: 'Maximum seconds to wait on a single page scrape.',
247
+ default: 2.0,
248
+ required: false,
249
+ min: 0.1,
250
+ },
251
+ overall_deadline: {
252
+ type: 'number',
253
+ description: 'Wall-clock budget in seconds for the whole tool call. In-flight scrapes are abandoned past this so the response beats the kernel webhook timeout.',
254
+ default: 10.0,
255
+ required: false,
256
+ min: 1.0,
257
+ },
258
+ parallel_scrape: {
259
+ type: 'boolean',
260
+ description: 'Scrape all candidate pages concurrently (Promise.all raced against the deadline) instead of sequentially.',
261
+ default: true,
262
+ required: false,
263
+ },
264
+ snippets_only: {
265
+ type: 'boolean',
266
+ description: 'Skip page scraping entirely and return Google CSE snippets only. Fastest mode (sub-second).',
267
+ default: false,
268
+ required: false,
269
+ },
270
+ response_prefix: {
271
+ type: 'string',
272
+ description: 'Optional text prepended (separated by a blank line) to every non-empty search result. Use to give the calling agent a mechanical cue, e.g. "tell the user this came from a public web search".',
273
+ default: '',
274
+ required: false,
275
+ },
276
+ response_postfix: {
277
+ type: 'string',
278
+ description: 'Optional text appended (separated by a blank line) to every non-empty search result.',
279
+ default: '',
280
+ required: false,
281
+ },
225
282
  safe_search: {
226
283
  type: 'string',
227
284
  description: 'Safe search level.',
@@ -296,26 +353,42 @@ export class WebSearchSkill extends SkillBase {
296
353
  const maxContentLength = this.getConfig('max_content_length', 32768);
297
354
  const delaySeconds = this.getConfig('delay', 0.5);
298
355
  const noResultsMessage = this.getConfig('no_results_message', DEFAULT_NO_RESULTS_MESSAGE);
356
+ // Optional prefix/postfix wrapped around every non-empty search result.
357
+ // Mirrors the response_format_callback pattern from the Python
358
+ // native_vector_search skill and Python web_search skill.py:587-595.
359
+ // Applied only on successful results — error/no-results paths stay as-is.
360
+ const responsePrefix = this.getConfig('response_prefix', '');
361
+ const responsePostfix = this.getConfig('response_postfix', '');
362
+ // Latency-control params — Python skill.py:670-674 (commit 51101da).
363
+ // perPageTimeout: max seconds to wait on a single page fetch.
364
+ // overallDeadline: wall-clock budget for the whole tool call; in-flight
365
+ // scrapes are abandoned (and their fetches aborted) past it.
366
+ // parallelScrape: dispatch all scrapes concurrently and race them
367
+ // against the deadline, vs. one-after-the-other.
368
+ // snippetsOnly: skip scraping; format CSE snippets directly (sub-second).
369
+ const perPageTimeoutMs = Math.max(100, this.getConfig('per_page_timeout', 2.0) * 1000);
370
+ const overallDeadlineMs = Math.max(1000, this.getConfig('overall_deadline', 10.0) * 1000);
371
+ const parallelScrape = this.getConfig('parallel_scrape', true);
372
+ const snippetsOnly = this.getConfig('snippets_only', false);
299
373
  const toolName = this.getToolName();
300
374
  return [
301
- {
375
+ defineSkillTool({
302
376
  name: toolName,
303
377
  description: 'Search the web for high-quality information, automatically filtering low-quality results',
304
378
  parameters: {
305
379
  query: {
306
380
  type: 'string',
307
- description: "The search query - what you want to find information about",
381
+ description: 'The search query - what you want to find information about',
308
382
  },
309
383
  },
310
- required: ['query'],
311
- handler: async (args, _rawData) => {
312
- const rawQuery = args['query'];
313
- if (!rawQuery ||
314
- typeof rawQuery !== 'string' ||
315
- rawQuery.trim().length === 0) {
384
+ // Python passes no `required` (web_search/skill.py:707), so the wire
385
+ // schema has no `required` key. args.query is `string | undefined`,
386
+ // narrowed by the guard below.
387
+ handler: async (args) => {
388
+ if (!args.query || args.query.trim().length === 0) {
316
389
  return new FunctionResult('Please provide a search query. What would you like me to search for?');
317
390
  }
318
- const query = rawQuery.trim();
391
+ const query = args.query.trim();
319
392
  if (query.length > MAX_SKILL_INPUT_LENGTH) {
320
393
  return new FunctionResult('Search query is too long.');
321
394
  }
@@ -336,7 +409,11 @@ export class WebSearchSkill extends SkillBase {
336
409
  try {
337
410
  const encodedQuery = encodeURIComponent(query);
338
411
  const safeParam = safeSearch !== 'off' ? `&safe=${safeSearch}` : '';
339
- const url = `https://www.googleapis.com/customsearch/v1` +
412
+ // Base URL is normally googleapis.com; the porting-sdk's
413
+ // `audit_skills_dispatch.py` overrides via `WEB_SEARCH_BASE_URL`
414
+ // so the loopback fixture can stand in for Google CSE.
415
+ const base = process.env['WEB_SEARCH_BASE_URL'] ?? 'https://www.googleapis.com';
416
+ const url = `${base.replace(/\/+$/, '')}/customsearch/v1` +
340
417
  // Python uses timeout=15 on the API request (skill.py:220).
341
418
  `?key=${apiKey}&cx=${searchEngineId}&q=${encodedQuery}&num=${fetchCount}${safeParam}`;
342
419
  const controller = new AbortController();
@@ -356,40 +433,108 @@ export class WebSearchSkill extends SkillBase {
356
433
  if (!data.items || data.items.length === 0) {
357
434
  return new FunctionResult(WebSearchSkill._formatNoResultsMessage(noResultsMessage, query));
358
435
  }
436
+ // Snippets-only fast path — Python skill.py:454-456 (commit
437
+ // 51101da). Skip page scraping entirely and format the CSE
438
+ // snippets directly. Returns sub-second; good enough for most
439
+ // voice answers and never risks the kernel webhook timeout.
440
+ if (snippetsOnly) {
441
+ return new FunctionResult(WebSearchSkill._formatSnippetResults(query, data.items, count));
442
+ }
443
+ // Overall-deadline budget — Python skill.py:436 (commit 51101da).
444
+ // Wall-clock instant past which any not-yet-finished scrape is
445
+ // abandoned. A shared AbortController lets the deadline cancel
446
+ // in-flight fetches (best-effort) so the response always beats the
447
+ // kernel webhook timeout.
448
+ const deadlineAt = Date.now() + overallDeadlineMs;
449
+ const deadlineController = new AbortController();
450
+ const deadlineTimer = setTimeout(() => deadlineController.abort(), overallDeadlineMs);
359
451
  const allCandidates = [];
360
- for (let idx = 0; idx < data.items.length; idx++) {
361
- const item = data.items[idx];
452
+ // Fetch + score one candidate. Returns an enriched Candidate or
453
+ // null (parse failure / SSRF rejection / below-threshold / past
454
+ // the deadline). Mirrors Python's `_scrape_one` (skill.py:458-481).
455
+ const scrapeOne = async (item) => {
456
+ if (Date.now() >= deadlineAt)
457
+ return null;
458
+ let host;
362
459
  try {
363
460
  // SSRF / URL sanity — Python has no explicit pre-check; the
364
461
  // scraper's inner `validate_url` handles it. We pre-parse to
365
462
  // derive `host` for the domain-diverse selection pass.
366
- const host = new URL(item.link).host;
367
- const result = await this._scrapeUrl(item.link, maxContentLength, 10_000, query);
368
- if (result !== null && result.score >= minQualityScore) {
369
- allCandidates.push({
370
- item,
371
- text: result.text,
372
- score: result.score,
373
- host,
374
- text_length: result.text_length,
375
- sentence_count: result.sentence_count,
376
- query_relevance: result.query_relevance,
377
- query_words_found: result.query_words_found,
378
- domain: result.domain,
379
- });
380
- }
463
+ host = new URL(item.link).host;
381
464
  }
382
465
  catch {
383
- // URL parse failure — skip this result but still apply the
384
- // inter-request delay below so cadence matches Python.
466
+ return null;
467
+ }
468
+ const result = await this._scrapeUrl(item.link, maxContentLength, perPageTimeoutMs, query, deadlineController.signal);
469
+ if (result === null || result.score < minQualityScore) {
470
+ return null;
471
+ }
472
+ return {
473
+ item,
474
+ text: result.text,
475
+ score: result.score,
476
+ host,
477
+ text_length: result.text_length,
478
+ sentence_count: result.sentence_count,
479
+ query_relevance: result.query_relevance,
480
+ query_words_found: result.query_words_found,
481
+ domain: result.domain,
482
+ };
483
+ };
484
+ try {
485
+ if (parallelScrape) {
486
+ // Dispatch every scrape at once and race the whole batch
487
+ // against an overall-deadline timer. Python skill.py:484-503
488
+ // uses a ThreadPoolExecutor + as_completed and harvests each
489
+ // future as it finishes, breaking out when time runs out. To
490
+ // match that (keep the fast scrapes even if a slow sibling
491
+ // pushes the batch past the deadline) each scrapeOne pushes its
492
+ // own result into allCandidates as it resolves, rather than
493
+ // collecting atomically. Promise.race against a deadline
494
+ // sentinel then returns as soon as either the whole batch
495
+ // settles or the deadline fires.
496
+ const allScrapes = Promise.allSettled(data.items.map((it) => scrapeOne(it).then((cand) => {
497
+ if (cand !== null)
498
+ allCandidates.push(cand);
499
+ })));
500
+ const deadlineSentinel = Symbol('deadline');
501
+ const deadlineRace = new Promise((resolve) => {
502
+ const remaining = Math.max(0, deadlineAt - Date.now());
503
+ const t = setTimeout(() => resolve(deadlineSentinel), remaining);
504
+ // Don't keep the event loop alive solely for this timer.
505
+ if (typeof t.unref === 'function')
506
+ t.unref();
507
+ });
508
+ // When the deadline wins, allCandidates already holds whatever
509
+ // resolved in time; the stragglers are aborted in `finally`.
510
+ await Promise.race([allScrapes, deadlineRace]);
385
511
  }
386
- // Python skill.py:461-463 sleeps `delay` seconds between every
387
- // iteration regardless of success/failure. Skip on the last
388
- // iteration because there is nothing left to fetch.
389
- if (delaySeconds > 0 && idx < data.items.length - 1) {
390
- await new Promise((r) => setTimeout(r, delaySeconds * 1000));
512
+ else {
513
+ // Sequential mode (legacy). Still honors the overall deadline:
514
+ // bail before starting a scrape once we're out of time.
515
+ // Python skill.py:505-513.
516
+ for (let idx = 0; idx < data.items.length; idx++) {
517
+ if (Date.now() >= deadlineAt)
518
+ break;
519
+ const cand = await scrapeOne(data.items[idx]); // idx < length
520
+ if (cand !== null)
521
+ allCandidates.push(cand);
522
+ // Python skill.py:512-513 sleeps `delay` seconds between
523
+ // iterations. Skip on the last iteration (nothing left).
524
+ if (delaySeconds > 0 && idx < data.items.length - 1) {
525
+ if (Date.now() >= deadlineAt)
526
+ break;
527
+ await new Promise((r) => setTimeout(r, delaySeconds * 1000));
528
+ }
529
+ }
391
530
  }
392
531
  }
532
+ finally {
533
+ clearTimeout(deadlineTimer);
534
+ // Release any fetches still in flight (parallel mode harvested a
535
+ // subset; abort the stragglers so sockets don't dangle).
536
+ deadlineController.abort();
537
+ }
393
538
  // Two-pass selection: sort by score desc, then (1) take the
394
539
  // highest-quality result per unique host, (2) fill remaining
395
540
  // slots from the leftovers. Mirrors Python skill.py:~495-540.
@@ -414,10 +559,16 @@ export class WebSearchSkill extends SkillBase {
414
559
  }
415
560
  const scored = chosen;
416
561
  if (allCandidates.length === 0 || scored.length === 0) {
417
- // Python skill.py:465-466 / 488-489 return a plain "no quality
418
- // results" string, which the outer handler (skill.py:640-642)
419
- // detects and replaces with the configured `no_results_message`.
420
- // Skip the middleman and return the configured message directly.
562
+ // Time ran out (overall_deadline fired), every scrape failed
563
+ // (network / SSRF rejection / per_page_timeout), or every page
564
+ // was below the quality threshold. Python skill.py:515-519
565
+ // (commit 51101da) falls back to formatting the CSE snippets it
566
+ // already has rather than an empty "no results" message, so the
567
+ // kernel never sees a webhook timeout and the model always gets
568
+ // useful context back.
569
+ if (data.items && data.items.length > 0) {
570
+ return new FunctionResult(WebSearchSkill._formatSnippetResults(query, data.items, count));
571
+ }
421
572
  return new FunctionResult(WebSearchSkill._formatNoResultsMessage(noResultsMessage, query));
422
573
  }
423
574
  // Per-result content budget — Python skill.py:491-495 divides
@@ -436,7 +587,7 @@ export class WebSearchSkill extends SkillBase {
436
587
  `Showing top ${scored.length} from diverse sources:\n`,
437
588
  ];
438
589
  for (let i = 0; i < scored.length; i++) {
439
- const cand = scored[i];
590
+ const cand = scored[i]; // i < length
440
591
  let block = `=== RESULT ${i + 1} (Quality: ${cand.score.toFixed(2)}) ===\n`;
441
592
  block += `Title: ${cand.item.title}\n`;
442
593
  block += `URL: ${cand.item.link}\n`;
@@ -461,7 +612,18 @@ export class WebSearchSkill extends SkillBase {
461
612
  // Python's outer `_web_search_handler` (skill.py:644) wraps the
462
613
  // inner formatter output with a `"Quality web search results for
463
614
  // '<query>':\n\n"` preamble.
464
- return new FunctionResult(`Quality web search results for '${query}':\n\n${innerOutput}`);
615
+ let responseText = `Quality web search results for '${query}':\n\n${innerOutput}`;
616
+ // Python skill.py:653-656 wraps the success response with optional
617
+ // prefix/postfix separated by a blank line. Only applied here
618
+ // (success path); error / no-results / snippet-fallback paths
619
+ // intentionally bypass the wrapping.
620
+ if (responsePrefix) {
621
+ responseText = `${responsePrefix}\n\n${responseText}`;
622
+ }
623
+ if (responsePostfix) {
624
+ responseText = `${responseText}\n\n${responsePostfix}`;
625
+ }
626
+ return new FunctionResult(responseText);
465
627
  }
466
628
  catch (err) {
467
629
  log.error('web_search_failed', {
@@ -470,17 +632,47 @@ export class WebSearchSkill extends SkillBase {
470
632
  return new FunctionResult('Sorry, I encountered an error while searching. Please try again later.');
471
633
  }
472
634
  },
473
- },
635
+ }),
474
636
  ];
475
637
  }
638
+ /**
639
+ * Format Google CSE snippets without fetching the underlying pages.
640
+ *
641
+ * Python equivalent: `GoogleSearchScraper._format_snippet_results`
642
+ * (skill.py:416-437, commit 51101da). Used by the `snippets_only` fast path
643
+ * and as the graceful fallback when page scraping is abandoned by the
644
+ * `overall_deadline` or every page falls below the quality threshold. The
645
+ * result is shorter than a fully-scraped response but always non-empty when
646
+ * the CSE returned anything, so the kernel never sees a webhook timeout.
647
+ *
648
+ * @param query - The original search query (echoed in the header).
649
+ * @param items - Raw CSE items (title / link / snippet).
650
+ * @param numResults - How many snippets to surface (top N).
651
+ * @returns A formatted, non-empty snippet block.
652
+ */
653
+ static _formatSnippetResults(query, items, numResults) {
654
+ if (!items || items.length === 0) {
655
+ return `No search results found for query: ${query}`;
656
+ }
657
+ const top = items.slice(0, Math.max(numResults, 1));
658
+ const lines = [`Snippet-only results for '${query}' (page content not scraped):`, ''];
659
+ for (let i = 0; i < top.length; i++) {
660
+ const it = top[i]; // i < length
661
+ lines.push(`=== RESULT ${i + 1} ===`);
662
+ lines.push(`Title: ${it.title}`);
663
+ lines.push(`URL: ${it.link}`);
664
+ const snippet = (it.snippet ?? '').replace(/\n/g, ' ').trim();
665
+ lines.push(`Snippet: ${snippet}`);
666
+ lines.push('');
667
+ }
668
+ return lines.join('\n');
669
+ }
476
670
  /** Apply the `{query}` template to the no-results message. */
477
671
  static _formatNoResultsMessage(template, query) {
478
- return template.includes('{query}')
479
- ? template.replace(/\{query\}/g, query)
480
- : template;
672
+ return template.includes('{query}') ? template.replace(/\{query\}/g, query) : template;
481
673
  }
482
674
  /**
483
- * Check whether the URL points at Reddit. Python parity: `is_reddit_url`
675
+ * Check whether the URL points at Reddit. Python equivalent: `is_reddit_url`
484
676
  * (skill.py:66).
485
677
  */
486
678
  static _isRedditUrl(url) {
@@ -496,7 +688,7 @@ export class WebSearchSkill extends SkillBase {
496
688
  * Fetch a Reddit URL via the `.json` endpoint and build a structured summary
497
689
  * of the post + top comments.
498
690
  *
499
- * Python parity: `extract_reddit_content` (skill.py:71-190). Matches the
691
+ * Python equivalent: `extract_reddit_content` (skill.py:71-190). Matches the
500
692
  * post-title/author/score/comments assembly and the top-20 → valid → top-5
501
693
  * comment pipeline. Returns just the compiled text — Python's
502
694
  * `search_and_scrape_best` unconditionally overwrites Reddit's
@@ -507,26 +699,24 @@ export class WebSearchSkill extends SkillBase {
507
699
  * Falls through to HTML extraction on JSON fetch failure or malformed
508
700
  * payload, matching Python's `except Exception: fall back` behavior.
509
701
  */
510
- async _extractRedditContent(url, contentLimit, timeoutMs) {
702
+ async _extractRedditContent(url, contentLimit, timeoutMs, externalSignal) {
511
703
  try {
512
704
  if (!(await validateUrl(url))) {
513
705
  log.debug('web_search: reddit URL rejected by SSRF guard', { url });
514
706
  return null;
515
707
  }
516
- const jsonUrl = url.endsWith('.json')
517
- ? url
518
- : `${url.replace(/\/+$/, '')}.json`;
519
- const controller = new AbortController();
520
- const timer = setTimeout(() => controller.abort(), timeoutMs);
708
+ const jsonUrl = url.endsWith('.json') ? url : `${url.replace(/\/+$/, '')}.json`;
709
+ const { signal, dispose } = WebSearchSkill._fetchSignal(timeoutMs, externalSignal);
521
710
  let response;
522
711
  try {
523
- response = await fetch(jsonUrl, {
524
- signal: controller.signal,
712
+ // _publicFetch checks every redirect and the connected address.
713
+ response = await _publicFetch(jsonUrl, {
714
+ signal,
525
715
  headers: { 'User-Agent': 'SignalWire-WebSearch/2.0' },
526
716
  });
527
717
  }
528
718
  finally {
529
- clearTimeout(timer);
719
+ dispose();
530
720
  }
531
721
  if (!response.ok) {
532
722
  log.debug('web_search: reddit JSON non-200', {
@@ -567,10 +757,7 @@ export class WebSearchSkill extends SkillBase {
567
757
  if (c.kind !== 't1' || !c.data)
568
758
  continue;
569
759
  const body = (c.data['body'] ?? '').trim();
570
- if (!body ||
571
- body === '[removed]' ||
572
- body === '[deleted]' ||
573
- body.length <= 50) {
760
+ if (!body || body === '[removed]' || body === '[deleted]' || body.length <= 50) {
574
761
  continue;
575
762
  }
576
763
  validComments.push({
@@ -612,12 +799,18 @@ export class WebSearchSkill extends SkillBase {
612
799
  * to match Python's `search_and_scrape_best` overwrite behavior
613
800
  * (skill.py:447-448).
614
801
  *
615
- * Python parity: `extract_text_from_url` (skill.py:192-202). Returns `null`
802
+ * Python equivalent: `extract_text_from_url` (skill.py:192-202). Returns `null`
616
803
  * on any failure (network, non-200, parse error, or SSRF rejection).
804
+ *
805
+ * @param timeoutMs - Per-page fetch timeout (Python `per_page_timeout`).
806
+ * @param externalSignal - Optional shared abort signal driven by the
807
+ * handler's `overall_deadline`. When it fires, in-flight fetches are
808
+ * cancelled even if the per-page timeout has not elapsed. Combined with
809
+ * the per-page timeout via {@link AbortSignal.any}.
617
810
  */
618
- async _scrapeUrl(url, contentLimit, timeoutMs, query) {
811
+ async _scrapeUrl(url, contentLimit, timeoutMs, query, externalSignal) {
619
812
  if (WebSearchSkill._isRedditUrl(url)) {
620
- const reddit = await this._extractRedditContent(url, contentLimit, timeoutMs);
813
+ const reddit = await this._extractRedditContent(url, contentLimit, timeoutMs, externalSignal);
621
814
  if (reddit) {
622
815
  const metrics = WebSearchSkill._qualityMetrics(reddit.text, url, query);
623
816
  return { text: reddit.text, ...metrics };
@@ -631,11 +824,14 @@ export class WebSearchSkill extends SkillBase {
631
824
  log.debug('web_search: scrape URL rejected by SSRF guard', { url });
632
825
  return null;
633
826
  }
634
- const controller = new AbortController();
635
- const timer = setTimeout(() => controller.abort(), timeoutMs);
827
+ // Per-page timeout OR the shared overall-deadline signal, whichever trips
828
+ // first. The deadline can thus cancel a slow fetch that hasn't yet hit its
829
+ // own per-page timeout.
830
+ const { signal, dispose } = WebSearchSkill._fetchSignal(timeoutMs, externalSignal);
636
831
  try {
637
- const response = await fetch(url, {
638
- signal: controller.signal,
832
+ // _publicFetch checks every redirect and the connected address.
833
+ const response = await _publicFetch(url, {
834
+ signal,
639
835
  headers: {
640
836
  'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
641
837
  },
@@ -645,7 +841,7 @@ export class WebSearchSkill extends SkillBase {
645
841
  return null;
646
842
  }
647
843
  const body = await response.text();
648
- let text = extractTextFromHtml(body);
844
+ let text = await extractTextFromHtml(body);
649
845
  if (text.length > contentLimit) {
650
846
  text = text.slice(0, contentLimit);
651
847
  }
@@ -662,8 +858,33 @@ export class WebSearchSkill extends SkillBase {
662
858
  return null;
663
859
  }
664
860
  finally {
665
- clearTimeout(timer);
861
+ dispose();
862
+ }
863
+ }
864
+ /**
865
+ * Build the {@link AbortSignal} for a single page fetch: a per-page timeout,
866
+ * optionally combined with an externally-supplied deadline signal so either
867
+ * one can cancel the request. Returns a `dispose` callback that clears the
868
+ * internal timer (call it from a `finally`).
869
+ *
870
+ * @param timeoutMs - Per-page timeout in milliseconds.
871
+ * @param externalSignal - Optional shared abort signal (overall deadline).
872
+ */
873
+ static _fetchSignal(timeoutMs, externalSignal) {
874
+ const controller = new AbortController();
875
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
876
+ const dispose = () => clearTimeout(timer);
877
+ if (!externalSignal) {
878
+ return { signal: controller.signal, dispose };
666
879
  }
880
+ // If the deadline already fired, short-circuit to an aborted signal.
881
+ if (externalSignal.aborted) {
882
+ controller.abort();
883
+ }
884
+ return {
885
+ signal: AbortSignal.any([controller.signal, externalSignal]),
886
+ dispose,
887
+ };
667
888
  }
668
889
  /**
669
890
  * Six-factor content quality metrics (score + sub-metrics used in the
@@ -671,7 +892,7 @@ export class WebSearchSkill extends SkillBase {
671
892
  * boilerplate penalty, sentence structure, domain reputation, and query
672
893
  * relevance.
673
894
  *
674
- * Python parity: `_calculate_content_quality` (skill.py:284-414). Preserves
895
+ * Python equivalent: `_calculate_content_quality` (skill.py:284-414). Preserves
675
896
  * the weights (0.25/0.10/0.10/0.15/0.15/0.25), the 26-phrase boilerplate
676
897
  * list, the quality/low-quality domain lists, and the phrase-match bonus
677
898
  * on relevance. Also returns the same metric fields Python exposes
@@ -712,9 +933,7 @@ export class WebSearchSkill extends SkillBase {
712
933
  }
713
934
  // 2. Word diversity — unique / (total * 0.3). Python skill.py:313-321.
714
935
  const words = text.toLowerCase().split(/\s+/).filter(Boolean);
715
- const diversityScore = words.length === 0
716
- ? 0
717
- : Math.min(1, new Set(words).size / (words.length * 0.3));
936
+ const diversityScore = words.length === 0 ? 0 : Math.min(1, new Set(words).size / (words.length * 0.3));
718
937
  // 3. Boilerplate penalty — 26 phrases, -15% per phrase.
719
938
  // Python skill.py:324-335.
720
939
  const boilerplatePhrases = [
@@ -750,9 +969,7 @@ export class WebSearchSkill extends SkillBase {
750
969
  const boilerplatePenalty = Math.max(0, 1 - boilerplateCount * 0.15);
751
970
  // 4. Sentence score — count sentences with >30 chars; target 10.
752
971
  // Python skill.py:339-342.
753
- const sentences = text
754
- .split(/[.!?]+/)
755
- .filter((s) => s.trim().length > 30);
972
+ const sentences = text.split(/[.!?]+/).filter((s) => s.trim().length > 30);
756
973
  const sentenceScore = Math.min(1, sentences.length / 10);
757
974
  // 5. Domain score — quality domains +1.5×, low-quality 0.1×, else 1.0.
758
975
  // Python skill.py:344-365.