@terreno/ai 57.8.0 → 57.10.1

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 (425) hide show
  1. package/.cursorrules +2 -2
  2. package/README.md +2 -1
  3. package/bunfig.toml +1 -1
  4. package/dist/aiApp.d.ts +16 -5
  5. package/dist/aiApp.js +17 -7
  6. package/dist/harness/adminScreens.d.ts +6 -0
  7. package/dist/harness/adminScreens.js +11 -0
  8. package/dist/harness/agentLoop.d.ts +61 -0
  9. package/dist/harness/agentLoop.js +798 -0
  10. package/dist/harness/agentTaskNames.d.ts +4 -0
  11. package/dist/harness/agentTaskNames.js +7 -0
  12. package/dist/harness/approvalPolicy.d.ts +3 -0
  13. package/dist/harness/approvalPolicy.js +23 -0
  14. package/dist/harness/approvals.d.ts +101 -0
  15. package/dist/harness/approvals.js +468 -0
  16. package/dist/harness/commit.d.ts +238 -0
  17. package/dist/harness/commit.js +678 -0
  18. package/dist/harness/conversation.d.ts +75 -0
  19. package/dist/harness/conversation.js +397 -0
  20. package/dist/harness/defineAgent.d.ts +9 -0
  21. package/dist/harness/defineAgent.js +65 -0
  22. package/dist/harness/defineTask.d.ts +11 -0
  23. package/dist/harness/defineTask.js +59 -0
  24. package/dist/harness/defineTool.d.ts +7 -0
  25. package/dist/harness/defineTool.js +36 -0
  26. package/dist/harness/definitionError.d.ts +8 -0
  27. package/dist/harness/definitionError.js +15 -0
  28. package/dist/harness/errors.d.ts +127 -0
  29. package/dist/harness/errors.js +101 -0
  30. package/dist/harness/eventHub.d.ts +45 -0
  31. package/dist/harness/eventHub.js +135 -0
  32. package/dist/harness/events.d.ts +95 -0
  33. package/dist/harness/events.js +267 -0
  34. package/dist/harness/executionEnv.d.ts +31 -0
  35. package/dist/harness/executionEnv.js +2 -0
  36. package/dist/harness/extensions.d.ts +82 -0
  37. package/dist/harness/extensions.js +274 -0
  38. package/dist/harness/harness.d.ts +163 -0
  39. package/dist/harness/harness.js +520 -0
  40. package/dist/harness/harnessApp.d.ts +44 -0
  41. package/dist/harness/harnessApp.js +62 -0
  42. package/dist/harness/internalRuntime.d.ts +16 -0
  43. package/dist/harness/internalRuntime.js +18 -0
  44. package/dist/harness/leases.d.ts +35 -0
  45. package/dist/harness/leases.js +86 -0
  46. package/dist/harness/memo.d.ts +24 -0
  47. package/dist/harness/memo.js +78 -0
  48. package/dist/harness/modelCall.d.ts +45 -0
  49. package/dist/harness/modelCall.js +147 -0
  50. package/dist/harness/models/harnessApproval.d.ts +2 -0
  51. package/dist/harness/models/harnessApproval.js +100 -0
  52. package/dist/harness/models/harnessConversation.d.ts +2 -0
  53. package/dist/harness/models/harnessConversation.js +117 -0
  54. package/dist/harness/models/harnessEvent.d.ts +3 -0
  55. package/dist/harness/models/harnessEvent.js +73 -0
  56. package/dist/harness/models/harnessInboxEvent.d.ts +2 -0
  57. package/dist/harness/models/harnessInboxEvent.js +58 -0
  58. package/dist/harness/models/harnessMemo.d.ts +2 -0
  59. package/dist/harness/models/harnessMemo.js +42 -0
  60. package/dist/harness/models/harnessMessage.d.ts +2 -0
  61. package/dist/harness/models/harnessMessage.js +73 -0
  62. package/dist/harness/models/harnessOwner.d.ts +2 -0
  63. package/dist/harness/models/harnessOwner.js +36 -0
  64. package/dist/harness/models/harnessTask.d.ts +2 -0
  65. package/dist/harness/models/harnessTask.js +186 -0
  66. package/dist/harness/ownership.d.ts +89 -0
  67. package/dist/harness/ownership.js +438 -0
  68. package/dist/harness/registry.d.ts +29 -0
  69. package/dist/harness/registry.js +93 -0
  70. package/dist/harness/retryBackoff.d.ts +31 -0
  71. package/dist/harness/retryBackoff.js +50 -0
  72. package/dist/harness/routes/approvals.d.ts +13 -0
  73. package/dist/harness/routes/approvals.js +93 -0
  74. package/dist/harness/routes/conversations.d.ts +11 -0
  75. package/dist/harness/routes/conversations.js +66 -0
  76. package/dist/harness/routes/events.d.ts +19 -0
  77. package/dist/harness/routes/events.js +215 -0
  78. package/dist/harness/routes/tasks.d.ts +11 -0
  79. package/dist/harness/routes/tasks.js +108 -0
  80. package/dist/harness/runners/inProcessRunner.d.ts +57 -0
  81. package/dist/harness/runners/inProcessRunner.js +196 -0
  82. package/dist/harness/runtime.d.ts +34 -0
  83. package/dist/harness/runtime.js +551 -0
  84. package/dist/harness/subagent.d.ts +53 -0
  85. package/dist/harness/subagent.js +134 -0
  86. package/dist/harness/suspend.d.ts +8 -0
  87. package/dist/harness/suspend.js +16 -0
  88. package/dist/harness/transaction.d.ts +3 -0
  89. package/dist/harness/transaction.js +22 -0
  90. package/dist/harness/waits.d.ts +100 -0
  91. package/dist/harness/waits.js +214 -0
  92. package/dist/index.d.ts +19 -1
  93. package/dist/index.js +45 -2
  94. package/dist/models/aiDataset.d.ts +2 -0
  95. package/dist/models/aiDataset.js +67 -0
  96. package/dist/models/aiRequest.js +1 -1
  97. package/dist/models/gptHistory.js +88 -2
  98. package/dist/observability/adminScreens.d.ts +5 -0
  99. package/dist/observability/adminScreens.js +32 -0
  100. package/dist/observability/compileTemplate.d.ts +1 -0
  101. package/dist/observability/compileTemplate.js +13 -0
  102. package/dist/observability/datasetImport.d.ts +11 -0
  103. package/dist/observability/datasetImport.js +185 -0
  104. package/dist/observability/evaluate.d.ts +31 -0
  105. package/dist/observability/evaluate.js +200 -0
  106. package/dist/observability/evaluatorTemplates.d.ts +17 -0
  107. package/dist/observability/evaluatorTemplates.js +111 -0
  108. package/dist/observability/jsonPath.d.ts +2 -0
  109. package/dist/observability/jsonPath.js +57 -0
  110. package/dist/observability/local/datasetStore.d.ts +87 -0
  111. package/dist/observability/local/datasetStore.js +326 -0
  112. package/dist/observability/local/evaluatorStore.d.ts +44 -0
  113. package/dist/observability/local/evaluatorStore.js +182 -0
  114. package/dist/observability/local/experimentRunner.d.ts +96 -0
  115. package/dist/observability/local/experimentRunner.js +419 -0
  116. package/dist/observability/local/localPlugin.d.ts +22 -0
  117. package/dist/observability/local/localPlugin.js +76 -0
  118. package/dist/observability/local/models/obsDataset.d.ts +2 -0
  119. package/dist/observability/local/models/obsDataset.js +37 -0
  120. package/dist/observability/local/models/obsDatasetItem.d.ts +2 -0
  121. package/dist/observability/local/models/obsDatasetItem.js +76 -0
  122. package/dist/observability/local/models/obsEvaluator.d.ts +2 -0
  123. package/dist/observability/local/models/obsEvaluator.js +98 -0
  124. package/dist/observability/local/models/obsExperiment.d.ts +2 -0
  125. package/dist/observability/local/models/obsExperiment.js +87 -0
  126. package/dist/observability/local/models/obsExperimentItem.d.ts +2 -0
  127. package/dist/observability/local/models/obsExperimentItem.js +45 -0
  128. package/dist/observability/local/models/obsPrompt.d.ts +2 -0
  129. package/dist/observability/local/models/obsPrompt.js +42 -0
  130. package/dist/observability/local/models/obsPromptLabel.d.ts +2 -0
  131. package/dist/observability/local/models/obsPromptLabel.js +39 -0
  132. package/dist/observability/local/models/obsPromptVersion.d.ts +2 -0
  133. package/dist/observability/local/models/obsPromptVersion.js +96 -0
  134. package/dist/observability/local/models/obsReviewItem.d.ts +2 -0
  135. package/dist/observability/local/models/obsReviewItem.js +75 -0
  136. package/dist/observability/local/models/obsScore.d.ts +2 -0
  137. package/dist/observability/local/models/obsScore.js +58 -0
  138. package/dist/observability/local/models/obsSpan.d.ts +2 -0
  139. package/dist/observability/local/models/obsSpan.js +64 -0
  140. package/dist/observability/local/models/obsTrace.d.ts +2 -0
  141. package/dist/observability/local/models/obsTrace.js +93 -0
  142. package/dist/observability/local/promptStore.d.ts +180 -0
  143. package/dist/observability/local/promptStore.js +444 -0
  144. package/dist/observability/local/reviewStore.d.ts +50 -0
  145. package/dist/observability/local/reviewStore.js +203 -0
  146. package/dist/observability/local/traceStore.d.ts +103 -0
  147. package/dist/observability/local/traceStore.js +325 -0
  148. package/dist/observability/observabilityApp.d.ts +24 -0
  149. package/dist/observability/observabilityApp.js +157 -0
  150. package/dist/observability/observabilityAppRegistry.d.ts +14 -0
  151. package/dist/observability/observabilityAppRegistry.js +16 -0
  152. package/dist/observability/permissions.d.ts +7 -0
  153. package/dist/observability/permissions.js +60 -0
  154. package/dist/observability/reviewPanels.d.ts +18 -0
  155. package/dist/observability/reviewPanels.js +46 -0
  156. package/dist/observability/routes/datasets.d.ts +7 -0
  157. package/dist/observability/routes/datasets.js +149 -0
  158. package/dist/observability/routes/evaluators.d.ts +7 -0
  159. package/dist/observability/routes/evaluators.js +123 -0
  160. package/dist/observability/routes/experiments.d.ts +7 -0
  161. package/dist/observability/routes/experiments.js +95 -0
  162. package/dist/observability/routes/observabilityRouteAccess.d.ts +13 -0
  163. package/dist/observability/routes/observabilityRouteAccess.js +67 -0
  164. package/dist/observability/routes/prompts.d.ts +12 -0
  165. package/dist/observability/routes/prompts.js +172 -0
  166. package/dist/observability/routes/requestAiService.d.ts +13 -0
  167. package/dist/observability/routes/requestAiService.js +21 -0
  168. package/dist/observability/routes/review.d.ts +7 -0
  169. package/dist/observability/routes/review.js +79 -0
  170. package/dist/observability/routes/status.d.ts +5 -0
  171. package/dist/observability/routes/status.js +31 -0
  172. package/dist/observability/routes/testMultiStage.d.ts +9 -0
  173. package/dist/observability/routes/testMultiStage.js +67 -0
  174. package/dist/observability/routes/traces.d.ts +7 -0
  175. package/dist/observability/routes/traces.js +129 -0
  176. package/dist/observability/schemaValidation.d.ts +5 -0
  177. package/dist/observability/schemaValidation.js +26 -0
  178. package/dist/observability/sopThresholds.d.ts +2 -0
  179. package/dist/observability/sopThresholds.js +21 -0
  180. package/dist/observability/status.d.ts +23 -0
  181. package/dist/observability/status.js +34 -0
  182. package/dist/observability/testMultiStageSchemas.d.ts +10 -0
  183. package/dist/observability/testMultiStageSchemas.js +79 -0
  184. package/dist/observability/testMultiStageWorkflow.d.ts +20 -0
  185. package/dist/observability/testMultiStageWorkflow.js +218 -0
  186. package/dist/observability/types.d.ts +159 -0
  187. package/dist/observability/types.js +67 -0
  188. package/dist/routes/files.js +20 -7
  189. package/dist/routes/gpt.js +179 -488
  190. package/dist/routes/gptActions.d.ts +9 -0
  191. package/dist/routes/gptActions.js +212 -0
  192. package/dist/routes/gptDatasets.d.ts +5 -0
  193. package/dist/routes/gptDatasets.js +94 -0
  194. package/dist/routes/gptHistories.d.ts +3 -1
  195. package/dist/routes/gptHistories.js +188 -2
  196. package/dist/service/aiDatasets.d.ts +57 -0
  197. package/dist/service/aiDatasets.js +253 -0
  198. package/dist/service/aiService.d.ts +50 -1
  199. package/dist/service/aiService.js +431 -77
  200. package/dist/service/askFiles.d.ts +49 -0
  201. package/dist/service/askFiles.js +162 -0
  202. package/dist/service/asks.d.ts +76 -0
  203. package/dist/service/asks.js +284 -0
  204. package/dist/service/chatTurn.d.ts +128 -0
  205. package/dist/service/chatTurn.js +1674 -0
  206. package/dist/service/fileStorage.d.ts +4 -0
  207. package/dist/service/fileStorage.js +7 -2
  208. package/dist/service/fileUploadsGate.d.ts +8 -0
  209. package/dist/service/fileUploadsGate.js +18 -0
  210. package/dist/service/fillActionIds.d.ts +6 -0
  211. package/dist/service/fillActionIds.js +79 -0
  212. package/dist/service/gemini.d.ts +3 -3
  213. package/dist/service/gemini.js +3 -3
  214. package/dist/service/jsonFenceModel.d.ts +7 -0
  215. package/dist/service/jsonFenceModel.js +45 -0
  216. package/dist/service/prompts.d.ts +52 -0
  217. package/dist/service/prompts.js +96 -1
  218. package/dist/service/sanitizeHtml.d.ts +11 -0
  219. package/dist/service/sanitizeHtml.js +108 -0
  220. package/dist/service/vertex.d.ts +6 -6
  221. package/dist/service/vertex.js +5 -5
  222. package/dist/types/harness.d.ts +934 -0
  223. package/dist/types/harness.js +133 -0
  224. package/dist/types/index.d.ts +219 -13
  225. package/dist/types/index.js +2 -0
  226. package/dist/types/observability.d.ts +288 -0
  227. package/dist/types/observability.js +2 -0
  228. package/package.json +17 -5
  229. package/src/aiApp.test.ts +207 -1
  230. package/src/aiApp.ts +31 -8
  231. package/src/harness/adminScreens.test.ts +34 -0
  232. package/src/harness/adminScreens.ts +11 -0
  233. package/src/harness/agentLoop.test.ts +1034 -0
  234. package/src/harness/agentLoop.ts +1082 -0
  235. package/src/harness/agentRecovery.test.ts +380 -0
  236. package/src/harness/agentTaskNames.ts +4 -0
  237. package/src/harness/approvalPolicy.ts +28 -0
  238. package/src/harness/approvals.test.ts +1094 -0
  239. package/src/harness/approvals.ts +644 -0
  240. package/src/harness/commit.ts +1049 -0
  241. package/src/harness/conversation.ts +503 -0
  242. package/src/harness/defineAgent.test.ts +92 -0
  243. package/src/harness/defineAgent.ts +82 -0
  244. package/src/harness/defineTask.test.ts +59 -0
  245. package/src/harness/defineTask.ts +76 -0
  246. package/src/harness/defineTool.ts +45 -0
  247. package/src/harness/definitionError.ts +13 -0
  248. package/src/harness/errors.test.ts +90 -0
  249. package/src/harness/errors.ts +119 -0
  250. package/src/harness/eventHub.test.ts +124 -0
  251. package/src/harness/eventHub.ts +159 -0
  252. package/src/harness/events.test.ts +757 -0
  253. package/src/harness/events.ts +384 -0
  254. package/src/harness/executionEnv.ts +34 -0
  255. package/src/harness/extensions.test.ts +1218 -0
  256. package/src/harness/extensions.ts +382 -0
  257. package/src/harness/harness.test.ts +693 -0
  258. package/src/harness/harness.ts +767 -0
  259. package/src/harness/harnessApp.ts +76 -0
  260. package/src/harness/internalRuntime.ts +44 -0
  261. package/src/harness/leases.ts +132 -0
  262. package/src/harness/memo.ts +107 -0
  263. package/src/harness/modelCall.test.ts +134 -0
  264. package/src/harness/modelCall.ts +200 -0
  265. package/src/harness/models/harnessApproval.ts +109 -0
  266. package/src/harness/models/harnessConversation.ts +142 -0
  267. package/src/harness/models/harnessEvent.ts +92 -0
  268. package/src/harness/models/harnessInboxEvent.ts +73 -0
  269. package/src/harness/models/harnessMemo.ts +43 -0
  270. package/src/harness/models/harnessMessage.ts +85 -0
  271. package/src/harness/models/harnessModels.test.ts +60 -0
  272. package/src/harness/models/harnessOwner.ts +40 -0
  273. package/src/harness/models/harnessTask.ts +201 -0
  274. package/src/harness/ownership.test.ts +1087 -0
  275. package/src/harness/ownership.ts +618 -0
  276. package/src/harness/recovery.test.ts +912 -0
  277. package/src/harness/registry.ts +124 -0
  278. package/src/harness/retries.test.ts +292 -0
  279. package/src/harness/retryBackoff.test.ts +100 -0
  280. package/src/harness/retryBackoff.ts +77 -0
  281. package/src/harness/routes/approvals.ts +123 -0
  282. package/src/harness/routes/conversations.test.ts +518 -0
  283. package/src/harness/routes/conversations.ts +102 -0
  284. package/src/harness/routes/events.ts +280 -0
  285. package/src/harness/routes/tasks.test.ts +198 -0
  286. package/src/harness/routes/tasks.ts +146 -0
  287. package/src/harness/runners/inProcessRunner.test.ts +402 -0
  288. package/src/harness/runners/inProcessRunner.ts +220 -0
  289. package/src/harness/runtime.ts +714 -0
  290. package/src/harness/subagent.test.ts +696 -0
  291. package/src/harness/subagent.ts +192 -0
  292. package/src/harness/suspend.ts +13 -0
  293. package/src/harness/transaction.ts +17 -0
  294. package/src/harness/versioning.test.ts +288 -0
  295. package/src/harness/waits.test.ts +693 -0
  296. package/src/harness/waits.ts +356 -0
  297. package/src/index.test.ts +13 -0
  298. package/src/index.ts +70 -0
  299. package/src/isolated/adminScreensConfig.isolated.ts +143 -0
  300. package/src/models/aiDataset.test.ts +34 -0
  301. package/src/models/aiDataset.ts +78 -0
  302. package/src/models/aiRequest.test.ts +2 -2
  303. package/src/models/aiRequest.ts +2 -1
  304. package/src/models/gptHistory.test.ts +156 -0
  305. package/src/models/gptHistory.ts +106 -4
  306. package/src/observability/adminScreens.test.ts +71 -0
  307. package/src/observability/adminScreens.ts +42 -0
  308. package/src/observability/compileTemplate.test.ts +14 -0
  309. package/src/observability/compileTemplate.ts +10 -0
  310. package/src/observability/datasetImport.test.ts +95 -0
  311. package/src/observability/datasetImport.ts +220 -0
  312. package/src/observability/evaluate.test.ts +549 -0
  313. package/src/observability/evaluate.ts +254 -0
  314. package/src/observability/evaluatorTemplates.ts +124 -0
  315. package/src/observability/jsonPath.test.ts +52 -0
  316. package/src/observability/jsonPath.ts +60 -0
  317. package/src/observability/local/datasetStore.test.ts +230 -0
  318. package/src/observability/local/datasetStore.ts +452 -0
  319. package/src/observability/local/evaluatorStore.test.ts +138 -0
  320. package/src/observability/local/evaluatorStore.ts +224 -0
  321. package/src/observability/local/experimentRunner.test.ts +489 -0
  322. package/src/observability/local/experimentRunner.ts +548 -0
  323. package/src/observability/local/localPlugin.ts +88 -0
  324. package/src/observability/local/models/obsDataset.ts +38 -0
  325. package/src/observability/local/models/obsDatasetItem.ts +80 -0
  326. package/src/observability/local/models/obsEvaluator.ts +102 -0
  327. package/src/observability/local/models/obsExperiment.ts +91 -0
  328. package/src/observability/local/models/obsExperimentItem.ts +52 -0
  329. package/src/observability/local/models/obsPrompt.ts +43 -0
  330. package/src/observability/local/models/obsPromptLabel.ts +43 -0
  331. package/src/observability/local/models/obsPromptVersion.ts +107 -0
  332. package/src/observability/local/models/obsReviewItem.ts +79 -0
  333. package/src/observability/local/models/obsScore.ts +59 -0
  334. package/src/observability/local/models/obsSpan.ts +65 -0
  335. package/src/observability/local/models/obsTrace.ts +94 -0
  336. package/src/observability/local/obsModels.test.ts +119 -0
  337. package/src/observability/local/promptStore.test.ts +351 -0
  338. package/src/observability/local/promptStore.ts +665 -0
  339. package/src/observability/local/reviewStore.test.ts +164 -0
  340. package/src/observability/local/reviewStore.ts +264 -0
  341. package/src/observability/local/traceStore.test.ts +264 -0
  342. package/src/observability/local/traceStore.ts +440 -0
  343. package/src/observability/observabilityApp.test.ts +92 -0
  344. package/src/observability/observabilityApp.ts +185 -0
  345. package/src/observability/observabilityAppRegistry.test.ts +30 -0
  346. package/src/observability/observabilityAppRegistry.ts +35 -0
  347. package/src/observability/permissions.test.ts +96 -0
  348. package/src/observability/permissions.ts +78 -0
  349. package/src/observability/reviewPanels.test.ts +35 -0
  350. package/src/observability/reviewPanels.ts +64 -0
  351. package/src/observability/routes/datasets.test.ts +176 -0
  352. package/src/observability/routes/datasets.ts +252 -0
  353. package/src/observability/routes/evaluators.test.ts +119 -0
  354. package/src/observability/routes/evaluators.ts +207 -0
  355. package/src/observability/routes/experiments.test.ts +282 -0
  356. package/src/observability/routes/experiments.ts +152 -0
  357. package/src/observability/routes/observabilityRbac.test.ts +767 -0
  358. package/src/observability/routes/observabilityRouteAccess.ts +106 -0
  359. package/src/observability/routes/prompts.test.ts +320 -0
  360. package/src/observability/routes/prompts.ts +263 -0
  361. package/src/observability/routes/requestAiService.ts +36 -0
  362. package/src/observability/routes/review.test.ts +120 -0
  363. package/src/observability/routes/review.ts +125 -0
  364. package/src/observability/routes/status.test.ts +116 -0
  365. package/src/observability/routes/status.ts +47 -0
  366. package/src/observability/routes/testMultiStage.test.ts +214 -0
  367. package/src/observability/routes/testMultiStage.ts +96 -0
  368. package/src/observability/routes/traces.test.ts +167 -0
  369. package/src/observability/routes/traces.ts +172 -0
  370. package/src/observability/schemaValidation.ts +29 -0
  371. package/src/observability/sopThresholds.ts +20 -0
  372. package/src/observability/status.test.ts +38 -0
  373. package/src/observability/status.ts +56 -0
  374. package/src/observability/testMultiStageSchemas.ts +95 -0
  375. package/src/observability/testMultiStageWorkflow.test.ts +114 -0
  376. package/src/observability/testMultiStageWorkflow.ts +307 -0
  377. package/src/observability/types.ts +262 -0
  378. package/src/routes/files.test.ts +84 -9
  379. package/src/routes/files.ts +23 -7
  380. package/src/routes/gpt.test.ts +3279 -0
  381. package/src/routes/gpt.ts +214 -552
  382. package/src/routes/gptActions.test.ts +241 -0
  383. package/src/routes/gptActions.ts +255 -0
  384. package/src/routes/gptApprovals.test.ts +762 -0
  385. package/src/routes/gptDatasets.test.ts +86 -0
  386. package/src/routes/gptDatasets.ts +104 -0
  387. package/src/routes/gptFiles.test.ts +589 -0
  388. package/src/routes/gptHistories.test.ts +933 -0
  389. package/src/routes/gptHistories.ts +266 -5
  390. package/src/routes/routes.test.ts +676 -5
  391. package/src/service/aiDatasets.test.ts +123 -0
  392. package/src/service/aiDatasets.ts +316 -0
  393. package/src/service/aiService.test.ts +614 -0
  394. package/src/service/aiService.ts +575 -111
  395. package/src/service/askFiles.test.ts +96 -0
  396. package/src/service/askFiles.ts +222 -0
  397. package/src/service/asks.test.ts +946 -0
  398. package/src/service/asks.ts +423 -0
  399. package/src/service/chatTurn.ts +2287 -0
  400. package/src/service/fileStorage.test.ts +11 -0
  401. package/src/service/fileStorage.ts +10 -2
  402. package/src/service/fileUploadsGate.ts +23 -0
  403. package/src/service/fillActionIds.test.ts +65 -0
  404. package/src/service/fillActionIds.ts +98 -0
  405. package/src/service/gemini.test.ts +16 -10
  406. package/src/service/gemini.ts +3 -3
  407. package/src/service/jsonFenceModel.test.ts +47 -0
  408. package/src/service/jsonFenceModel.ts +53 -0
  409. package/src/service/prompts.test.ts +21 -0
  410. package/src/service/prompts.ts +147 -0
  411. package/src/service/sanitizeHtml.test.ts +61 -0
  412. package/src/service/sanitizeHtml.ts +109 -0
  413. package/src/service/vertex.test.ts +49 -49
  414. package/src/service/vertex.ts +7 -8
  415. package/src/tests/bunSetup.test.ts +7 -4
  416. package/src/tests/bunSetup.ts +7 -7
  417. package/src/tests/chatHarness.ts +478 -0
  418. package/src/tests/generateStream.ts +49 -0
  419. package/src/tests/harnessErrors.ts +22 -0
  420. package/src/tests/harnessStreaming.ts +227 -0
  421. package/src/tests/helpers.ts +9 -2
  422. package/src/types/harness.ts +1095 -0
  423. package/src/types/index.ts +237 -12
  424. package/src/types/observability.ts +344 -0
  425. package/src/types/sanitize-html.d.ts +25 -0
