@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,1082 @@
1
+ import {randomUUID} from "node:crypto";
2
+ import {
3
+ tool as aiTool,
4
+ generateText,
5
+ type JSONValue,
6
+ jsonSchema,
7
+ type LanguageModel,
8
+ type ModelMessage,
9
+ NoObjectGeneratedError,
10
+ NoOutputGeneratedError,
11
+ Output,
12
+ streamText,
13
+ type TextPart,
14
+ type ToolCallPart,
15
+ type ToolContent,
16
+ type ToolResultPart,
17
+ type ToolSet,
18
+ } from "ai";
19
+ import {DateTime} from "luxon";
20
+ import type mongoose from "mongoose";
21
+ import type {ModelPrice} from "../observability/types";
22
+ import {withStrippedJsonFencesModel} from "../service/jsonFenceModel";
23
+ import {normalizeLlmJsonTextForStructuredOutput} from "../service/parseAiJson";
24
+ import type {
25
+ AnyHarnessToolDefinition,
26
+ HarnessAgentDefinition,
27
+ HarnessChildOutcome,
28
+ HarnessConversationDocument,
29
+ HarnessExtensionDefinition,
30
+ HarnessHookApi,
31
+ HarnessMessageDocument,
32
+ HarnessMessagePart,
33
+ HarnessModelResolver,
34
+ HarnessQueuedSubmission,
35
+ HarnessReplayPolicy,
36
+ HarnessSystemPromptPart,
37
+ HarnessTaskDefinition,
38
+ HarnessTaskRuntime,
39
+ HarnessTaskView,
40
+ HarnessToolCallPart,
41
+ HarnessToolResultPart,
42
+ HarnessTurnResult,
43
+ } from "../types/harness";
44
+ import {HARNESS_MESSAGE_ROLES, HARNESS_WHEN_BUSY} from "../types/harness";
45
+ import {AGENT_TOOL_TASK_NAME, AGENT_TURN_TASK_NAME} from "./agentTaskNames";
46
+ import type {HarnessCommitWrites, HarnessModels} from "./commit";
47
+ import {defineTask} from "./defineTask";
48
+ import {errorMessage, harnessError} from "./errors";
49
+ import {HarnessDeltaWriter, insertMessages, type ResolvedStreamingOptions} from "./events";
50
+ import {
51
+ buildSystemPrompt,
52
+ HarnessExtensionError,
53
+ hashText,
54
+ resolveExtensions,
55
+ resolveTools,
56
+ runAfterTool,
57
+ runBeforeModelRequest,
58
+ runBeforeTool,
59
+ } from "./extensions";
60
+ import {internalRuntime} from "./internalRuntime";
61
+ import {callModelWithFallback, HarnessModelCallError} from "./modelCall";
62
+ import {isHarnessSuspendSignal} from "./suspend";
63
+
64
+ /** Everything the built-in agent tasks need from their harness. */
65
+ export interface AgentLoopContext {
66
+ agents: Map<string, HarnessAgentDefinition>;
67
+ extensions: Map<string, HarnessExtensionDefinition>;
68
+ models: HarnessModels;
69
+ /** Read at call time so an `ObservabilityApp` registered later still prices calls. */
70
+ priceMap: () => Record<string, ModelPrice> | undefined;
71
+ random?: () => number;
72
+ resolveModel?: HarnessModelResolver;
73
+ streaming: ResolvedStreamingOptions;
74
+ }
75
+
76
+ export interface AgentTurnInput {
77
+ conversationId: string;
78
+ }
79
+
80
+ interface PendingToolCall {
81
+ input: unknown;
82
+ toolCallId: string;
83
+ toolName: string;
84
+ }
85
+
86
+ interface AgentTurnState {
87
+ /** Model requests made so far in this turn. */
88
+ step: number;
89
+ /** Text of the latest assistant message. */
90
+ text: string;
91
+ /** Tool calls of the latest assistant message, awaiting results. */
92
+ toolCalls?: PendingToolCall[];
93
+ }
94
+
95
+ interface AgentToolInput {
96
+ agentName: string;
97
+ conversationId: string;
98
+ /** Whether the conversation's agent snapshot lists this tool; others are refused. */
99
+ enabled: boolean;
100
+ input: unknown;
101
+ replay: HarnessReplayPolicy;
102
+ toolCallId: string;
103
+ toolName: string;
104
+ }
105
+
106
+ interface AgentToolResult {
107
+ /** Text the tool sent through `api.output`, when any. */
108
+ streamedOutput?: string;
109
+ value: unknown;
110
+ }
111
+
112
+ export interface AgentTasks {
113
+ tool: HarnessTaskDefinition<AgentToolInput, unknown, AgentToolResult>;
114
+ turn: HarnessTaskDefinition<AgentTurnInput, AgentTurnState, HarnessTurnResult>;
115
+ }
116
+
117
+ /** A tool's own `execute` threw; reported to the model as `Tool "<name>" failed: ...`. */
118
+ class ToolExecuteError extends Error {
119
+ constructor(toolName: string, cause: unknown) {
120
+ super(`Tool "${toolName}" failed: ${errorMessage(cause)}`);
121
+ this.name = "ToolExecuteError";
122
+ }
123
+ }
124
+
125
+ /** Tool results must be JSON; `undefined` becomes `null`. */
126
+ const toJsonValue = (value: unknown): unknown => {
127
+ if (value === undefined) {
128
+ return null;
129
+ }
130
+ return JSON.parse(JSON.stringify(value));
131
+ };
132
+
133
+ const requireAgent = (context: AgentLoopContext, name: string): HarnessAgentDefinition => {
134
+ const agent = context.agents.get(name);
135
+ if (!agent) {
136
+ throw harnessError({
137
+ detail: `Agent "${name}" is not in this harness registry`,
138
+ kind: "notRegistered",
139
+ });
140
+ }
141
+ return agent;
142
+ };
143
+
144
+ const textOf = (parts: ReadonlyArray<HarnessMessagePart>): string =>
145
+ parts
146
+ .filter((part): part is {text: string; type: "text"} => part.type === "text")
147
+ .map((part) => part.text)
148
+ .join("");
149
+
150
+ const isSystemPromptRecord = (message: Pick<HarnessMessageDocument, "parts">): boolean =>
151
+ message.parts.some((part) => part.type === "system-prompt");
152
+
153
+ /**
154
+ * Mark assistant messages from this turn aborted when they still contain a tool call
155
+ * with no stored result. The next request skips those messages, so a provider never
156
+ * sees a tool call without its tool result.
157
+ */
158
+ const markUnansweredToolCallsAborted = async ({
159
+ conversationId,
160
+ models,
161
+ turnTaskId,
162
+ }: {
163
+ conversationId: string;
164
+ models: HarnessModels;
165
+ turnTaskId: string;
166
+ }): Promise<void> => {
167
+ const messages = await models.message.find({conversationId, turnTaskId}).sort({seq: 1});
168
+ const answered = new Set<string>();
169
+ for (const message of messages) {
170
+ if (message.role !== HARNESS_MESSAGE_ROLES.tool) {
171
+ continue;
172
+ }
173
+ if (message.toolCallId) {
174
+ answered.add(message.toolCallId);
175
+ }
176
+ for (const part of message.parts) {
177
+ if (part.type === "tool-result") {
178
+ answered.add(part.toolCallId);
179
+ }
180
+ }
181
+ }
182
+ const orphanIds = messages
183
+ .filter((message) => message.role === HARNESS_MESSAGE_ROLES.assistant && !message.aborted)
184
+ .filter((message) =>
185
+ message.parts.some((part) => part.type === "tool-call" && !answered.has(part.toolCallId))
186
+ )
187
+ .map((message) => message._id);
188
+ if (orphanIds.length === 0) {
189
+ return;
190
+ }
191
+ await models.message.updateMany({_id: {$in: orphanIds}}, {$set: {aborted: true}});
192
+ };
193
+
194
+ /** Convert the stored transcript to AI SDK messages. Aborted (partial) messages are skipped. */
195
+ const toModelMessages = (
196
+ history: ReadonlyArray<Pick<HarnessMessageDocument, "aborted" | "parts" | "role">>
197
+ ): ModelMessage[] => {
198
+ const messages: ModelMessage[] = [];
199
+ for (const message of history) {
200
+ // Aborted partials and recorded system prompts are never replayed to the model.
201
+ if (message.aborted || isSystemPromptRecord(message)) {
202
+ continue;
203
+ }
204
+ if (message.role === HARNESS_MESSAGE_ROLES.user) {
205
+ messages.push({content: textOf(message.parts), role: "user"});
206
+ } else if (message.role === HARNESS_MESSAGE_ROLES.system) {
207
+ messages.push({content: textOf(message.parts), role: "system"});
208
+ } else if (message.role === HARNESS_MESSAGE_ROLES.assistant) {
209
+ const content: Array<TextPart | ToolCallPart> = [];
210
+ for (const part of message.parts) {
211
+ if (part.type === "text" && part.text) {
212
+ content.push({text: part.text, type: "text"});
213
+ } else if (part.type === "tool-call") {
214
+ content.push({
215
+ input: part.input,
216
+ toolCallId: part.toolCallId,
217
+ toolName: part.toolName,
218
+ type: "tool-call",
219
+ });
220
+ }
221
+ }
222
+ if (content.length > 0) {
223
+ messages.push({content, role: "assistant"});
224
+ }
225
+ } else {
226
+ const content: ToolContent = message.parts
227
+ .filter((part): part is HarnessToolResultPart => part.type === "tool-result")
228
+ .map(
229
+ (part): ToolResultPart => ({
230
+ output: part.isError
231
+ ? {type: "error-text", value: String(part.output)}
232
+ : {type: "json", value: (part.output ?? null) as JSONValue},
233
+ toolCallId: part.toolCallId,
234
+ toolName: part.toolName,
235
+ type: "tool-result",
236
+ })
237
+ );
238
+ if (content.length > 0) {
239
+ messages.push({content, role: "tool"});
240
+ }
241
+ }
242
+ }
243
+ return messages;
244
+ };
245
+
246
+ /** AI SDK tools without `execute`: the model's calls come back to the turn, which runs them. */
247
+ const buildToolSet = (
248
+ available: Map<string, AnyHarnessToolDefinition>,
249
+ allowed: ReadonlyArray<string>
250
+ ): ToolSet | undefined => {
251
+ const tools = [...available.values()].filter((tool) => allowed.includes(tool.name));
252
+ if (tools.length === 0) {
253
+ return undefined;
254
+ }
255
+ return Object.fromEntries(
256
+ tools.map((tool) => [
257
+ tool.name,
258
+ aiTool({description: tool.description, inputSchema: tool.parameters as never}),
259
+ ])
260
+ );
261
+ };
262
+
263
+ const costUsd = ({
264
+ inputTokens,
265
+ modelId,
266
+ outputTokens,
267
+ priceMap,
268
+ }: {
269
+ inputTokens?: number;
270
+ modelId: string;
271
+ outputTokens?: number;
272
+ priceMap?: Record<string, ModelPrice>;
273
+ }): number | undefined => {
274
+ const price = priceMap?.[modelId];
275
+ if (!price || inputTokens === undefined || outputTokens === undefined) {
276
+ return undefined;
277
+ }
278
+ return (price.inputPerMTok * inputTokens + price.outputPerMTok * outputTokens) / 1_000_000;
279
+ };
280
+
281
+ /** Hand out `count` consecutive message seqs for a conversation inside a transaction. */
282
+ const allocateSeqs = async ({
283
+ conversationId,
284
+ count,
285
+ models,
286
+ session,
287
+ }: {
288
+ conversationId: string;
289
+ count: number;
290
+ models: HarnessModels;
291
+ session: mongoose.ClientSession;
292
+ }): Promise<number> => {
293
+ const updated = await models.conversation.findOneAndUpdate(
294
+ {_id: conversationId},
295
+ {$inc: {seq: count}},
296
+ {returnDocument: "after", session}
297
+ );
298
+ if (!updated) {
299
+ throw harnessError({
300
+ detail: `Conversation ${conversationId} no longer exists`,
301
+ kind: "notFound",
302
+ });
303
+ }
304
+ return updated.seq - count + 1;
305
+ };
306
+
307
+ /** How an `LLM` span names the system prompt it sent. */
308
+ interface SystemPromptSpan {
309
+ hash: string;
310
+ /** The `system` message holding the text; unset when it is the snapshot's instructions. */
311
+ messageSeq?: number;
312
+ sections: HarnessSystemPromptPart["sections"];
313
+ }
314
+
315
+ /**
316
+ * Decide how a request's effective system prompt is recorded. When it differs from the
317
+ * last recorded prompt (or, before any, from the conversation's instructions), `write`
318
+ * appends a `system` message with a `system-prompt` part inside the request's commit, so
319
+ * the transcript holds exactly what the model saw. `span` names it by hash and seq.
320
+ */
321
+ const promptRecord = ({
322
+ conversation,
323
+ history,
324
+ models,
325
+ sections,
326
+ system,
327
+ }: {
328
+ conversation: HarnessConversationDocument;
329
+ history: ReadonlyArray<HarnessMessageDocument>;
330
+ models: HarnessModels;
331
+ sections: HarnessSystemPromptPart["sections"];
332
+ system: string;
333
+ }): {span: SystemPromptSpan; write: HarnessCommitWrites} => {
334
+ const hash = hashText(system);
335
+ const last = [...history].reverse().find(isSystemPromptRecord);
336
+ const lastPart = last?.parts.find(
337
+ (part): part is HarnessSystemPromptPart => part.type === "system-prompt"
338
+ );
339
+ const baseline = lastPart ? lastPart.hash : hashText(conversation.agent.instructions);
340
+ const span: SystemPromptSpan = {hash, messageSeq: lastPart ? last?.seq : undefined, sections};
341
+ if (hash === baseline) {
342
+ return {span, write: async () => {}};
343
+ }
344
+ const conversationId = String(conversation._id);
345
+ return {
346
+ span,
347
+ write: async ({session, task}) => {
348
+ const seq = await allocateSeqs({conversationId, count: 1, models, session});
349
+ const part: HarnessSystemPromptPart = {hash, sections, text: system, type: "system-prompt"};
350
+ await insertMessages({
351
+ messages: [
352
+ {
353
+ conversationId: conversation._id,
354
+ parts: [part],
355
+ role: HARNESS_MESSAGE_ROLES.system,
356
+ seq,
357
+ turnTaskId: task._id,
358
+ },
359
+ ],
360
+ models,
361
+ session,
362
+ });
363
+ span.messageSeq = seq;
364
+ },
365
+ };
366
+ };
367
+
368
+ /** What the turn keeps from one model response. */
369
+ interface ModelResponse {
370
+ finishReason: string;
371
+ /** Why the answer failed the conversation's `outputSchema`, when it did. */
372
+ invalidOutput?: string;
373
+ /** Parsed structured output, when the conversation requests one. */
374
+ output?: unknown;
375
+ text: string;
376
+ toolCalls: ReadonlyArray<{input: unknown; toolCallId: string; toolName: string}>;
377
+ usage: {inputTokens?: number; outputTokens?: number};
378
+ }
379
+
380
+ /**
381
+ * The SDK parses structured output only for a final answer (`stop`, or text without tool
382
+ * calls); otherwise reading it throws. Missing output is the caller's to report.
383
+ */
384
+ const structuredOutputOf = (generated: {output: unknown}): unknown => {
385
+ try {
386
+ return generated.output;
387
+ } catch (error: unknown) {
388
+ if (NoOutputGeneratedError.isInstance(error)) {
389
+ return undefined;
390
+ }
391
+ throw error;
392
+ }
393
+ };
394
+
395
+ const describeInvalidOutput = (agentName: string, error: NoObjectGeneratedError): string => {
396
+ const cause = error.cause ? `: ${errorMessage(error.cause)}` : "";
397
+ return `Agent "${agentName}" output does not match its schema (${error.message})${cause}`;
398
+ };
399
+
400
+ /** Parse the final answer against the agent's `output` schema. */
401
+ const parseStructuredOutput = (
402
+ agent: HarnessAgentDefinition,
403
+ text: string
404
+ ): {error?: string; output?: unknown} => {
405
+ if (!agent.output) {
406
+ return {};
407
+ }
408
+ let parsed: unknown;
409
+ try {
410
+ parsed = JSON.parse(normalizeLlmJsonTextForStructuredOutput(text));
411
+ } catch (error: unknown) {
412
+ return {error: `Agent "${agent.name}" output is not JSON: ${errorMessage(error)}`};
413
+ }
414
+ const result = agent.output.safeParse(parsed);
415
+ if (!result.success) {
416
+ return {
417
+ error: `Agent "${agent.name}" output does not match its schema: ${result.error.message}`,
418
+ };
419
+ }
420
+ return {output: result.data};
421
+ };
422
+
423
+ const loadConversation = (
424
+ models: HarnessModels,
425
+ conversationId: string
426
+ ): Promise<HarnessConversationDocument> =>
427
+ models.conversation.findExactlyOne({_id: conversationId});
428
+
429
+ /**
430
+ * Steering submissions waiting for this turn's next model request, and the commit write
431
+ * that stores them as user messages (before the assistant answer) and removes them from
432
+ * the queue. Entries whose message already exists are only removed.
433
+ */
434
+ const pendingSteering = async ({
435
+ conversation,
436
+ models,
437
+ }: {
438
+ conversation: HarnessConversationDocument;
439
+ models: HarnessModels;
440
+ }): Promise<{entries: HarnessQueuedSubmission[]; write: HarnessCommitWrites}> => {
441
+ const steer = conversation.queued.filter(
442
+ (entry) => entry.whenBusy === HARNESS_WHEN_BUSY.steer && entry.requestId
443
+ );
444
+ if (steer.length === 0) {
445
+ return {entries: [], write: async () => {}};
446
+ }
447
+ const requestIds = steer.map((entry) => entry.requestId as string);
448
+ const delivered = new Set(
449
+ (
450
+ await models.message
451
+ .find({conversationId: conversation._id, requestId: {$in: requestIds}})
452
+ .select({requestId: 1})
453
+ .lean()
454
+ ).map((message) => message.requestId)
455
+ );
456
+ const entries = steer.filter((entry) => !delivered.has(entry.requestId));
457
+ const conversationId = String(conversation._id);
458
+ return {
459
+ entries,
460
+ write: async ({session, task}) => {
461
+ if (entries.length > 0) {
462
+ const first = await allocateSeqs({conversationId, count: entries.length, models, session});
463
+ await insertMessages({
464
+ messages: entries.map((entry, index) => ({
465
+ conversationId: conversation._id,
466
+ parts: [{text: String(entry.content ?? ""), type: "text"}],
467
+ requestId: entry.requestId,
468
+ role: HARNESS_MESSAGE_ROLES.user,
469
+ seq: first + index,
470
+ turnTaskId: task._id,
471
+ })),
472
+ models,
473
+ session,
474
+ });
475
+ }
476
+ await models.conversation.updateOne(
477
+ {_id: conversation._id},
478
+ {$pull: {queued: {requestId: {$in: requestIds}}}},
479
+ {session}
480
+ );
481
+ },
482
+ };
483
+ };
484
+
485
+ /**
486
+ * Stream one model request, writing its text as coalesced `delta` events on the
487
+ * conversation stream while it arrives. Each attempt streams under a fresh `requestKey`,
488
+ * so a client can drop the text of an attempt that failed. Deltas are flushed before the
489
+ * response returns, so they precede the commit's `message.created`.
490
+ */
491
+ const streamModelRequest = async ({
492
+ context,
493
+ conversationId,
494
+ messages,
495
+ model,
496
+ rt,
497
+ step,
498
+ system,
499
+ tools,
500
+ }: {
501
+ context: AgentLoopContext;
502
+ conversationId: string;
503
+ messages: ModelMessage[];
504
+ model: LanguageModel;
505
+ rt: HarnessTaskRuntime<AgentTurnState, HarnessTurnResult>;
506
+ step: number;
507
+ system: string | undefined;
508
+ tools: ToolSet | undefined;
509
+ }): Promise<ModelResponse> => {
510
+ const deltas = new HarnessDeltaWriter({
511
+ models: context.models,
512
+ options: context.streaming,
513
+ source: {conversationId, requestKey: randomUUID(), step, turnTaskId: rt.taskId},
514
+ });
515
+ try {
516
+ const streamed = streamText({
517
+ abortSignal: rt.signal,
518
+ // Retries and fallbacks are the harness's; the SDK must not retry on its own.
519
+ maxRetries: 0,
520
+ messages,
521
+ model,
522
+ // Errors are rethrown below, where the harness classifies and retries them.
523
+ onError: () => {},
524
+ system,
525
+ tools,
526
+ });
527
+ for await (const part of streamed.fullStream) {
528
+ if (part.type === "text-delta") {
529
+ deltas.push(part.text);
530
+ } else if (part.type === "error") {
531
+ throw part.error;
532
+ } else if (part.type === "abort") {
533
+ throw rt.signal.reason ?? new Error("Model request aborted");
534
+ }
535
+ }
536
+ const [text, toolCalls, finishReason, usage] = await Promise.all([
537
+ streamed.text,
538
+ streamed.toolCalls,
539
+ streamed.finishReason,
540
+ streamed.usage,
541
+ ]);
542
+ return {finishReason, text, toolCalls, usage};
543
+ } finally {
544
+ await deltas.close();
545
+ }
546
+ };
547
+
548
+ /**
549
+ * Build the built-in `terreno.agent.turn@1` and `terreno.agent.tool@1` task definitions.
550
+ *
551
+ * A turn alternates two replay-safe phases. `request` calls the model (with retries and
552
+ * fallbacks) and commits the assistant message and its LLM span with the checkpoint.
553
+ * `tools` runs each tool call as a child task, waits for all of them, and commits the
554
+ * tool result messages. The loop ends when the model answers without tool calls, or once
555
+ * `maxSteps` model requests have been made.
556
+ */
557
+ export const createAgentTasks = (context: AgentLoopContext): AgentTasks => {
558
+ const {models} = context;
559
+
560
+ /**
561
+ * Free the conversation inside a turn's terminal commit, so `idle` lands with the
562
+ * outcome. Fenced on this turn; the runner's post-commit release covers thrown failures.
563
+ */
564
+ const releaseConversationIn: HarnessCommitWrites = async ({session, task}) => {
565
+ await models.conversation.updateOne(
566
+ {
567
+ _id: (task.input as AgentTurnInput).conversationId,
568
+ activeTurnTaskId: task._id,
569
+ status: "busy",
570
+ },
571
+ {$set: {status: "idle"}, $unset: {activeTurnTaskId: 1}},
572
+ {session}
573
+ );
574
+ };
575
+
576
+ /** Extensions a conversation uses, from its snapshot. */
577
+ const conversationExtensions = (
578
+ conversation: HarnessConversationDocument
579
+ ): HarnessExtensionDefinition[] =>
580
+ resolveExtensions(context.extensions, conversation.agent.extensions ?? []);
581
+
582
+ /** Hook api for a tool call: memos are scoped to the turn task that owns the call. */
583
+ const toolHookApi = async ({
584
+ conversationId,
585
+ extensions,
586
+ rt,
587
+ }: {
588
+ conversationId: string;
589
+ extensions: ReadonlyArray<HarnessExtensionDefinition>;
590
+ rt: HarnessTaskRuntime<unknown, AgentToolResult>;
591
+ }): Promise<HarnessHookApi> => {
592
+ let turnTaskId = rt.taskId;
593
+ if (extensions.length > 0) {
594
+ const self = await models.task.findExactlyOne({_id: rt.taskId});
595
+ turnTaskId = String(self.ownership.id ?? rt.taskId);
596
+ }
597
+ return {
598
+ conversationId,
599
+ memo: internalRuntime(rt as HarnessTaskRuntime<unknown, unknown>).memoFor(turnTaskId),
600
+ signal: rt.signal,
601
+ taskId: rt.taskId,
602
+ turnTaskId,
603
+ };
604
+ };
605
+
606
+ const runTool = async (
607
+ task: HarnessTaskView<AgentToolInput, unknown>,
608
+ rt: HarnessTaskRuntime<unknown, AgentToolResult>
609
+ ): Promise<void> => {
610
+ const {agentName, conversationId, enabled, input, toolCallId, toolName} = task.input;
611
+ const fail = (error: string): Promise<void> => rt.commit({terminal: {error, status: "failed"}});
612
+ const agent = context.agents.get(agentName);
613
+ let extensions: HarnessExtensionDefinition[] = [];
614
+ let tool: AnyHarnessToolDefinition | undefined;
615
+ try {
616
+ if (enabled && agent) {
617
+ extensions = conversationExtensions(await loadConversation(models, conversationId));
618
+ tool = resolveTools(agent, extensions).get(toolName);
619
+ }
620
+ } catch (error: unknown) {
621
+ await fail(errorMessage(error));
622
+ return;
623
+ }
624
+ if (!tool) {
625
+ await fail(`Unknown tool "${toolName}"`);
626
+ return;
627
+ }
628
+ const parsed = tool.parameters.safeParse(input);
629
+ if (!parsed.success) {
630
+ await fail(`Invalid arguments for tool "${toolName}": ${parsed.error.message}`);
631
+ return;
632
+ }
633
+ const streamed: string[] = [];
634
+ let value: unknown;
635
+ try {
636
+ const api = await toolHookApi({conversationId, extensions, rt});
637
+ const before = await runBeforeTool({
638
+ api,
639
+ approvalFor: internalRuntime(rt as HarnessTaskRuntime<unknown, unknown>).approvalFor,
640
+ call: {args: parsed.data, toolCallId, toolName},
641
+ extensions,
642
+ });
643
+ if (before.blocked !== undefined) {
644
+ await fail(before.blocked);
645
+ return;
646
+ }
647
+ const args = tool.parameters.safeParse(before.args);
648
+ if (!args.success) {
649
+ await fail(
650
+ `Invalid arguments for tool "${toolName}" after beforeTool hooks: ${args.error.message}`
651
+ );
652
+ return;
653
+ }
654
+ let returned: unknown;
655
+ try {
656
+ returned = await tool.execute(args.data, {
657
+ conversationId,
658
+ env: rt.env,
659
+ output: (text: string) => {
660
+ streamed.push(String(text));
661
+ },
662
+ signal: rt.signal,
663
+ taskId: rt.taskId,
664
+ });
665
+ } catch (error: unknown) {
666
+ throw new ToolExecuteError(toolName, error);
667
+ }
668
+ value = toJsonValue(
669
+ await runAfterTool({
670
+ api,
671
+ call: {args: args.data, toolCallId, toolName},
672
+ extensions,
673
+ result: toJsonValue(returned),
674
+ })
675
+ );
676
+ } catch (error: unknown) {
677
+ // An abort or an approval wait is the harness's business; any other throw is
678
+ // reported to the model.
679
+ if (rt.signal.aborted || isHarnessSuspendSignal(error)) {
680
+ throw error;
681
+ }
682
+ await fail(
683
+ error instanceof ToolExecuteError || error instanceof HarnessExtensionError
684
+ ? error.message
685
+ : `Tool "${toolName}" failed: ${errorMessage(error)}`
686
+ );
687
+ return;
688
+ }
689
+ const result: AgentToolResult = {value};
690
+ if (streamed.length > 0) {
691
+ result.streamedOutput = streamed.join("");
692
+ }
693
+ await rt.commit({terminal: {result, status: "completed"}});
694
+ };
695
+
696
+ const tool = defineTask<AgentToolInput, unknown, AgentToolResult>({
697
+ // The replay choice is the tool's, so it picks the phase; both phases run the same code.
698
+ initial: (input) => ({phase: input.replay === "safe" ? "executeSafe" : "execute"}),
699
+ name: AGENT_TOOL_TASK_NAME,
700
+ onInterrupt: "fail",
701
+ phases: {
702
+ execute: {run: runTool},
703
+ executeSafe: {replay: "safe", run: runTool},
704
+ },
705
+ // A failing tool is reported to the model, not retried.
706
+ retry: {maxAttempts: 1},
707
+ spanKind: "TOOL",
708
+ spanName: (input) => input.toolName,
709
+ version: 1,
710
+ });
711
+
712
+ const request = async (
713
+ task: HarnessTaskView<AgentTurnInput, AgentTurnState>,
714
+ rt: HarnessTaskRuntime<AgentTurnState, HarnessTurnResult>
715
+ ): Promise<void> => {
716
+ const {conversationId} = task.input;
717
+ const conversation = await loadConversation(models, conversationId);
718
+ const agent = requireAgent(context, conversation.agent.name);
719
+ if (!context.resolveModel) {
720
+ throw harnessError({
721
+ detail: "Harness.open needs a models resolver to run agents",
722
+ kind: "configInvalid",
723
+ });
724
+ }
725
+ const extensions = conversationExtensions(conversation);
726
+ const history = await models.message.find({conversationId}).sort({seq: 1});
727
+ const tools = buildToolSet(resolveTools(agent, extensions), conversation.agent.tools);
728
+ const steering = await pendingSteering({conversation, models});
729
+ // Steering messages join this request after the stored transcript; the commit stores them.
730
+ const transcript = [
731
+ ...toModelMessages(history),
732
+ ...steering.entries.map(
733
+ (entry): ModelMessage => ({content: String(entry.content ?? ""), role: "user"})
734
+ ),
735
+ ];
736
+ const step = task.state.step + 1;
737
+ const internals = internalRuntime(rt as HarnessTaskRuntime<unknown, unknown>);
738
+ const api: HarnessHookApi = {
739
+ conversationId,
740
+ memo: rt.memo,
741
+ signal: rt.signal,
742
+ taskId: rt.taskId,
743
+ turnTaskId: rt.taskId,
744
+ };
745
+ const built = await buildSystemPrompt({
746
+ api,
747
+ extensions,
748
+ input: {
749
+ agentName: agent.name,
750
+ conversationId,
751
+ messages: [...transcript],
752
+ step,
753
+ },
754
+ instructions: conversation.agent.instructions,
755
+ });
756
+ const {request: modelRequest, rewrittenBy} = await runBeforeModelRequest({
757
+ api,
758
+ extensions,
759
+ request: {messages: [...transcript], system: built.text},
760
+ });
761
+ const {messages, system} = modelRequest;
762
+ const prompt = promptRecord({
763
+ conversation,
764
+ history,
765
+ models,
766
+ sections: built.sections,
767
+ system,
768
+ });
769
+ const spanInput = {
770
+ // The transcript is stored permanently; the span names the slice that was sent so
771
+ // its size stays bounded however long the conversation grows.
772
+ messages: {
773
+ count: messages.length,
774
+ fromSeq: history[0]?.seq,
775
+ // A hook replaced the messages: name exactly what was sent by hash.
776
+ ...(rewrittenBy.length > 0 ? {hash: hashText(JSON.stringify(messages))} : {}),
777
+ toSeq: history.at(-1)?.seq,
778
+ },
779
+ models: [conversation.agent.model, ...(conversation.agent.fallbackModels ?? [])],
780
+ ...(rewrittenBy.length > 0 ? {rewrittenBy} : {}),
781
+ system: prompt.span,
782
+ tools: tools ? Object.keys(tools) : [],
783
+ };
784
+ const commit = internals.commitWithWrites;
785
+ const startedAt = DateTime.now();
786
+ const resolveModel = context.resolveModel;
787
+ const {outputSchema} = conversation.agent;
788
+ const output = outputSchema
789
+ ? Output.object({schema: jsonSchema(JSON.parse(outputSchema))})
790
+ : undefined;
791
+ const requestModel = () =>
792
+ callModelWithFallback({
793
+ call: async (model): Promise<ModelResponse> => {
794
+ if (!output) {
795
+ return streamModelRequest({
796
+ context,
797
+ conversationId,
798
+ messages,
799
+ model,
800
+ rt,
801
+ step,
802
+ system,
803
+ tools,
804
+ });
805
+ }
806
+ try {
807
+ const generated = await generateText({
808
+ abortSignal: rt.signal,
809
+ // Retries and fallbacks are the harness's; the SDK must not retry on its own.
810
+ maxRetries: 0,
811
+ messages,
812
+ // Same fence and preamble cleanup AIService applies before `Output` parsing.
813
+ model: output ? withStrippedJsonFencesModel(model) : model,
814
+ output,
815
+ system,
816
+ tools,
817
+ });
818
+ return {
819
+ finishReason: generated.finishReason,
820
+ output: output ? structuredOutputOf(generated) : undefined,
821
+ text: generated.text,
822
+ toolCalls: generated.toolCalls,
823
+ usage: generated.usage,
824
+ };
825
+ } catch (error: unknown) {
826
+ // The model answered, but not with the requested structure: that is the
827
+ // turn's outcome, not a model failure to retry or fall back from.
828
+ if (!NoObjectGeneratedError.isInstance(error)) {
829
+ throw error;
830
+ }
831
+ return {
832
+ finishReason: error.finishReason ?? "stop",
833
+ invalidOutput: describeInvalidOutput(conversation.agent.name, error),
834
+ text: error.text ?? "",
835
+ toolCalls: [],
836
+ usage: error.usage ?? {inputTokens: undefined, outputTokens: undefined},
837
+ };
838
+ }
839
+ },
840
+ models: [conversation.agent.model, ...(conversation.agent.fallbackModels ?? [])],
841
+ random: context.random,
842
+ resolveModel,
843
+ retry: agent.modelRetry,
844
+ signal: rt.signal,
845
+ });
846
+ let call: Awaited<ReturnType<typeof requestModel>>;
847
+ try {
848
+ call = await requestModel();
849
+ } catch (error: unknown) {
850
+ if (!(error instanceof HarnessModelCallError) || rt.signal.aborted) {
851
+ throw error;
852
+ }
853
+ // Record every failed attempt on an error LLM span with the failed outcome.
854
+ const last = error.attempts.at(-1);
855
+ await commit({terminal: {error: error.message, status: "failed"}}, async (context) => {
856
+ await prompt.write(context);
857
+ const endedAt = DateTime.now();
858
+ await models.span.create(
859
+ [
860
+ {
861
+ durationMs: endedAt.diff(startedAt).toMillis(),
862
+ endedAt: endedAt.toJSDate(),
863
+ error: error.message,
864
+ input: spanInput,
865
+ kind: "LLM",
866
+ name: last ? `${last.provider}/${last.modelId}` : "model",
867
+ output: {attempts: error.attempts},
868
+ parentSpanId: context.task.rootSpanId,
869
+ startedAt: startedAt.toJSDate(),
870
+ startOffsetMs: startedAt.diff(context.traceStartedAt).toMillis(),
871
+ status: "error",
872
+ traceId: context.task.traceId,
873
+ },
874
+ ],
875
+ {session: context.session}
876
+ );
877
+ await releaseConversationIn(context);
878
+ });
879
+ return;
880
+ }
881
+ const {result} = call;
882
+ const text = result.text ?? "";
883
+ const toolCalls: PendingToolCall[] = result.toolCalls.map((toolCall) => ({
884
+ input: toolCall.input,
885
+ toolCallId: toolCall.toolCallId,
886
+ toolName: toolCall.toolName,
887
+ }));
888
+ const parts: HarnessMessagePart[] = [
889
+ ...(text ? [{text, type: "text" as const}] : []),
890
+ ...toolCalls.map((toolCall): HarnessToolCallPart => ({...toolCall, type: "tool-call"})),
891
+ ];
892
+
893
+ const writes: HarnessCommitWrites = async (writeContext) => {
894
+ const {session, task: turn, traceStartedAt} = writeContext;
895
+ await steering.write(writeContext);
896
+ await prompt.write(writeContext);
897
+ const seq = await allocateSeqs({conversationId, count: 1, models, session});
898
+ await insertMessages({
899
+ messages: [
900
+ {
901
+ conversationId: conversation._id,
902
+ parts,
903
+ role: HARNESS_MESSAGE_ROLES.assistant,
904
+ seq,
905
+ turnTaskId: turn._id,
906
+ },
907
+ ],
908
+ models,
909
+ session,
910
+ });
911
+ const endedAt = DateTime.now();
912
+ const {inputTokens, outputTokens} = result.usage;
913
+ await models.span.create(
914
+ [
915
+ {
916
+ durationMs: endedAt.diff(startedAt).toMillis(),
917
+ endedAt: endedAt.toJSDate(),
918
+ input: spanInput,
919
+ kind: "LLM",
920
+ name: `${call.model.provider}/${call.model.modelId}`,
921
+ output: {
922
+ attempts: call.attempts,
923
+ finishReason: result.finishReason,
924
+ text,
925
+ toolCalls,
926
+ },
927
+ parentSpanId: turn.rootSpanId,
928
+ startedAt: startedAt.toJSDate(),
929
+ startOffsetMs: startedAt.diff(traceStartedAt).toMillis(),
930
+ status: "ok",
931
+ traceId: turn.traceId,
932
+ usage: {
933
+ costUsd: costUsd({
934
+ inputTokens,
935
+ modelId: call.model.modelId,
936
+ outputTokens,
937
+ priceMap: context.priceMap(),
938
+ }),
939
+ inputTokens,
940
+ model: call.model.modelId,
941
+ outputTokens,
942
+ },
943
+ },
944
+ ],
945
+ {session}
946
+ );
947
+ };
948
+
949
+ if (toolCalls.length > 0) {
950
+ await commit({phase: "tools", state: {step, text, toolCalls}}, writes);
951
+ return;
952
+ }
953
+ const finalWrites: HarnessCommitWrites = async (writeContext) => {
954
+ await writes(writeContext);
955
+ await releaseConversationIn(writeContext);
956
+ };
957
+ const structured = outputSchema
958
+ ? {error: result.invalidOutput, output: result.output}
959
+ : parseStructuredOutput(agent, text);
960
+ if (structured.error) {
961
+ await commit({terminal: {error: structured.error, status: "failed"}}, finalWrites);
962
+ return;
963
+ }
964
+ const done: HarnessTurnResult = {finishReason: "stop", steps: step, text};
965
+ if (structured.output !== undefined) {
966
+ done.output = structured.output;
967
+ }
968
+ await commit({terminal: {result: done, status: "completed"}}, finalWrites);
969
+ };
970
+
971
+ const runTools = async (
972
+ task: HarnessTaskView<AgentTurnInput, AgentTurnState>,
973
+ rt: HarnessTaskRuntime<AgentTurnState, HarnessTurnResult>
974
+ ): Promise<void> => {
975
+ const {conversationId} = task.input;
976
+ const {step, text} = task.state;
977
+ const toolCalls = task.state.toolCalls ?? [];
978
+ const conversation = await loadConversation(models, conversationId);
979
+ const agent = requireAgent(context, conversation.agent.name);
980
+
981
+ // A wrap that throws here is reported by the tool call itself, which resolves again.
982
+ let available: Map<string, AnyHarnessToolDefinition> | undefined;
983
+ try {
984
+ available = resolveTools(agent, conversationExtensions(conversation));
985
+ } catch {
986
+ available = undefined;
987
+ }
988
+ const ids: string[] = [];
989
+ for (const [index, call] of toolCalls.entries()) {
990
+ const declared = available?.get(call.toolName);
991
+ ids.push(
992
+ await rt.createTask(
993
+ tool,
994
+ {
995
+ agentName: agent.name,
996
+ conversationId,
997
+ enabled:
998
+ (available === undefined || Boolean(declared)) &&
999
+ conversation.agent.tools.includes(call.toolName),
1000
+ input: call.input,
1001
+ replay: declared?.replay ?? "never",
1002
+ toolCallId: call.toolCallId,
1003
+ toolName: call.toolName,
1004
+ },
1005
+ {key: `${index}:${call.toolCallId}`}
1006
+ )
1007
+ );
1008
+ }
1009
+ const outcomes = await rt.waitForTasks(ids);
1010
+
1011
+ const results = toolCalls.map((call, index): HarnessToolResultPart => {
1012
+ const outcome = outcomes[index] as HarnessChildOutcome;
1013
+ const isError = outcome.status !== "completed";
1014
+ return {
1015
+ isError,
1016
+ output: isError
1017
+ ? (outcome.error ?? `Tool call ${outcome.status}`)
1018
+ : ((outcome.result as AgentToolResult | undefined)?.value ?? null),
1019
+ toolCallId: call.toolCallId,
1020
+ toolName: call.toolName,
1021
+ type: "tool-result",
1022
+ };
1023
+ });
1024
+
1025
+ const writes: HarnessCommitWrites = async ({session, task: turn}) => {
1026
+ if (results.length === 0) {
1027
+ return;
1028
+ }
1029
+ const first = await allocateSeqs({conversationId, count: results.length, models, session});
1030
+ await insertMessages({
1031
+ messages: results.map((part, index) => ({
1032
+ conversationId: conversation._id,
1033
+ parts: [part],
1034
+ role: HARNESS_MESSAGE_ROLES.tool,
1035
+ seq: first + index,
1036
+ status: part.isError ? ("error" as const) : ("ok" as const),
1037
+ toolCallId: part.toolCallId,
1038
+ toolName: part.toolName,
1039
+ turnTaskId: turn._id,
1040
+ })),
1041
+ models,
1042
+ session,
1043
+ });
1044
+ };
1045
+
1046
+ const commit = internalRuntime(rt as HarnessTaskRuntime<unknown, unknown>).commitWithWrites;
1047
+ if (step >= conversation.agent.maxSteps) {
1048
+ await commit(
1049
+ {terminal: {result: {finishReason: "max-steps", steps: step, text}, status: "completed"}},
1050
+ async (writeContext) => {
1051
+ await writes(writeContext);
1052
+ await releaseConversationIn(writeContext);
1053
+ }
1054
+ );
1055
+ return;
1056
+ }
1057
+ await commit({phase: "request", state: {step, text}}, writes);
1058
+ };
1059
+
1060
+ const turn = defineTask<AgentTurnInput, AgentTurnState, HarnessTurnResult>({
1061
+ abort: async (task) => {
1062
+ await markUnansweredToolCallsAborted({
1063
+ conversationId: task.input.conversationId,
1064
+ models,
1065
+ turnTaskId: task.id,
1066
+ });
1067
+ },
1068
+ initial: () => ({phase: "request", state: {step: 0, text: ""}}),
1069
+ name: AGENT_TURN_TASK_NAME,
1070
+ phases: {
1071
+ // A model request has no side effect, so an interrupted one is simply re-requested.
1072
+ request: {replay: "safe", run: request},
1073
+ // Tool children are idempotent per phase visit, so re-running the fan-out is safe.
1074
+ tools: {replay: "safe", run: runTools},
1075
+ },
1076
+ // Model retries and fallbacks happen inside `request`; a turn that still fails, fails.
1077
+ retry: {maxAttempts: 1},
1078
+ version: 1,
1079
+ });
1080
+
1081
+ return {tool, turn};
1082
+ };