plugin-agent-orchestrator 1.1.8 → 1.2.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 (495) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +207 -204
  3. package/client-v2.d.ts +2 -2
  4. package/client-v2.js +1 -1
  5. package/client.d.ts +2 -2
  6. package/client.js +1 -1
  7. package/dist/client/117.6c69b6a87751dd18.js +10 -0
  8. package/dist/client/253.52f62e1bc0e9520a.js +10 -0
  9. package/dist/client/325.8f7f509bdb35e142.js +10 -0
  10. package/dist/client/404.86593f98c9768ed5.js +10 -0
  11. package/dist/client/453.fa2d169576262213.js +10 -0
  12. package/dist/client/53.567db3ae078650c6.js +10 -0
  13. package/dist/client/619.01713281e5e951d3.js +10 -0
  14. package/dist/client/652.69da1598312b3a3f.js +10 -0
  15. package/dist/client/773.648965568ff476f9.js +10 -0
  16. package/dist/client/981.37e7aeecdb1ef6fa.js +10 -0
  17. package/dist/client/993.ac89f3852990918d.js +10 -0
  18. package/dist/client/index.js +1 -1
  19. package/dist/client-v2/117.c982d79ff68738f5.js +10 -0
  20. package/dist/client-v2/214.94c4257bf2838577.js +10 -0
  21. package/dist/client-v2/253.8e19956d2a44dfb8.js +10 -0
  22. package/dist/client-v2/264.80e8e358c8c6c2e5.js +10 -0
  23. package/dist/client-v2/325.fafe5a6e83ba9cb3.js +10 -0
  24. package/dist/client-v2/404.ab032b79c95dab6f.js +10 -0
  25. package/dist/client-v2/{41.3deb9e57a0f64fc4.js → 41.cd5610fcf7446127.js} +1 -1
  26. package/dist/client-v2/453.42c6d70628d56cc2.js +10 -0
  27. package/dist/client-v2/{53.349fff8db80b19d4.js → 53.37c08089a648f89a.js} +1 -1
  28. package/dist/client-v2/{619.0a2144aaffefe018.js → 619.6e9618550101e819.js} +1 -1
  29. package/dist/client-v2/652.eeba4e0c38367321.js +10 -0
  30. package/dist/client-v2/{70.ffff2997c10fd4b0.js → 70.332698e53eb59677.js} +1 -1
  31. package/dist/client-v2/773.4de2ba5acb07318c.js +10 -0
  32. package/dist/client-v2/981.76060f466e6f7c11.js +10 -0
  33. package/dist/client-v2/993.f8cdb5172566ce75.js +10 -0
  34. package/dist/client-v2/index.js +1 -1
  35. package/dist/externalVersion.js +13 -7
  36. package/dist/locale/en-US.json +308 -1
  37. package/dist/locale/vi-VN.json +5 -1
  38. package/dist/locale/zh-CN.json +308 -1
  39. package/dist/node_modules/acorn/LICENSE +21 -0
  40. package/dist/node_modules/acorn/bin/acorn +4 -0
  41. package/dist/node_modules/acorn/dist/acorn.d.mts +857 -0
  42. package/dist/node_modules/acorn/dist/acorn.d.ts +857 -0
  43. package/dist/node_modules/acorn/dist/acorn.js +1 -0
  44. package/dist/node_modules/acorn/dist/bin.js +90 -0
  45. package/dist/node_modules/acorn/package.json +1 -0
  46. package/dist/node_modules/acorn-walk/LICENSE +21 -0
  47. package/dist/node_modules/acorn-walk/dist/walk.d.mts +177 -0
  48. package/dist/node_modules/acorn-walk/dist/walk.d.ts +177 -0
  49. package/dist/node_modules/acorn-walk/dist/walk.js +1 -0
  50. package/dist/node_modules/acorn-walk/node_modules/.bin/acorn +15 -0
  51. package/dist/node_modules/acorn-walk/node_modules/.bin/acorn.cmd +7 -0
  52. package/dist/node_modules/acorn-walk/node_modules/acorn/bin/acorn +4 -0
  53. package/dist/node_modules/acorn-walk/node_modules/acorn/dist/acorn.d.mts +866 -0
  54. package/dist/node_modules/acorn-walk/node_modules/acorn/dist/acorn.d.ts +866 -0
  55. package/dist/node_modules/acorn-walk/node_modules/acorn/dist/acorn.js +6174 -0
  56. package/dist/node_modules/acorn-walk/node_modules/acorn/dist/bin.js +90 -0
  57. package/dist/node_modules/acorn-walk/node_modules/acorn/package.json +50 -0
  58. package/dist/node_modules/acorn-walk/package.json +1 -0
  59. package/dist/node_modules/adm-zip/adm-zip.js +1 -1
  60. package/dist/node_modules/adm-zip/package.json +1 -1
  61. package/dist/node_modules/ajv/package.json +1 -1
  62. package/dist/node_modules/zod/index.cjs +1 -1
  63. package/dist/node_modules/zod/package.json +1 -1
  64. package/dist/server/collections/agent-auto-approval-checkpoints.js +47 -0
  65. package/dist/server/collections/agent-execution-spans.js +148 -9
  66. package/dist/server/collections/agent-governance-audit-events.js +47 -0
  67. package/dist/server/collections/agent-governance-policies.js +47 -0
  68. package/dist/server/collections/agent-governance-policy-versions.js +48 -0
  69. package/dist/server/collections/agent-governance-prompt-bindings.js +50 -0
  70. package/dist/server/collections/agent-hierarchy-invocations.js +59 -0
  71. package/dist/server/collections/agent-loop-runs.js +23 -5
  72. package/dist/server/collections/agent-routing-graph-locks.js +40 -0
  73. package/dist/server/collections/agent-session-auto-approvals.js +45 -0
  74. package/dist/server/collections/orchestrator-config.js +17 -0
  75. package/dist/server/migrations/20261110000000-add-usage-pricing-snapshots.js +117 -0
  76. package/dist/server/migrations/20261110010000-add-usage-department-attribution.js +54 -0
  77. package/dist/server/migrations/20261119000000-widen-native-employee-identifiers.js +59 -0
  78. package/dist/server/plugin.js +169 -33
  79. package/dist/server/resources/agent-auto-approval.js +80 -0
  80. package/dist/server/resources/agent-governance.js +192 -0
  81. package/dist/server/resources/agent-harness-profile.js +11 -3
  82. package/dist/server/resources/agent-monitor.js +109 -339
  83. package/dist/server/resources/agent-usage.js +423 -0
  84. package/dist/server/resources/hierarchical-routing.js +60 -0
  85. package/dist/server/resources/native-monitor-format.js +179 -0
  86. package/dist/server/resources/tracing.js +35 -12
  87. package/dist/server/services/AgentGovernanceService.js +500 -0
  88. package/dist/server/services/AutoApprovalCheckpoint.js +133 -0
  89. package/dist/server/services/CodeValidator.js +8 -4
  90. package/dist/server/services/DepartmentAttribution.js +65 -0
  91. package/dist/server/services/ExecutionSpanService.js +96 -3
  92. package/dist/server/services/GovernanceAdmission.js +271 -0
  93. package/dist/server/services/HarnessCapabilities.js +118 -0
  94. package/dist/server/services/HarnessCompiler.js +3 -0
  95. package/dist/server/services/HarnessSchema.js +13 -1
  96. package/dist/server/services/HierarchicalAgentRuntime.js +925 -0
  97. package/dist/server/services/HierarchyEnrollmentGuard.js +216 -0
  98. package/dist/server/services/HierarchyInvocationJournal.js +157 -0
  99. package/dist/server/services/HierarchyRequestCancellation.js +150 -0
  100. package/dist/server/services/LoopBudgetService.js +29 -11
  101. package/dist/server/services/LoopRunRepository.js +16 -7
  102. package/dist/server/services/LoopRunStateMachine.js +20 -9
  103. package/dist/server/services/LoopTriggerService.js +1 -1
  104. package/dist/server/services/LoopWorkerService.js +71 -37
  105. package/dist/server/services/ManagedPromptProtection.js +99 -0
  106. package/dist/server/services/NativeAgentMonitorSyncService.js +584 -0
  107. package/dist/server/services/NativeSubAgentObserver.js +141 -508
  108. package/dist/server/services/NativeUsageAttribution.js +97 -0
  109. package/dist/server/services/PluginAiRuntimeAdapter.js +107 -9
  110. package/dist/server/services/RoutingBindingRepository.js +156 -0
  111. package/dist/server/services/RoutingBindingValidation.js +161 -0
  112. package/dist/server/services/SandboxRunner.js +19 -0
  113. package/dist/server/services/SessionAutoApproval.js +173 -0
  114. package/dist/server/services/TokenTracker.js +787 -104
  115. package/dist/server/services/TracingRetentionPolicy.js +66 -0
  116. package/dist/server/services/VerificationService.js +20 -10
  117. package/dist/server/skill-hub/plugin.js +17 -0
  118. package/dist/server/skill-hub/sandbox-config.json +6 -6
  119. package/dist/server/skill-hub/services/RegistrySkillInstallationService.js +2 -2
  120. package/dist/server/skill-hub/services/registry-node-package.js +191 -0
  121. package/dist/server/skill-hub/tasks/SkillExecutionTask.js +21 -6
  122. package/dist/server/tools/skill-execute.js +1 -0
  123. package/dist/server/utils/ensure-indexes.js +15 -5
  124. package/package.json +66 -53
  125. package/server.d.ts +2 -2
  126. package/server.js +1 -1
  127. package/src/client/AgentRunsTab.tsx +2 -2
  128. package/src/client/ApprovalsTab.tsx +2 -2
  129. package/src/client/HarnessProfilesTab.tsx +2 -2
  130. package/src/client/OrchestratorSettings.tsx +152 -152
  131. package/src/client/SkillPages.tsx +34 -0
  132. package/src/client/__tests__/embedded-settings.test.tsx +225 -0
  133. package/src/client/hooks/useRunEventStream.ts +76 -76
  134. package/src/client/index.tsx +2 -2
  135. package/src/client/plugin.tsx +71 -33
  136. package/src/client/skill-hub/components/ExecutionHistory.tsx +200 -200
  137. package/src/client/skill-hub/components/GitSkillImport.tsx +562 -562
  138. package/src/client/skill-hub/components/LoopSettings.tsx +331 -331
  139. package/src/client/skill-hub/components/SkillEditor.tsx +460 -460
  140. package/src/client/skill-hub/components/SkillManager.tsx +194 -194
  141. package/src/client/skill-hub/components/SkillMetrics.tsx +162 -162
  142. package/src/client/skill-hub/components/SkillTestPanel.tsx +141 -141
  143. package/src/client/skill-hub/index.tsx +6 -6
  144. package/src/client/skill-hub/locale.ts +16 -16
  145. package/src/client/skill-hub/tools/InteractionSchemasProvider.tsx +147 -132
  146. package/src/client/skill-hub/tools/SkillHubCard.tsx +110 -104
  147. package/src/client/skill-hub/tools/__tests__/skill-hub-card.test.tsx +255 -0
  148. package/src/client/skill-hub/tools/loopTemplates.ts +52 -52
  149. package/src/client/skill-hub/tools/registerSkillLoopCards.ts +80 -71
  150. package/src/client/skill-hub/utils/jsonFields.ts +41 -41
  151. package/src/client-v2/__tests__/embedded-settings.test.tsx +202 -0
  152. package/src/client-v2/__tests__/hierarchical-routing-settings.test.tsx +350 -0
  153. package/src/client-v2/auto-approval/AutoApprovalBridge.tsx +513 -0
  154. package/src/client-v2/auto-approval/AutoApprovalProvider.tsx +399 -0
  155. package/src/client-v2/auto-approval/__tests__/session-auto-approval.test.tsx +1676 -0
  156. package/src/client-v2/components/AIEmployeeSelect.tsx +47 -47
  157. package/src/client-v2/components/AIEmployeesContext.tsx +97 -97
  158. package/src/client-v2/components/AgentBindingsTab.tsx +541 -269
  159. package/src/client-v2/components/AgentRunsTab.tsx +85 -83
  160. package/src/client-v2/components/ApprovalsTab.tsx +337 -337
  161. package/src/client-v2/components/EmployeeGovernanceTab.tsx +695 -0
  162. package/src/client-v2/components/HarnessProfilesTab.tsx +700 -541
  163. package/src/client-v2/components/HarnessSettingsForm.tsx +221 -0
  164. package/src/client-v2/components/KnowledgeAccessTab.tsx +116 -116
  165. package/src/client-v2/components/RetrievalTraceTab.tsx +162 -162
  166. package/src/client-v2/components/UsageGovernanceTab.tsx +379 -0
  167. package/src/client-v2/index.tsx +1 -1
  168. package/src/client-v2/pages/AgentBindingsPage.tsx +15 -13
  169. package/src/client-v2/pages/ApprovalsPage.tsx +12 -10
  170. package/src/client-v2/pages/EmployeeGovernancePage.tsx +15 -0
  171. package/src/client-v2/pages/ExecutionHistoryPage.tsx +12 -10
  172. package/src/client-v2/pages/HarnessProfilesPage.tsx +12 -10
  173. package/src/client-v2/pages/KnowledgeAccessPage.tsx +12 -10
  174. package/src/client-v2/pages/LoopSettingsPage.tsx +12 -10
  175. package/src/client-v2/pages/MemoryInspectorPage.tsx +15 -13
  176. package/src/client-v2/pages/RetrievalTracePage.tsx +12 -10
  177. package/src/client-v2/pages/RulesPage.tsx +15 -13
  178. package/src/client-v2/pages/SkillDefinitionsPage.tsx +12 -10
  179. package/src/client-v2/pages/SkillMetricsPage.tsx +12 -10
  180. package/src/client-v2/pages/TracingPage.tsx +15 -13
  181. package/src/client-v2/pages/UsageGovernancePage.tsx +15 -0
  182. package/src/client-v2/plugin.tsx +134 -111
  183. package/src/client-v2/skill-hub/components/ExecutionHistory.tsx +196 -196
  184. package/src/client-v2/skill-hub/components/FileLinkList.tsx +37 -37
  185. package/src/client-v2/skill-hub/components/GitSkillImport.tsx +539 -539
  186. package/src/client-v2/skill-hub/components/LoopSettings.tsx +331 -331
  187. package/src/client-v2/skill-hub/components/SkillEditor.tsx +453 -453
  188. package/src/client-v2/skill-hub/components/SkillManager.tsx +191 -174
  189. package/src/client-v2/skill-hub/components/SkillMetrics.tsx +162 -162
  190. package/src/client-v2/skill-hub/components/SkillTestPanel.tsx +135 -135
  191. package/src/client-v2/skill-hub/locale.ts +13 -13
  192. package/src/client-v2/skill-hub/tools/InteractionSchemasProvider.tsx +62 -0
  193. package/src/client-v2/skill-hub/tools/SkillHubCard.tsx +104 -0
  194. package/src/client-v2/skill-hub/tools/__tests__/interactions.test.ts +126 -0
  195. package/src/client-v2/skill-hub/tools/interactions.ts +137 -0
  196. package/src/client-v2/skill-hub/tools/loopTemplates.ts +52 -52
  197. package/src/client-v2/skill-hub/utils/jsonFields.ts +41 -41
  198. package/src/client-v2/utils/jsonFields.ts +41 -41
  199. package/src/index.ts +2 -2
  200. package/src/locale/en-US.json +308 -1
  201. package/src/locale/vi-VN.json +5 -1
  202. package/src/locale/zh-CN.json +308 -1
  203. package/src/server/__tests__/agent-execution-context.test.ts +18 -18
  204. package/src/server/__tests__/agent-governance.integration.test.ts +385 -0
  205. package/src/server/__tests__/agent-knowledge-insights.test.ts +123 -123
  206. package/src/server/__tests__/agent-monitor-acl.integration.test.ts +267 -0
  207. package/src/server/__tests__/agent-registry-service.test.ts +147 -147
  208. package/src/server/__tests__/agent-runtime-lifecycle.test.ts +46 -46
  209. package/src/server/__tests__/agent-usage-report.integration.test.ts +335 -0
  210. package/src/server/__tests__/auto-approval-checkpoint.integration.test.ts +295 -0
  211. package/src/server/__tests__/code-validator.test.ts +63 -63
  212. package/src/server/__tests__/external-rag-search.test.ts +107 -107
  213. package/src/server/__tests__/harness-capabilities.test.ts +88 -0
  214. package/src/server/__tests__/harness-compiler.test.ts +278 -214
  215. package/src/server/__tests__/harness-profile-service.test.ts +167 -167
  216. package/src/server/__tests__/harness-runtime-policy.test.ts +293 -293
  217. package/src/server/__tests__/harness-tool-plan.test.ts +175 -172
  218. package/src/server/__tests__/hierarchical-routing.integration.test.ts +2318 -0
  219. package/src/server/__tests__/hierarchy-invocation-journal.integration.test.ts +119 -0
  220. package/src/server/__tests__/input-schema-validator.test.ts +26 -26
  221. package/src/server/__tests__/loop-approval-decision.test.ts +624 -512
  222. package/src/server/__tests__/loop-approval-expiry.test.ts +258 -258
  223. package/src/server/__tests__/loop-budget-service.test.ts +29 -0
  224. package/src/server/__tests__/loop-pattern-schema.test.ts +73 -73
  225. package/src/server/__tests__/loop-run-repository.test.ts +25 -0
  226. package/src/server/__tests__/loop-run-state-machine.test.ts +101 -101
  227. package/src/server/__tests__/loop-trigger-service.test.ts +185 -148
  228. package/src/server/__tests__/loop-worker-claim.test.ts +110 -10
  229. package/src/server/__tests__/loop-worker-execution.test.ts +375 -317
  230. package/src/server/__tests__/native-agent-monitor-sync.test.ts +343 -0
  231. package/src/server/__tests__/native-hierarchy-probe.integration.test.ts +527 -0
  232. package/src/server/__tests__/native-sub-agent-observer.test.ts +463 -662
  233. package/src/server/__tests__/native-usage-attribution.integration.test.ts +168 -0
  234. package/src/server/__tests__/plugin-ai-runtime-adapter.test.ts +403 -0
  235. package/src/server/__tests__/registry-node-package.test.ts +299 -0
  236. package/src/server/__tests__/routing-binding-graph.integration.test.ts +217 -0
  237. package/src/server/__tests__/routing-binding-validation.test.ts +256 -0
  238. package/src/server/__tests__/session-auto-approval.integration.test.ts +329 -0
  239. package/src/server/__tests__/skill-access-service.test.ts +64 -64
  240. package/src/server/__tests__/skill-execute.test.ts +81 -70
  241. package/src/server/__tests__/skill-execution-task-policy.test.ts +140 -140
  242. package/src/server/__tests__/skill-review-guard.test.ts +171 -0
  243. package/src/server/__tests__/skill-sandbox-worker-mode.test.ts +15 -15
  244. package/src/server/__tests__/skill-settings.test.ts +63 -63
  245. package/src/server/__tests__/skill-tool-name.test.ts +23 -23
  246. package/src/server/__tests__/token-tracker.test.ts +632 -0
  247. package/src/server/__tests__/tool-loop-detection.test.ts +276 -276
  248. package/src/server/__tests__/tracing-retention-policy.test.ts +30 -0
  249. package/src/server/__tests__/usage-ledger.integration.test.ts +187 -0
  250. package/src/server/collections/agent-auto-approval-checkpoints.ts +18 -0
  251. package/src/server/collections/agent-execution-spans.ts +386 -245
  252. package/src/server/collections/agent-governance-audit-events.ts +19 -0
  253. package/src/server/collections/agent-governance-policies.ts +19 -0
  254. package/src/server/collections/agent-governance-policy-versions.ts +20 -0
  255. package/src/server/collections/agent-governance-prompt-bindings.ts +22 -0
  256. package/src/server/collections/agent-hierarchy-invocations.ts +30 -0
  257. package/src/server/collections/agent-loop-action-approvals.ts +39 -39
  258. package/src/server/collections/agent-loop-runs.ts +389 -369
  259. package/src/server/collections/agent-loop-steps.ts +220 -220
  260. package/src/server/collections/agent-memory-contexts.ts +95 -95
  261. package/src/server/collections/agent-routing-graph-locks.ts +11 -0
  262. package/src/server/collections/agent-session-auto-approvals.ts +16 -0
  263. package/src/server/collections/orchestrator-config.ts +113 -87
  264. package/src/server/collections/orchestrator-logs.ts +116 -116
  265. package/src/server/collections/skill-definitions.ts +159 -159
  266. package/src/server/collections/skill-executions.ts +154 -154
  267. package/src/server/collections/skill-loop-configs.ts +65 -65
  268. package/src/server/collections/skill-metrics.ts +36 -36
  269. package/src/server/collections/skill-registry-installations.ts +41 -41
  270. package/src/server/collections/skill-worker-configs.ts +86 -86
  271. package/src/server/index.ts +1 -1
  272. package/src/server/migrations/20260423000000-add-progress-fields.ts +50 -50
  273. package/src/server/migrations/20260425000000-add-interaction-schema.ts +37 -37
  274. package/src/server/migrations/20260427000000-add-tracing-detail-fields.ts +41 -41
  275. package/src/server/migrations/20260427000001-change-other-json-to-text.ts +61 -61
  276. package/src/server/migrations/20260524001000-add-plan-approval-and-harness-profiles.ts +145 -145
  277. package/src/server/migrations/20260601000000-add-token-fields.ts +89 -89
  278. package/src/server/migrations/20260615000000-normalize-ai-employee-tool-bindings.ts +39 -39
  279. package/src/server/migrations/20260621000000-native-policy-profile-defaults.ts +190 -190
  280. package/src/server/migrations/20260727000000-remove-unused-knowledge-scopes.ts +25 -25
  281. package/src/server/migrations/20260727010000-backfill-skill-tool-names.ts +45 -45
  282. package/src/server/migrations/20261110000000-add-usage-pricing-snapshots.ts +110 -0
  283. package/src/server/migrations/20261110010000-add-usage-department-attribution.ts +28 -0
  284. package/src/server/migrations/20261119000000-widen-native-employee-identifiers.ts +37 -0
  285. package/src/server/plugin.ts +724 -573
  286. package/src/server/resources/agent-auto-approval.ts +51 -0
  287. package/src/server/resources/agent-governance.ts +161 -0
  288. package/src/server/resources/agent-harness-profile.ts +103 -94
  289. package/src/server/resources/agent-knowledge-insights.ts +306 -306
  290. package/src/server/resources/agent-loop-approval.ts +84 -84
  291. package/src/server/resources/agent-loop-events-stream.ts +108 -108
  292. package/src/server/resources/agent-loop.ts +252 -252
  293. package/src/server/resources/agent-monitor.ts +208 -482
  294. package/src/server/resources/agent-usage.ts +413 -0
  295. package/src/server/resources/hierarchical-routing.ts +39 -0
  296. package/src/server/resources/native-monitor-format.ts +150 -0
  297. package/src/server/resources/tracing.ts +296 -267
  298. package/src/server/services/AgentExecutionContext.ts +23 -23
  299. package/src/server/services/AgentGovernanceService.ts +541 -0
  300. package/src/server/services/AgentMemoryContextService.ts +344 -344
  301. package/src/server/services/AgentRegistryService.ts +220 -220
  302. package/src/server/services/AgentRuntimeLifecycle.ts +64 -64
  303. package/src/server/services/AutoApprovalCheckpoint.ts +140 -0
  304. package/src/server/services/CodeValidator.ts +257 -238
  305. package/src/server/services/DepartmentAttribution.ts +47 -0
  306. package/src/server/services/DurableCircuitBreakerService.ts +235 -235
  307. package/src/server/services/ExecutionSpanService.ts +271 -146
  308. package/src/server/services/FileManager.ts +159 -159
  309. package/src/server/services/GovernanceAdmission.ts +314 -0
  310. package/src/server/services/HarnessCapabilities.ts +112 -0
  311. package/src/server/services/HarnessCompiler.ts +182 -170
  312. package/src/server/services/HarnessProfileService.ts +235 -235
  313. package/src/server/services/HarnessSchema.ts +224 -194
  314. package/src/server/services/HierarchicalAgentRuntime.ts +1052 -0
  315. package/src/server/services/HierarchyEnrollmentGuard.ts +211 -0
  316. package/src/server/services/HierarchyInvocationJournal.ts +172 -0
  317. package/src/server/services/HierarchyRequestCancellation.ts +132 -0
  318. package/src/server/services/InputSchemaValidator.ts +44 -44
  319. package/src/server/services/LoopBudgetService.ts +325 -271
  320. package/src/server/services/LoopControlService.ts +120 -120
  321. package/src/server/services/LoopPatternSchema.ts +231 -231
  322. package/src/server/services/LoopPatternService.ts +171 -171
  323. package/src/server/services/LoopRunRepository.ts +343 -332
  324. package/src/server/services/LoopRunStateMachine.ts +538 -525
  325. package/src/server/services/LoopSchedulerService.ts +195 -195
  326. package/src/server/services/LoopTriggerService.ts +162 -159
  327. package/src/server/services/LoopWorkerService.ts +975 -912
  328. package/src/server/services/ManagedPromptProtection.ts +81 -0
  329. package/src/server/services/NativeAgentMonitorSyncService.ts +684 -0
  330. package/src/server/services/NativeSubAgentObserver.ts +324 -757
  331. package/src/server/services/NativeUsageAttribution.ts +91 -0
  332. package/src/server/services/PathLockService.ts +317 -317
  333. package/src/server/services/PluginAiRuntimeAdapter.ts +518 -387
  334. package/src/server/services/RoutingBindingRepository.ts +146 -0
  335. package/src/server/services/RoutingBindingValidation.ts +161 -0
  336. package/src/server/services/RunEventBus.ts +58 -58
  337. package/src/server/services/SandboxRunner.ts +526 -492
  338. package/src/server/services/SessionAutoApproval.ts +167 -0
  339. package/src/server/services/SkillAccessService.ts +175 -175
  340. package/src/server/services/SkillManager.ts +585 -585
  341. package/src/server/services/SkillRepositoryService.ts +236 -236
  342. package/src/server/services/TokenTracker.ts +1151 -287
  343. package/src/server/services/ToolLoopDetectionService.ts +210 -210
  344. package/src/server/services/TracingRetentionPolicy.ts +49 -0
  345. package/src/server/services/VerificationSchema.ts +31 -31
  346. package/src/server/services/VerificationService.ts +325 -313
  347. package/src/server/services/WorkerEnvManager.ts +198 -198
  348. package/src/server/services/__tests__/SkillRepositoryService.test.ts +33 -33
  349. package/src/server/services/harness-runtime-policy.ts +134 -134
  350. package/src/server/services/pythonGuardTemplate.ts +87 -87
  351. package/src/server/services/sandboxCapabilities.ts +348 -348
  352. package/src/server/skill-hub/actions/__tests__/git-import.test.ts +563 -563
  353. package/src/server/skill-hub/actions/git-import.ts +936 -936
  354. package/src/server/skill-hub/mcp/McpController.ts +107 -107
  355. package/src/server/skill-hub/middlewares/git-import-request-method-policy.ts +51 -51
  356. package/src/server/skill-hub/plugin.ts +1272 -1232
  357. package/src/server/skill-hub/sandbox-config.json +6 -6
  358. package/src/server/skill-hub/services/RegistrySkillInstallationService.ts +291 -281
  359. package/src/server/skill-hub/services/__tests__/RegistrySkillInstallationService.test.ts +295 -295
  360. package/src/server/skill-hub/services/registry-node-package.ts +191 -0
  361. package/src/server/skill-hub/tasks/SkillExecutionTask.ts +597 -568
  362. package/src/server/skill-hub/utils/json-fields.ts +57 -57
  363. package/src/server/tools/delegate-task.ts +30 -30
  364. package/src/server/tools/external-rag-search.ts +329 -329
  365. package/src/server/tools/skill-execute.ts +226 -216
  366. package/src/server/types.ts +21 -21
  367. package/src/server/utils/ai-manager.ts +24 -24
  368. package/src/server/utils/ctx-utils.ts +132 -132
  369. package/src/server/utils/ensure-indexes.ts +113 -96
  370. package/src/server/utils/ha-lock.ts +80 -80
  371. package/src/server/utils/loop-pattern-context.ts +84 -84
  372. package/src/server/utils/record-utils.ts +19 -19
  373. package/src/server/utils/skill-settings.ts +135 -135
  374. package/src/server/utils/skill-tool-name.ts +58 -58
  375. package/dist/client-v2/117.7565cff57c39318a.js +0 -10
  376. package/dist/client-v2/214.106635011859dede.js +0 -10
  377. package/dist/client-v2/253.59577b40d9875be0.js +0 -10
  378. package/dist/client-v2/264.7ed8bee71fa5935c.js +0 -10
  379. package/dist/client-v2/418.41ed200e7d6da332.js +0 -10
  380. package/dist/client-v2/794.a67a2614405ba627.js +0 -10
  381. package/dist/client-v2/981.e4a1f41cfc94a856.js +0 -10
  382. package/dist/client-v2/993.b0688fdc5ccb000a.js +0 -10
  383. package/dist/node_modules/simple-git/dist/cjs/index.js +0 -7399
  384. package/dist/node_modules/simple-git/dist/esm/index.js +0 -4745
  385. package/dist/node_modules/simple-git/dist/esm/package.json +0 -3
  386. package/dist/node_modules/simple-git/dist/src/lib/api.d.ts +0 -13
  387. package/dist/node_modules/simple-git/dist/src/lib/args/log-format.d.ts +0 -9
  388. package/dist/node_modules/simple-git/dist/src/lib/errors/git-construct-error.d.ts +0 -15
  389. package/dist/node_modules/simple-git/dist/src/lib/errors/git-error.d.ts +0 -30
  390. package/dist/node_modules/simple-git/dist/src/lib/errors/git-plugin-error.d.ts +0 -7
  391. package/dist/node_modules/simple-git/dist/src/lib/errors/git-response-error.d.ts +0 -32
  392. package/dist/node_modules/simple-git/dist/src/lib/errors/task-configuration-error.d.ts +0 -12
  393. package/dist/node_modules/simple-git/dist/src/lib/git-factory.d.ts +0 -15
  394. package/dist/node_modules/simple-git/dist/src/lib/git-logger.d.ts +0 -21
  395. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-branch-delete.d.ts +0 -5
  396. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-branch.d.ts +0 -2
  397. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-commit.d.ts +0 -2
  398. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-diff-summary.d.ts +0 -3
  399. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-fetch.d.ts +0 -2
  400. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-list-log-summary.d.ts +0 -6
  401. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-merge.d.ts +0 -11
  402. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-move.d.ts +0 -2
  403. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-pull.d.ts +0 -6
  404. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-push.d.ts +0 -4
  405. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-remote-messages.d.ts +0 -5
  406. package/dist/node_modules/simple-git/dist/src/lib/parsers/parse-remote-objects.d.ts +0 -3
  407. package/dist/node_modules/simple-git/dist/src/lib/plugins/abort-plugin.d.ts +0 -3
  408. package/dist/node_modules/simple-git/dist/src/lib/plugins/block-unsafe-operations-plugin.d.ts +0 -3
  409. package/dist/node_modules/simple-git/dist/src/lib/plugins/command-config-prefixing-plugin.d.ts +0 -2
  410. package/dist/node_modules/simple-git/dist/src/lib/plugins/completion-detection.plugin.d.ts +0 -3
  411. package/dist/node_modules/simple-git/dist/src/lib/plugins/custom-binary.plugin.d.ts +0 -3
  412. package/dist/node_modules/simple-git/dist/src/lib/plugins/error-detection.plugin.d.ts +0 -7
  413. package/dist/node_modules/simple-git/dist/src/lib/plugins/index.d.ts +0 -11
  414. package/dist/node_modules/simple-git/dist/src/lib/plugins/plugin-store.d.ts +0 -11
  415. package/dist/node_modules/simple-git/dist/src/lib/plugins/progress-monitor-plugin.d.ts +0 -3
  416. package/dist/node_modules/simple-git/dist/src/lib/plugins/simple-git-plugin.d.ts +0 -48
  417. package/dist/node_modules/simple-git/dist/src/lib/plugins/spawn-options-plugin.d.ts +0 -3
  418. package/dist/node_modules/simple-git/dist/src/lib/plugins/suffix-paths.plugin.d.ts +0 -2
  419. package/dist/node_modules/simple-git/dist/src/lib/plugins/timout-plugin.d.ts +0 -3
  420. package/dist/node_modules/simple-git/dist/src/lib/responses/BranchDeleteSummary.d.ts +0 -12
  421. package/dist/node_modules/simple-git/dist/src/lib/responses/BranchSummary.d.ts +0 -14
  422. package/dist/node_modules/simple-git/dist/src/lib/responses/CheckIgnore.d.ts +0 -4
  423. package/dist/node_modules/simple-git/dist/src/lib/responses/CleanSummary.d.ts +0 -9
  424. package/dist/node_modules/simple-git/dist/src/lib/responses/ConfigList.d.ts +0 -13
  425. package/dist/node_modules/simple-git/dist/src/lib/responses/DiffSummary.d.ts +0 -10
  426. package/dist/node_modules/simple-git/dist/src/lib/responses/FileStatusSummary.d.ts +0 -9
  427. package/dist/node_modules/simple-git/dist/src/lib/responses/GetRemoteSummary.d.ts +0 -11
  428. package/dist/node_modules/simple-git/dist/src/lib/responses/InitSummary.d.ts +0 -9
  429. package/dist/node_modules/simple-git/dist/src/lib/responses/MergeSummary.d.ts +0 -16
  430. package/dist/node_modules/simple-git/dist/src/lib/responses/PullSummary.d.ts +0 -25
  431. package/dist/node_modules/simple-git/dist/src/lib/responses/StatusSummary.d.ts +0 -19
  432. package/dist/node_modules/simple-git/dist/src/lib/responses/TagList.d.ts +0 -7
  433. package/dist/node_modules/simple-git/dist/src/lib/runners/git-executor-chain.d.ts +0 -25
  434. package/dist/node_modules/simple-git/dist/src/lib/runners/git-executor.d.ts +0 -14
  435. package/dist/node_modules/simple-git/dist/src/lib/runners/promise-wrapped.d.ts +0 -2
  436. package/dist/node_modules/simple-git/dist/src/lib/runners/scheduler.d.ts +0 -11
  437. package/dist/node_modules/simple-git/dist/src/lib/runners/tasks-pending-queue.d.ts +0 -23
  438. package/dist/node_modules/simple-git/dist/src/lib/simple-git-api.d.ts +0 -20
  439. package/dist/node_modules/simple-git/dist/src/lib/task-callback.d.ts +0 -2
  440. package/dist/node_modules/simple-git/dist/src/lib/tasks/apply-patch.d.ts +0 -3
  441. package/dist/node_modules/simple-git/dist/src/lib/tasks/branch.d.ts +0 -7
  442. package/dist/node_modules/simple-git/dist/src/lib/tasks/change-working-directory.d.ts +0 -2
  443. package/dist/node_modules/simple-git/dist/src/lib/tasks/check-ignore.d.ts +0 -2
  444. package/dist/node_modules/simple-git/dist/src/lib/tasks/check-is-repo.d.ts +0 -9
  445. package/dist/node_modules/simple-git/dist/src/lib/tasks/checkout.d.ts +0 -2
  446. package/dist/node_modules/simple-git/dist/src/lib/tasks/clean.d.ts +0 -25
  447. package/dist/node_modules/simple-git/dist/src/lib/tasks/clone.d.ts +0 -9
  448. package/dist/node_modules/simple-git/dist/src/lib/tasks/commit.d.ts +0 -4
  449. package/dist/node_modules/simple-git/dist/src/lib/tasks/config.d.ts +0 -8
  450. package/dist/node_modules/simple-git/dist/src/lib/tasks/count-objects.d.ts +0 -12
  451. package/dist/node_modules/simple-git/dist/src/lib/tasks/diff-name-status.d.ts +0 -12
  452. package/dist/node_modules/simple-git/dist/src/lib/tasks/diff.d.ts +0 -5
  453. package/dist/node_modules/simple-git/dist/src/lib/tasks/fetch.d.ts +0 -4
  454. package/dist/node_modules/simple-git/dist/src/lib/tasks/first-commit.d.ts +0 -2
  455. package/dist/node_modules/simple-git/dist/src/lib/tasks/grep.d.ts +0 -12
  456. package/dist/node_modules/simple-git/dist/src/lib/tasks/hash-object.d.ts +0 -5
  457. package/dist/node_modules/simple-git/dist/src/lib/tasks/init.d.ts +0 -3
  458. package/dist/node_modules/simple-git/dist/src/lib/tasks/log.d.ts +0 -32
  459. package/dist/node_modules/simple-git/dist/src/lib/tasks/merge.d.ts +0 -4
  460. package/dist/node_modules/simple-git/dist/src/lib/tasks/move.d.ts +0 -3
  461. package/dist/node_modules/simple-git/dist/src/lib/tasks/pull.d.ts +0 -3
  462. package/dist/node_modules/simple-git/dist/src/lib/tasks/push.d.ts +0 -9
  463. package/dist/node_modules/simple-git/dist/src/lib/tasks/remote.d.ts +0 -8
  464. package/dist/node_modules/simple-git/dist/src/lib/tasks/reset.d.ts +0 -11
  465. package/dist/node_modules/simple-git/dist/src/lib/tasks/show.d.ts +0 -2
  466. package/dist/node_modules/simple-git/dist/src/lib/tasks/stash-list.d.ts +0 -4
  467. package/dist/node_modules/simple-git/dist/src/lib/tasks/status.d.ts +0 -3
  468. package/dist/node_modules/simple-git/dist/src/lib/tasks/sub-module.d.ts +0 -5
  469. package/dist/node_modules/simple-git/dist/src/lib/tasks/tag.d.ts +0 -18
  470. package/dist/node_modules/simple-git/dist/src/lib/tasks/task.d.ts +0 -14
  471. package/dist/node_modules/simple-git/dist/src/lib/tasks/version.d.ts +0 -9
  472. package/dist/node_modules/simple-git/dist/src/lib/types/handlers.d.ts +0 -21
  473. package/dist/node_modules/simple-git/dist/src/lib/types/index.d.ts +0 -136
  474. package/dist/node_modules/simple-git/dist/src/lib/types/tasks.d.ts +0 -19
  475. package/dist/node_modules/simple-git/dist/src/lib/utils/argument-filters.d.ts +0 -14
  476. package/dist/node_modules/simple-git/dist/src/lib/utils/exit-codes.d.ts +0 -10
  477. package/dist/node_modules/simple-git/dist/src/lib/utils/git-output-streams.d.ts +0 -7
  478. package/dist/node_modules/simple-git/dist/src/lib/utils/index.d.ts +0 -8
  479. package/dist/node_modules/simple-git/dist/src/lib/utils/line-parser.d.ts +0 -15
  480. package/dist/node_modules/simple-git/dist/src/lib/utils/simple-git-options.d.ts +0 -2
  481. package/dist/node_modules/simple-git/dist/src/lib/utils/task-options.d.ts +0 -13
  482. package/dist/node_modules/simple-git/dist/src/lib/utils/task-parser.d.ts +0 -5
  483. package/dist/node_modules/simple-git/dist/src/lib/utils/util.d.ts +0 -47
  484. package/dist/node_modules/simple-git/dist/typings/errors.d.ts +0 -5
  485. package/dist/node_modules/simple-git/dist/typings/index.d.ts +0 -14
  486. package/dist/node_modules/simple-git/dist/typings/response.d.ts +0 -556
  487. package/dist/node_modules/simple-git/dist/typings/simple-git.d.ts +0 -1033
  488. package/dist/node_modules/simple-git/dist/typings/types.d.ts +0 -22
  489. package/dist/node_modules/simple-git/node_modules/debug/package.json +0 -64
  490. package/dist/node_modules/simple-git/node_modules/debug/src/browser.js +0 -272
  491. package/dist/node_modules/simple-git/node_modules/debug/src/common.js +0 -292
  492. package/dist/node_modules/simple-git/node_modules/debug/src/index.js +0 -10
  493. package/dist/node_modules/simple-git/node_modules/debug/src/node.js +0 -263
  494. package/dist/node_modules/simple-git/package.json +0 -1
  495. package/dist/node_modules/simple-git/promise.js +0 -17