@@ -0,0 +1,124 @@
1
+ import type {
2
+ HarnessAgentDefinition,
3
+ HarnessExtensionDefinition,
4
+ HarnessTaskDefinition,
5
+ } from "../types/harness";
6
+ import {HARNESS_TERMINAL_STATUSES} from "../types/harness";
7
+ import type {HarnessModels} from "./commit";
8
+ import {taskDefinitionKey} from "./defineTask";
9
+ import {harnessError} from "./errors";
10
+
11
+ /** Any task definition, whatever its input, state, and output types. */
12
+ export type AnyHarnessTaskDefinition = HarnessTaskDefinition<never, unknown, unknown>;
13
+
14
+ /** Anything `Harness.open({registry})` accepts. */
15
+ export type HarnessRegistryEntry =
16
+ | AnyHarnessTaskDefinition
17
+ | HarnessAgentDefinition
18
+ | HarnessExtensionDefinition;
19
+
20
+ /**
21
+ * Separate agents and extensions (each by unique name) from task definitions, and check
22
+ * that every extension an agent uses is registered.
23
+ */
24
+ export const splitRegistry = (
25
+ registry: ReadonlyArray<HarnessRegistryEntry>
26
+ ): {
27
+ agents: Map<string, HarnessAgentDefinition>;
28
+ extensions: Map<string, HarnessExtensionDefinition>;
29
+ tasks: AnyHarnessTaskDefinition[];
30
+ } => {
31
+ const agents = new Map<string, HarnessAgentDefinition>();
32
+ const extensions = new Map<string, HarnessExtensionDefinition>();
33
+ const tasks: AnyHarnessTaskDefinition[] = [];
34
+ for (const entry of registry) {
35
+ if (entry.kind === "extension") {
36
+ if (extensions.has(entry.name)) {
37
+ throw harnessError({
38
+ detail: `Harness registry lists extension "${entry.name}" more than once`,
39
+ kind: "configInvalid",
40
+ });
41
+ }
42
+ extensions.set(entry.name, entry);
43
+ continue;
44
+ }
45
+ if (entry.kind !== "agent") {
46
+ tasks.push(entry);
47
+ continue;
48
+ }
49
+ if (agents.has(entry.name)) {
50
+ throw harnessError({
51
+ detail: `Harness registry lists agent "${entry.name}" more than once`,
52
+ kind: "configInvalid",
53
+ });
54
+ }
55
+ agents.set(entry.name, entry);
56
+ }
57
+ for (const agent of agents.values()) {
58
+ const missing = agent.extensions.find((name) => !extensions.has(name));
59
+ if (missing !== undefined) {
60
+ throw harnessError({
61
+ detail: `Agent "${agent.name}" uses extension "${missing}", which is not in this harness registry`,
62
+ kind: "configInvalid",
63
+ });
64
+ }
65
+ }
66
+ return {agents, extensions, tasks};
67
+ };
68
+
69
+ /**
70
+ * Index definitions by exact `name@version`. Several versions of one name may sit side by
71
+ * side so in-flight runs keep the handler they started on; one version listed twice throws.
72
+ */
73
+ export const buildTaskRegistry = (
74
+ registry: ReadonlyArray<AnyHarnessTaskDefinition>
75
+ ): Map<string, HarnessTaskDefinition> => {
76
+ const definitions = new Map<string, HarnessTaskDefinition>();
77
+ for (const definition of registry) {
78
+ if (definitions.has(definition.key)) {
79
+ throw harnessError({
80
+ detail: `Harness registry lists ${definition.key} more than once`,
81
+ kind: "configInvalid",
82
+ });
83
+ }
84
+ definitions.set(definition.key, definition as unknown as HarnessTaskDefinition);
85
+ }
86
+ return definitions;
87
+ };
88
+
89
+ interface VersionCount {
90
+ _id: {name: string; version: number};
91
+ count: number;
92
+ }
93
+
94
+ /**
95
+ * Throw before any claim when a non-terminal task (pending, running, waiting, interrupted,
96
+ * or being aborted) is pinned to a `name@version` this registry lacks, listing each one
97
+ * with its task count. Running such a process would strand those tasks silently.
98
+ */
99
+ export const assertInFlightVersionsRegistered = async ({
100
+ definitions,
101
+ models,
102
+ }: {
103
+ definitions: Map<string, HarnessTaskDefinition>;
104
+ models: HarnessModels;
105
+ }): Promise<void> => {
106
+ const counts = await models.task.aggregate<VersionCount>([
107
+ {$match: {status: {$nin: [...HARNESS_TERMINAL_STATUSES]}}},
108
+ {$group: {_id: {name: "$name", version: "$version"}, count: {$sum: 1}}},
109
+ ]);
110
+ const missing = counts
111
+ .map(({_id, count}) => ({count, key: taskDefinitionKey(_id)}))
112
+ .filter(({key}) => !definitions.has(key))
113
+ .sort((a, b) => a.key.localeCompare(b.key));
114
+ if (missing.length === 0) {
115
+ return;
116
+ }
117
+ const listed = missing
118
+ .map(({count, key}) => `${key} (${count} task${count === 1 ? "" : "s"})`)
119
+ .join(", ");
120
+ throw harnessError({
121
+ detail: `Harness.start: in-flight tasks use task versions this registry does not register: ${listed}. Register those definitions (keep old versions until their tasks finish) or resolve the tasks first.`,
122
+ kind: "configInvalid",
123
+ });
124
+ };
@@ -0,0 +1,292 @@
1
+ import {afterEach, beforeAll, beforeEach, describe, expect, it} from "bun:test";
2
+ import {DateTime, Settings} from "luxon";
3
+
4
+ import {createLocalObservabilityPlugin} from "../observability/local/localPlugin";
5
+ import {registerObsSpan} from "../observability/local/models/obsSpan";
6
+ import {registerObsTrace} from "../observability/local/models/obsTrace";
7
+ import type {HarnessTaskDocument, HarnessTestHooks} from "../types/harness";
8
+ import type {ObsSpanModel, ObsTraceModel} from "../types/observability";
9
+ import {type AnyHarnessTaskDefinition, defineTask, Harness, InProcessRunner} from "./harness";
10
+ import {registerHarnessTask} from "./models/harnessTask";
11
+
12
+ const TaskModel = registerHarnessTask();
13
+ let SpanModel: ObsSpanModel;
14
+ let TraceModel: ObsTraceModel;
15
+ const openHarnesses: Harness[] = [];
16
+
17
+ const pause = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
18
+
19
+ const waitUntil = async (predicate: () => Promise<boolean>, label: string): Promise<void> => {
20
+ for (let i = 0; i < 300; i++) {
21
+ if (await predicate()) {
22
+ return;
23
+ }
24
+ await pause(10);
25
+ }
26
+ throw new Error(`waitUntil timed out: ${label}`);
27
+ };
28
+
29
+ const openHarness = async (
30
+ registry: ReadonlyArray<AnyHarnessTaskDefinition>,
31
+ testHooks?: HarnessTestHooks
32
+ ): Promise<Harness> => {
33
+ const harness = await Harness.open({
34
+ registry,
35
+ runner: new InProcessRunner({pollInterval: {milliseconds: 20}}),
36
+ testHooks,
37
+ });
38
+ openHarnesses.push(harness);
39
+ return harness;
40
+ };
41
+
42
+ const phaseSpans = async (
43
+ task: HarnessTaskDocument
44
+ ): Promise<Array<{error?: string; input?: unknown; output?: unknown; status: string}>> => {
45
+ const spans = await SpanModel.find({_id: {$ne: task.rootSpanId}, traceId: task.traceId}).sort({
46
+ _id: 1,
47
+ });
48
+ return spans.map((span) => ({
49
+ error: span.error,
50
+ input: span.input,
51
+ output: span.output,
52
+ status: span.status,
53
+ }));
54
+ };
55
+
56
+ /** A one-phase task whose phase throws until it has failed `failures` times. */
57
+ const flakyTask = ({
58
+ failures,
59
+ name,
60
+ retry,
61
+ }: {
62
+ failures: number;
63
+ name: string;
64
+ retry: {backoffMs?: number; maxAttempts?: number; maxBackoffMs?: number};
65
+ }): {attemptsSeen: number[]; definition: AnyHarnessTaskDefinition} => {
66
+ const attemptsSeen: number[] = [];
67
+ const definition = defineTask<unknown, unknown, {ok: boolean}>({
68
+ initial: () => ({phase: "call"}),
69
+ name,
70
+ phases: {
71
+ call: {
72
+ run: async (task, rt) => {
73
+ attemptsSeen.push(task.attempt);
74
+ if (attemptsSeen.length <= failures) {
75
+ throw new Error(`EHR 503 (run ${attemptsSeen.length})`);
76
+ }
77
+ await rt.commit({terminal: {result: {ok: true}, status: "completed"}});
78
+ },
79
+ },
80
+ },
81
+ retry,
82
+ version: 1,
83
+ });
84
+ return {attemptsSeen, definition: definition as unknown as AnyHarnessTaskDefinition};
85
+ };
86
+
87
+ describe("Harness phase retries", () => {
88
+ beforeAll(() => {
89
+ createLocalObservabilityPlugin();
90
+ SpanModel = registerObsSpan();
91
+ TraceModel = registerObsTrace();
92
+ });
93
+
94
+ beforeEach(async () => {
95
+ await Promise.all([
96
+ TaskModel.deleteMany({}),
97
+ SpanModel.deleteMany({}),
98
+ TraceModel.deleteMany({}),
99
+ ]);
100
+ });
101
+
102
+ afterEach(async () => {
103
+ Settings.now = () => Date.now();
104
+ await Promise.all(openHarnesses.splice(0).map((harness) => harness.stop()));
105
+ });
106
+
107
+ it("retries a phase that throws twice, then completes with one error span per failure", async () => {
108
+ const {attemptsSeen, definition} = flakyTask({
109
+ failures: 2,
110
+ name: "test.flaky",
111
+ retry: {backoffMs: 0, maxAttempts: 3},
112
+ });
113
+ const harness = await openHarness([definition]);
114
+ await harness.start();
115
+
116
+ const done = await harness.waitForTask((await harness.createTask(definition, {}))._id);
117
+ expect(done.status).toBe("completed");
118
+ expect(done.outcome?.result).toEqual({ok: true});
119
+ expect(attemptsSeen).toEqual([0, 1, 2]);
120
+
121
+ const spans = await phaseSpans(done);
122
+ expect(spans.map((span) => span.status)).toEqual(["error", "error", "ok"]);
123
+ expect(spans[0]).toMatchObject({
124
+ error: "EHR 503 (run 1)",
125
+ input: {attempt: 0},
126
+ output: {retry: {attempt: 1, maxAttempts: 3}},
127
+ });
128
+ expect(spans[1]).toMatchObject({
129
+ error: "EHR 503 (run 2)",
130
+ input: {attempt: 1},
131
+ output: {retry: {attempt: 2, maxAttempts: 3}},
132
+ });
133
+ const trace = await TraceModel.findExactlyOne({_id: done.traceId});
134
+ expect(trace.status).toBe("ok");
135
+ });
136
+
137
+ it("fails the task with outcome.error once maxAttempts runs are used up", async () => {
138
+ const {attemptsSeen, definition} = flakyTask({
139
+ failures: 5,
140
+ name: "test.exhausted",
141
+ retry: {backoffMs: 0, maxAttempts: 2},
142
+ });
143
+ const harness = await openHarness([definition]);
144
+ await harness.start();
145
+
146
+ const done = await harness.waitForTask((await harness.createTask(definition, {}))._id);
147
+ expect(done.status).toBe("failed");
148
+ expect(done.toObject().outcome).toEqual({error: "EHR 503 (run 2)", status: "failed"});
149
+ expect(done.attempt).toBe(2);
150
+ expect(done.runAt).toBeUndefined();
151
+ expect(attemptsSeen).toEqual([0, 1]);
152
+
153
+ const spans = await phaseSpans(done);
154
+ expect(spans.map((span) => span.status)).toEqual(["error", "error"]);
155
+ expect(spans[1].output).toEqual({terminal: {error: "EHR 503 (run 2)", status: "failed"}});
156
+ const trace = await TraceModel.findExactlyOne({_id: done.traceId});
157
+ expect(trace.status).toBe("error");
158
+ expect(trace.errorSummary).toBe("EHR 503 (run 2)");
159
+ });
160
+
161
+ it("uses the default policy (3 attempts) when the definition sets none", async () => {
162
+ const attemptsSeen: number[] = [];
163
+ const noPolicy = defineTask<unknown, unknown, unknown>({
164
+ initial: () => ({phase: "call"}),
165
+ name: "test.defaultPolicy",
166
+ phases: {
167
+ call: {
168
+ run: async (task) => {
169
+ attemptsSeen.push(task.attempt);
170
+ throw new Error("always down");
171
+ },
172
+ },
173
+ },
174
+ version: 1,
175
+ });
176
+ // Zero jitter keeps the default 1 s base backoff at its 0.5 s floor.
177
+ const harness = await openHarness([noPolicy], {random: () => 0});
178
+ await harness.start();
179
+
180
+ const done = await harness.waitForTask((await harness.createTask(noPolicy, {}))._id, {
181
+ timeout: {seconds: 10},
182
+ });
183
+ expect(done.status).toBe("failed");
184
+ expect(attemptsSeen).toEqual([0, 1, 2]);
185
+ });
186
+
187
+ it("schedules each retry with exponential backoff and does not run it before runAt", async () => {
188
+ const start = DateTime.now();
189
+ let clock = start;
190
+ Settings.now = () => clock.toMillis();
191
+
192
+ const {attemptsSeen, definition} = flakyTask({
193
+ failures: 2,
194
+ name: "test.backoff",
195
+ retry: {backoffMs: 1000, maxAttempts: 3, maxBackoffMs: 60_000},
196
+ });
197
+ // random 0.5 puts each delay at 75% of its capped value: 750 ms, then 1500 ms.
198
+ const harness = await openHarness([definition], {random: () => 0.5});
199
+ await harness.start();
200
+ const created = await harness.createTask(definition, {});
201
+
202
+ await waitUntil(
203
+ async () => (await TaskModel.findExactlyOne({_id: created._id})).attempt === 1,
204
+ "first retry"
205
+ );
206
+ const firstRetry = await TaskModel.findExactlyOne({_id: created._id});
207
+ expect(firstRetry.status).toBe("pending");
208
+ expect(firstRetry.lease?.token).toBeUndefined();
209
+ expect(firstRetry.runAt?.getTime()).toBe(start.plus({milliseconds: 750}).toMillis());
210
+
211
+ // Real time passes, Luxon's clock does not: the runner must leave the task alone.
212
+ await pause(200);
213
+ expect(attemptsSeen).toEqual([0]);
214
+
215
+ clock = start.plus({milliseconds: 749});
216
+ await pause(100);
217
+ expect(attemptsSeen).toEqual([0]);
218
+
219
+ clock = start.plus({milliseconds: 750});
220
+ await waitUntil(
221
+ async () => (await TaskModel.findExactlyOne({_id: created._id})).attempt === 2,
222
+ "second retry"
223
+ );
224
+ const secondRetry = await TaskModel.findExactlyOne({_id: created._id});
225
+ expect(secondRetry.runAt?.getTime()).toBe(start.plus({milliseconds: 750 + 1500}).toMillis());
226
+ await pause(150);
227
+ expect(attemptsSeen).toEqual([0, 1]);
228
+
229
+ clock = start.plus({milliseconds: 750 + 1500});
230
+ const done = await harness.waitForTask(created._id);
231
+ expect(done.status).toBe("completed");
232
+ expect(attemptsSeen).toEqual([0, 1, 2]);
233
+ // A terminal commit keeps the count of failures its final phase absorbed.
234
+ expect(done.attempt).toBe(2);
235
+ expect(done.runAt).toBeUndefined();
236
+ });
237
+
238
+ it("fails at once, without retrying, when the phase misuses the task API", async () => {
239
+ let runs = 0;
240
+ const misuse = defineTask<unknown, unknown, unknown>({
241
+ initial: () => ({phase: "start"}),
242
+ name: "test.misuse",
243
+ phases: {
244
+ start: {
245
+ run: async (_task, rt) => {
246
+ runs += 1;
247
+ await rt.commit({phase: "nowhere"});
248
+ },
249
+ },
250
+ },
251
+ retry: {backoffMs: 0, maxAttempts: 5},
252
+ version: 1,
253
+ });
254
+ const harness = await openHarness([misuse]);
255
+ await harness.start();
256
+
257
+ const done = await harness.waitForTask((await harness.createTask(misuse, {}))._id);
258
+ expect(done.status).toBe("failed");
259
+ expect(done.attempt).toBe(0);
260
+ expect(runs).toBe(1);
261
+ });
262
+
263
+ it("writes no retry when the run lost its lease before the phase threw", async () => {
264
+ const thrown = Promise.withResolvers<void>();
265
+ const stolen = defineTask<unknown, unknown, unknown>({
266
+ initial: () => ({phase: "call"}),
267
+ name: "test.stolenRetry",
268
+ phases: {
269
+ call: {
270
+ run: async (task) => {
271
+ await TaskModel.updateOne({_id: task.id}, {$set: {"lease.token": "other-runner"}});
272
+ thrown.resolve();
273
+ throw new Error("boom");
274
+ },
275
+ },
276
+ },
277
+ retry: {backoffMs: 0, maxAttempts: 3},
278
+ version: 1,
279
+ });
280
+ const harness = await openHarness([stolen]);
281
+ await harness.start();
282
+ const created = await harness.createTask(stolen, {});
283
+ await thrown.promise;
284
+ await harness.stop();
285
+
286
+ const task = await TaskModel.findExactlyOne({_id: created._id});
287
+ expect(task.status).toBe("running");
288
+ expect(task.attempt).toBe(0);
289
+ expect(task.lease?.token).toBe("other-runner");
290
+ expect(await SpanModel.countDocuments({name: "call"})).toBe(0);
291
+ });
292
+ });
@@ -0,0 +1,100 @@
1
+ import {afterEach, beforeEach, describe, expect, it} from "bun:test";
2
+ import {DateTime, Settings} from "luxon";
3
+ import {harnessErrorMatching} from "../tests/harnessErrors";
4
+ import {defineTask} from "./defineTask";
5
+ import {nextRetryAt, resolveRetryPolicy} from "./retryBackoff";
6
+
7
+ const policy = {backoffMs: 1000, maxAttempts: 5, maxBackoffMs: 5000};
8
+ const frozen = DateTime.fromISO("2026-10-03T12:00:00.000Z");
9
+
10
+ /** Retry delay in ms, measured against a frozen Luxon clock. */
11
+ const retryDelayMs = ({
12
+ failedAttempts,
13
+ random,
14
+ }: {
15
+ failedAttempts: number;
16
+ random?: () => number;
17
+ }): number => nextRetryAt({failedAttempts, policy, random}).toMillis() - frozen.toMillis();
18
+
19
+ describe("retryBackoff", () => {
20
+ beforeEach(() => {
21
+ Settings.now = () => frozen.toMillis();
22
+ });
23
+
24
+ afterEach(() => {
25
+ Settings.now = () => Date.now();
26
+ });
27
+
28
+ it("fills omitted retry fields with the defaults", () => {
29
+ expect(resolveRetryPolicy(undefined)).toEqual({
30
+ backoffMs: 1000,
31
+ maxAttempts: 3,
32
+ maxBackoffMs: 60_000,
33
+ });
34
+ expect(resolveRetryPolicy({maxAttempts: 7})).toEqual({
35
+ backoffMs: 1000,
36
+ maxAttempts: 7,
37
+ maxBackoffMs: 60_000,
38
+ });
39
+ });
40
+
41
+ it("doubles the delay per failure and caps it at maxBackoffMs", () => {
42
+ const fullDelay = (failedAttempts: number): number =>
43
+ retryDelayMs({failedAttempts, random: () => 1});
44
+ expect([1, 2, 3, 4, 5].map(fullDelay)).toEqual([1000, 2000, 4000, 5000, 5000]);
45
+ });
46
+
47
+ it("applies equal jitter: between half and all of the capped delay", () => {
48
+ expect(retryDelayMs({failedAttempts: 2, random: () => 0})).toBe(1000);
49
+ expect(retryDelayMs({failedAttempts: 2, random: () => 0.5})).toBe(1500);
50
+ for (let i = 0; i < 50; i++) {
51
+ const delay = retryDelayMs({failedAttempts: 3});
52
+ expect(delay).toBeGreaterThanOrEqual(2000);
53
+ expect(delay).toBeLessThanOrEqual(4000);
54
+ }
55
+ });
56
+
57
+ it("measures the retry time from Luxon's clock", () => {
58
+ const runAt = nextRetryAt({failedAttempts: 1, policy, random: () => 0.5});
59
+ expect(runAt.toMillis() - frozen.toMillis()).toBe(750);
60
+ });
61
+
62
+ it("rejects retry policies defineTask cannot apply", () => {
63
+ const build = (retry: Record<string, number>): unknown =>
64
+ defineTask({
65
+ initial: () => ({phase: "only"}),
66
+ name: "test.badRetry",
67
+ phases: {only: {run: async (_task, rt) => rt.commit({terminal: {status: "completed"}})}},
68
+ retry,
69
+ version: 1,
70
+ });
71
+ expect(() => build({maxAttempts: 0})).toThrow(
72
+ harnessErrorMatching("definitionInvalid", "retry.maxAttempts must be a positive integer")
73
+ );
74
+ expect(() => build({maxAttempts: 1.5})).toThrow(
75
+ harnessErrorMatching("definitionInvalid", "retry.maxAttempts must be a positive integer")
76
+ );
77
+ expect(() => build({backoffMs: -1})).toThrow(
78
+ harnessErrorMatching("definitionInvalid", "retry.backoffMs must be a non-negative number")
79
+ );
80
+ expect(() => build({backoffMs: 500, maxBackoffMs: 100})).toThrow(
81
+ harnessErrorMatching(
82
+ "definitionInvalid",
83
+ "retry.maxBackoffMs must be at least retry.backoffMs"
84
+ )
85
+ );
86
+ expect(() => build({backoffMs: 0, maxAttempts: 1})).not.toThrow();
87
+ });
88
+
89
+ it("rejects a non-function abort handler", () => {
90
+ expect(() =>
91
+ defineTask({
92
+ abort: "nope" as unknown as () => Promise<void>,
93
+ initial: () => ({phase: "only"}),
94
+ name: "test.badAbort",
95
+ phases: {only: {run: async (_task, rt) => rt.commit({terminal: {status: "completed"}})}},
96
+ version: 1,
97
+ })
98
+ ).toThrow(harnessErrorMatching("definitionInvalid", "abort must be a function"));
99
+ });
100
+ });
@@ -0,0 +1,77 @@
1
+ import {DateTime} from "luxon";
2
+
3
+ import type {HarnessRetryPolicy} from "../types/harness";
4
+ import {HARNESS_RETRY_DEFAULTS} from "../types/harness";
5
+ import {HarnessDefinitionError} from "./definitionError";
6
+
7
+ export interface ResolvedRetryPolicy {
8
+ backoffMs: number;
9
+ maxAttempts: number;
10
+ maxBackoffMs: number;
11
+ }
12
+
13
+ /** Fill the fields a definition left out with `HARNESS_RETRY_DEFAULTS`. */
14
+ export const resolveRetryPolicy = (policy: HarnessRetryPolicy | undefined): ResolvedRetryPolicy => {
15
+ return {
16
+ backoffMs: policy?.backoffMs ?? HARNESS_RETRY_DEFAULTS.backoffMs,
17
+ maxAttempts: policy?.maxAttempts ?? HARNESS_RETRY_DEFAULTS.maxAttempts,
18
+ maxBackoffMs: policy?.maxBackoffMs ?? HARNESS_RETRY_DEFAULTS.maxBackoffMs,
19
+ };
20
+ };
21
+
22
+ /**
23
+ * Throw when a retry policy cannot be applied. `scope` prefixes the message (for example
24
+ * `defineTask(name)`); `field` names the option (`retry`, `modelRetry`).
25
+ */
26
+ export const assertValidRetryPolicy = (
27
+ scope: string,
28
+ policy: HarnessRetryPolicy,
29
+ field = "retry"
30
+ ): void => {
31
+ const {backoffMs, maxAttempts, maxBackoffMs} = resolveRetryPolicy(policy);
32
+ if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
33
+ throw new HarnessDefinitionError(`${scope}: ${field}.maxAttempts must be a positive integer`);
34
+ }
35
+ if (!Number.isFinite(backoffMs) || backoffMs < 0) {
36
+ throw new HarnessDefinitionError(`${scope}: ${field}.backoffMs must be a non-negative number`);
37
+ }
38
+ if (!Number.isFinite(maxBackoffMs) || maxBackoffMs < backoffMs) {
39
+ throw new HarnessDefinitionError(
40
+ `${scope}: ${field}.maxBackoffMs must be at least ${field}.backoffMs`
41
+ );
42
+ }
43
+ };
44
+
45
+ /**
46
+ * Delay before the next run after `failedAttempts` failures: exponential
47
+ * (`backoffMs * 2^(failedAttempts - 1)`, capped at `maxBackoffMs`) with equal jitter, so
48
+ * the result lies in `[delay / 2, delay]`. Spreading retries keeps a shared outage from
49
+ * waking every failed task at the same instant.
50
+ */
51
+ export const retryDelayMs = ({
52
+ failedAttempts,
53
+ policy,
54
+ random = Math.random,
55
+ }: {
56
+ failedAttempts: number;
57
+ policy: ResolvedRetryPolicy;
58
+ random?: () => number;
59
+ }): number => {
60
+ const exponent = Math.max(0, failedAttempts - 1);
61
+ const capped = Math.min(policy.maxBackoffMs, policy.backoffMs * 2 ** exponent);
62
+ const half = capped / 2;
63
+ return Math.round(half + random() * half);
64
+ };
65
+
66
+ /** When the next run may start, measured from Luxon's clock (`DateTime.now()`). */
67
+ export const nextRetryAt = ({
68
+ failedAttempts,
69
+ policy,
70
+ random,
71
+ }: {
72
+ failedAttempts: number;
73
+ policy: ResolvedRetryPolicy;
74
+ random?: () => number;
75
+ }): DateTime => {
76
+ return DateTime.now().plus({milliseconds: retryDelayMs({failedAttempts, policy, random})});
77
+ };