@terreno/ai 57.9.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 (412) hide show
  1. package/README.md +1 -0
  2. package/bunfig.toml +1 -1
  3. package/dist/aiApp.d.ts +8 -2
  4. package/dist/aiApp.js +12 -6
  5. package/dist/harness/adminScreens.d.ts +6 -0
  6. package/dist/harness/adminScreens.js +11 -0
  7. package/dist/harness/agentLoop.d.ts +61 -0
  8. package/dist/harness/agentLoop.js +798 -0
  9. package/dist/harness/agentTaskNames.d.ts +4 -0
  10. package/dist/harness/agentTaskNames.js +7 -0
  11. package/dist/harness/approvalPolicy.d.ts +3 -0
  12. package/dist/harness/approvalPolicy.js +23 -0
  13. package/dist/harness/approvals.d.ts +101 -0
  14. package/dist/harness/approvals.js +468 -0
  15. package/dist/harness/commit.d.ts +238 -0
  16. package/dist/harness/commit.js +678 -0
  17. package/dist/harness/conversation.d.ts +75 -0
  18. package/dist/harness/conversation.js +397 -0
  19. package/dist/harness/defineAgent.d.ts +9 -0
  20. package/dist/harness/defineAgent.js +65 -0
  21. package/dist/harness/defineTask.d.ts +11 -0
  22. package/dist/harness/defineTask.js +59 -0
  23. package/dist/harness/defineTool.d.ts +7 -0
  24. package/dist/harness/defineTool.js +36 -0
  25. package/dist/harness/definitionError.d.ts +8 -0
  26. package/dist/harness/definitionError.js +15 -0
  27. package/dist/harness/errors.d.ts +127 -0
  28. package/dist/harness/errors.js +101 -0
  29. package/dist/harness/eventHub.d.ts +45 -0
  30. package/dist/harness/eventHub.js +135 -0
  31. package/dist/harness/events.d.ts +95 -0
  32. package/dist/harness/events.js +267 -0
  33. package/dist/harness/executionEnv.d.ts +31 -0
  34. package/dist/harness/executionEnv.js +2 -0
  35. package/dist/harness/extensions.d.ts +82 -0
  36. package/dist/harness/extensions.js +274 -0
  37. package/dist/harness/harness.d.ts +163 -0
  38. package/dist/harness/harness.js +520 -0
  39. package/dist/harness/harnessApp.d.ts +44 -0
  40. package/dist/harness/harnessApp.js +62 -0
  41. package/dist/harness/internalRuntime.d.ts +16 -0
  42. package/dist/harness/internalRuntime.js +18 -0
  43. package/dist/harness/leases.d.ts +35 -0
  44. package/dist/harness/leases.js +86 -0
  45. package/dist/harness/memo.d.ts +24 -0
  46. package/dist/harness/memo.js +78 -0
  47. package/dist/harness/modelCall.d.ts +45 -0
  48. package/dist/harness/modelCall.js +147 -0
  49. package/dist/harness/models/harnessApproval.d.ts +2 -0
  50. package/dist/harness/models/harnessApproval.js +100 -0
  51. package/dist/harness/models/harnessConversation.d.ts +2 -0
  52. package/dist/harness/models/harnessConversation.js +117 -0
  53. package/dist/harness/models/harnessEvent.d.ts +3 -0
  54. package/dist/harness/models/harnessEvent.js +73 -0
  55. package/dist/harness/models/harnessInboxEvent.d.ts +2 -0
  56. package/dist/harness/models/harnessInboxEvent.js +58 -0
  57. package/dist/harness/models/harnessMemo.d.ts +2 -0
  58. package/dist/harness/models/harnessMemo.js +42 -0
  59. package/dist/harness/models/harnessMessage.d.ts +2 -0
  60. package/dist/harness/models/harnessMessage.js +73 -0
  61. package/dist/harness/models/harnessOwner.d.ts +2 -0
  62. package/dist/harness/models/harnessOwner.js +36 -0
  63. package/dist/harness/models/harnessTask.d.ts +2 -0
  64. package/dist/harness/models/harnessTask.js +186 -0
  65. package/dist/harness/ownership.d.ts +89 -0
  66. package/dist/harness/ownership.js +438 -0
  67. package/dist/harness/registry.d.ts +29 -0
  68. package/dist/harness/registry.js +93 -0
  69. package/dist/harness/retryBackoff.d.ts +31 -0
  70. package/dist/harness/retryBackoff.js +50 -0
  71. package/dist/harness/routes/approvals.d.ts +13 -0
  72. package/dist/harness/routes/approvals.js +93 -0
  73. package/dist/harness/routes/conversations.d.ts +11 -0
  74. package/dist/harness/routes/conversations.js +66 -0
  75. package/dist/harness/routes/events.d.ts +19 -0
  76. package/dist/harness/routes/events.js +215 -0
  77. package/dist/harness/routes/tasks.d.ts +11 -0
  78. package/dist/harness/routes/tasks.js +108 -0
  79. package/dist/harness/runners/inProcessRunner.d.ts +57 -0
  80. package/dist/harness/runners/inProcessRunner.js +196 -0
  81. package/dist/harness/runtime.d.ts +34 -0
  82. package/dist/harness/runtime.js +551 -0
  83. package/dist/harness/subagent.d.ts +53 -0
  84. package/dist/harness/subagent.js +134 -0
  85. package/dist/harness/suspend.d.ts +8 -0
  86. package/dist/harness/suspend.js +16 -0
  87. package/dist/harness/transaction.d.ts +3 -0
  88. package/dist/harness/transaction.js +22 -0
  89. package/dist/harness/waits.d.ts +100 -0
  90. package/dist/harness/waits.js +214 -0
  91. package/dist/index.d.ts +19 -1
  92. package/dist/index.js +45 -2
  93. package/dist/models/aiDataset.d.ts +2 -0
  94. package/dist/models/aiDataset.js +67 -0
  95. package/dist/models/aiRequest.js +1 -1
  96. package/dist/models/gptHistory.js +73 -0
  97. package/dist/observability/adminScreens.d.ts +5 -0
  98. package/dist/observability/adminScreens.js +32 -0
  99. package/dist/observability/compileTemplate.d.ts +1 -0
  100. package/dist/observability/compileTemplate.js +13 -0
  101. package/dist/observability/datasetImport.d.ts +11 -0
  102. package/dist/observability/datasetImport.js +185 -0
  103. package/dist/observability/evaluate.d.ts +31 -0
  104. package/dist/observability/evaluate.js +200 -0
  105. package/dist/observability/evaluatorTemplates.d.ts +17 -0
  106. package/dist/observability/evaluatorTemplates.js +111 -0
  107. package/dist/observability/jsonPath.d.ts +2 -0
  108. package/dist/observability/jsonPath.js +57 -0
  109. package/dist/observability/local/datasetStore.d.ts +87 -0
  110. package/dist/observability/local/datasetStore.js +326 -0
  111. package/dist/observability/local/evaluatorStore.d.ts +44 -0
  112. package/dist/observability/local/evaluatorStore.js +182 -0
  113. package/dist/observability/local/experimentRunner.d.ts +96 -0
  114. package/dist/observability/local/experimentRunner.js +419 -0
  115. package/dist/observability/local/localPlugin.d.ts +22 -0
  116. package/dist/observability/local/localPlugin.js +76 -0
  117. package/dist/observability/local/models/obsDataset.d.ts +2 -0
  118. package/dist/observability/local/models/obsDataset.js +37 -0
  119. package/dist/observability/local/models/obsDatasetItem.d.ts +2 -0
  120. package/dist/observability/local/models/obsDatasetItem.js +76 -0
  121. package/dist/observability/local/models/obsEvaluator.d.ts +2 -0
  122. package/dist/observability/local/models/obsEvaluator.js +98 -0
  123. package/dist/observability/local/models/obsExperiment.d.ts +2 -0
  124. package/dist/observability/local/models/obsExperiment.js +87 -0
  125. package/dist/observability/local/models/obsExperimentItem.d.ts +2 -0
  126. package/dist/observability/local/models/obsExperimentItem.js +45 -0
  127. package/dist/observability/local/models/obsPrompt.d.ts +2 -0
  128. package/dist/observability/local/models/obsPrompt.js +42 -0
  129. package/dist/observability/local/models/obsPromptLabel.d.ts +2 -0
  130. package/dist/observability/local/models/obsPromptLabel.js +39 -0
  131. package/dist/observability/local/models/obsPromptVersion.d.ts +2 -0
  132. package/dist/observability/local/models/obsPromptVersion.js +96 -0
  133. package/dist/observability/local/models/obsReviewItem.d.ts +2 -0
  134. package/dist/observability/local/models/obsReviewItem.js +75 -0
  135. package/dist/observability/local/models/obsScore.d.ts +2 -0
  136. package/dist/observability/local/models/obsScore.js +58 -0
  137. package/dist/observability/local/models/obsSpan.d.ts +2 -0
  138. package/dist/observability/local/models/obsSpan.js +64 -0
  139. package/dist/observability/local/models/obsTrace.d.ts +2 -0
  140. package/dist/observability/local/models/obsTrace.js +93 -0
  141. package/dist/observability/local/promptStore.d.ts +180 -0
  142. package/dist/observability/local/promptStore.js +444 -0
  143. package/dist/observability/local/reviewStore.d.ts +50 -0
  144. package/dist/observability/local/reviewStore.js +203 -0
  145. package/dist/observability/local/traceStore.d.ts +103 -0
  146. package/dist/observability/local/traceStore.js +325 -0
  147. package/dist/observability/observabilityApp.d.ts +24 -0
  148. package/dist/observability/observabilityApp.js +157 -0
  149. package/dist/observability/observabilityAppRegistry.d.ts +14 -0
  150. package/dist/observability/observabilityAppRegistry.js +16 -0
  151. package/dist/observability/permissions.d.ts +7 -0
  152. package/dist/observability/permissions.js +60 -0
  153. package/dist/observability/reviewPanels.d.ts +18 -0
  154. package/dist/observability/reviewPanels.js +46 -0
  155. package/dist/observability/routes/datasets.d.ts +7 -0
  156. package/dist/observability/routes/datasets.js +149 -0
  157. package/dist/observability/routes/evaluators.d.ts +7 -0
  158. package/dist/observability/routes/evaluators.js +123 -0
  159. package/dist/observability/routes/experiments.d.ts +7 -0
  160. package/dist/observability/routes/experiments.js +95 -0
  161. package/dist/observability/routes/observabilityRouteAccess.d.ts +13 -0
  162. package/dist/observability/routes/observabilityRouteAccess.js +67 -0
  163. package/dist/observability/routes/prompts.d.ts +12 -0
  164. package/dist/observability/routes/prompts.js +172 -0
  165. package/dist/observability/routes/requestAiService.d.ts +13 -0
  166. package/dist/observability/routes/requestAiService.js +21 -0
  167. package/dist/observability/routes/review.d.ts +7 -0
  168. package/dist/observability/routes/review.js +79 -0
  169. package/dist/observability/routes/status.d.ts +5 -0
  170. package/dist/observability/routes/status.js +31 -0
  171. package/dist/observability/routes/testMultiStage.d.ts +9 -0
  172. package/dist/observability/routes/testMultiStage.js +67 -0
  173. package/dist/observability/routes/traces.d.ts +7 -0
  174. package/dist/observability/routes/traces.js +129 -0
  175. package/dist/observability/schemaValidation.d.ts +5 -0
  176. package/dist/observability/schemaValidation.js +26 -0
  177. package/dist/observability/sopThresholds.d.ts +2 -0
  178. package/dist/observability/sopThresholds.js +21 -0
  179. package/dist/observability/status.d.ts +23 -0
  180. package/dist/observability/status.js +34 -0
  181. package/dist/observability/testMultiStageSchemas.d.ts +10 -0
  182. package/dist/observability/testMultiStageSchemas.js +79 -0
  183. package/dist/observability/testMultiStageWorkflow.d.ts +20 -0
  184. package/dist/observability/testMultiStageWorkflow.js +218 -0
  185. package/dist/observability/types.d.ts +159 -0
  186. package/dist/observability/types.js +67 -0
  187. package/dist/routes/files.js +18 -7
  188. package/dist/routes/gpt.js +79 -689
  189. package/dist/routes/gptActions.d.ts +9 -0
  190. package/dist/routes/gptActions.js +212 -0
  191. package/dist/routes/gptDatasets.d.ts +5 -0
  192. package/dist/routes/gptDatasets.js +94 -0
  193. package/dist/routes/gptHistories.d.ts +3 -1
  194. package/dist/routes/gptHistories.js +188 -2
  195. package/dist/service/aiDatasets.d.ts +57 -0
  196. package/dist/service/aiDatasets.js +253 -0
  197. package/dist/service/aiService.d.ts +50 -1
  198. package/dist/service/aiService.js +426 -77
  199. package/dist/service/askFiles.d.ts +49 -0
  200. package/dist/service/askFiles.js +162 -0
  201. package/dist/service/asks.d.ts +76 -0
  202. package/dist/service/asks.js +284 -0
  203. package/dist/service/chatTurn.d.ts +128 -0
  204. package/dist/service/chatTurn.js +1674 -0
  205. package/dist/service/fileStorage.d.ts +4 -0
  206. package/dist/service/fileStorage.js +7 -2
  207. package/dist/service/fillActionIds.d.ts +6 -0
  208. package/dist/service/fillActionIds.js +79 -0
  209. package/dist/service/jsonFenceModel.d.ts +7 -0
  210. package/dist/service/jsonFenceModel.js +45 -0
  211. package/dist/service/prompts.d.ts +52 -0
  212. package/dist/service/prompts.js +96 -1
  213. package/dist/service/sanitizeHtml.d.ts +11 -0
  214. package/dist/service/sanitizeHtml.js +108 -0
  215. package/dist/types/harness.d.ts +934 -0
  216. package/dist/types/harness.js +133 -0
  217. package/dist/types/index.d.ts +192 -14
  218. package/dist/types/index.js +2 -0
  219. package/dist/types/observability.d.ts +288 -0
  220. package/dist/types/observability.js +2 -0
  221. package/package.json +17 -5
  222. package/src/aiApp.test.ts +207 -1
  223. package/src/aiApp.ts +19 -6
  224. package/src/harness/adminScreens.test.ts +34 -0
  225. package/src/harness/adminScreens.ts +11 -0
  226. package/src/harness/agentLoop.test.ts +1034 -0
  227. package/src/harness/agentLoop.ts +1082 -0
  228. package/src/harness/agentRecovery.test.ts +380 -0
  229. package/src/harness/agentTaskNames.ts +4 -0
  230. package/src/harness/approvalPolicy.ts +28 -0
  231. package/src/harness/approvals.test.ts +1094 -0
  232. package/src/harness/approvals.ts +644 -0
  233. package/src/harness/commit.ts +1049 -0
  234. package/src/harness/conversation.ts +503 -0
  235. package/src/harness/defineAgent.test.ts +92 -0
  236. package/src/harness/defineAgent.ts +82 -0
  237. package/src/harness/defineTask.test.ts +59 -0
  238. package/src/harness/defineTask.ts +76 -0
  239. package/src/harness/defineTool.ts +45 -0
  240. package/src/harness/definitionError.ts +13 -0
  241. package/src/harness/errors.test.ts +90 -0
  242. package/src/harness/errors.ts +119 -0
  243. package/src/harness/eventHub.test.ts +124 -0
  244. package/src/harness/eventHub.ts +159 -0
  245. package/src/harness/events.test.ts +757 -0
  246. package/src/harness/events.ts +384 -0
  247. package/src/harness/executionEnv.ts +34 -0
  248. package/src/harness/extensions.test.ts +1218 -0
  249. package/src/harness/extensions.ts +382 -0
  250. package/src/harness/harness.test.ts +693 -0
  251. package/src/harness/harness.ts +767 -0
  252. package/src/harness/harnessApp.ts +76 -0
  253. package/src/harness/internalRuntime.ts +44 -0
  254. package/src/harness/leases.ts +132 -0
  255. package/src/harness/memo.ts +107 -0
  256. package/src/harness/modelCall.test.ts +134 -0
  257. package/src/harness/modelCall.ts +200 -0
  258. package/src/harness/models/harnessApproval.ts +109 -0
  259. package/src/harness/models/harnessConversation.ts +142 -0
  260. package/src/harness/models/harnessEvent.ts +92 -0
  261. package/src/harness/models/harnessInboxEvent.ts +73 -0
  262. package/src/harness/models/harnessMemo.ts +43 -0
  263. package/src/harness/models/harnessMessage.ts +85 -0
  264. package/src/harness/models/harnessModels.test.ts +60 -0
  265. package/src/harness/models/harnessOwner.ts +40 -0
  266. package/src/harness/models/harnessTask.ts +201 -0
  267. package/src/harness/ownership.test.ts +1087 -0
  268. package/src/harness/ownership.ts +618 -0
  269. package/src/harness/recovery.test.ts +912 -0
  270. package/src/harness/registry.ts +124 -0
  271. package/src/harness/retries.test.ts +292 -0
  272. package/src/harness/retryBackoff.test.ts +100 -0
  273. package/src/harness/retryBackoff.ts +77 -0
  274. package/src/harness/routes/approvals.ts +123 -0
  275. package/src/harness/routes/conversations.test.ts +518 -0
  276. package/src/harness/routes/conversations.ts +102 -0
  277. package/src/harness/routes/events.ts +280 -0
  278. package/src/harness/routes/tasks.test.ts +198 -0
  279. package/src/harness/routes/tasks.ts +146 -0
  280. package/src/harness/runners/inProcessRunner.test.ts +402 -0
  281. package/src/harness/runners/inProcessRunner.ts +220 -0
  282. package/src/harness/runtime.ts +714 -0
  283. package/src/harness/subagent.test.ts +696 -0
  284. package/src/harness/subagent.ts +192 -0
  285. package/src/harness/suspend.ts +13 -0
  286. package/src/harness/transaction.ts +17 -0
  287. package/src/harness/versioning.test.ts +288 -0
  288. package/src/harness/waits.test.ts +693 -0
  289. package/src/harness/waits.ts +356 -0
  290. package/src/index.test.ts +13 -0
  291. package/src/index.ts +70 -0
  292. package/src/isolated/adminScreensConfig.isolated.ts +143 -0
  293. package/src/models/aiDataset.test.ts +34 -0
  294. package/src/models/aiDataset.ts +78 -0
  295. package/src/models/aiRequest.ts +2 -1
  296. package/src/models/gptHistory.test.ts +156 -0
  297. package/src/models/gptHistory.ts +89 -1
  298. package/src/observability/adminScreens.test.ts +71 -0
  299. package/src/observability/adminScreens.ts +42 -0
  300. package/src/observability/compileTemplate.test.ts +14 -0
  301. package/src/observability/compileTemplate.ts +10 -0
  302. package/src/observability/datasetImport.test.ts +95 -0
  303. package/src/observability/datasetImport.ts +220 -0
  304. package/src/observability/evaluate.test.ts +549 -0
  305. package/src/observability/evaluate.ts +254 -0
  306. package/src/observability/evaluatorTemplates.ts +124 -0
  307. package/src/observability/jsonPath.test.ts +52 -0
  308. package/src/observability/jsonPath.ts +60 -0
  309. package/src/observability/local/datasetStore.test.ts +230 -0
  310. package/src/observability/local/datasetStore.ts +452 -0
  311. package/src/observability/local/evaluatorStore.test.ts +138 -0
  312. package/src/observability/local/evaluatorStore.ts +224 -0
  313. package/src/observability/local/experimentRunner.test.ts +489 -0
  314. package/src/observability/local/experimentRunner.ts +548 -0
  315. package/src/observability/local/localPlugin.ts +88 -0
  316. package/src/observability/local/models/obsDataset.ts +38 -0
  317. package/src/observability/local/models/obsDatasetItem.ts +80 -0
  318. package/src/observability/local/models/obsEvaluator.ts +102 -0
  319. package/src/observability/local/models/obsExperiment.ts +91 -0
  320. package/src/observability/local/models/obsExperimentItem.ts +52 -0
  321. package/src/observability/local/models/obsPrompt.ts +43 -0
  322. package/src/observability/local/models/obsPromptLabel.ts +43 -0
  323. package/src/observability/local/models/obsPromptVersion.ts +107 -0
  324. package/src/observability/local/models/obsReviewItem.ts +79 -0
  325. package/src/observability/local/models/obsScore.ts +59 -0
  326. package/src/observability/local/models/obsSpan.ts +65 -0
  327. package/src/observability/local/models/obsTrace.ts +94 -0
  328. package/src/observability/local/obsModels.test.ts +119 -0
  329. package/src/observability/local/promptStore.test.ts +351 -0
  330. package/src/observability/local/promptStore.ts +665 -0
  331. package/src/observability/local/reviewStore.test.ts +164 -0
  332. package/src/observability/local/reviewStore.ts +264 -0
  333. package/src/observability/local/traceStore.test.ts +264 -0
  334. package/src/observability/local/traceStore.ts +440 -0
  335. package/src/observability/observabilityApp.test.ts +92 -0
  336. package/src/observability/observabilityApp.ts +185 -0
  337. package/src/observability/observabilityAppRegistry.test.ts +30 -0
  338. package/src/observability/observabilityAppRegistry.ts +35 -0
  339. package/src/observability/permissions.test.ts +96 -0
  340. package/src/observability/permissions.ts +78 -0
  341. package/src/observability/reviewPanels.test.ts +35 -0
  342. package/src/observability/reviewPanels.ts +64 -0
  343. package/src/observability/routes/datasets.test.ts +176 -0
  344. package/src/observability/routes/datasets.ts +252 -0
  345. package/src/observability/routes/evaluators.test.ts +119 -0
  346. package/src/observability/routes/evaluators.ts +207 -0
  347. package/src/observability/routes/experiments.test.ts +282 -0
  348. package/src/observability/routes/experiments.ts +152 -0
  349. package/src/observability/routes/observabilityRbac.test.ts +767 -0
  350. package/src/observability/routes/observabilityRouteAccess.ts +106 -0
  351. package/src/observability/routes/prompts.test.ts +320 -0
  352. package/src/observability/routes/prompts.ts +263 -0
  353. package/src/observability/routes/requestAiService.ts +36 -0
  354. package/src/observability/routes/review.test.ts +120 -0
  355. package/src/observability/routes/review.ts +125 -0
  356. package/src/observability/routes/status.test.ts +116 -0
  357. package/src/observability/routes/status.ts +47 -0
  358. package/src/observability/routes/testMultiStage.test.ts +214 -0
  359. package/src/observability/routes/testMultiStage.ts +96 -0
  360. package/src/observability/routes/traces.test.ts +167 -0
  361. package/src/observability/routes/traces.ts +172 -0
  362. package/src/observability/schemaValidation.ts +29 -0
  363. package/src/observability/sopThresholds.ts +20 -0
  364. package/src/observability/status.test.ts +38 -0
  365. package/src/observability/status.ts +56 -0
  366. package/src/observability/testMultiStageSchemas.ts +95 -0
  367. package/src/observability/testMultiStageWorkflow.test.ts +114 -0
  368. package/src/observability/testMultiStageWorkflow.ts +307 -0
  369. package/src/observability/types.ts +262 -0
  370. package/src/routes/files.test.ts +63 -9
  371. package/src/routes/files.ts +21 -7
  372. package/src/routes/gpt.test.ts +3279 -0
  373. package/src/routes/gpt.ts +91 -816
  374. package/src/routes/gptActions.test.ts +241 -0
  375. package/src/routes/gptActions.ts +255 -0
  376. package/src/routes/gptApprovals.test.ts +762 -0
  377. package/src/routes/gptDatasets.test.ts +86 -0
  378. package/src/routes/gptDatasets.ts +104 -0
  379. package/src/routes/gptFiles.test.ts +589 -0
  380. package/src/routes/gptHistories.test.ts +933 -0
  381. package/src/routes/gptHistories.ts +266 -5
  382. package/src/routes/routes.test.ts +222 -2
  383. package/src/service/aiDatasets.test.ts +123 -0
  384. package/src/service/aiDatasets.ts +316 -0
  385. package/src/service/aiService.test.ts +593 -0
  386. package/src/service/aiService.ts +568 -111
  387. package/src/service/askFiles.test.ts +96 -0
  388. package/src/service/askFiles.ts +222 -0
  389. package/src/service/asks.test.ts +946 -0
  390. package/src/service/asks.ts +423 -0
  391. package/src/service/chatTurn.ts +2287 -0
  392. package/src/service/fileStorage.test.ts +11 -0
  393. package/src/service/fileStorage.ts +10 -2
  394. package/src/service/fillActionIds.test.ts +65 -0
  395. package/src/service/fillActionIds.ts +98 -0
  396. package/src/service/jsonFenceModel.test.ts +47 -0
  397. package/src/service/jsonFenceModel.ts +53 -0
  398. package/src/service/prompts.test.ts +21 -0
  399. package/src/service/prompts.ts +147 -0
  400. package/src/service/sanitizeHtml.test.ts +61 -0
  401. package/src/service/sanitizeHtml.ts +109 -0
  402. package/src/tests/bunSetup.test.ts +7 -4
  403. package/src/tests/bunSetup.ts +7 -7
  404. package/src/tests/chatHarness.ts +478 -0
  405. package/src/tests/generateStream.ts +49 -0
  406. package/src/tests/harnessErrors.ts +22 -0
  407. package/src/tests/harnessStreaming.ts +227 -0
  408. package/src/tests/helpers.ts +9 -2
  409. package/src/types/harness.ts +1095 -0
  410. package/src/types/index.ts +209 -13
  411. package/src/types/observability.ts +344 -0
  412. package/src/types/sanitize-html.d.ts +25 -0