@@ -1,287 +1,1151 @@
1
- export interface TokenUsage {
2
- inputTokens: number;
3
- outputTokens: number;
4
- totalTokens: number;
5
- cost: number;
6
- }
7
-
8
- export interface BudgetConfig {
9
- budgetMaxTokens?: number;
10
- budgetMaxCost?: number;
11
- }
12
-
13
- export interface BudgetCheckResult {
14
- allowed: boolean;
15
- reason?: string;
16
- }
17
-
18
- /**
19
- * Default pricing per 1K tokens (USD).
20
- * These are conservative estimates; override via env vars:
21
- * ORCHESTRATOR_PRICE_PER_1K_INPUT
22
- * ORCHESTRATOR_PRICE_PER_1K_OUTPUT
23
- */
24
- const PRICE_PER_1K_INPUT = Number(process.env.ORCHESTRATOR_PRICE_PER_1K_INPUT || 0.003);
25
- const PRICE_PER_1K_OUTPUT = Number(process.env.ORCHESTRATOR_PRICE_PER_1K_OUTPUT || 0.015);
26
-
27
- /**
28
- * Estimate cost based on token counts.
29
- */
30
- export function estimateCost(inputTokens: number, outputTokens: number): number {
31
- return (inputTokens / 1000) * PRICE_PER_1K_INPUT + (outputTokens / 1000) * PRICE_PER_1K_OUTPUT;
32
- }
33
-
34
- /**
35
- * Extract usage_metadata from a legacy agent final state.
36
- *
37
- * Legacy agent execution returned a final state object with a `messages` array.
38
- * The last AIMessage in that array carries `usage_metadata` populated by the
39
- * LLM provider after the final generation step. This is the standard LangChain
40
- * approach — no private API access needed.
41
- *
42
- * Expected message shape:
43
- * AIMessage.usage_metadata = {
44
- * input_tokens: number,
45
- * output_tokens: number,
46
- * total_tokens: number,
47
- * }
48
- */
49
- type LegacyUsageMetadata = {
50
- input_tokens?: number;
51
- output_tokens?: number;
52
- total_tokens?: number;
53
- };
54
-
55
- type LegacyAIMessage = {
56
- usage_metadata?: LegacyUsageMetadata;
57
- [key: string]: unknown;
58
- };
59
-
60
- type LegacyFinalState =
61
- | {
62
- messages?: LegacyAIMessage[];
63
- }
64
- | null
65
- | undefined;
66
-
67
- export function extractTokenUsage(finalState: LegacyFinalState): TokenUsage | null {
68
- if (!finalState?.messages || !Array.isArray(finalState.messages)) return null;
69
-
70
- // Accumulate usage across all AI messages in the run (each LLM call adds usage)
71
- let totalInput = 0;
72
- let totalOutput = 0;
73
- let totalAll = 0;
74
-
75
- for (const msg of finalState.messages) {
76
- if (msg?.usage_metadata) {
77
- const um = msg.usage_metadata;
78
- totalInput += um.input_tokens || 0;
79
- totalOutput += um.output_tokens || 0;
80
- totalAll += um.total_tokens || 0;
81
- }
82
- }
83
-
84
- if (totalAll === 0) return null;
85
-
86
- return {
87
- inputTokens: totalInput,
88
- outputTokens: totalOutput,
89
- totalTokens: totalAll,
90
- cost: estimateCost(totalInput, totalOutput),
91
- };
92
- }
93
-
94
- /**
95
- * Service for tracking token consumption across agent runs and spans.
96
- *
97
- * Responsibilities:
98
- * 1. Parse token usage from LangGraph execution results
99
- * 2. Persist token counts to agentExecutionSpans
100
- * 3. Accumulate totals at the agentLoopRuns level
101
- * 4. Enforce budget limits (max tokens / max cost per run)
102
- */
103
- export class TokenTracker {
104
- constructor(
105
- private readonly plugin: {
106
- app: { log?: { warn?: (...args: unknown[]) => void } };
107
- db: {
108
- getRepository: (name: string) => {
109
- find?: (opts?: Record<string, unknown>) => Promise<unknown[]>;
110
- findOne?: (opts?: Record<string, unknown>) => Promise<unknown>;
111
- update?: (opts: Record<string, unknown>) => Promise<unknown>;
112
- };
113
- };
114
- },
115
- ) {}
116
-
117
- get db() {
118
- return this.plugin.db;
119
- }
120
-
121
- get app() {
122
- return this.plugin.app;
123
- }
124
-
125
- /**
126
- * Track token usage for a single execution span.
127
- * Updates the span record and accumulates into the parent run.
128
- *
129
- * @param spanId - The agentExecutionSpans.id to update
130
- * @param usage - Parsed token usage from extractTokenUsage()
131
- * @param runId - Optional agentLoopRuns.id to accumulate totals
132
- */
133
- async trackSpan(spanId: string | number | undefined, usage: TokenUsage, runId?: string | number): Promise<void> {
134
- if (!spanId) return;
135
-
136
- try {
137
- const repo = this.db.getRepository('agentExecutionSpans');
138
- if (!repo) return;
139
-
140
- await repo.update({
141
- filterByTk: spanId,
142
- values: {
143
- inputTokens: usage.inputTokens,
144
- outputTokens: usage.outputTokens,
145
- totalTokens: usage.totalTokens,
146
- cost: usage.cost,
147
- },
148
- });
149
-
150
- if (runId != null) {
151
- await this.accumulateToRun(runId);
152
- }
153
- } catch (e: unknown) {
154
- this.app.log?.warn?.('[TokenTracker] Failed to track span tokens', e);
155
- }
156
- }
157
-
158
- /**
159
- * Recalculate total token/cost for a run by summing all its spans.
160
- */
161
- async accumulateToRun(runId: string | number): Promise<void> {
162
- try {
163
- const spansRepo = this.db.getRepository('agentExecutionSpans');
164
- if (!spansRepo) return;
165
-
166
- // Project only token fields to minimize memory; cap at 10K spans per run.
167
- const spans = await spansRepo.find({
168
- filter: { agentLoopRunId: String(runId) },
169
- fields: ['inputTokens', 'outputTokens', 'cost'],
170
- limit: 10_000,
171
- });
172
-
173
- let totalInput = 0;
174
- let totalOutput = 0;
175
- let totalCost = 0;
176
-
177
- for (const span of spans) {
178
- totalInput += Number(span.get?.('inputTokens') || span.inputTokens || 0);
179
- totalOutput += Number(span.get?.('outputTokens') || span.outputTokens || 0);
180
- totalCost += Number(span.get?.('cost') || span.cost || 0);
181
- }
182
-
183
- const runsRepo = this.db.getRepository('agentLoopRuns');
184
- if (!runsRepo) return;
185
-
186
- await runsRepo.update({
187
- filterByTk: runId,
188
- values: {
189
- totalInputTokens: totalInput,
190
- totalOutputTokens: totalOutput,
191
- totalTokens: totalInput + totalOutput,
192
- totalCost,
193
- },
194
- });
195
- } catch (e: unknown) {
196
- this.app.log?.warn?.('[TokenTracker] Failed to accumulate run totals', e);
197
- }
198
- }
199
-
200
- /**
201
- * Check if a run has exceeded its budget limits.
202
- */
203
- async checkBudget(runId: string | number): Promise<BudgetCheckResult> {
204
- try {
205
- const repo = this.db.getRepository('agentLoopRuns');
206
- if (!repo) return { allowed: true };
207
-
208
- const run = await repo.findOne({ filter: { id: runId } });
209
- if (!run) return { allowed: true };
210
-
211
- const budgetMaxTokens = Number(run.get?.('budgetMaxTokens') ?? 0);
212
- const budgetMaxCost = Number(run.get?.('budgetMaxCost') ?? 0);
213
-
214
- if (budgetMaxTokens <= 0 && budgetMaxCost <= 0) return { allowed: true };
215
-
216
- const totalTokens = Number(run.get?.('totalTokens') || 0);
217
- const totalCost = Number(run.get?.('totalCost') || 0);
218
-
219
- if (budgetMaxTokens > 0 && totalTokens >= budgetMaxTokens) {
220
- return {
221
- allowed: false,
222
- reason: `Budget exceeded: ${totalTokens}/${budgetMaxTokens} tokens used. Maximum allowed tokens for this run: ${budgetMaxTokens}.`,
223
- };
224
- }
225
-
226
- if (budgetMaxCost > 0 && totalCost >= budgetMaxCost) {
227
- return {
228
- allowed: false,
229
- reason: `Budget exceeded: $${totalCost.toFixed(4)}/$${budgetMaxCost.toFixed(
230
- 4,
231
- )} spent. Maximum allowed cost for this run: $${budgetMaxCost}.`,
232
- };
233
- }
234
-
235
- return { allowed: true };
236
- } catch (e: unknown) {
237
- this.app.log?.warn?.('[TokenTracker] Budget check failed, allowing', e);
238
- return { allowed: true };
239
- }
240
- }
241
-
242
- /**
243
- * Track actual token usage from the LLM response on a span.
244
- * This is preferred over estimateAndTrack when the LLM provides real usage metadata.
245
- * Falls back to estimation if usage is null.
246
- */
247
- async trackActualUsage(
248
- spanId: string | number | undefined,
249
- tokenUsage: { inputTokens: number; outputTokens: number; totalTokens: number; cost: number } | null,
250
- input: string,
251
- output: string,
252
- runId?: string | number,
253
- ): Promise<void> {
254
- if (tokenUsage && tokenUsage.totalTokens > 0) {
255
- await this.trackSpan(spanId, tokenUsage, runId);
256
- return;
257
- }
258
- // Fall back to estimation when actual usage is not available
259
- await this.estimateAndTrack(spanId, input, output, runId);
260
- }
261
-
262
- /**
263
- * Estimate tokens from text length and track on a span.
264
- * Rough heuristic: ~4 chars per token for English text.
265
- * Use when actual usage_metadata is not available (e.g. native plugin-ai flow).
266
- */
267
- async estimateAndTrack(
268
- spanId: string | number | undefined,
269
- input: string,
270
- output: string,
271
- runId?: string | number,
272
- ): Promise<void> {
273
- if (!spanId) return;
274
- const inputTokens = Math.ceil((input || '').length / 4);
275
- const outputTokens = Math.ceil((output || '').length / 4);
276
- await this.trackSpan(
277
- spanId,
278
- {
279
- inputTokens,
280
- outputTokens,
281
- totalTokens: inputTokens + outputTokens,
282
- cost: estimateCost(inputTokens, outputTokens),
283
- },
284
- runId,
285
- );
286
- }
287
- }
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ import { read } from '../utils/record-utils';
4
+
5
+ export interface TokenUsage {
6
+ inputTokens: number;
7
+ outputTokens: number;
8
+ totalTokens: number;
9
+ cost: number;
10
+ cachedTokens?: number;
11
+ reasoningTokens?: number;
12
+ }
13
+
14
+ export type UsageCounts = Omit<TokenUsage, 'cost'> & { cost?: number | null };
15
+ export type UsageSource = 'actual' | 'estimated' | 'missing';
16
+ export type PricingStatus = 'configured' | 'estimated' | 'native' | 'unpriced' | 'non_usd' | 'mixed_currency';
17
+
18
+ export interface BudgetConfig {
19
+ budgetMaxTokens?: number;
20
+ budgetMaxCost?: number;
21
+ }
22
+
23
+ export interface BudgetCheckResult {
24
+ allowed: boolean;
25
+ reason?: string;
26
+ }
27
+
28
+ export type PriceSnapshot = {
29
+ inputPer1k?: number | null;
30
+ outputPer1k?: number | null;
31
+ cachedInputPer1k?: number | null;
32
+ currency?: string;
33
+ version?: string;
34
+ source?: 'model_pricing_json' | 'legacy_global_env' | 'provider';
35
+ status?: PricingStatus;
36
+ cost?: number | null;
37
+ };
38
+
39
+ export type ModelCallUsageInput = {
40
+ usageIdentity: string;
41
+ nativeIdentity?: string;
42
+ sessionId: string;
43
+ messageId: string;
44
+ usage: UsageCounts | null;
45
+ model?: string;
46
+ provider?: string;
47
+ llmService?: string;
48
+ runId?: string | number | null;
49
+ spanId?: string | number;
50
+ rootRunId?: string;
51
+ parentSpanId?: string;
52
+ role?: string;
53
+ employeeUsername?: string;
54
+ userId?: string | number;
55
+ /** Trusted department snapshot captured for this exact model call. */
56
+ departmentId?: string | number;
57
+ source: 'ai_usage_event' | 'loop_runtime';
58
+ priceSnapshot?: PriceSnapshot;
59
+ nativeCost?: number | null;
60
+ occurredAt?: Date | string | number;
61
+ recomputeRunTotals?: boolean;
62
+ };
63
+
64
+ export type LoopInvocationUsageInput = {
65
+ runId: string | number;
66
+ stepId: string | number;
67
+ sessionId: string;
68
+ messageId?: string;
69
+ usage: UsageCounts | null;
70
+ input: string;
71
+ output: string;
72
+ role: string;
73
+ employeeUsername: string;
74
+ userId?: string | number;
75
+ rootRunId?: string;
76
+ };
77
+
78
+ export type NativeUsageSyncInput = {
79
+ sessionId: string;
80
+ /** An invocation was made; an empty source page is incomplete rather than a free call. */
81
+ expectEvents?: boolean;
82
+ runId?: string | number;
83
+ rootRunId?: string;
84
+ parentSpanId?: string;
85
+ role?: string;
86
+ employeeUsername?: string;
87
+ userId?: string | number;
88
+ };
89
+
90
+ type Repository = {
91
+ find?: (opts: Record<string, unknown>) => Promise<unknown[]>;
92
+ findOne?: (opts: Record<string, unknown>) => Promise<unknown>;
93
+ create?: (opts: Record<string, unknown>) => Promise<unknown>;
94
+ update?: (opts: Record<string, unknown>) => Promise<unknown>;
95
+ };
96
+
97
+ type UsageTransaction = { LOCK?: { UPDATE?: unknown } };
98
+ type UsageDatabase = {
99
+ getRepository: (name: string) => Repository | undefined;
100
+ sequelize?: {
101
+ transaction?: <T>(operation: (transaction: UsageTransaction) => Promise<T>) => Promise<T>;
102
+ };
103
+ };
104
+
105
+ type Rate = {
106
+ inputPer1k: number;
107
+ outputPer1k: number;
108
+ cachedInputPer1k?: number;
109
+ currency: string;
110
+ version: string;
111
+ };
112
+
113
+ type RecordLike = Record<string, unknown>;
114
+ type LogMetadata = { module?: string; submodule?: string; method?: string; [key: string]: unknown };
115
+
116
+ const USAGE_EVENT_TYPE = 'llm_message';
117
+ const USAGE_PAGE_SIZE = 1_000;
118
+
119
+ function asRecord(value: unknown): RecordLike {
120
+ return value && typeof value === 'object' && !Array.isArray(value) ? (value as RecordLike) : {};
121
+ }
122
+
123
+ function readNumber(value: unknown): number | undefined {
124
+ if (typeof value === 'string' && !value.trim()) return undefined;
125
+ const number = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : NaN;
126
+ return Number.isFinite(number) && number >= 0 ? number : undefined;
127
+ }
128
+
129
+ function readOptionalNumber(record: unknown, key: string): number | undefined {
130
+ const raw = read(record, key);
131
+ return readNumber(raw);
132
+ }
133
+
134
+ function identityPart(value: unknown) {
135
+ return String(value ?? '').trim();
136
+ }
137
+
138
+ function normalizedCurrency(value: unknown) {
139
+ const currency = identityPart(value).toUpperCase();
140
+ return /^[A-Z]{3}$/.test(currency) ? currency : '';
141
+ }
142
+
143
+ function usageEventIdentity(sessionId: string, messageId: string) {
144
+ return `ai-usage-event:${sessionId}:${messageId}`;
145
+ }
146
+
147
+ export function usageFromAIUsageEvent(event: unknown): UsageCounts | null {
148
+ const raw = asRecord(read(event, 'rawUsageMetadata'));
149
+ const hasRawInput = ['input_tokens', 'prompt_tokens', 'inputTokens', 'promptTokens'].some(
150
+ (key) => Object.prototype.hasOwnProperty.call(raw, key) && readNumber(raw[key]) !== undefined,
151
+ );
152
+ const hasRawOutput = ['output_tokens', 'completion_tokens', 'outputTokens', 'completionTokens'].some(
153
+ (key) => Object.prototype.hasOwnProperty.call(raw, key) && readNumber(raw[key]) !== undefined,
154
+ );
155
+ const hasRawTotal = ['total_tokens', 'totalTokens'].some(
156
+ (key) => Object.prototype.hasOwnProperty.call(raw, key) && readNumber(raw[key]) !== undefined,
157
+ );
158
+
159
+ const inputTokens = readOptionalNumber(event, 'inputTokens');
160
+ const outputTokens = readOptionalNumber(event, 'outputTokens');
161
+ const totalTokens = readOptionalNumber(event, 'totalTokens');
162
+ if (!hasRawInput && !hasRawOutput && !hasRawTotal && inputTokens === 0 && outputTokens === 0 && totalTokens === 0) {
163
+ return null;
164
+ }
165
+ if (inputTokens === undefined || outputTokens === undefined) return null;
166
+ if ((!hasRawInput && inputTokens === 0) || (!hasRawOutput && outputTokens === 0)) return null;
167
+
168
+ const cachedTokens = readOptionalNumber(event, 'cachedTokens');
169
+ const reasoningTokens = readOptionalNumber(event, 'reasoningTokens');
170
+ return {
171
+ inputTokens,
172
+ outputTokens,
173
+ totalTokens: totalTokens ?? inputTokens + outputTokens,
174
+ ...(cachedTokens === undefined ? {} : { cachedTokens }),
175
+ ...(reasoningTokens === undefined ? {} : { reasoningTokens }),
176
+ };
177
+ }
178
+
179
+ function usageIsValid(usage: UsageCounts | null): usage is UsageCounts {
180
+ return Boolean(
181
+ usage &&
182
+ readNumber(usage.inputTokens) !== undefined &&
183
+ readNumber(usage.outputTokens) !== undefined &&
184
+ readNumber(usage.totalTokens) !== undefined,
185
+ );
186
+ }
187
+
188
+ function normalizedModelKey(provider: string | undefined, model: string | undefined, llmService: string | undefined) {
189
+ const modelName = identityPart(model).toLowerCase();
190
+ if (!modelName) return '';
191
+ const providerName = identityPart(provider).toLowerCase() || identityPart(llmService).toLowerCase();
192
+ return providerName ? `${providerName}/${modelName}` : modelName;
193
+ }
194
+
195
+ function configuredRate(provider?: string, model?: string, llmService?: string): Rate | null {
196
+ const json = process.env.ORCHESTRATOR_MODEL_PRICING_JSON;
197
+ if (!json) return null;
198
+
199
+ let entries: RecordLike;
200
+ try {
201
+ entries = asRecord(JSON.parse(json));
202
+ } catch {
203
+ return null;
204
+ }
205
+
206
+ const normalizedEntries = new Map<string, RecordLike>();
207
+ for (const [key, value] of Object.entries(entries)) {
208
+ normalizedEntries.set(key.trim().toLowerCase(), asRecord(value));
209
+ }
210
+ const modelKey = normalizedModelKey(provider, model, llmService);
211
+ const entry =
212
+ normalizedEntries.get(modelKey) ??
213
+ (!provider ? normalizedEntries.get(identityPart(model).toLowerCase()) : undefined);
214
+ if (!entry) return null;
215
+
216
+ const inputPer1k = readNumber(entry.inputPer1k);
217
+ const outputPer1k = readNumber(entry.outputPer1k);
218
+ const currency = normalizedCurrency(entry.currency);
219
+ if (inputPer1k === undefined || outputPer1k === undefined || !currency) return null;
220
+
221
+ const cachedInputPer1k = readNumber(entry.cachedInputPer1k);
222
+ return {
223
+ inputPer1k,
224
+ outputPer1k,
225
+ ...(cachedInputPer1k === undefined ? {} : { cachedInputPer1k }),
226
+ currency,
227
+ version:
228
+ identityPart(entry.version) || identityPart(process.env.ORCHESTRATOR_MODEL_PRICING_VERSION) || 'unversioned',
229
+ };
230
+ }
231
+
232
+ function legacyGlobalRate(): Rate | null {
233
+ const inputPer1k = readNumber(process.env.ORCHESTRATOR_PRICE_PER_1K_INPUT);
234
+ const outputPer1k = readNumber(process.env.ORCHESTRATOR_PRICE_PER_1K_OUTPUT);
235
+ if (inputPer1k === undefined || outputPer1k === undefined) return null;
236
+ return {
237
+ inputPer1k,
238
+ outputPer1k,
239
+ currency: 'USD',
240
+ version: 'legacy-global-env',
241
+ };
242
+ }
243
+
244
+ function legacyCostEstimate(inputTokens: number, outputTokens: number): number | null {
245
+ const rate = legacyGlobalRate();
246
+ if (!rate) return null;
247
+ return (inputTokens / 1000) * rate.inputPer1k + (outputTokens / 1000) * rate.outputPer1k;
248
+ }
249
+
250
+ /**
251
+ * Compatibility estimate for older callers. It only uses rates that were explicitly configured
252
+ * through the legacy environment variables; NaN is the unpriced sentinel when no rate is set.
253
+ */
254
+ export function estimateCost(inputTokens: number, outputTokens: number): number {
255
+ return legacyCostEstimate(inputTokens, outputTokens) ?? Number.NaN;
256
+ }
257
+
258
+ function pricingFor(input: ModelCallUsageInput): {
259
+ cost: number | null;
260
+ status: PricingStatus;
261
+ priceSource: string | null;
262
+ snapshot: PriceSnapshot;
263
+ } {
264
+ const supplied = input.priceSnapshot
265
+ ? { ...input.priceSnapshot, currency: normalizedCurrency(input.priceSnapshot.currency) || undefined }
266
+ : undefined;
267
+ const nativeCost = readNumber(input.nativeCost) ?? readNumber(supplied?.cost);
268
+ if (nativeCost !== undefined) {
269
+ const currency = normalizedCurrency(supplied?.currency);
270
+ if (currency !== 'USD') {
271
+ const status = currency ? 'non_usd' : 'unpriced';
272
+ return { cost: null, status, priceSource: supplied?.source ?? 'provider', snapshot: { ...supplied, status } };
273
+ }
274
+ return {
275
+ cost: nativeCost,
276
+ status: supplied?.status ?? 'native',
277
+ priceSource: supplied?.source ?? 'provider',
278
+ snapshot: supplied ?? { status: 'native', source: 'provider' },
279
+ };
280
+ }
281
+
282
+ const suppliedInputRate = readNumber(supplied?.inputPer1k);
283
+ const suppliedOutputRate = readNumber(supplied?.outputPer1k);
284
+ const suppliedCachedInputRate = readNumber(supplied?.cachedInputPer1k);
285
+ if (supplied && identityPart(supplied.currency).toUpperCase() !== 'USD') {
286
+ const status = supplied.currency ? 'non_usd' : 'unpriced';
287
+ return { cost: null, status, priceSource: supplied.source ?? null, snapshot: { ...supplied, status } };
288
+ }
289
+ if (supplied && usageIsValid(input.usage) && suppliedInputRate !== undefined && suppliedOutputRate !== undefined) {
290
+ const cachedTokens = Math.min(input.usage.cachedTokens ?? 0, input.usage.inputTokens);
291
+ const regularInput = input.usage.inputTokens - cachedTokens;
292
+ const inputCost =
293
+ suppliedCachedInputRate === undefined
294
+ ? (input.usage.inputTokens / 1000) * suppliedInputRate
295
+ : (regularInput / 1000) * suppliedInputRate + (cachedTokens / 1000) * suppliedCachedInputRate;
296
+ return {
297
+ cost: inputCost + (input.usage.outputTokens / 1000) * suppliedOutputRate,
298
+ status: supplied.status ?? 'native',
299
+ priceSource: supplied.source ?? 'provider',
300
+ snapshot: supplied,
301
+ };
302
+ }
303
+
304
+ const rate = configuredRate(input.provider, input.model, input.llmService);
305
+ if (rate && rate.currency !== 'USD') {
306
+ return {
307
+ cost: null,
308
+ status: 'non_usd',
309
+ priceSource: 'model_pricing_json',
310
+ snapshot: { ...rate, source: 'model_pricing_json', status: 'non_usd' },
311
+ };
312
+ }
313
+ if (rate && usageIsValid(input.usage)) {
314
+ const cachedTokens = Math.min(input.usage.cachedTokens ?? 0, input.usage.inputTokens);
315
+ const regularInput = input.usage.inputTokens - cachedTokens;
316
+ const inputCost =
317
+ rate.cachedInputPer1k === undefined
318
+ ? (input.usage.inputTokens / 1000) * rate.inputPer1k
319
+ : (regularInput / 1000) * rate.inputPer1k + (cachedTokens / 1000) * rate.cachedInputPer1k;
320
+ return {
321
+ cost: inputCost + (input.usage.outputTokens / 1000) * rate.outputPer1k,
322
+ status: 'configured',
323
+ priceSource: 'model_pricing_json',
324
+ snapshot: {
325
+ inputPer1k: rate.inputPer1k,
326
+ outputPer1k: rate.outputPer1k,
327
+ ...(rate.cachedInputPer1k === undefined ? {} : { cachedInputPer1k: rate.cachedInputPer1k }),
328
+ currency: rate.currency,
329
+ version: rate.version,
330
+ source: 'model_pricing_json',
331
+ status: 'configured',
332
+ },
333
+ };
334
+ }
335
+
336
+ // The old global values remain an explicit estimate only for model-less legacy callers.
337
+ // A known provider/model never silently inherits a global rate for another model.
338
+ if (!input.model && !input.provider && !input.llmService && usageIsValid(input.usage)) {
339
+ const legacyRate = legacyGlobalRate();
340
+ const cost = legacyCostEstimate(input.usage.inputTokens, input.usage.outputTokens);
341
+ if (legacyRate && cost !== null) {
342
+ return {
343
+ cost,
344
+ status: 'estimated',
345
+ priceSource: 'legacy_global_env',
346
+ snapshot: {
347
+ inputPer1k: legacyRate.inputPer1k,
348
+ outputPer1k: legacyRate.outputPer1k,
349
+ currency: legacyRate.currency,
350
+ version: legacyRate.version,
351
+ source: 'legacy_global_env',
352
+ status: 'estimated',
353
+ },
354
+ };
355
+ }
356
+ }
357
+
358
+ return { cost: null, status: 'unpriced', priceSource: null, snapshot: { status: 'unpriced' } };
359
+ }
360
+
361
+ function storedNumber(record: unknown, key: string): number | null {
362
+ const value = read(record, key);
363
+ return value === null || value === undefined || value === '' ? null : readNumber(value) ?? null;
364
+ }
365
+
366
+ function sourceDate(value: unknown) {
367
+ if (value instanceof Date && Number.isFinite(value.getTime())) return value;
368
+ if (typeof value === 'string' || typeof value === 'number') {
369
+ const date = new Date(value);
370
+ if (Number.isFinite(date.getTime())) return date;
371
+ }
372
+ return undefined;
373
+ }
374
+
375
+ function storedPriceSnapshot(record: unknown): PriceSnapshot {
376
+ const currency = identityPart(read(record, 'priceCurrency'));
377
+ const version = identityPart(read(record, 'priceVersion'));
378
+ const source = identityPart(read(record, 'priceSource'));
379
+ const status = identityPart(read(record, 'pricingStatus'));
380
+ return {
381
+ inputPer1k: storedNumber(record, 'priceInputPer1k'),
382
+ outputPer1k: storedNumber(record, 'priceOutputPer1k'),
383
+ cachedInputPer1k: storedNumber(record, 'priceCachedInputPer1k'),
384
+ ...(currency ? { currency } : {}),
385
+ ...(version ? { version } : {}),
386
+ ...(source ? { source: source as PriceSnapshot['source'] } : {}),
387
+ ...(status ? { status: status as PricingStatus } : {}),
388
+ };
389
+ }
390
+
391
+ function sameUsage(record: unknown, usage: UsageCounts | null): boolean {
392
+ if (!usageIsValid(usage)) return false;
393
+ return (
394
+ storedNumber(record, 'inputTokens') === usage.inputTokens &&
395
+ storedNumber(record, 'outputTokens') === usage.outputTokens &&
396
+ storedNumber(record, 'totalTokens') === usage.totalTokens &&
397
+ storedNumber(record, 'cachedTokens') === (usage.cachedTokens ?? null) &&
398
+ storedNumber(record, 'reasoningTokens') === (usage.reasoningTokens ?? null)
399
+ );
400
+ }
401
+
402
+ function incompleteSessions(record: unknown): string[] {
403
+ const value = read(record, 'usageIncompleteSessions');
404
+ if (Array.isArray(value)) return value.filter((entry): entry is string => typeof entry === 'string' && !!entry);
405
+ return [];
406
+ }
407
+
408
+ function spanIdentity(record: unknown) {
409
+ const value = read(record, 'id');
410
+ return typeof value === 'string' || typeof value === 'number' ? value : undefined;
411
+ }
412
+
413
+ function isModelCall(record: unknown) {
414
+ return read(record, 'type') === 'model_call';
415
+ }
416
+
417
+ function messageIdFor(event: unknown): string {
418
+ return identityPart(read(event, 'messageId'));
419
+ }
420
+
421
+ /**
422
+ * Tracks provider usage on model-call spans. Agent/sub-agent/tool spans remain graph projections
423
+ * only and are never included in usage totals, avoiding parent/child double counting.
424
+ */
425
+ export class TokenTracker {
426
+ constructor(
427
+ private readonly plugin: {
428
+ app: {
429
+ log?: { warn?: (message: string, meta?: LogMetadata) => void };
430
+ logger?: { warn?: (message: string, meta?: LogMetadata) => void };
431
+ };
432
+ db: UsageDatabase;
433
+ },
434
+ ) {}
435
+
436
+ get db() {
437
+ return this.plugin.db;
438
+ }
439
+
440
+ get app() {
441
+ return this.plugin.app;
442
+ }
443
+
444
+ private warn(message: string, error: unknown) {
445
+ try {
446
+ this.app.log?.warn?.(message, { error });
447
+ this.app.logger?.warn?.(message, { error });
448
+ } catch {
449
+ // Telemetry logging must not affect the caller's execution.
450
+ }
451
+ }
452
+
453
+ private withTransaction<T>(operation: (transaction?: UsageTransaction) => Promise<T>) {
454
+ const sequelize = this.db.sequelize;
455
+ return sequelize?.transaction ? sequelize.transaction((active) => operation(active)) : operation();
456
+ }
457
+
458
+ private async markSessionIncomplete(runId: string | number, sessionId: string, incomplete: boolean) {
459
+ await this.withTransaction(async (transaction) => {
460
+ const repo = this.db.getRepository('agentLoopRuns');
461
+ if (!repo?.findOne || !repo.update) throw new Error('Run repository is unavailable.');
462
+ const txOptions = transaction
463
+ ? { transaction, ...(transaction.LOCK?.UPDATE === undefined ? {} : { lock: transaction.LOCK.UPDATE }) }
464
+ : {};
465
+ const run = await repo.findOne({ filterByTk: runId, ...txOptions });
466
+ if (!run) throw new Error(`Run ${runId} does not exist.`);
467
+ const sessions = new Set(incompleteSessions(run));
468
+ if (incomplete) sessions.add(sessionId);
469
+ else sessions.delete(sessionId);
470
+ const currentUsageStatus = identityPart(read(run, 'usageStatus'));
471
+ await repo.update({
472
+ filterByTk: runId,
473
+ values: {
474
+ usageIncompleteSessions: [...sessions],
475
+ ...(incomplete
476
+ ? {
477
+ usageStatus: currentUsageStatus && currentUsageStatus !== 'missing' ? 'partial' : 'missing',
478
+ pricingStatus: 'unpriced',
479
+ totalCost: null,
480
+ }
481
+ : {}),
482
+ },
483
+ ...(transaction ? { transaction } : {}),
484
+ });
485
+ });
486
+ }
487
+
488
+ /**
489
+ * Upserts a single provider model-call usage record by its durable identity. Native usage events
490
+ * use `ai-usage-event:<sessionId>:<messageId>`; retries and resume history therefore reconcile
491
+ * the same row instead of adding its tokens again.
492
+ */
493
+ async recordModelCallUsage(input: ModelCallUsageInput): Promise<string | number | undefined> {
494
+ const usageIdentity = identityPart(input.usageIdentity);
495
+ if (!usageIdentity) return undefined;
496
+
497
+ const persist = async (transaction?: UsageTransaction) => {
498
+ const repo = this.db.getRepository('agentExecutionSpans');
499
+ if (!repo?.create || !repo.update || !repo.findOne) return undefined;
500
+ const txOptions = transaction
501
+ ? { transaction, ...(transaction.LOCK?.UPDATE === undefined ? {} : { lock: transaction.LOCK.UPDATE }) }
502
+ : {};
503
+ const existingByIdentity = await repo.findOne({ filter: { usageIdentity }, ...txOptions });
504
+ const existingById =
505
+ input.spanId !== undefined ? await repo.findOne({ filterByTk: input.spanId, ...txOptions }) : null;
506
+ const existing = existingByIdentity || (existingById && isModelCall(existingById) ? existingById : null);
507
+ if (existing && !isModelCall(existing)) {
508
+ this.warn('[TokenTracker] Refused to attach model-call usage to a non-model-call span.', usageIdentity);
509
+ return undefined;
510
+ }
511
+ if (
512
+ existingById &&
513
+ !existingByIdentity &&
514
+ identityPart(read(existingById, 'usageIdentity')) &&
515
+ identityPart(read(existingById, 'usageIdentity')) !== usageIdentity
516
+ ) {
517
+ this.warn('[TokenTracker] Refused to replace a different model-call usage identity.', usageIdentity);
518
+ return undefined;
519
+ }
520
+
521
+ const origin = input.source;
522
+ const existingOrigin = identityPart(read(existing, 'usageOrigin'));
523
+ const existingUsageSource = identityPart(read(existing, 'usageSource'));
524
+ const hasIncomingUsage = usageIsValid(input.usage);
525
+ const preserveNativeData =
526
+ existingOrigin === 'ai_usage_event' &&
527
+ (origin === 'loop_runtime' || (existingUsageSource === 'actual' && !hasIncomingUsage));
528
+ const preserveKnownUsage =
529
+ (existingUsageSource === 'actual' || existingUsageSource === 'estimated') && !hasIncomingUsage;
530
+ const shouldPreserveUsage = preserveNativeData || preserveKnownUsage;
531
+ const usage = shouldPreserveUsage ? null : input.usage;
532
+ const usageSource: UsageSource = shouldPreserveUsage
533
+ ? (identityPart(read(existing, 'usageSource')) as UsageSource) || 'missing'
534
+ : usageIsValid(usage)
535
+ ? 'actual'
536
+ : 'missing';
537
+ const preservePrice =
538
+ shouldPreserveUsage || (existingUsageSource === 'actual' && sameUsage(existing, input.usage));
539
+ const historicalSnapshot = storedPriceSnapshot(existing);
540
+ const hasHistoricalRates = historicalSnapshot.inputPer1k != null && historicalSnapshot.outputPer1k != null;
541
+ let resolvedPricing: ReturnType<typeof pricingFor> | null = null;
542
+ if (!preservePrice) {
543
+ if (hasHistoricalRates && (existingUsageSource === 'actual' || existingUsageSource === 'estimated')) {
544
+ resolvedPricing = pricingFor({ ...input, nativeCost: undefined, priceSnapshot: historicalSnapshot });
545
+ } else if (existingUsageSource === 'actual') {
546
+ // Without saved unit rates a corrected quantity cannot be repriced from current prices.
547
+ // Keep the original snapshot and mark the corrected call unpriced.
548
+ const status = historicalSnapshot.status === 'non_usd' ? 'non_usd' : 'unpriced';
549
+ resolvedPricing = {
550
+ cost: null,
551
+ status,
552
+ priceSource: historicalSnapshot.source ?? null,
553
+ snapshot: { ...historicalSnapshot, status },
554
+ };
555
+ } else {
556
+ resolvedPricing = pricingFor(input);
557
+ }
558
+ }
559
+ const now = new Date();
560
+ const occurredAt = sourceDate(input.occurredAt) || sourceDate(read(existing, 'usageOccurredAt'));
561
+ // Reconciliation of a native event must never replace a previously captured department.
562
+ const existingDepartmentId = read(existing, 'departmentId');
563
+ const departmentId = existingDepartmentId ?? input.departmentId;
564
+ const values: RecordLike = {
565
+ type: 'model_call',
566
+ usageIdentity,
567
+ ...(input.nativeIdentity ? { nativeIdentity: input.nativeIdentity } : {}),
568
+ usageSessionId: input.sessionId,
569
+ usageMessageId: input.messageId,
570
+ ...(input.runId === undefined ? {} : { agentLoopRunId: input.runId }),
571
+ ...(input.rootRunId ? { rootRunId: input.rootRunId } : {}),
572
+ ...(input.parentSpanId ? { parentSpanId: input.parentSpanId } : {}),
573
+ ...(input.role ? { role: input.role } : {}),
574
+ ...(input.employeeUsername ? { employeeUsername: input.employeeUsername } : {}),
575
+ ...(input.userId == null ? {} : { userId: input.userId }),
576
+ ...(departmentId == null
577
+ ? {}
578
+ : {
579
+ departmentId,
580
+ departmentAttribution:
581
+ existingDepartmentId == null ? 'snapshot' : read(existing, 'departmentAttribution'),
582
+ }),
583
+ ...(input.model ? { model: input.model } : {}),
584
+ ...(input.provider ? { provider: input.provider } : {}),
585
+ ...(input.llmService ? { llmService: input.llmService } : {}),
586
+ source: input.source === 'ai_usage_event' ? 'native-plugin-ai' : 'loop-runtime-usage',
587
+ usageSource,
588
+ usageOrigin: shouldPreserveUsage ? existingOrigin || identityPart(read(existing, 'usageOrigin')) : origin,
589
+ inputTokens: shouldPreserveUsage ? read(existing, 'inputTokens') : usage?.inputTokens ?? null,
590
+ outputTokens: shouldPreserveUsage ? read(existing, 'outputTokens') : usage?.outputTokens ?? null,
591
+ totalTokens: shouldPreserveUsage ? read(existing, 'totalTokens') : usage?.totalTokens ?? null,
592
+ cachedTokens: shouldPreserveUsage ? read(existing, 'cachedTokens') : usage?.cachedTokens ?? null,
593
+ reasoningTokens: shouldPreserveUsage ? read(existing, 'reasoningTokens') : usage?.reasoningTokens ?? null,
594
+ cost: preservePrice ? read(existing, 'cost') : resolvedPricing?.cost ?? null,
595
+ pricingStatus: preservePrice ? read(existing, 'pricingStatus') : resolvedPricing?.status ?? 'unpriced',
596
+ priceSource: preservePrice ? read(existing, 'priceSource') : resolvedPricing?.priceSource ?? null,
597
+ priceCurrency: preservePrice ? read(existing, 'priceCurrency') : resolvedPricing?.snapshot.currency ?? null,
598
+ priceVersion: preservePrice ? read(existing, 'priceVersion') : resolvedPricing?.snapshot.version ?? null,
599
+ priceInputPer1k: preservePrice
600
+ ? read(existing, 'priceInputPer1k')
601
+ : resolvedPricing?.snapshot.inputPer1k ?? null,
602
+ priceOutputPer1k: preservePrice
603
+ ? read(existing, 'priceOutputPer1k')
604
+ : resolvedPricing?.snapshot.outputPer1k ?? null,
605
+ priceCachedInputPer1k: preservePrice
606
+ ? read(existing, 'priceCachedInputPer1k')
607
+ : resolvedPricing?.snapshot.cachedInputPer1k ?? null,
608
+ ...(occurredAt ? { usageOccurredAt: occurredAt } : {}),
609
+ ...(sourceDate(input.occurredAt) ? { startedAt: occurredAt, endedAt: occurredAt } : {}),
610
+ ...(existing
611
+ ? {}
612
+ : { status: 'success', startedAt: occurredAt || now, endedAt: occurredAt || now, createdAt: now }),
613
+ updatedAt: now,
614
+ };
615
+
616
+ const id = spanIdentity(existing);
617
+ if (id !== undefined) {
618
+ await repo.update({ filterByTk: id, values, ...txOptions });
619
+ return id;
620
+ }
621
+
622
+ const created = await repo.create({
623
+ values: {
624
+ rootRunId: input.rootRunId || `session:${input.sessionId}`,
625
+ status: 'success',
626
+ startedAt: occurredAt || now,
627
+ endedAt: occurredAt || now,
628
+ createdAt: now,
629
+ ...values,
630
+ },
631
+ ...txOptions,
632
+ });
633
+ return spanIdentity(created);
634
+ };
635
+
636
+ try {
637
+ let id: string | number | undefined;
638
+ try {
639
+ id = await this.withTransaction(persist);
640
+ } catch {
641
+ // A unique-key race aborts its transaction. Retry in a fresh transaction so the winning
642
+ // row is re-read under lock and its actual usage/price snapshot is merged safely.
643
+ id = await this.withTransaction(persist);
644
+ }
645
+ if (id === undefined) return undefined;
646
+ if (input.runId != null && input.recomputeRunTotals !== false && !(await this.accumulateToRun(input.runId))) {
647
+ return undefined;
648
+ }
649
+ return id;
650
+ } catch (error) {
651
+ this.warn('[TokenTracker] Failed to track model-call usage', error);
652
+ return undefined;
653
+ }
654
+ }
655
+
656
+ /**
657
+ * Imports authoritative core aiUsageEvents for one session. The same identity is used by the
658
+ * native monitor projection, so loop retries and observer reconciliation update one model-call.
659
+ */
660
+ async syncNativeUsageEvents(input: NativeUsageSyncInput): Promise<number> {
661
+ try {
662
+ const repo = this.db.getRepository('aiUsageEvents');
663
+ if (!repo?.find) {
664
+ if (input.expectEvents && input.runId != null)
665
+ await this.markSessionIncomplete(input.runId, input.sessionId, true);
666
+ return 0;
667
+ }
668
+ let tracked = 0;
669
+ let lastMessageId: string | undefined;
670
+ let hasMore = true;
671
+ while (hasMore) {
672
+ const events = await repo.find({
673
+ filter: {
674
+ sessionId: input.sessionId,
675
+ eventType: USAGE_EVENT_TYPE,
676
+ ...(lastMessageId ? { messageId: { $gt: lastMessageId } } : {}),
677
+ },
678
+ sort: ['messageId'],
679
+ limit: USAGE_PAGE_SIZE,
680
+ });
681
+ for (const event of events) {
682
+ const sessionId = identityPart(read(event, 'sessionId')) || input.sessionId;
683
+ const messageId = messageIdFor(event);
684
+ if (!messageId) throw new Error('Native usage event has no message identity.');
685
+ const nativeCost = readNumber(read(event, 'cost'));
686
+ const priceSnapshotValue = read(event, 'priceSnapshot');
687
+ const priceSnapshot =
688
+ priceSnapshotValue && typeof priceSnapshotValue === 'object'
689
+ ? (priceSnapshotValue as PriceSnapshot)
690
+ : undefined;
691
+ const occurredAt = sourceDate(read(event, 'occurredAt'));
692
+ const id = await this.recordModelCallUsage({
693
+ usageIdentity: usageEventIdentity(sessionId, messageId),
694
+ nativeIdentity: usageEventIdentity(sessionId, messageId),
695
+ sessionId,
696
+ messageId,
697
+ usage: usageFromAIUsageEvent(event),
698
+ model: identityPart(read(event, 'model')) || undefined,
699
+ provider: identityPart(read(event, 'provider')) || undefined,
700
+ llmService: identityPart(read(event, 'llmService')) || undefined,
701
+ runId: input.runId,
702
+ rootRunId: input.rootRunId,
703
+ parentSpanId: input.parentSpanId,
704
+ role: input.role,
705
+ employeeUsername: input.employeeUsername || identityPart(read(event, 'aiEmployeeUsername')) || undefined,
706
+ userId: input.userId ?? (read(event, 'userId') as string | number | undefined),
707
+ source: 'ai_usage_event',
708
+ recomputeRunTotals: false,
709
+ ...(occurredAt ? { occurredAt } : {}),
710
+ ...(priceSnapshot ? { priceSnapshot } : {}),
711
+ ...(nativeCost === undefined ? {} : { nativeCost }),
712
+ });
713
+ if (id === undefined) throw new Error(`Could not persist usage event ${messageId}.`);
714
+ tracked += 1;
715
+ }
716
+ if (events.length < USAGE_PAGE_SIZE) {
717
+ hasMore = false;
718
+ continue;
719
+ }
720
+ const nextMessageId = messageIdFor(events[events.length - 1]);
721
+ if (!nextMessageId || nextMessageId === lastMessageId)
722
+ throw new Error('Native usage pagination did not advance.');
723
+ lastMessageId = nextMessageId;
724
+ }
725
+ if (input.runId != null && (tracked > 0 || input.expectEvents)) {
726
+ // An empty query cannot prove an invocation consumed no tokens. Retain a previous
727
+ // incomplete marker until at least one source event can be fully reconciled.
728
+ await this.markSessionIncomplete(input.runId, input.sessionId, tracked === 0);
729
+ if (!(await this.accumulateToRun(input.runId))) throw new Error('Could not recalculate usage totals.');
730
+ }
731
+ return tracked;
732
+ } catch (error) {
733
+ this.warn('[TokenTracker] Failed to synchronize native usage events', error);
734
+ if (input.runId != null) {
735
+ try {
736
+ await this.markSessionIncomplete(input.runId, input.sessionId, true);
737
+ } catch (markError) {
738
+ this.warn('[TokenTracker] Failed to mark incomplete run usage', markError);
739
+ }
740
+ }
741
+ return -1;
742
+ }
743
+ }
744
+
745
+ /**
746
+ * Persists the loop adapter's transcript aggregate only as a non-additive summary when the
747
+ * authoritative aiUsageEvents rows are unavailable. Summary rows stay out of run totals so a
748
+ * later native reconciliation cannot double-count resume history or model-call children.
749
+ */
750
+ async trackLoopInvocationUsage(input: LoopInvocationUsageInput): Promise<void> {
751
+ const nativeRows = await this.syncNativeUsageEvents({
752
+ sessionId: input.sessionId,
753
+ expectEvents: true,
754
+ runId: input.runId,
755
+ rootRunId: input.rootRunId,
756
+ role: input.role,
757
+ employeeUsername: input.employeeUsername,
758
+ userId: input.userId,
759
+ });
760
+ if (nativeRows !== 0) return;
761
+
762
+ try {
763
+ const repo = this.db.getRepository('agentExecutionSpans');
764
+ if (!repo?.findOne || !repo?.create || !repo.update) return;
765
+ const usageIdentity = `loop-invocation-summary:${input.runId}:${input.stepId}`;
766
+ const existing = await repo.findOne({ filter: { usageIdentity } });
767
+ const now = new Date();
768
+ let usage: UsageCounts | null = usageIsValid(input.usage) ? input.usage : null;
769
+ let source: UsageSource = usage ? 'actual' : 'missing';
770
+ if (!usage) {
771
+ const inputTokens = Math.ceil((input.input || '').length / 4);
772
+ const outputTokens = Math.ceil((input.output || '').length / 4);
773
+ usage = { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
774
+ source = 'estimated';
775
+ }
776
+ const priced = pricingFor({
777
+ usageIdentity,
778
+ sessionId: input.sessionId,
779
+ messageId: input.messageId || '',
780
+ usage,
781
+ source: 'loop_runtime',
782
+ });
783
+ const values: RecordLike = {
784
+ type: 'invocation_summary',
785
+ usageIdentity,
786
+ usageSessionId: input.sessionId,
787
+ usageMessageId: input.messageId || null,
788
+ agentLoopRunId: input.runId,
789
+ agentLoopStepId: input.stepId,
790
+ rootRunId: input.rootRunId || `loop:${input.runId}`,
791
+ role: input.role,
792
+ employeeUsername: input.employeeUsername,
793
+ ...(input.userId == null ? {} : { userId: input.userId }),
794
+ source: 'loop-runtime-summary',
795
+ usageSource: source,
796
+ usageOrigin: 'loop_invocation_summary',
797
+ inputTokens: usage.inputTokens,
798
+ outputTokens: usage.outputTokens,
799
+ totalTokens: usage.totalTokens,
800
+ cachedTokens: usage.cachedTokens ?? null,
801
+ reasoningTokens: usage.reasoningTokens ?? null,
802
+ cost: priced.cost,
803
+ pricingStatus: priced.cost === null ? 'unpriced' : source === 'estimated' ? 'estimated' : priced.status,
804
+ priceSource: priced.priceSource,
805
+ priceCurrency: priced.snapshot.currency ?? null,
806
+ priceVersion: priced.snapshot.version ?? null,
807
+ priceInputPer1k: priced.snapshot.inputPer1k ?? null,
808
+ priceOutputPer1k: priced.snapshot.outputPer1k ?? null,
809
+ priceCachedInputPer1k: priced.snapshot.cachedInputPer1k ?? null,
810
+ status: 'success',
811
+ startedAt: now,
812
+ endedAt: now,
813
+ updatedAt: now,
814
+ };
815
+ const existingId = spanIdentity(existing);
816
+ if (existingId !== undefined) {
817
+ await repo.update({ filterByTk: existingId, values });
818
+ } else {
819
+ await repo.create({ values: { createdAt: now, ...values } });
820
+ }
821
+ } catch (error) {
822
+ this.warn('[TokenTracker] Failed to persist loop invocation usage summary', error);
823
+ }
824
+ }
825
+
826
+ /**
827
+ * Compatibility API for callers that already hold an agentExecutionSpans primary key. This
828
+ * method deliberately keeps span identity separate from agentLoopSteps IDs.
829
+ */
830
+ async trackSpan(spanId: string | number | undefined, usage: TokenUsage, runId?: string | number): Promise<void> {
831
+ if (spanId === undefined || spanId === null || spanId === '') return;
832
+
833
+ try {
834
+ const repo = this.db.getRepository('agentExecutionSpans');
835
+ if (!repo?.findOne || !repo.update) return;
836
+ const span = await repo.findOne({ filterByTk: spanId });
837
+ if (!span) return;
838
+ const inputTokens = readNumber(usage.inputTokens);
839
+ const outputTokens = readNumber(usage.outputTokens);
840
+ const totalTokens = readNumber(usage.totalTokens);
841
+ if (inputTokens === undefined || outputTokens === undefined || totalTokens === undefined) return;
842
+
843
+ const model = identityPart(read(span, 'model')) || undefined;
844
+ const provider = identityPart(read(span, 'provider')) || undefined;
845
+ const llmService = identityPart(read(span, 'llmService')) || undefined;
846
+ const resolved = pricingFor({
847
+ usageIdentity: identityPart(read(span, 'usageIdentity')) || `legacy-span:${spanId}`,
848
+ nativeIdentity: identityPart(read(span, 'nativeIdentity')) || undefined,
849
+ sessionId: identityPart(read(span, 'sessionId')),
850
+ messageId: identityPart(read(span, 'messageId')),
851
+ usage: { inputTokens, outputTokens, totalTokens, cost: usage.cost, cachedTokens: usage.cachedTokens },
852
+ model,
853
+ provider,
854
+ llmService,
855
+ source: 'loop_runtime',
856
+ });
857
+ await repo.update({
858
+ filterByTk: spanId,
859
+ values: {
860
+ inputTokens,
861
+ outputTokens,
862
+ totalTokens,
863
+ cachedTokens: usage.cachedTokens ?? null,
864
+ reasoningTokens: usage.reasoningTokens ?? null,
865
+ usageSource: 'actual',
866
+ usageOrigin: 'legacy_tracker',
867
+ cost: resolved.cost,
868
+ pricingStatus: resolved.status,
869
+ priceSource: resolved.priceSource,
870
+ priceCurrency: resolved.snapshot.currency ?? null,
871
+ priceVersion: resolved.snapshot.version ?? null,
872
+ priceInputPer1k: resolved.snapshot.inputPer1k ?? null,
873
+ priceOutputPer1k: resolved.snapshot.outputPer1k ?? null,
874
+ priceCachedInputPer1k: resolved.snapshot.cachedInputPer1k ?? null,
875
+ updatedAt: new Date(),
876
+ },
877
+ });
878
+
879
+ if (runId != null) await this.accumulateToRun(runId);
880
+ } catch (error) {
881
+ this.warn('[TokenTracker] Failed to track span tokens', error);
882
+ }
883
+ }
884
+
885
+ /** Recalculates totals from model-call spans only. Parent and child span tokens are not added. */
886
+ async accumulateToRun(runId: string | number): Promise<boolean> {
887
+ try {
888
+ return await this.withTransaction(async (transaction) => {
889
+ const spansRepo = this.db.getRepository('agentExecutionSpans');
890
+ const runsRepo = this.db.getRepository('agentLoopRuns');
891
+ if (!spansRepo?.find || !runsRepo?.findOne || !runsRepo.update) return false;
892
+ const txOptions = transaction
893
+ ? { transaction, ...(transaction.LOCK?.UPDATE === undefined ? {} : { lock: transaction.LOCK.UPDATE }) }
894
+ : {};
895
+ // All writers recomputing a run acquire the same row lock before reading its spans.
896
+ // A later writer therefore includes every model-call committed by earlier writers.
897
+ const run = await runsRepo.findOne({ filterByTk: runId, ...txOptions });
898
+ if (!run) return false;
899
+
900
+ let totalInput = 0;
901
+ let totalOutput = 0;
902
+ let totalTokens = 0;
903
+ let totalCost = 0;
904
+ let hasKnownUsage = false;
905
+ let hasMissingUsage = incompleteSessions(run).length > 0;
906
+ let hasEstimatedUsage = false;
907
+ let hasActualUsage = false;
908
+ let hasUnpriced = incompleteSessions(run).length > 0;
909
+ let hasNonUsd = false;
910
+ let hasEstimatedPrice = false;
911
+ let rowCount = 0;
912
+ let lastId: string | number | undefined;
913
+
914
+ let hasMore = true;
915
+ while (hasMore) {
916
+ const spans = await spansRepo.find({
917
+ filter: {
918
+ agentLoopRunId: runId,
919
+ type: 'model_call',
920
+ ...(lastId === undefined ? {} : { id: { $gt: lastId } }),
921
+ },
922
+ fields: [
923
+ 'id',
924
+ 'inputTokens',
925
+ 'outputTokens',
926
+ 'totalTokens',
927
+ 'cost',
928
+ 'usageSource',
929
+ 'pricingStatus',
930
+ 'priceCurrency',
931
+ ],
932
+ sort: ['id'],
933
+ limit: USAGE_PAGE_SIZE,
934
+ ...(transaction ? { transaction } : {}),
935
+ });
936
+ rowCount += spans.length;
937
+ for (const span of spans) {
938
+ const source = identityPart(read(span, 'usageSource'));
939
+ const inputTokens = storedNumber(span, 'inputTokens');
940
+ const outputTokens = storedNumber(span, 'outputTokens');
941
+ const storedTotalTokens = storedNumber(span, 'totalTokens');
942
+ if (source === 'missing' || inputTokens === null || outputTokens === null) {
943
+ hasMissingUsage = true;
944
+ } else {
945
+ hasKnownUsage = true;
946
+ totalInput += inputTokens;
947
+ totalOutput += outputTokens;
948
+ totalTokens += storedTotalTokens ?? inputTokens + outputTokens;
949
+ if (source === 'estimated' || !source) hasEstimatedUsage = true;
950
+ if (source === 'actual') hasActualUsage = true;
951
+ }
952
+
953
+ const pricingStatus = identityPart(read(span, 'pricingStatus'));
954
+ const currency = identityPart(read(span, 'priceCurrency')).toUpperCase();
955
+ const cost = storedNumber(span, 'cost');
956
+ if (pricingStatus === 'non_usd' || (currency && currency !== 'USD')) hasNonUsd = true;
957
+ if (pricingStatus === 'unpriced' || cost === null || currency !== 'USD') {
958
+ hasUnpriced = true;
959
+ } else {
960
+ totalCost += cost;
961
+ if (pricingStatus === 'estimated') hasEstimatedPrice = true;
962
+ }
963
+ }
964
+ if (spans.length < USAGE_PAGE_SIZE) {
965
+ hasMore = false;
966
+ continue;
967
+ }
968
+ const nextId = spanIdentity(spans[spans.length - 1]);
969
+ if (nextId === undefined || nextId === lastId) throw new Error('Usage rollup pagination did not advance.');
970
+ lastId = nextId;
971
+ }
972
+
973
+ const usageStatus = !hasKnownUsage
974
+ ? 'missing'
975
+ : hasMissingUsage
976
+ ? 'partial'
977
+ : hasEstimatedUsage
978
+ ? 'estimated'
979
+ : hasActualUsage
980
+ ? 'actual'
981
+ : 'partial';
982
+ const pricingStatus = hasNonUsd
983
+ ? 'non_usd'
984
+ : hasUnpriced || rowCount === 0
985
+ ? 'unpriced'
986
+ : hasEstimatedPrice
987
+ ? 'estimated'
988
+ : 'configured';
989
+ await runsRepo.update({
990
+ filterByTk: runId,
991
+ values: {
992
+ totalInputTokens: hasKnownUsage ? totalInput : null,
993
+ totalOutputTokens: hasKnownUsage ? totalOutput : null,
994
+ totalTokens: hasKnownUsage ? totalTokens : null,
995
+ totalCost: hasUnpriced || rowCount === 0 ? null : totalCost,
996
+ usageStatus,
997
+ pricingStatus,
998
+ },
999
+ ...(transaction ? { transaction } : {}),
1000
+ });
1001
+ return true;
1002
+ });
1003
+ } catch (error) {
1004
+ this.warn('[TokenTracker] Failed to accumulate run totals', error);
1005
+ return false;
1006
+ }
1007
+ }
1008
+
1009
+ /** Checks configured budgets. Unknown cost is never treated as a free run. */
1010
+ async checkBudget(runId: string | number): Promise<BudgetCheckResult> {
1011
+ try {
1012
+ const repo = this.db.getRepository('agentLoopRuns');
1013
+ if (!repo?.findOne) return { allowed: true };
1014
+
1015
+ const run = await repo.findOne({ filter: { id: runId } });
1016
+ if (!run) return { allowed: true };
1017
+
1018
+ const budgetMaxTokens = Number(read(run, 'budgetMaxTokens') ?? 0);
1019
+ const budgetMaxCost = Number(read(run, 'budgetMaxCost') ?? 0);
1020
+ if (budgetMaxTokens <= 0 && budgetMaxCost <= 0) return { allowed: true };
1021
+
1022
+ const usageStatus = identityPart(read(run, 'usageStatus'));
1023
+ const pricingStatus = identityPart(read(run, 'pricingStatus'));
1024
+ const hasIncompleteSessions = incompleteSessions(run).length > 0;
1025
+ const totalTokens = readNumber(read(run, 'totalTokens'));
1026
+ const totalCost = readNumber(read(run, 'totalCost'));
1027
+ const hasInvocations = (readNumber(read(run, 'invocationCount')) ?? 0) > 0;
1028
+
1029
+ if (
1030
+ budgetMaxTokens > 0 &&
1031
+ (hasIncompleteSessions ||
1032
+ usageStatus === 'partial' ||
1033
+ usageStatus === 'missing' ||
1034
+ (totalTokens === undefined && (usageStatus !== '' || hasInvocations)))
1035
+ ) {
1036
+ return {
1037
+ allowed: false,
1038
+ reason: 'Token usage is unavailable, so this run cannot be checked against its token budget.',
1039
+ };
1040
+ }
1041
+ if (
1042
+ budgetMaxCost > 0 &&
1043
+ (hasIncompleteSessions ||
1044
+ pricingStatus === 'unpriced' ||
1045
+ pricingStatus === 'non_usd' ||
1046
+ (totalCost === undefined && (pricingStatus !== '' || hasInvocations)))
1047
+ ) {
1048
+ return {
1049
+ allowed: false,
1050
+ reason: 'Model pricing is unavailable, so this run cannot be checked against its cost budget.',
1051
+ };
1052
+ }
1053
+ if (budgetMaxTokens > 0 && totalTokens !== undefined && totalTokens >= budgetMaxTokens) {
1054
+ return {
1055
+ allowed: false,
1056
+ reason: `Budget exceeded: ${totalTokens}/${budgetMaxTokens} tokens used. Maximum allowed tokens for this run: ${budgetMaxTokens}.`,
1057
+ };
1058
+ }
1059
+ if (budgetMaxCost > 0 && totalCost !== undefined && totalCost >= budgetMaxCost) {
1060
+ return {
1061
+ allowed: false,
1062
+ reason: `Budget exceeded: $${totalCost.toFixed(4)}/$${budgetMaxCost.toFixed(
1063
+ 4,
1064
+ )} spent. Maximum allowed cost for this run: $${budgetMaxCost}.`,
1065
+ };
1066
+ }
1067
+
1068
+ return { allowed: true };
1069
+ } catch (error) {
1070
+ this.warn('[TokenTracker] Budget check failed, allowing', error);
1071
+ return { allowed: true };
1072
+ }
1073
+ }
1074
+
1075
+ /**
1076
+ * Compatibility API for callers that update an existing span. Missing usage falls back to an
1077
+ * explicit text estimate; zero-token actual usage remains actual and is never re-estimated.
1078
+ */
1079
+ async trackActualUsage(
1080
+ spanId: string | number | undefined,
1081
+ tokenUsage: UsageCounts | null,
1082
+ input: string,
1083
+ output: string,
1084
+ runId?: string | number,
1085
+ ): Promise<void> {
1086
+ if (usageIsValid(tokenUsage)) {
1087
+ await this.trackSpan(spanId, { ...tokenUsage, cost: tokenUsage.cost ?? Number.NaN }, runId);
1088
+ return;
1089
+ }
1090
+ await this.estimateAndTrack(spanId, input, output, runId);
1091
+ }
1092
+
1093
+ /** Stores the legacy text-length estimate explicitly, scoped to an existing span. */
1094
+ async estimateAndTrack(
1095
+ spanId: string | number | undefined,
1096
+ input: string,
1097
+ output: string,
1098
+ runId?: string | number,
1099
+ ): Promise<void> {
1100
+ if (spanId === undefined || spanId === null || spanId === '') return;
1101
+ try {
1102
+ const repo = this.db.getRepository('agentExecutionSpans');
1103
+ if (!repo?.findOne || !repo.update) return;
1104
+ const span = await repo.findOne({ filterByTk: spanId });
1105
+ if (!span) return;
1106
+ const inputTokens = Math.ceil((input || '').length / 4);
1107
+ const outputTokens = Math.ceil((output || '').length / 4);
1108
+ const usage: UsageCounts = {
1109
+ inputTokens,
1110
+ outputTokens,
1111
+ totalTokens: inputTokens + outputTokens,
1112
+ };
1113
+ const resolved = pricingFor({
1114
+ usageIdentity: identityPart(read(span, 'usageIdentity')) || `legacy-span:${spanId}`,
1115
+ sessionId: identityPart(read(span, 'sessionId')),
1116
+ messageId: identityPart(read(span, 'messageId')),
1117
+ usage,
1118
+ model: identityPart(read(span, 'model')) || undefined,
1119
+ provider: identityPart(read(span, 'provider')) || undefined,
1120
+ llmService: identityPart(read(span, 'llmService')) || undefined,
1121
+ source: 'loop_runtime',
1122
+ });
1123
+ await repo.update({
1124
+ filterByTk: spanId,
1125
+ values: {
1126
+ inputTokens,
1127
+ outputTokens,
1128
+ totalTokens: inputTokens + outputTokens,
1129
+ cachedTokens: null,
1130
+ reasoningTokens: null,
1131
+ usageSource: 'estimated',
1132
+ usageOrigin: 'text_length_estimate',
1133
+ cost: resolved.cost,
1134
+ pricingStatus: resolved.cost === null ? 'unpriced' : 'estimated',
1135
+ priceSource: resolved.priceSource,
1136
+ priceCurrency: resolved.snapshot.currency ?? null,
1137
+ priceVersion: resolved.snapshot.version ?? null,
1138
+ priceInputPer1k: resolved.snapshot.inputPer1k ?? null,
1139
+ priceOutputPer1k: resolved.snapshot.outputPer1k ?? null,
1140
+ priceCachedInputPer1k: resolved.snapshot.cachedInputPer1k ?? null,
1141
+ updatedAt: new Date(),
1142
+ },
1143
+ });
1144
+ if (runId != null) await this.accumulateToRun(runId);
1145
+ } catch (error) {
1146
+ this.warn('[TokenTracker] Failed to estimate span tokens', error);
1147
+ }
1148
+ }
1149
+ }
1150
+
1151
+ export { usageEventIdentity };