@@ -0,0 +1,1095 @@
1
+ import type {FindExactlyOnePlugin, FindOneOrNonePlugin, PermissionMethod, z} from "@terreno/api";
2
+ import type {LanguageModel, ModelMessage} from "ai";
3
+ import type {Duration, DurationLike} from "luxon";
4
+ import type mongoose from "mongoose";
5
+
6
+ import type {ExecutionEnv} from "../harness/executionEnv";
7
+
8
+ /** Every lifecycle status a harness task can hold. */
9
+ export const HARNESS_TASK_STATUSES = {
10
+ aborted: "aborted",
11
+ completed: "completed",
12
+ failed: "failed",
13
+ interrupted: "interrupted",
14
+ pending: "pending",
15
+ running: "running",
16
+ waiting: "waiting",
17
+ } as const;
18
+
19
+ export type HarnessTaskStatus = (typeof HARNESS_TASK_STATUSES)[keyof typeof HARNESS_TASK_STATUSES];
20
+
21
+ /** Statuses after which a task never runs again. */
22
+ export const HARNESS_TERMINAL_STATUSES: ReadonlySet<HarnessTaskStatus> = new Set([
23
+ HARNESS_TASK_STATUSES.aborted,
24
+ HARNESS_TASK_STATUSES.completed,
25
+ HARNESS_TASK_STATUSES.failed,
26
+ ]);
27
+
28
+ export type HarnessTerminalStatus = "aborted" | "completed" | "failed";
29
+
30
+ /** Whether a phase (or tool) may re-run after it was interrupted mid-flight. */
31
+ export type HarnessReplayPolicy = "never" | "safe";
32
+
33
+ /** What an interrupted `replay: "never"` phase does; see `onInterrupt` on `defineTask`. */
34
+ export const HARNESS_INTERRUPT_ACTIONS = {
35
+ fail: "fail",
36
+ park: "park",
37
+ } as const;
38
+
39
+ export type HarnessInterruptAction =
40
+ (typeof HARNESS_INTERRUPT_ACTIONS)[keyof typeof HARNESS_INTERRUPT_ACTIONS];
41
+
42
+ /** Span kinds a task's own audit span may take. */
43
+ export type HarnessTaskSpanKind = "AGENT" | "CHAIN" | "TOOL";
44
+
45
+ export type HarnessOwnershipKind = "conversation" | "root" | "task";
46
+
47
+ export interface HarnessOwnership {
48
+ id?: mongoose.Types.ObjectId;
49
+ kind: HarnessOwnershipKind;
50
+ }
51
+
52
+ /** How a thrown phase is retried. Every field is optional; see `HARNESS_RETRY_DEFAULTS`. */
53
+ export interface HarnessRetryPolicy {
54
+ /** Base delay before the first retry; doubles on every later failure. */
55
+ backoffMs?: number;
56
+ /** Runs allowed per phase visit (first run included) before the task fails. */
57
+ maxAttempts?: number;
58
+ /** Upper bound on any single retry delay, before jitter. */
59
+ maxBackoffMs?: number;
60
+ }
61
+
62
+ /** Retry policy applied to fields a task definition leaves out. */
63
+ export const HARNESS_RETRY_DEFAULTS = {
64
+ backoffMs: 1000,
65
+ maxAttempts: 3,
66
+ maxBackoffMs: 60_000,
67
+ } as const;
68
+
69
+ export interface HarnessLease {
70
+ acquiredAt?: Date;
71
+ expiresAt?: Date;
72
+ owner?: string;
73
+ token?: string;
74
+ }
75
+
76
+ /** What a `waiting` task is blocked on. */
77
+ export const HARNESS_WAIT_KINDS = {
78
+ event: "event",
79
+ sleep: "sleep",
80
+ tasks: "tasks",
81
+ } as const;
82
+
83
+ export type HarnessWaitKind = (typeof HARNESS_WAIT_KINDS)[keyof typeof HARNESS_WAIT_KINDS];
84
+
85
+ /** How `rt.waitForTasks` resolves: when every child settles, or at the first failure. */
86
+ export const HARNESS_WAIT_POLICIES = {
87
+ all: "all",
88
+ failFast: "failFast",
89
+ } as const;
90
+
91
+ export type HarnessWaitPolicy = (typeof HARNESS_WAIT_POLICIES)[keyof typeof HARNESS_WAIT_POLICIES];
92
+
93
+ /** How one `rt.waitFor` / `rt.sleep` call resolved. */
94
+ export const HARNESS_WAIT_RESOLUTIONS = {
95
+ /** A sleep reached its `timeoutAt`. */
96
+ elapsed: "elapsed",
97
+ /** An event was delivered. */
98
+ event: "event",
99
+ /** An event wait reached its `timeoutAt` first. */
100
+ timeout: "timeout",
101
+ } as const;
102
+
103
+ export type HarnessWaitResolution =
104
+ (typeof HARNESS_WAIT_RESOLUTIONS)[keyof typeof HARNESS_WAIT_RESOLUTIONS];
105
+
106
+ /**
107
+ * Durable record of one `rt.waitFor` / `rt.sleep` call, stored on the task under
108
+ * `waits["<step>:<call index>"]` so a re-run of the same phase visit returns what the
109
+ * call returned the first time.
110
+ */
111
+ export interface HarnessWaitCall {
112
+ /** Event id delivered to the call (`resolution: "event"`). */
113
+ eventId?: mongoose.Types.ObjectId;
114
+ /** Event name for an event wait. */
115
+ key?: string;
116
+ kind: "event" | "sleep";
117
+ resolution?: HarnessWaitResolution;
118
+ resolvedAt?: Date;
119
+ /** When the call first ran; the resume span starts here. */
120
+ startedAt: Date;
121
+ timeoutAt?: Date;
122
+ }
123
+
124
+ export interface HarnessWaiting {
125
+ key?: string;
126
+ kind?: HarnessWaitKind;
127
+ policy?: HarnessWaitPolicy;
128
+ taskIds?: mongoose.Types.ObjectId[];
129
+ timeoutAt?: Date;
130
+ }
131
+
132
+ /** Recorded by `harness.abort` before any handler runs; blocks new claims of the task. */
133
+ export interface HarnessAbortRequest {
134
+ at: Date;
135
+ /** Until when one aborter holds the right to run the handler and commit the abort. */
136
+ handlerClaimExpiresAt?: Date;
137
+ reason: string;
138
+ userId?: mongoose.Types.ObjectId;
139
+ }
140
+
141
+ export interface HarnessOutcome {
142
+ error?: string;
143
+ result?: unknown;
144
+ status: HarnessTerminalStatus;
145
+ }
146
+
147
+ export interface HarnessTaskDocument extends mongoose.Document<mongoose.Types.ObjectId> {
148
+ abortRequested?: HarnessAbortRequest;
149
+ /** Owning tasks from the root down to the parent; empty for a root task. */
150
+ ancestorIds?: mongoose.Types.ObjectId[];
151
+ attempt: number;
152
+ background: boolean;
153
+ created: Date;
154
+ deleted: boolean;
155
+ input?: unknown;
156
+ lease?: HarnessLease;
157
+ name: string;
158
+ outcome?: HarnessOutcome;
159
+ ownership: HarnessOwnership;
160
+ phase: string;
161
+ requestId?: string;
162
+ retry?: HarnessRetryPolicy;
163
+ rootSpanId: mongoose.Types.ObjectId;
164
+ rootTaskId: mongoose.Types.ObjectId;
165
+ runAt?: Date;
166
+ state?: unknown;
167
+ status: HarnessTaskStatus;
168
+ /** Events received by `harness.sendEvent`; orders the task's inbox. */
169
+ eventSeq: number;
170
+ /** Phase commits so far; identifies the current phase visit. */
171
+ step: number;
172
+ traceId: mongoose.Types.ObjectId;
173
+ updated: Date;
174
+ userId?: mongoose.Types.ObjectId;
175
+ version: number;
176
+ waiting?: HarnessWaiting;
177
+ /** `rt.waitFor` / `rt.sleep` calls of the current phase visit, by `<step>:<call index>`. */
178
+ waits?: Record<string, HarnessWaitCall>;
179
+ }
180
+
181
+ export interface HarnessTaskStatics
182
+ extends FindExactlyOnePlugin<HarnessTaskDocument>,
183
+ FindOneOrNonePlugin<HarnessTaskDocument> {}
184
+
185
+ export interface HarnessTaskModel extends mongoose.Model<HarnessTaskDocument>, HarnessTaskStatics {}
186
+
187
+ /** Singleton lease that decides which `InProcessRunner` drains tasks. */
188
+ export interface HarnessOwnerDocument extends mongoose.Document<mongoose.Types.ObjectId> {
189
+ created: Date;
190
+ expiresAt: Date;
191
+ key: string;
192
+ owner: string;
193
+ updated: Date;
194
+ }
195
+
196
+ export interface HarnessOwnerModel
197
+ extends mongoose.Model<HarnessOwnerDocument>,
198
+ FindExactlyOnePlugin<HarnessOwnerDocument>,
199
+ FindOneOrNonePlugin<HarnessOwnerDocument> {}
200
+
201
+ /** Read-only view of a task handed to each phase. */
202
+ export interface HarnessTaskView<In, State> {
203
+ attempt: number;
204
+ id: string;
205
+ input: In;
206
+ name: string;
207
+ phase: string;
208
+ state: State;
209
+ userId?: string;
210
+ version: number;
211
+ }
212
+
213
+ /** Move to another phase, optionally replacing state (omitted state is kept). */
214
+ export interface HarnessPhaseCommit<State> {
215
+ phase: string;
216
+ state?: State;
217
+ }
218
+
219
+ export type HarnessTerminalCommit<Out> =
220
+ | {terminal: {result?: Out; status: "completed"}}
221
+ | {terminal: {error: string; status: "failed"}};
222
+
223
+ export type HarnessCommit<State, Out> = HarnessPhaseCommit<State> | HarnessTerminalCommit<Out>;
224
+
225
+ /** Options for `rt.createTask`. */
226
+ export interface HarnessChildTaskOptions {
227
+ /**
228
+ * Stored on the child. A background task belongs to its owner but not to the owner's
229
+ * current conversation turn (turn-abort semantics ship with conversations).
230
+ */
231
+ background?: boolean;
232
+ /**
233
+ * Stable name for this child within the current attempt of the current phase visit.
234
+ * Defaults to the call's position (`0`, `1`, ...). A re-run of the same attempt (wake,
235
+ * crash replay) gets the child created first instead of a duplicate; a retry creates a
236
+ * fresh child.
237
+ */
238
+ key?: string;
239
+ }
240
+
241
+ /** Settled child as returned by `rt.waitForTasks`, in the order of the ids passed. */
242
+ export interface HarnessChildOutcome {
243
+ error?: string;
244
+ id: string;
245
+ name: string;
246
+ result?: unknown;
247
+ status: HarnessTerminalStatus;
248
+ }
249
+
250
+ export interface HarnessWaitForOptions {
251
+ /** Resolve with `undefined` when no event arrives within this long. Default: wait forever. */
252
+ timeout?: DurationLike;
253
+ }
254
+
255
+ export interface HarnessSendEventOptions {
256
+ /** Idempotency key, unique per task: a repeated send returns the event sent first. */
257
+ requestId?: string;
258
+ }
259
+
260
+ /** An event sent to a task by `harness.sendEvent`, buffered until a `rt.waitFor` takes it. */
261
+ export interface HarnessInboxEventDocument extends mongoose.Document<mongoose.Types.ObjectId> {
262
+ /** `<step>:<call index>` of the `rt.waitFor` call that received it. */
263
+ consumedKey?: string;
264
+ consumedAt?: Date;
265
+ created: Date;
266
+ name: string;
267
+ payload?: unknown;
268
+ requestId?: string;
269
+ /** Position in the task's inbox (1, 2, ...); delivery is FIFO per event name. */
270
+ seq: number;
271
+ taskId: mongoose.Types.ObjectId;
272
+ updated: Date;
273
+ }
274
+
275
+ export interface HarnessInboxEventModel
276
+ extends mongoose.Model<HarnessInboxEventDocument>,
277
+ FindExactlyOnePlugin<HarnessInboxEventDocument>,
278
+ FindOneOrNonePlugin<HarnessInboxEventDocument> {}
279
+
280
+ export interface HarnessWaitForTasksOptions {
281
+ /** Default `all`. */
282
+ policy?: HarnessWaitPolicy;
283
+ }
284
+
285
+ /** Runtime surface handed to phases. */
286
+ export interface HarnessTaskRuntime<State, Out> {
287
+ /**
288
+ * Ask a human to approve. Creates a `HarnessApproval` (once per call per phase visit) in
289
+ * the same transaction that parks the task `waiting` on the approval's own event, then
290
+ * returns the decision once a permitted user approves or rejects it, or
291
+ * `{approved: false, expired: true}` once `timeout` passes. Who may decide comes from the
292
+ * definition's `approvals[key].approvers` (default `[Permissions.IsAdmin]`).
293
+ */
294
+ approval: HarnessApprovalRequest;
295
+ /** Persist the checkpoint (or terminal outcome) and its audit span in one transaction. */
296
+ commit: (next: HarnessCommit<State, Out>) => Promise<void>;
297
+ /** Create a child task owned by this task, in the same trace. Returns the child id. */
298
+ createTask: <ChildIn, ChildState, ChildOut>(
299
+ definition: HarnessTaskDefinition<ChildIn, ChildState, ChildOut>,
300
+ input: ChildIn,
301
+ options?: HarnessChildTaskOptions
302
+ ) => Promise<string>;
303
+ /**
304
+ * Execution environment from `Harness.open({env})`, when one was given. Phase 1 ships the
305
+ * `ExecutionEnv` interface only; implementations land with coding agents.
306
+ */
307
+ env?: ExecutionEnv;
308
+ /**
309
+ * Run `agent` as a subagent: a conversation owned by this task whose turn is a child
310
+ * task, nested under this task's span as an `AGENT` span. Returns the final assistant
311
+ * text, or, when `output` (or the agent's own `output`) is set, the parsed object.
312
+ * Until the turn settles the task commits `waiting` and the phase stops; it re-runs
313
+ * when the turn ends, and this call then finds the same conversation and returns.
314
+ * Call it sequentially; for parallel fan-out use `createTask` + `waitForTasks`.
315
+ * Throws `HarnessSubagentError` when the turn fails, is aborted, or its output does not
316
+ * match the schema.
317
+ */
318
+ runAgent: <Result = string>(
319
+ agent: HarnessAgentDefinition,
320
+ options: HarnessRunAgentOptions<Result>
321
+ ) => Promise<Result>;
322
+ /**
323
+ * Durable decision storage scoped to this task. `rt.memo(key)` reads the stored value
324
+ * (`undefined` when unset); `rt.memo(key, value)` stores `value` unless the key is
325
+ * already set, and returns whichever value is stored: the first write wins, across
326
+ * concurrent calls, replays, and restarts.
327
+ */
328
+ memo: HarnessMemo;
329
+ /**
330
+ * Append `text` to the task's event stream as an `output` event (permanent). A phase
331
+ * that re-runs (replay, retry) sends its output again.
332
+ */
333
+ output: (text: string) => Promise<void>;
334
+ /** Aborted when the task is aborted or this run loses its lease; stop work promptly. */
335
+ signal: AbortSignal;
336
+ /**
337
+ * Return once `duration` has passed. Until then the task commits `waiting` (kind
338
+ * `sleep`), gives up its lease, and the phase stops; it re-runs at `timeoutAt`, and this
339
+ * call then returns.
340
+ */
341
+ sleep: (duration: DurationLike) => Promise<void>;
342
+ taskId: string;
343
+ /**
344
+ * Return the payload of the oldest undelivered `event` sent to this task with
345
+ * `harness.sendEvent`, or `undefined` once `timeout` passes first. Until then the task
346
+ * commits `waiting` (kind `event`), gives up its lease, and the phase stops; it re-runs
347
+ * when the event arrives or the timeout passes. A re-run of the same phase visit gets
348
+ * the same result from the same call.
349
+ */
350
+ waitFor: <T = unknown>(event: string, options?: HarnessWaitForOptions) => Promise<T | undefined>;
351
+ /**
352
+ * Return child outcomes once they settle under `policy`. Until then the task commits
353
+ * `waiting`, gives up its lease, and the phase stops; it re-runs from its checkpoint
354
+ * when the children settle, and this call then returns the outcomes.
355
+ */
356
+ waitForTasks: (
357
+ ids: ReadonlyArray<mongoose.Types.ObjectId | string>,
358
+ options?: HarnessWaitForTasksOptions
359
+ ) => Promise<HarnessChildOutcome[]>;
360
+ }
361
+
362
+ /**
363
+ * Read or first-write a durable memo. Values must be JSON-serializable; `undefined` as the
364
+ * value means "read".
365
+ */
366
+ export interface HarnessMemo {
367
+ <T = unknown>(key: string): Promise<T | undefined>;
368
+ <T>(key: string, value: T): Promise<T>;
369
+ }
370
+
371
+ /** Options for `rt.runAgent`. */
372
+ export interface HarnessRunAgentOptions<Result> {
373
+ /** The subagent's user message. A non-string value is sent as JSON. */
374
+ input: unknown;
375
+ /** Replaces the agent's instructions for this subagent conversation only. */
376
+ instructions?: string;
377
+ /**
378
+ * Structured output schema; defaults to the agent's own `output`. Requested through the
379
+ * AI SDK's `Output.object`, then validated with this schema before it is returned.
380
+ */
381
+ output?: z.ZodType<Result>;
382
+ }
383
+
384
+ /** Runtime handed to a task's `abort` handler. */
385
+ export interface HarnessAbortRuntime {
386
+ /** Why the task is being aborted. */
387
+ reason: string;
388
+ taskId: string;
389
+ /** Who requested the abort, when known. */
390
+ userId?: string;
391
+ }
392
+
393
+ export interface HarnessPhaseDefinition<In, State, Out> {
394
+ /** Defaults to `never`: an interrupted phase is parked, not re-run. */
395
+ replay?: HarnessReplayPolicy;
396
+ run(task: HarnessTaskView<In, State>, rt: HarnessTaskRuntime<State, Out>): Promise<void>;
397
+ }
398
+
399
+ export interface HarnessTaskDefinitionInput<In, State, Out> {
400
+ /**
401
+ * Who may decide each `rt.approval(key)` of this definition, by key. A key left out
402
+ * defaults to `[Permissions.IsAdmin]`. Kept in code, never stored: the HTTP routes look
403
+ * the policy up by the approval's `name@version` and `key` at request time.
404
+ */
405
+ approvals?: Readonly<Record<string, HarnessApprovalPolicy>>;
406
+ /**
407
+ * Compensation handler run before the task is marked `aborted`, after every task it
408
+ * owns is already aborted. A throw is recorded on the abort span; the abort proceeds.
409
+ */
410
+ abort?(task: HarnessTaskView<In, State>, rt: HarnessAbortRuntime): Promise<void>;
411
+ initial(input: In): {phase: string; state?: State};
412
+ name: string;
413
+ /**
414
+ * What an interrupted `replay: "never"` phase does. `park` (default) sets `interrupted`
415
+ * and waits for `resolveInterrupted`; `fail` ends the task `failed` with an
416
+ * "Interrupted, not retried" error so a waiting owner can carry on (agent tool calls).
417
+ */
418
+ onInterrupt?: HarnessInterruptAction;
419
+ phases: Record<string, HarnessPhaseDefinition<In, State, Out>>;
420
+ retry?: HarnessRetryPolicy;
421
+ /** Kind of the task's own audit span. Default `CHAIN`. */
422
+ spanKind?: HarnessTaskSpanKind;
423
+ /** Name of the task's own audit span. Default `name@version`. */
424
+ spanName?: (input: In) => string;
425
+ version: number;
426
+ }
427
+
428
+ export interface HarnessTaskDefinition<In = unknown, State = unknown, Out = unknown>
429
+ extends HarnessTaskDefinitionInput<In, State, Out> {
430
+ key: string;
431
+ kind: "task";
432
+ }
433
+
434
+ /** Options for `harness.abort`. */
435
+ export interface HarnessAbortOptions {
436
+ /** Why the task is aborted; required and recorded in each abort span and outcome. */
437
+ reason: string;
438
+ /** Who requested the abort; recorded as `abortedBy`. */
439
+ userId?: mongoose.Types.ObjectId | string;
440
+ }
441
+
442
+ export interface HarnessCreateTaskOptions {
443
+ /** Idempotency key: a second create with the same id returns the existing task. */
444
+ requestId?: string;
445
+ userId?: mongoose.Types.ObjectId | string;
446
+ }
447
+
448
+ /** How an interrupted task is resolved by an operator. */
449
+ export const HARNESS_RESOLVE_ACTIONS = {
450
+ abort: "abort",
451
+ complete: "complete",
452
+ retry: "retry",
453
+ } as const;
454
+
455
+ export type HarnessResolveAction =
456
+ (typeof HARNESS_RESOLVE_ACTIONS)[keyof typeof HARNESS_RESOLVE_ACTIONS];
457
+
458
+ export interface HarnessResolveInterruptedOptions {
459
+ action: HarnessResolveAction;
460
+ /** Why the operator chose this action; required and recorded in the audit span. */
461
+ reason: string;
462
+ /** Result stored on the task for `complete`. */
463
+ result?: unknown;
464
+ /** Operator who resolved the task; recorded as `decidedBy`. */
465
+ userId?: mongoose.Types.ObjectId | string;
466
+ }
467
+
468
+ export interface HarnessTestHooks {
469
+ /** Runs inside the commit transaction after every write, before it commits. */
470
+ beforeCommitEnd?: (context: {
471
+ phase: string;
472
+ session: mongoose.ClientSession;
473
+ taskId: string;
474
+ }) => Promise<void> | void;
475
+ /**
476
+ * While it returns true every lease renewal (owner and task) is skipped and owner
477
+ * acquisition fails, as if the process had frozen. Simulates a crash in tests.
478
+ */
479
+ isHeartbeatSuspended?: () => boolean;
480
+ /** Replaces `Math.random` for retry jitter so backoff delays are deterministic. */
481
+ random?: () => number;
482
+ }
483
+
484
+ /** Lease settings a runner applies to the owner lease and every task lease it takes. */
485
+ export interface HarnessLeaseSettings {
486
+ /** How long a lease lives without a renewal. */
487
+ duration: Duration;
488
+ /** How often the holder renews; must be shorter than `duration`. */
489
+ heartbeat: Duration;
490
+ /** Runner instance id written into every lease it holds. */
491
+ owner: string;
492
+ }
493
+
494
+ /**
495
+ * What the harness hands a runner: hold the owner lease, recover tasks whose lease
496
+ * expired, claim one runnable task, then run it to a stop.
497
+ */
498
+ export interface HarnessRunnerContext {
499
+ /** Take or renew the singleton `HarnessOwner` lease; false when another owner holds it. */
500
+ acquireOwnerLease: (lease: HarnessLeaseSettings) => Promise<boolean>;
501
+ claimNext: (lease: HarnessLeaseSettings) => Promise<HarnessTaskDocument | null>;
502
+ /**
503
+ * Resume or park every `running` task whose lease expired. Returns how many were made
504
+ * runnable again.
505
+ */
506
+ recoverExpired: () => Promise<number>;
507
+ /** Give up the owner lease so a standby can take over without waiting for expiry. */
508
+ releaseOwnerLease: (lease: HarnessLeaseSettings) => Promise<void>;
509
+ runTask: (task: HarnessTaskDocument, lease: HarnessLeaseSettings) => Promise<void>;
510
+ }
511
+
512
+ /** Decides who executes runnable tasks and when. */
513
+ export interface HarnessRunner {
514
+ start: (context: HarnessRunnerContext) => Promise<void>;
515
+ stop: () => Promise<void>;
516
+ /** Hint that new work may be runnable now. */
517
+ wake: () => void;
518
+ }
519
+
520
+ // ---------------------------------------------------------------------------------------
521
+ // Agents, tools, conversations
522
+ // ---------------------------------------------------------------------------------------
523
+
524
+ /** Names a model; `Harness.open({models})` turns it into a `LanguageModel`. */
525
+ export interface HarnessModelRef {
526
+ modelId: string;
527
+ provider: string;
528
+ }
529
+
530
+ /** Resolves a model reference to a Vercel AI SDK `LanguageModel`. */
531
+ export type HarnessModelResolver = (ref: HarnessModelRef) => LanguageModel;
532
+
533
+ /** Defaults for an agent's model-call retries (per model, before fallbacks). */
534
+ export const HARNESS_MODEL_RETRY_DEFAULTS = {
535
+ backoffMs: 500,
536
+ maxAttempts: 3,
537
+ maxBackoffMs: 8000,
538
+ } as const;
539
+
540
+ /** Model requests one turn may make when an agent leaves `maxSteps` out. */
541
+ export const HARNESS_AGENT_DEFAULT_MAX_STEPS = 10;
542
+
543
+ /** What a tool's `execute` receives besides its arguments. */
544
+ export interface HarnessToolApi {
545
+ conversationId: string;
546
+ /** Execution environment from `Harness.open({env})`, when one was given. */
547
+ env?: ExecutionEnv;
548
+ /** Append progress text; recorded on the tool's span (`output.streamedOutput`). */
549
+ output: (text: string) => void;
550
+ /** Aborted when the turn is aborted or this run loses its lease. */
551
+ signal: AbortSignal;
552
+ /** The tool call's own task id. */
553
+ taskId: string;
554
+ }
555
+
556
+ export interface HarnessToolDefinitionInput<Args, Result> {
557
+ description: string;
558
+ execute: (args: Args, api: HarnessToolApi) => Promise<Result>;
559
+ /** Letters, digits, `_` and `-`, at most 64 characters (provider limit). */
560
+ name: string;
561
+ /** Zod schema for the arguments. Sent to the model and checked before `execute`. */
562
+ parameters: z.ZodType<Args>;
563
+ /** Default `never`: an interrupted call is reported to the model, not re-run. */
564
+ replay?: HarnessReplayPolicy;
565
+ }
566
+
567
+ export interface HarnessToolDefinition<Args = unknown, Result = unknown>
568
+ extends HarnessToolDefinitionInput<Args, Result> {
569
+ kind: "tool";
570
+ replay: HarnessReplayPolicy;
571
+ }
572
+
573
+ /**
574
+ * Any tool, whatever its argument and result types. `execute` arguments are contravariant, so
575
+ * `never` accepts every tool in heterogeneous lists without an explicit `any`.
576
+ */
577
+ export type AnyHarnessToolDefinition = HarnessToolDefinition<never, unknown>;
578
+
579
+ export interface HarnessAgentDefinitionInput {
580
+ /** Tried in order once the primary model's retryable failures exhaust `modelRetry`. */
581
+ fallbackModels?: HarnessModelRef[];
582
+ /** System prompt for every request. */
583
+ instructions: string;
584
+ /** Model requests one turn may make. Default `HARNESS_AGENT_DEFAULT_MAX_STEPS`. */
585
+ maxSteps?: number;
586
+ model: HarnessModelRef;
587
+ /** Retries per model for 429 / 5xx / network errors. See `HARNESS_MODEL_RETRY_DEFAULTS`. */
588
+ modelRetry?: HarnessRetryPolicy;
589
+ /** Unique within a harness registry. */
590
+ name: string;
591
+ /**
592
+ * Extensions every conversation with this agent uses, in order, by name or definition.
593
+ * Each must be listed in the harness registry.
594
+ */
595
+ extensions?: ReadonlyArray<HarnessExtensionDefinition | string>;
596
+ /** When set, the final answer is parsed as JSON and validated; the turn result carries it. */
597
+ output?: z.ZodType;
598
+ tools?: ReadonlyArray<AnyHarnessToolDefinition>;
599
+ }
600
+
601
+ export interface HarnessAgentDefinition extends Omit<HarnessAgentDefinitionInput, "extensions"> {
602
+ /** Extension names, in order. */
603
+ extensions: ReadonlyArray<string>;
604
+ kind: "agent";
605
+ maxSteps: number;
606
+ tools: ReadonlyArray<AnyHarnessToolDefinition>;
607
+ }
608
+
609
+ // ---------------------------------------------------------------------------------------
610
+ // Extensions, hooks, wraps
611
+ // ---------------------------------------------------------------------------------------
612
+
613
+ /** What every hook and section receives besides its own arguments. */
614
+ export interface HarnessHookApi {
615
+ conversationId: string;
616
+ /**
617
+ * Durable memo scoped to the turn task (also from tool hooks, which run in the tool
618
+ * call's task), so a decision survives a re-run of the request or the tool call.
619
+ */
620
+ memo: HarnessMemo;
621
+ /** Aborted when the turn is aborted or this run loses its lease. */
622
+ signal: AbortSignal;
623
+ /** The task running the hook: the turn for sections and `beforeModelRequest`, the tool call for tool hooks. */
624
+ taskId: string;
625
+ /** The turn task. Memo keys are scoped to it. */
626
+ turnTaskId: string;
627
+ }
628
+
629
+ /** What a `beforeTool` hook receives: the hook api plus approvals. */
630
+ export interface HarnessToolHookApi extends HarnessHookApi {
631
+ /**
632
+ * `rt.approval` of the tool call's task. Approvers come from the hook's own extension
633
+ * (`approvals[key]`, default `[Permissions.IsAdmin]`). Until the decision the tool call
634
+ * waits; the call (and this hook) re-runs from the top once it is decided, so memoize
635
+ * the decision by `toolCallId`.
636
+ */
637
+ approval: HarnessApprovalRequest;
638
+ }
639
+
640
+ /** The request a `beforeModelRequest` hook may rewrite. */
641
+ export interface HarnessModelRequest {
642
+ /** AI SDK messages built from the transcript. */
643
+ messages: ModelMessage[];
644
+ /** Effective system prompt: agent instructions plus extension sections. */
645
+ system: string;
646
+ }
647
+
648
+ /** A tool call as tool hooks see it. */
649
+ export interface HarnessToolCall {
650
+ /** Arguments, already validated against the tool's `parameters`. */
651
+ args: unknown;
652
+ toolCallId: string;
653
+ toolName: string;
654
+ }
655
+
656
+ /** `beforeTool` outcome: keep going, refuse the call, or replace its arguments. */
657
+ export type HarnessBeforeToolResult = {args: unknown} | {block: string} | undefined;
658
+
659
+ type MaybePromise<T> = Promise<T> | T;
660
+
661
+ export interface HarnessHookHandlers {
662
+ /** Return a replacement result, or `undefined` to keep it. Runs only after `execute` returns. */
663
+ afterTool: (call: HarnessToolCall, result: unknown, api: HarnessHookApi) => MaybePromise<unknown>;
664
+ /** Return a replacement request, or `undefined` to keep it. */
665
+ beforeModelRequest: (
666
+ request: HarnessModelRequest,
667
+ api: HarnessHookApi
668
+ ) => MaybePromise<HarnessModelRequest | undefined>;
669
+ /** `{block}` refuses the call (the reason is the model's error result); `{args}` rewrites. */
670
+ beforeTool: (
671
+ call: HarnessToolCall,
672
+ api: HarnessToolHookApi
673
+ ) => MaybePromise<HarnessBeforeToolResult>;
674
+ }
675
+
676
+ export const HARNESS_HOOK_KINDS = {
677
+ afterTool: "afterTool",
678
+ beforeModelRequest: "beforeModelRequest",
679
+ beforeTool: "beforeTool",
680
+ } as const;
681
+
682
+ export type HarnessHookKind = keyof HarnessHookHandlers;
683
+
684
+ /** One hook, made by `hook(kind, fn)`. */
685
+ export type HarnessHook = {
686
+ [K in HarnessHookKind]: {hook: K; kind: "hook"; run: HarnessHookHandlers[K]};
687
+ }[HarnessHookKind];
688
+
689
+ /** What a section builder receives about the request it contributes to. */
690
+ export interface HarnessSectionInput {
691
+ agentName: string;
692
+ conversationId: string;
693
+ /** Messages about to be sent (before `beforeModelRequest` hooks). */
694
+ messages: ReadonlyArray<ModelMessage>;
695
+ /** 1 for the turn's first model request, 2 for the next, ... */
696
+ step: number;
697
+ }
698
+
699
+ /** A named piece of the system prompt, rebuilt before every model request. */
700
+ export interface HarnessSection {
701
+ build: (input: HarnessSectionInput, api: HarnessHookApi) => MaybePromise<string | undefined>;
702
+ kind: "section";
703
+ name: string;
704
+ }
705
+
706
+ /** Replaces the winning tool of `toolName` with a decorated tool, made by `wrapTool`. */
707
+ export interface HarnessToolWrap {
708
+ kind: "wrap";
709
+ toolName: string;
710
+ wrap: (tool: AnyHarnessToolDefinition) => AnyHarnessToolDefinition;
711
+ }
712
+
713
+ export interface HarnessExtensionDefinitionInput {
714
+ /** Who may decide each `api.approval(key)` this extension's `beforeTool` hooks request. */
715
+ approvals?: Readonly<Record<string, HarnessApprovalPolicy>>;
716
+ hooks?: ReadonlyArray<HarnessHook>;
717
+ /** Unique within a harness registry; agents and conversations reference it by name. */
718
+ name: string;
719
+ sections?: ReadonlyArray<HarnessSection>;
720
+ /** Added to the agent's tools; a later tool with the same name replaces an earlier one. */
721
+ tools?: ReadonlyArray<AnyHarnessToolDefinition>;
722
+ wraps?: ReadonlyArray<HarnessToolWrap>;
723
+ }
724
+
725
+ export interface HarnessExtensionDefinition {
726
+ approvals: Readonly<Record<string, HarnessApprovalPolicy>>;
727
+ hooks: ReadonlyArray<HarnessHook>;
728
+ kind: "extension";
729
+ name: string;
730
+ sections: ReadonlyArray<HarnessSection>;
731
+ tools: ReadonlyArray<AnyHarnessToolDefinition>;
732
+ wraps: ReadonlyArray<HarnessToolWrap>;
733
+ }
734
+
735
+ /** Durable memo row; unique per `(taskId, key)`. */
736
+ export interface HarnessMemoDocument extends mongoose.Document<mongoose.Types.ObjectId> {
737
+ created: Date;
738
+ key: string;
739
+ taskId: mongoose.Types.ObjectId;
740
+ updated: Date;
741
+ value?: unknown;
742
+ }
743
+
744
+ export interface HarnessMemoModel
745
+ extends mongoose.Model<HarnessMemoDocument>,
746
+ FindExactlyOnePlugin<HarnessMemoDocument>,
747
+ FindOneOrNonePlugin<HarnessMemoDocument> {}
748
+
749
+ export const HARNESS_CONVERSATION_STATUSES = {
750
+ busy: "busy",
751
+ idle: "idle",
752
+ } as const;
753
+
754
+ export type HarnessConversationStatus =
755
+ (typeof HARNESS_CONVERSATION_STATUSES)[keyof typeof HARNESS_CONVERSATION_STATUSES];
756
+
757
+ export const HARNESS_MESSAGE_ROLES = {
758
+ assistant: "assistant",
759
+ system: "system",
760
+ tool: "tool",
761
+ user: "user",
762
+ } as const;
763
+
764
+ export type HarnessMessageRole = (typeof HARNESS_MESSAGE_ROLES)[keyof typeof HARNESS_MESSAGE_ROLES];
765
+
766
+ export interface HarnessTextPart {
767
+ text: string;
768
+ type: "text";
769
+ }
770
+
771
+ export interface HarnessToolCallPart {
772
+ input: unknown;
773
+ toolCallId: string;
774
+ toolName: string;
775
+ type: "tool-call";
776
+ }
777
+
778
+ /**
779
+ * The effective system prompt of a model request, recorded on a `system` message when it
780
+ * differs from the last one recorded. Never sent to the model as a message.
781
+ */
782
+ export interface HarnessSystemPromptPart {
783
+ /** sha256 of `text`. */
784
+ hash: string;
785
+ /** Extension sections that contributed, in prompt order. */
786
+ sections: Array<{extension: string; name: string}>;
787
+ text: string;
788
+ type: "system-prompt";
789
+ }
790
+
791
+ export interface HarnessToolResultPart {
792
+ isError: boolean;
793
+ output: unknown;
794
+ toolCallId: string;
795
+ toolName: string;
796
+ type: "tool-result";
797
+ }
798
+
799
+ export type HarnessMessagePart =
800
+ | HarnessSystemPromptPart
801
+ | HarnessTextPart
802
+ | HarnessToolCallPart
803
+ | HarnessToolResultPart;
804
+
805
+ /** Agent config snapshotted onto a conversation when it is created. */
806
+ export interface HarnessConversationAgent {
807
+ extensions: string[];
808
+ fallbackModels: HarnessModelRef[];
809
+ instructions: string;
810
+ maxSteps: number;
811
+ model: HarnessModelRef;
812
+ name: string;
813
+ /**
814
+ * JSON Schema (serialized) the final answer must match, requested from the model as
815
+ * structured output. Set by `rt.runAgent` with an `output` schema.
816
+ */
817
+ outputSchema?: string;
818
+ tools: string[];
819
+ }
820
+
821
+ /** What `send` does with a message that arrives while a turn is running. */
822
+ export const HARNESS_WHEN_BUSY = {
823
+ /** Run it as its own turn once the active turn (and any earlier queued ones) finish. */
824
+ queue: "queue",
825
+ /** Add it to the active turn: its next model request includes the message. */
826
+ steer: "steer",
827
+ } as const;
828
+
829
+ export type HarnessWhenBusy = (typeof HARNESS_WHEN_BUSY)[keyof typeof HARNESS_WHEN_BUSY];
830
+
831
+ /** A submission waiting on a conversation: queued for a later turn, or steering the active one. */
832
+ export interface HarnessQueuedSubmission {
833
+ content?: unknown;
834
+ requestId?: string;
835
+ submittedAt?: Date;
836
+ whenBusy?: HarnessWhenBusy;
837
+ }
838
+
839
+ export interface HarnessConversationDocument extends mongoose.Document<mongoose.Types.ObjectId> {
840
+ activeTurnTaskId?: mongoose.Types.ObjectId;
841
+ agent: HarnessConversationAgent;
842
+ created: Date;
843
+ deleted: boolean;
844
+ /** Which `rt.runAgent` call of the owning task created this subagent conversation. */
845
+ ownerKey?: string;
846
+ ownership: HarnessOwnership;
847
+ queued: HarnessQueuedSubmission[];
848
+ /** Highest message `seq` handed out so far. */
849
+ seq: number;
850
+ status: HarnessConversationStatus;
851
+ updated: Date;
852
+ userId?: mongoose.Types.ObjectId;
853
+ }
854
+
855
+ export interface HarnessConversationModel
856
+ extends mongoose.Model<HarnessConversationDocument>,
857
+ FindExactlyOnePlugin<HarnessConversationDocument>,
858
+ FindOneOrNonePlugin<HarnessConversationDocument> {}
859
+
860
+ export interface HarnessMessageDocument extends mongoose.Document<mongoose.Types.ObjectId> {
861
+ aborted: boolean;
862
+ conversationId: mongoose.Types.ObjectId;
863
+ created: Date;
864
+ deleted: boolean;
865
+ parts: HarnessMessagePart[];
866
+ /** Submitter's idempotency key, on user messages that came from `submit` / `send`. */
867
+ requestId?: string;
868
+ role: HarnessMessageRole;
869
+ seq: number;
870
+ status?: "error" | "ok";
871
+ toolCallId?: string;
872
+ toolName?: string;
873
+ turnTaskId?: mongoose.Types.ObjectId;
874
+ updated: Date;
875
+ }
876
+
877
+ export interface HarnessMessageModel
878
+ extends mongoose.Model<HarnessMessageDocument>,
879
+ FindExactlyOnePlugin<HarnessMessageDocument>,
880
+ FindOneOrNonePlugin<HarnessMessageDocument> {}
881
+
882
+ /** Result of a completed `terreno.agent.turn` task. */
883
+ export interface HarnessTurnResult {
884
+ /** `stop` when the model answered without tool calls; `max-steps` when the cap ended it. */
885
+ finishReason: "max-steps" | "stop";
886
+ /** Parsed structured output, when the agent declares `output`. */
887
+ output?: unknown;
888
+ /** Model requests made in the turn. */
889
+ steps: number;
890
+ /** Text of the last assistant message. */
891
+ text: string;
892
+ }
893
+
894
+ export interface HarnessSubmitOptions {
895
+ content: string;
896
+ /** Idempotency key: a repeated submit returns the turn task it started. */
897
+ requestId: string;
898
+ }
899
+
900
+ export interface HarnessSendOptions extends HarnessSubmitOptions {
901
+ /** What to do when a turn is already running. */
902
+ whenBusy: HarnessWhenBusy;
903
+ }
904
+
905
+ /** How `send` handled a submission. */
906
+ export const HARNESS_SUBMIT_DISPOSITIONS = {
907
+ /** Waiting for the active turn (and earlier queued submissions) to finish. */
908
+ queued: "queued",
909
+ /** Started a new turn. */
910
+ started: "started",
911
+ /** Joined the active turn; its next model request includes the message. */
912
+ steered: "steered",
913
+ } as const;
914
+
915
+ export type HarnessSubmitDisposition =
916
+ (typeof HARNESS_SUBMIT_DISPOSITIONS)[keyof typeof HARNESS_SUBMIT_DISPOSITIONS];
917
+
918
+ export interface HarnessSubmitResult {
919
+ conversationId: string;
920
+ disposition: HarnessSubmitDisposition;
921
+ requestId: string;
922
+ /** The turn that runs (or ran) the message; unset while it is queued. */
923
+ turnTaskId?: string;
924
+ }
925
+
926
+ // ---------------------------------------------------------------------------------------
927
+ // Event log (SSE source)
928
+ // ---------------------------------------------------------------------------------------
929
+
930
+ /** Every `HarnessEvent` type. Conversation streams and task streams carry different ones. */
931
+ export const HARNESS_EVENT_TYPES = {
932
+ /** Task stream: an approval was approved, rejected, or expired. */
933
+ approvalDecided: "approval.decided",
934
+ /** Task stream: `rt.approval` created a pending approval. */
935
+ approvalRequested: "approval.requested",
936
+ /** Conversation stream: coalesced model text while a request streams; expires. */
937
+ delta: "delta",
938
+ /** Conversation stream: a transcript message was committed. */
939
+ messageCreated: "message.created",
940
+ /** Conversation stream: `send` queued a message or added it to the active turn. */
941
+ messageQueued: "message.queued",
942
+ /** Task stream: text a phase sent with `rt.output`. */
943
+ output: "output",
944
+ /** Task stream: a task was created or committed a new status or phase. */
945
+ taskStatus: "task.status",
946
+ /** Conversation stream: a tool call's task ended. */
947
+ toolFinished: "tool.finished",
948
+ /** Conversation stream: a tool call's task was created. */
949
+ toolStarted: "tool.started",
950
+ /** Conversation stream: a turn task ended. */
951
+ turnFinished: "turn.finished",
952
+ /** Conversation stream: a turn task was created. */
953
+ turnStarted: "turn.started",
954
+ } as const;
955
+
956
+ export type HarnessEventType = (typeof HARNESS_EVENT_TYPES)[keyof typeof HARNESS_EVENT_TYPES];
957
+
958
+ /** One entry of a conversation's or task tree's event log. */
959
+ export interface HarnessEventDocument extends mongoose.Document<mongoose.Types.ObjectId> {
960
+ created: Date;
961
+ /** Set on `delta` events only; Mongo deletes the row after it. */
962
+ expiresAt?: Date;
963
+ payload?: unknown;
964
+ /** Position in the stream: strictly increasing from 1, unique per stream. */
965
+ seq: number;
966
+ /** Conversation id, or root task id for a task tree. */
967
+ streamId: mongoose.Types.ObjectId;
968
+ /** Task the event is about, when there is one. */
969
+ taskId?: mongoose.Types.ObjectId;
970
+ /** On task-stream events: the task and every task above it. */
971
+ taskPath: mongoose.Types.ObjectId[];
972
+ type: HarnessEventType;
973
+ }
974
+
975
+ export interface HarnessEventModel extends mongoose.Model<HarnessEventDocument> {}
976
+
977
+ /** Hands out a stream's event `seq`s. */
978
+ export interface HarnessEventStreamDocument extends mongoose.Document<mongoose.Types.ObjectId> {
979
+ seq: number;
980
+ }
981
+
982
+ export interface HarnessEventStreamModel extends mongoose.Model<HarnessEventStreamDocument> {}
983
+
984
+ /** How a streaming model request is written to the event log. */
985
+ export interface HarnessStreamingOptions {
986
+ /** Flush a delta once this many characters are buffered. Default 200. */
987
+ deltaFlushChars?: number;
988
+ /** Flush buffered text at least this often while a request streams. Default 250 ms. */
989
+ deltaFlushInterval?: DurationLike;
990
+ /** How long `delta` events are kept. Default 1 hour. */
991
+ deltaTtl?: DurationLike;
992
+ }
993
+
994
+ // ---------------------------------------------------------------------------------------
995
+ // Approvals
996
+ // ---------------------------------------------------------------------------------------
997
+
998
+ /** Lifecycle of a `HarnessApproval`. */
999
+ export const HARNESS_APPROVAL_STATUSES = {
1000
+ approved: "approved",
1001
+ expired: "expired",
1002
+ pending: "pending",
1003
+ rejected: "rejected",
1004
+ } as const;
1005
+
1006
+ export type HarnessApprovalStatus =
1007
+ (typeof HARNESS_APPROVAL_STATUSES)[keyof typeof HARNESS_APPROVAL_STATUSES];
1008
+
1009
+ /** A human decision requested by `rt.approval` (or a `beforeTool` hook's `api.approval`). */
1010
+ export interface HarnessApprovalDocument extends mongoose.Document<mongoose.Types.ObjectId> {
1011
+ /** `<step>:<n>` of the wait call that requested it; unique per task. */
1012
+ callKey: string;
1013
+ created: Date;
1014
+ decidedAt?: Date;
1015
+ decidedBy?: mongoose.Types.ObjectId;
1016
+ /** `name@version:key` of the requesting task definition and approval key. */
1017
+ definitionKey: string;
1018
+ /** Inbox event the decision sends to the task. */
1019
+ event: string;
1020
+ expiresAt?: Date;
1021
+ /** Extension whose `approvals` hold the approvers (hook approvals only). */
1022
+ extension?: string;
1023
+ /** Approval key; selects the approvers policy. */
1024
+ key: string;
1025
+ payload?: unknown;
1026
+ reason?: string;
1027
+ rootTaskId: mongoose.Types.ObjectId;
1028
+ status: HarnessApprovalStatus;
1029
+ summary?: string;
1030
+ taskId: mongoose.Types.ObjectId;
1031
+ title: string;
1032
+ traceId: mongoose.Types.ObjectId;
1033
+ updated: Date;
1034
+ }
1035
+
1036
+ export interface HarnessApprovalModel
1037
+ extends mongoose.Model<HarnessApprovalDocument>,
1038
+ FindExactlyOnePlugin<HarnessApprovalDocument>,
1039
+ FindOneOrNonePlugin<HarnessApprovalDocument> {}
1040
+
1041
+ /**
1042
+ * One approver check, in the `@terreno/api` permission shape: `(method, user, approval)`.
1043
+ * `method` is `list`, `read`, or `update` (approve / reject). Every check of a policy must
1044
+ * pass (AND), like modelRouter permissions.
1045
+ */
1046
+ export type HarnessApprover = PermissionMethod<HarnessApprovalDocument>;
1047
+
1048
+ /** Who may decide one approval key. An empty `approvers` list means nobody (over HTTP). */
1049
+ export interface HarnessApprovalPolicy {
1050
+ approvers: ReadonlyArray<HarnessApprover>;
1051
+ }
1052
+
1053
+ /** Options for `rt.approval` / `api.approval`. */
1054
+ export interface HarnessApprovalOptions {
1055
+ /**
1056
+ * Called once, after the approval is first stored, with the stored document (send an
1057
+ * email or push with `@terreno/comms`). Best-effort: a throw is logged and ignored, and a
1058
+ * crash right after the commit skips it.
1059
+ */
1060
+ notify?: (approval: HarnessApprovalDocument) => Promise<void> | void;
1061
+ /** What the approver reviews (JSON). */
1062
+ payload?: unknown;
1063
+ /** Short explanation shown under the title. */
1064
+ summary?: string;
1065
+ /** Expire the approval when nobody decides within this long. Must be positive. */
1066
+ timeout?: DurationLike;
1067
+ title: string;
1068
+ }
1069
+
1070
+ /** What `rt.approval` returns. */
1071
+ export interface HarnessApprovalResult {
1072
+ approvalId: string;
1073
+ approved: boolean;
1074
+ /** ISO time of the decision; unset when expired. */
1075
+ decidedAt?: string;
1076
+ /** User id of the decider; unset when expired or decided without a user. */
1077
+ decidedBy?: string;
1078
+ /** True when `timeout` passed before a decision. */
1079
+ expired?: boolean;
1080
+ reason?: string;
1081
+ }
1082
+
1083
+ export type HarnessApprovalRequest = (
1084
+ key: string,
1085
+ options: HarnessApprovalOptions
1086
+ ) => Promise<HarnessApprovalResult>;
1087
+
1088
+ /** Options for `harness.decideApproval`. */
1089
+ export interface HarnessDecideApprovalOptions {
1090
+ approved: boolean;
1091
+ /** Why; recorded on the approval and its span. */
1092
+ reason?: string;
1093
+ /** Who decided; recorded as `decidedBy`. */
1094
+ userId?: mongoose.Types.ObjectId | string;
1095
+ }