observability-toolkit-hooks 0.0.0-stage → 1.0.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 (306) hide show
  1. package/CONFIG.md +144 -0
  2. package/LICENSE +95 -0
  3. package/README.md +201 -2
  4. package/dist/handlers/compact.js +38 -0
  5. package/dist/handlers/mcp-status.js +66 -0
  6. package/dist/handlers/notification.js +45 -0
  7. package/dist/handlers/post-tool-agent.js +157 -0
  8. package/dist/handlers/post-tool-changelog-sync.js +148 -0
  9. package/dist/handlers/post-tool-code-structure.js +116 -0
  10. package/dist/handlers/post-tool-edit-ledger.js +15 -0
  11. package/dist/handlers/post-tool-failure.js +83 -0
  12. package/dist/handlers/post-tool-git.js +79 -0
  13. package/dist/handlers/post-tool-mcp.js +105 -0
  14. package/dist/handlers/post-tool-outcome.js +48 -0
  15. package/dist/handlers/post-tool-task-state.js +74 -0
  16. package/dist/handlers/post-tool.js +132 -0
  17. package/dist/handlers/pre-tool-agent.js +192 -0
  18. package/dist/handlers/pre-tool.js +218 -0
  19. package/dist/handlers/session-end.js +39 -0
  20. package/dist/handlers/session-start.js +262 -0
  21. package/dist/handlers/stop-error-reminder.js +195 -0
  22. package/dist/handlers/stop-quality-evaluation.js +58 -0
  23. package/dist/handlers/stop-session-summary.js +62 -0
  24. package/dist/handlers/stop-token-metrics.js +83 -0
  25. package/dist/handlers/stop.js +25 -0
  26. package/dist/handlers/subagent.js +105 -0
  27. package/dist/handlers/tool-event-router.js +39 -0
  28. package/dist/handlers/user-prompt.js +218 -0
  29. package/dist/hook-runner.js +10 -0
  30. package/dist/hook-runner.js.map +7 -0
  31. package/dist/lib/agent/agent-context.js +123 -0
  32. package/dist/lib/agent/agent-evaluations.js +155 -0
  33. package/dist/lib/agent/agent-file-budget.js +65 -0
  34. package/dist/lib/agent/agent-sources.js +165 -0
  35. package/dist/lib/agent/synth-spans.js +51 -0
  36. package/dist/lib/core/bounded-label.js +6 -0
  37. package/dist/lib/core/category-rules.js +11 -0
  38. package/dist/lib/core/child-result.js +19 -0
  39. package/dist/lib/core/config-dir-recovery.js +22 -0
  40. package/dist/lib/core/constants.js +171 -0
  41. package/dist/lib/core/detached-runner.js +55 -0
  42. package/dist/lib/core/file-utils.js +353 -0
  43. package/dist/lib/core/format-utils.js +51 -0
  44. package/dist/lib/core/http-utils.js +74 -0
  45. package/dist/lib/core/http1-fetch.js +14 -0
  46. package/dist/lib/core/identity-key-resolver.js +149 -0
  47. package/dist/lib/core/jsonl-tail.js +207 -0
  48. package/dist/lib/core/load-envrc.js +72 -0
  49. package/dist/lib/core/parsers.js +43 -0
  50. package/dist/lib/core/regex.js +27 -0
  51. package/dist/lib/core/settings-env.js +31 -0
  52. package/dist/lib/core/shell-command.js +122 -0
  53. package/dist/lib/core/units.js +97 -0
  54. package/dist/lib/git/git-cache.js +158 -0
  55. package/dist/lib/git/git-commit.js +189 -0
  56. package/dist/lib/git/git-exec.js +30 -0
  57. package/dist/lib/mcp/mcp-completeness.js +40 -0
  58. package/dist/lib/mcp/mcp-config.js +118 -0
  59. package/dist/lib/mcp/mcp-failure-latch.js +22 -0
  60. package/dist/lib/mcp/mcp-identity-launcher.js +43 -0
  61. package/dist/lib/otel/attributes.js +322 -0
  62. package/dist/lib/otel/evaluation-attrs.js +51 -0
  63. package/dist/lib/otel/file-exporters.js +169 -0
  64. package/dist/lib/otel/host-resource.js +61 -0
  65. package/dist/lib/otel/otel-headers-helper.js +26 -0
  66. package/dist/lib/otel/otel-monitor.js +181 -0
  67. package/dist/lib/otel/otel.js +235 -0
  68. package/dist/lib/otel/otlp-headers.js +101 -0
  69. package/dist/lib/otel/otlp-post.js +122 -0
  70. package/dist/lib/otel/otlp-serialize.js +142 -0
  71. package/dist/lib/otel/otlp-signal.js +2 -0
  72. package/dist/lib/otel/remote-spans.js +142 -0
  73. package/dist/lib/otel/service-identity.js +10 -0
  74. package/dist/lib/otel/telemetry-alerts.js +43 -0
  75. package/dist/lib/otel/token-metrics.js +122 -0
  76. package/dist/lib/otel/trace-context.js +81 -0
  77. package/dist/lib/quality/judge-meta-eval.js +70 -0
  78. package/dist/lib/quality/judge-prompts.js +104 -0
  79. package/dist/lib/quality/judge-providers.js +193 -0
  80. package/dist/lib/quality/judge-transport.js +93 -0
  81. package/dist/lib/quality/llm-judge.js +170 -0
  82. package/dist/lib/quality/quality-budget.js +99 -0
  83. package/dist/lib/quality/quality-degradation.js +156 -0
  84. package/dist/lib/quality/quality-eval-handoff.js +74 -0
  85. package/dist/lib/quality/quality-evaluator.js +178 -0
  86. package/dist/lib/quality/quality-sampler.js +43 -0
  87. package/dist/lib/quality/quality-signals.js +150 -0
  88. package/dist/lib/runtime/categorizers.js +101 -0
  89. package/dist/lib/runtime/hook-input.js +16 -0
  90. package/dist/lib/runtime/hook-output.js +50 -0
  91. package/dist/lib/runtime/output-analyzer.js +160 -0
  92. package/dist/lib/runtime/run-handlers.js +32 -0
  93. package/dist/lib/runtime/tool-input.js +111 -0
  94. package/dist/lib/runtime/tool-output.js +44 -0
  95. package/dist/lib/runtime/unknown-tool.js +32 -0
  96. package/dist/lib/session/edit-ledger.js +29 -0
  97. package/dist/lib/session/forked-skill.js +39 -0
  98. package/dist/lib/session/handoffs.js +77 -0
  99. package/dist/lib/session/session-state.js +169 -0
  100. package/dist/lib/session/skill-rules.js +196 -0
  101. package/dist/lib/session/task-tracker.js +83 -0
  102. package/dist/lib/shipper/shipper-credentials.js +38 -0
  103. package/dist/lib/shipper/shipper-cursor.js +89 -0
  104. package/dist/lib/shipper/shipper-status.js +174 -0
  105. package/dist/lib/shipper/span-shipper.js +272 -0
  106. package/dist/lib/shipper/telemetry-shipper.js +39 -0
  107. package/dist/lib/transcript/agent-transcript-metrics.js +34 -0
  108. package/dist/lib/transcript/context-breakdown.js +134 -0
  109. package/dist/lib/transcript/context-history.js +69 -0
  110. package/dist/lib/transcript/context-tracker.js +226 -0
  111. package/dist/lib/transcript/message-count.js +49 -0
  112. package/dist/lib/transcript/model-ids.js +36 -0
  113. package/dist/lib/transcript/model-pricing.js +153 -0
  114. package/dist/lib/transcript/token-metrics-checkpoint.js +152 -0
  115. package/dist/lib/transcript/tool-call-durations.js +64 -0
  116. package/dist/lib/transcript/transcript-entry.js +67 -0
  117. package/dist/lib/transcript/transcript-fold.js +130 -0
  118. package/dist/lib/transcript/transcript-layout.js +39 -0
  119. package/dist/lib/transcript/transcript-parser.js +117 -0
  120. package/dist/runner/agent-context-4XTCLMLZ.js +23 -0
  121. package/dist/runner/agent-context-4XTCLMLZ.js.map +7 -0
  122. package/dist/runner/agent-file-budget-Q33ESBBE.js +68 -0
  123. package/dist/runner/agent-file-budget-Q33ESBBE.js.map +7 -0
  124. package/dist/runner/agent-transcript-metrics-W5CZZFMI.js +39 -0
  125. package/dist/runner/agent-transcript-metrics-W5CZZFMI.js.map +7 -0
  126. package/dist/runner/chunk-2NTNAJZE.js +49 -0
  127. package/dist/runner/chunk-2NTNAJZE.js.map +7 -0
  128. package/dist/runner/chunk-4KWBQTTG.js +78 -0
  129. package/dist/runner/chunk-4KWBQTTG.js.map +7 -0
  130. package/dist/runner/chunk-52RY6LQT.js +699 -0
  131. package/dist/runner/chunk-52RY6LQT.js.map +7 -0
  132. package/dist/runner/chunk-7OM5CYES.js +8695 -0
  133. package/dist/runner/chunk-7OM5CYES.js.map +7 -0
  134. package/dist/runner/chunk-7PEOKGYR.js +1568 -0
  135. package/dist/runner/chunk-7PEOKGYR.js.map +7 -0
  136. package/dist/runner/chunk-AGSGKELQ.js +126 -0
  137. package/dist/runner/chunk-AGSGKELQ.js.map +7 -0
  138. package/dist/runner/chunk-AVM7PJFW.js +12 -0
  139. package/dist/runner/chunk-AVM7PJFW.js.map +7 -0
  140. package/dist/runner/chunk-C3WHUMU5.js +178 -0
  141. package/dist/runner/chunk-C3WHUMU5.js.map +7 -0
  142. package/dist/runner/chunk-DGB4NSSD.js +157 -0
  143. package/dist/runner/chunk-DGB4NSSD.js.map +7 -0
  144. package/dist/runner/chunk-DNSTWC26.js +151 -0
  145. package/dist/runner/chunk-DNSTWC26.js.map +7 -0
  146. package/dist/runner/chunk-FDJJ3TYU.js +449 -0
  147. package/dist/runner/chunk-FDJJ3TYU.js.map +7 -0
  148. package/dist/runner/chunk-FGKYDQHZ.js +137 -0
  149. package/dist/runner/chunk-FGKYDQHZ.js.map +7 -0
  150. package/dist/runner/chunk-GG2I4TGI.js +582 -0
  151. package/dist/runner/chunk-GG2I4TGI.js.map +7 -0
  152. package/dist/runner/chunk-GNNKUMRF.js +60 -0
  153. package/dist/runner/chunk-GNNKUMRF.js.map +7 -0
  154. package/dist/runner/chunk-I7TD2QVR.js +118 -0
  155. package/dist/runner/chunk-I7TD2QVR.js.map +7 -0
  156. package/dist/runner/chunk-IJ4SLUBV.js +78 -0
  157. package/dist/runner/chunk-IJ4SLUBV.js.map +7 -0
  158. package/dist/runner/chunk-IY7AP7NA.js +32 -0
  159. package/dist/runner/chunk-IY7AP7NA.js.map +7 -0
  160. package/dist/runner/chunk-J3F3Z3EQ.js +177 -0
  161. package/dist/runner/chunk-J3F3Z3EQ.js.map +7 -0
  162. package/dist/runner/chunk-JLEO5OHU.js +104 -0
  163. package/dist/runner/chunk-JLEO5OHU.js.map +7 -0
  164. package/dist/runner/chunk-JRNNLOPR.js +168 -0
  165. package/dist/runner/chunk-JRNNLOPR.js.map +7 -0
  166. package/dist/runner/chunk-KGSA5JYP.js +82 -0
  167. package/dist/runner/chunk-KGSA5JYP.js.map +7 -0
  168. package/dist/runner/chunk-LBCZAYFR.js +125 -0
  169. package/dist/runner/chunk-LBCZAYFR.js.map +7 -0
  170. package/dist/runner/chunk-LHWRXY2G.js +41 -0
  171. package/dist/runner/chunk-LHWRXY2G.js.map +7 -0
  172. package/dist/runner/chunk-LQ2LGUYJ.js +41 -0
  173. package/dist/runner/chunk-LQ2LGUYJ.js.map +7 -0
  174. package/dist/runner/chunk-LYY6RCIE.js +158 -0
  175. package/dist/runner/chunk-LYY6RCIE.js.map +7 -0
  176. package/dist/runner/chunk-M4R4QIQH.js +41 -0
  177. package/dist/runner/chunk-M4R4QIQH.js.map +7 -0
  178. package/dist/runner/chunk-MC75VXMX.js +207 -0
  179. package/dist/runner/chunk-MC75VXMX.js.map +7 -0
  180. package/dist/runner/chunk-NKZU4RRG.js +104 -0
  181. package/dist/runner/chunk-NKZU4RRG.js.map +7 -0
  182. package/dist/runner/chunk-PJHWHJ3K.js +56 -0
  183. package/dist/runner/chunk-PJHWHJ3K.js.map +7 -0
  184. package/dist/runner/chunk-RIGVYJ2O.js +114 -0
  185. package/dist/runner/chunk-RIGVYJ2O.js.map +7 -0
  186. package/dist/runner/chunk-RWRGC7ZK.js +93 -0
  187. package/dist/runner/chunk-RWRGC7ZK.js.map +7 -0
  188. package/dist/runner/chunk-SRMAJQMV.js +54 -0
  189. package/dist/runner/chunk-SRMAJQMV.js.map +7 -0
  190. package/dist/runner/chunk-TRMFD36J.js +47 -0
  191. package/dist/runner/chunk-TRMFD36J.js.map +7 -0
  192. package/dist/runner/chunk-U4IOZYQ3.js +21 -0
  193. package/dist/runner/chunk-U4IOZYQ3.js.map +7 -0
  194. package/dist/runner/chunk-UEXDE3WP.js +83 -0
  195. package/dist/runner/chunk-UEXDE3WP.js.map +7 -0
  196. package/dist/runner/chunk-UW3GQZSM.js +50 -0
  197. package/dist/runner/chunk-UW3GQZSM.js.map +7 -0
  198. package/dist/runner/chunk-V2GSP6VR.js +46 -0
  199. package/dist/runner/chunk-V2GSP6VR.js.map +7 -0
  200. package/dist/runner/chunk-VOV4Y5VU.js +81 -0
  201. package/dist/runner/chunk-VOV4Y5VU.js.map +7 -0
  202. package/dist/runner/chunk-VT5T6OEI.js +65 -0
  203. package/dist/runner/chunk-VT5T6OEI.js.map +7 -0
  204. package/dist/runner/chunk-VUYVFWIN.js +12 -0
  205. package/dist/runner/chunk-VUYVFWIN.js.map +7 -0
  206. package/dist/runner/chunk-VVGOPPEN.js +36 -0
  207. package/dist/runner/chunk-VVGOPPEN.js.map +7 -0
  208. package/dist/runner/chunk-VXFSLM6P.js +14 -0
  209. package/dist/runner/chunk-VXFSLM6P.js.map +7 -0
  210. package/dist/runner/chunk-W3EK7JUT.js +26125 -0
  211. package/dist/runner/chunk-W3EK7JUT.js.map +7 -0
  212. package/dist/runner/chunk-WJHNCOUF.js +52 -0
  213. package/dist/runner/chunk-WJHNCOUF.js.map +7 -0
  214. package/dist/runner/chunk-WU7ANGCW.js +269 -0
  215. package/dist/runner/chunk-WU7ANGCW.js.map +7 -0
  216. package/dist/runner/chunk-X7XLMSZX.js +44 -0
  217. package/dist/runner/chunk-X7XLMSZX.js.map +7 -0
  218. package/dist/runner/chunk-XSO3B4QN.js +124 -0
  219. package/dist/runner/chunk-XSO3B4QN.js.map +7 -0
  220. package/dist/runner/chunk-YGFN3LN2.js +174 -0
  221. package/dist/runner/chunk-YGFN3LN2.js.map +7 -0
  222. package/dist/runner/chunk-YHYDBLVB.js +33 -0
  223. package/dist/runner/chunk-YHYDBLVB.js.map +7 -0
  224. package/dist/runner/compact-36NP3PKT.js +60 -0
  225. package/dist/runner/compact-36NP3PKT.js.map +7 -0
  226. package/dist/runner/getMachineId-bsd-AGENNHN6.js +42 -0
  227. package/dist/runner/getMachineId-bsd-AGENNHN6.js.map +7 -0
  228. package/dist/runner/getMachineId-bsd-I5WZGCL4.js +33 -0
  229. package/dist/runner/getMachineId-bsd-I5WZGCL4.js.map +7 -0
  230. package/dist/runner/getMachineId-bsd-ZXK225P7.js +33 -0
  231. package/dist/runner/getMachineId-bsd-ZXK225P7.js.map +7 -0
  232. package/dist/runner/getMachineId-darwin-47GDLEXL.js +42 -0
  233. package/dist/runner/getMachineId-darwin-47GDLEXL.js.map +7 -0
  234. package/dist/runner/getMachineId-darwin-5CRLMDD6.js +33 -0
  235. package/dist/runner/getMachineId-darwin-5CRLMDD6.js.map +7 -0
  236. package/dist/runner/getMachineId-darwin-ADG4I32N.js +33 -0
  237. package/dist/runner/getMachineId-darwin-ADG4I32N.js.map +7 -0
  238. package/dist/runner/getMachineId-linux-5KVS3T2M.js +27 -0
  239. package/dist/runner/getMachineId-linux-5KVS3T2M.js.map +7 -0
  240. package/dist/runner/getMachineId-linux-GDFB5GSO.js +34 -0
  241. package/dist/runner/getMachineId-linux-GDFB5GSO.js.map +7 -0
  242. package/dist/runner/getMachineId-linux-NQMWCRO3.js +27 -0
  243. package/dist/runner/getMachineId-linux-NQMWCRO3.js.map +7 -0
  244. package/dist/runner/getMachineId-unsupported-5PFIGMVX.js +18 -0
  245. package/dist/runner/getMachineId-unsupported-5PFIGMVX.js.map +7 -0
  246. package/dist/runner/getMachineId-unsupported-DW27K3ZX.js +18 -0
  247. package/dist/runner/getMachineId-unsupported-DW27K3ZX.js.map +7 -0
  248. package/dist/runner/getMachineId-unsupported-XV3FHTHD.js +25 -0
  249. package/dist/runner/getMachineId-unsupported-XV3FHTHD.js.map +7 -0
  250. package/dist/runner/getMachineId-win-5JVMW3EI.js +44 -0
  251. package/dist/runner/getMachineId-win-5JVMW3EI.js.map +7 -0
  252. package/dist/runner/getMachineId-win-SNESQF7R.js +35 -0
  253. package/dist/runner/getMachineId-win-SNESQF7R.js.map +7 -0
  254. package/dist/runner/getMachineId-win-UJYHSBM2.js +35 -0
  255. package/dist/runner/getMachineId-win-UJYHSBM2.js.map +7 -0
  256. package/dist/runner/git-commit-BA53DOJQ.js +30 -0
  257. package/dist/runner/git-commit-BA53DOJQ.js.map +7 -0
  258. package/dist/runner/hook-runner-JHH6PGKE.js +220 -0
  259. package/dist/runner/hook-runner-JHH6PGKE.js.map +7 -0
  260. package/dist/runner/judge-transport-R4TF5LEH.js +91 -0
  261. package/dist/runner/judge-transport-R4TF5LEH.js.map +7 -0
  262. package/dist/runner/mcp-status-QEUH2KGX.js +89 -0
  263. package/dist/runner/mcp-status-QEUH2KGX.js.map +7 -0
  264. package/dist/runner/notification-FKMBCSXF.js +69 -0
  265. package/dist/runner/notification-FKMBCSXF.js.map +7 -0
  266. package/dist/runner/post-tool-3MRHTBKH.js +192 -0
  267. package/dist/runner/post-tool-3MRHTBKH.js.map +7 -0
  268. package/dist/runner/post-tool-agent-BB34MNHI.js +370 -0
  269. package/dist/runner/post-tool-agent-BB34MNHI.js.map +7 -0
  270. package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js +147 -0
  271. package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js.map +7 -0
  272. package/dist/runner/post-tool-code-structure-LE7J2SC2.js +130 -0
  273. package/dist/runner/post-tool-code-structure-LE7J2SC2.js.map +7 -0
  274. package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js +30 -0
  275. package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js.map +7 -0
  276. package/dist/runner/post-tool-failure-XTH2I2Z7.js +111 -0
  277. package/dist/runner/post-tool-failure-XTH2I2Z7.js.map +7 -0
  278. package/dist/runner/post-tool-git-E46HZGZO.js +94 -0
  279. package/dist/runner/post-tool-git-E46HZGZO.js.map +7 -0
  280. package/dist/runner/post-tool-mcp-AMCDY5GH.js +144 -0
  281. package/dist/runner/post-tool-mcp-AMCDY5GH.js.map +7 -0
  282. package/dist/runner/post-tool-task-state-TLDOI33H.js +100 -0
  283. package/dist/runner/post-tool-task-state-TLDOI33H.js.map +7 -0
  284. package/dist/runner/pre-tool-SQE2FZQO.js +245 -0
  285. package/dist/runner/pre-tool-SQE2FZQO.js.map +7 -0
  286. package/dist/runner/pre-tool-agent-OZUPVFUI.js +218 -0
  287. package/dist/runner/pre-tool-agent-OZUPVFUI.js.map +7 -0
  288. package/dist/runner/quality-evaluator-XYNDKDRG.js +901 -0
  289. package/dist/runner/quality-evaluator-XYNDKDRG.js.map +7 -0
  290. package/dist/runner/session-end-3MJTDLLA.js +57 -0
  291. package/dist/runner/session-end-3MJTDLLA.js.map +7 -0
  292. package/dist/runner/session-start-5ZMCLKBS.js +352 -0
  293. package/dist/runner/session-start-5ZMCLKBS.js.map +7 -0
  294. package/dist/runner/shipper-status-MADX6SPG.js +37 -0
  295. package/dist/runner/shipper-status-MADX6SPG.js.map +7 -0
  296. package/dist/runner/span-shipper-4HQDHC47.js +3408 -0
  297. package/dist/runner/span-shipper-4HQDHC47.js.map +7 -0
  298. package/dist/runner/stop-RTKSIYJV.js +596 -0
  299. package/dist/runner/stop-RTKSIYJV.js.map +7 -0
  300. package/dist/runner/subagent-CBCG4OLZ.js +116 -0
  301. package/dist/runner/subagent-CBCG4OLZ.js.map +7 -0
  302. package/dist/runner/token-metrics-AD2RAFGM.js +31 -0
  303. package/dist/runner/token-metrics-AD2RAFGM.js.map +7 -0
  304. package/dist/runner/user-prompt-T5NZ2UJD.js +376 -0
  305. package/dist/runner/user-prompt-T5NZ2UJD.js.map +7 -0
  306. package/package.json +70 -5
@@ -0,0 +1,174 @@
1
+ /**
2
+ * The shipper's diagnostic sink (OBP8): it runs detached with no stdio and no OTel
3
+ * SDK, so this one overwritten status record is its only channel, and
4
+ * `handlers/session-start.ts` is its reader. `lastFailure` persists across healthy
5
+ * runs so "broke once and recovered" differs from "never worked", and `failureTally`
6
+ * counts each kind of failure so "once" differs from "every tenth run". Writes are
7
+ * last-writer-wins; a torn read reads as missing, which the next flush rewrites and
8
+ * which restarts the tally.
9
+ */
10
+ import { join } from 'node:path';
11
+ import { ELLIPSIS, TELEMETRY_DIR } from '../core/constants.js';
12
+ import { loadJson, writeJson } from '../core/file-utils.js';
13
+ import { errorSummary, truncate } from '../core/format-utils.js';
14
+ import { errorCauseChain, errorCode } from '../core/http-utils.js';
15
+ import { DURATION_MS } from '../core/units.js';
16
+ /** Also holds `cursor.json`. */
17
+ export const SHIPPER_CTX_DIRNAME = 'shipper-ctx';
18
+ const STATUS_FILENAME = 'status.json';
19
+ /** Written by the spawner (child never started), `shipTelemetry` (run happened) and hook-runner's ship branch (run threw). */
20
+ const SHIPPER_OUTCOMES = [
21
+ 'ok',
22
+ /** Delivered, but unparseable lines were consumed and lost; healthy, but visible. */
23
+ 'ok-with-discards',
24
+ 'export-failed',
25
+ 'no-endpoint',
26
+ 'no-auth',
27
+ /** `dist/hook-runner.js` missing: hooks never built. */
28
+ 'no-runner',
29
+ 'spawn-failed',
30
+ 'crashed',
31
+ /** Another run holds the lock; healthy. */
32
+ 'busy',
33
+ ];
34
+ /** Written when the lock is held, so it marks a run that did not happen. */
35
+ const NOT_A_RUN_OUTCOME = 'busy';
36
+ const HEALTHY_OUTCOMES = ['ok', 'ok-with-discards', 'busy'];
37
+ export function isShipperHealthy(outcome) {
38
+ return HEALTHY_OUTCOMES.includes(outcome);
39
+ }
40
+ export function addCount(counts, signal, n) {
41
+ counts[signal] = (counts[signal] ?? 0) + n;
42
+ }
43
+ export function hasCounts(counts) {
44
+ return Object.keys(counts).length > 0;
45
+ }
46
+ export function sumCounts(counts) {
47
+ return Object.values(counts).reduce((sum, n) => sum + n, 0);
48
+ }
49
+ function presentSignalCounts(source) {
50
+ return {
51
+ ...(source.shippedBySignal ? { shippedBySignal: source.shippedBySignal } : {}),
52
+ ...(source.discardedBySignal ? { discardedBySignal: source.discardedBySignal } : {}),
53
+ ...(source.withheldBySignal ? { withheldBySignal: source.withheldBySignal } : {}),
54
+ };
55
+ }
56
+ export function shipperStatusPath(telemetryDir = TELEMETRY_DIR) {
57
+ return join(telemetryDir, SHIPPER_CTX_DIRNAME, STATUS_FILENAME);
58
+ }
59
+ const MAX_DETAIL_LENGTH = 200;
60
+ export function shipperErrorDetail(error) {
61
+ if (!(error instanceof Error))
62
+ return truncateDetail(String(error));
63
+ // undici reports every transport failure as `TypeError: fetch failed`; the actionable part is on `cause`.
64
+ const { cause } = error;
65
+ const causeMessage = cause instanceof Error ? cause.message : undefined;
66
+ const message = errorSummary(error);
67
+ return truncateDetail(causeMessage ? `${message} (${causeMessage})` : message);
68
+ }
69
+ const UNKNOWN_ERROR_KIND = 'unknown';
70
+ /** The innermost cause's code or name, since undici's wrapper is the same `TypeError` for every transport failure. */
71
+ export function shipperErrorKind(error) {
72
+ if (!(error instanceof Error))
73
+ return UNKNOWN_ERROR_KIND;
74
+ let innermost = error;
75
+ for (const link of errorCauseChain(error))
76
+ innermost = link;
77
+ return errorCode(innermost) ?? innermost.name;
78
+ }
79
+ function tallyKey(update) {
80
+ return update.failureKind ? `${update.outcome}: ${update.failureKind}` : update.outcome;
81
+ }
82
+ function nextFailureTally(previous, update, at) {
83
+ if (update.outcome === NOT_A_RUN_OUTCOME)
84
+ return previous;
85
+ const byKind = { ...previous?.byKind };
86
+ if (!isShipperHealthy(update.outcome)) {
87
+ const key = tallyKey(update);
88
+ const seen = byKind[key];
89
+ byKind[key] = { count: (seen?.count ?? 0) + 1, firstAt: seen?.firstAt ?? at };
90
+ }
91
+ return { since: previous?.since ?? at, runs: (previous?.runs ?? 0) + 1, byKind };
92
+ }
93
+ function parseFailureTally(raw) {
94
+ const tally = raw;
95
+ if (!tally || typeof tally.since !== 'string')
96
+ return undefined;
97
+ if (!Number.isSafeInteger(tally.runs) || tally.runs < 0)
98
+ return undefined;
99
+ if (!tally.byKind || typeof tally.byKind !== 'object' || Array.isArray(tally.byKind))
100
+ return undefined;
101
+ const byKind = Object.fromEntries(Object.entries(tally.byKind).filter((pair) => typeof pair[1]?.count === 'number' && typeof pair[1].firstAt === 'string'));
102
+ return { since: tally.since, runs: tally.runs, byKind };
103
+ }
104
+ function truncateDetail(message) {
105
+ return truncate(message, MAX_DETAIL_LENGTH, ELLIPSIS);
106
+ }
107
+ /** Never throws: diagnostics must not become a failure mode of the thing they diagnose. */
108
+ export function recordShipperStatus(update, telemetryDir = TELEMETRY_DIR) {
109
+ try {
110
+ const at = new Date().toISOString();
111
+ const previous = readShipperStatus(telemetryDir);
112
+ const status = {
113
+ updatedAt: at,
114
+ outcome: update.outcome,
115
+ shipped: update.shipped ?? 0,
116
+ ...presentSignalCounts(update),
117
+ ...(update.detail ? { detail: update.detail } : {}),
118
+ ...(update.retriedSocketErrors ? { retriedSocketErrors: update.retriedSocketErrors } : {}),
119
+ };
120
+ const lastFailure = isShipperHealthy(update.outcome)
121
+ ? previous?.lastFailure
122
+ : { at, outcome: update.outcome, ...(update.detail ? { detail: update.detail } : {}) };
123
+ if (lastFailure)
124
+ status.lastFailure = lastFailure;
125
+ const failureTally = nextFailureTally(previous?.failureTally, update, at);
126
+ if (failureTally)
127
+ status.failureTally = failureTally;
128
+ writeJson(shipperStatusPath(telemetryDir), status, true, { silent: true });
129
+ }
130
+ catch {
131
+ // See above.
132
+ }
133
+ }
134
+ /** Age at which a lock-blocked run reports `busy` over the last status, so a stuck holder cannot leave a stale failure on screen. */
135
+ const STATUS_STALE_MS = DURATION_MS.FIVE_MINUTES;
136
+ const LOCK_HELD_DETAIL = 'another run holds the shipper lock';
137
+ /** The lock holder records its own outcome, so a fresh record is left alone. */
138
+ export function recordShipperBusy(telemetryDir = TELEMETRY_DIR) {
139
+ const previous = readShipperStatus(telemetryDir);
140
+ if (previous && Date.now() - Date.parse(previous.updatedAt) > STATUS_STALE_MS) {
141
+ recordShipperStatus({ outcome: 'busy', shipped: 0, detail: LOCK_HELD_DETAIL }, telemetryDir);
142
+ }
143
+ }
144
+ /** The spawner and the shipper refuse the same two states; a skip is recorded before it is returned. */
145
+ export function shipPreflight({ endpoint, hasAuth }, telemetryDir = TELEMETRY_DIR) {
146
+ if (endpoint && hasAuth())
147
+ return { endpoint };
148
+ const skipped = endpoint ? 'no-auth' : 'no-endpoint';
149
+ recordShipperStatus({ outcome: skipped }, telemetryDir);
150
+ return { skipped };
151
+ }
152
+ export function readShipperStatus(telemetryDir = TELEMETRY_DIR) {
153
+ const parsed = loadJson(shipperStatusPath(telemetryDir));
154
+ if (!parsed || typeof parsed.updatedAt !== 'string')
155
+ return null;
156
+ if (!SHIPPER_OUTCOMES.includes(parsed.outcome))
157
+ return null;
158
+ const failureTally = parseFailureTally(parsed.failureTally);
159
+ return {
160
+ updatedAt: parsed.updatedAt,
161
+ outcome: parsed.outcome,
162
+ shipped: typeof parsed.shipped === 'number' ? parsed.shipped : 0,
163
+ ...presentSignalCounts(parsed),
164
+ ...(typeof parsed.detail === 'string' ? { detail: parsed.detail } : {}),
165
+ ...(typeof parsed.retriedSocketErrors === 'number' ? { retriedSocketErrors: parsed.retriedSocketErrors } : {}),
166
+ ...(parsed.lastFailure ? { lastFailure: parsed.lastFailure } : {}),
167
+ ...(failureTally ? { failureTally } : {}),
168
+ };
169
+ }
170
+ /** `updatedAt` included: the record is rewritten only when a flush is attempted, so a stale timestamp means no flush ran. */
171
+ export function formatShipperWarning(status) {
172
+ const detail = status.detail ? `: ${status.detail}` : '';
173
+ return `Telemetry: not shipping — ${status.outcome}${detail} (last run ${status.updatedAt})`;
174
+ }
@@ -0,0 +1,272 @@
1
+ /**
2
+ * Detached shipper (`hook-runner ship-telemetry`): telemetry JSONL → OTLP, by
3
+ * signal. A cursor file holds a byte offset per file so each run ships only the
4
+ * delta (H11); a proper-lockfile lock makes concurrent runs a no-op; records are
5
+ * serialized by otlp-serialize.ts and POSTed by otlp-post.ts.
6
+ */
7
+ import { existsSync, writeFileSync } from 'node:fs';
8
+ import { dirname, join } from 'node:path';
9
+ import { lockSync } from 'proper-lockfile';
10
+ import { SHIPPER_LIMITS, TELEMETRY_DIR } from '../core/constants.js';
11
+ import { ensureDirExists } from '../core/file-utils.js';
12
+ import { bearerHeaders } from '../core/http-utils.js';
13
+ import { readMappedKey, resolveKeySecretName } from '../core/identity-key-resolver.js';
14
+ import { readBoundedLines } from '../core/jsonl-tail.js';
15
+ import { resolveOtlpEndpoint } from '../core/settings-env.js';
16
+ import { TIME_MS } from '../core/units.js';
17
+ import { pruneGitCache } from '../git/git-cache.js';
18
+ import { describeOtlpCredentialConflict, hasOtlpAuth } from '../otel/otlp-headers.js';
19
+ import { otlpPathFor, postOtlpBodies } from '../otel/otlp-post.js';
20
+ import { isStoredRecord, recordsCarried, serializeBatch } from '../otel/otlp-serialize.js';
21
+ import { pruneSessionState } from '../session/session-state.js';
22
+ import { createCredentialResolver, keyRouteOf, } from './shipper-credentials.js';
23
+ import { candidateFiles, cursorPath as shipperCursorPath, loadCursor, saveCursor, } from './shipper-cursor.js';
24
+ import { addCount, hasCounts, recordShipperBusy, recordShipperStatus, shipPreflight, shipperErrorDetail, shipperErrorKind, sumCounts, } from './shipper-status.js';
25
+ /** The terminator `lineBytes` counts; an aged file's unterminated last line is overcounted by it, harmlessly. */
26
+ const NEWLINE_BYTES = 1;
27
+ /** A run is normally <10 s. */
28
+ const LOCK_STALE_MS = TIME_MS.MINUTE;
29
+ function fitsBatch(batch, route, record) {
30
+ return batch.route === route &&
31
+ batch.records.length < SHIPPER_LIMITS.MAX_RECORDS_PER_BATCH &&
32
+ batch.bytes + record.lineBytes <= SHIPPER_LIMITS.MAX_BYTES_PER_POST;
33
+ }
34
+ /**
35
+ * One route per batch, in file order, so advancing the cursor to a batch's last record never skips one.
36
+ * Each batch is one POST, so it is also capped by count and source bytes.
37
+ */
38
+ function routeBatches(records) {
39
+ const batches = [];
40
+ for (const r of records) {
41
+ const route = keyRouteOf(r.record);
42
+ const last = batches.at(-1);
43
+ if (last && fitsBatch(last, route, r)) {
44
+ last.records.push(r);
45
+ last.bytes += r.lineBytes;
46
+ }
47
+ else {
48
+ batches.push({ route, records: [r], bytes: r.lineBytes });
49
+ }
50
+ }
51
+ return batches;
52
+ }
53
+ /**
54
+ * `discarded` counts dropped non-empty lines; their bytes are still consumed (a
55
+ * cursor refusing malformed content would stall forever), so the count is the
56
+ * only trace a record shape drifting from `isStoredRecord` leaves (OTEL5-11).
57
+ * An aged file stopped growing, so its unterminated last line is read as a line
58
+ * too; otherwise its cursor would sit before it forever (SHIP5). A line over
59
+ * `MAX_BYTES_PER_LINE` is discarded unread and the read resumes behind it.
60
+ */
61
+ function readNewRecords(filePath, start, signal, aged = false) {
62
+ const { lines, consumedEnd, skippedOversized } = readBoundedLines(filePath, start, {
63
+ windowBytes: SHIPPER_LIMITS.MAX_BYTES_PER_RUN,
64
+ maxLineBytes: SHIPPER_LIMITS.MAX_BYTES_PER_LINE,
65
+ eofTerminates: aged,
66
+ });
67
+ let discarded = skippedOversized;
68
+ const records = [];
69
+ for (const { text, endOffset } of lines) {
70
+ const lineBytes = Buffer.byteLength(text) + NEWLINE_BYTES;
71
+ try {
72
+ const record = JSON.parse(text);
73
+ if (isStoredRecord(signal, record)) {
74
+ records.push({ record, endOffset, lineBytes });
75
+ }
76
+ else {
77
+ discarded++;
78
+ }
79
+ }
80
+ catch {
81
+ discarded++;
82
+ }
83
+ }
84
+ return { records, consumedEnd, discarded };
85
+ }
86
+ const NOTHING_TO_SEND = 'empty batch';
87
+ /** A status code or error name, never a header value; the status file is the only channel that reaches a person. */
88
+ function postFailureDetail(outcome) {
89
+ switch (outcome.reason) {
90
+ case 'empty-batch':
91
+ return NOTHING_TO_SEND;
92
+ case 'rejected':
93
+ return `HTTP ${outcome.statusCode}`;
94
+ case 'threw':
95
+ return shipperErrorDetail(outcome.error);
96
+ }
97
+ }
98
+ function postFailure(signal, outcome) {
99
+ const detail = postFailureDetail(outcome);
100
+ return {
101
+ detail: `${signal} ${detail}`,
102
+ kind: outcome.reason === 'threw' ? shipperErrorKind(outcome.error) : detail,
103
+ };
104
+ }
105
+ /** A skip is recorded before it is returned. */
106
+ function resolveShipTarget(opts, telemetryDir) {
107
+ const overrideHeaders = opts.apiKey ? bearerHeaders(opts.apiKey) : undefined;
108
+ const preflight = shipPreflight({
109
+ // OTEL_* is stripped from hook processes, so this reads settings.json; the shipper
110
+ // is the sole producer of traces, so a missing endpoint silently drops them.
111
+ endpoint: opts.endpoint ?? resolveOtlpEndpoint(),
112
+ // The spawn guard in `telemetry-shipper.ts` reads the identity map where this reads the caller's key sources.
113
+ hasAuth: () => Boolean(overrideHeaders ?? opts.keyForRef) || hasOtlpAuth(),
114
+ }, telemetryDir);
115
+ if ('skipped' in preflight)
116
+ return { shipped: 0, skipped: preflight.skipped };
117
+ const credentialConflict = describeOtlpCredentialConflict();
118
+ if (credentialConflict) {
119
+ console.warn(`[span-shipper] ${credentialConflict}`);
120
+ }
121
+ return { endpoint: preflight.endpoint, overrideHeaders };
122
+ }
123
+ /** A release that never throws, or `undefined` when a concurrent run holds the lock. */
124
+ function acquireShipperLock(telemetryDir, cursorPath) {
125
+ try {
126
+ ensureDirExists(dirname(cursorPath));
127
+ if (!existsSync(cursorPath))
128
+ writeFileSync(cursorPath, '', { flag: 'wx' });
129
+ const release = lockSync(cursorPath, { stale: LOCK_STALE_MS });
130
+ return () => {
131
+ try {
132
+ release();
133
+ }
134
+ catch {
135
+ // Already released or compromised.
136
+ }
137
+ };
138
+ }
139
+ catch {
140
+ recordShipperBusy(telemetryDir);
141
+ return undefined;
142
+ }
143
+ }
144
+ /** Stops at the first failure. */
145
+ async function shipRecords(run, file, signal, records) {
146
+ const url = `${run.endpoint}${otlpPathFor(signal)}`;
147
+ const consumePrefix = (tally, batch, count) => {
148
+ const last = batch[count - 1];
149
+ if (!last)
150
+ return;
151
+ addCount(tally, signal, count);
152
+ run.cursor[file] = last.endOffset;
153
+ };
154
+ for (const { route, records: batch } of routeBatches(records)) {
155
+ // eslint-disable-next-line no-await-in-loop -- credentials resolve per route batch, in cursor order
156
+ const credential = await run.credentialFor(route, signal);
157
+ if ('withhold' in credential) {
158
+ consumePrefix(run.withheldBySignal, batch, batch.length);
159
+ continue;
160
+ }
161
+ if ('missing' in credential)
162
+ return { detail: `${signal} ${credential.missing}` };
163
+ const bodies = serializeBatch(signal, batch.map((r) => r.record));
164
+ // eslint-disable-next-line no-await-in-loop -- batches post in cursor order so a failure leaves the cursor at the delivered prefix
165
+ const outcome = await postOtlpBodies({ url, headers: credential.headers, bodies: bodies.map((b) => b.bytes) });
166
+ run.retriedSocketErrors += outcome.retriedSocketErrors ?? 0;
167
+ // A failed POST keeps the records its delivered bodies carried.
168
+ const landed = outcome.delivered
169
+ ? batch.length
170
+ : recordsCarried(bodies.slice(0, outcome.deliveredPrefix));
171
+ consumePrefix(run.shippedBySignal, batch, landed);
172
+ if (!outcome.delivered)
173
+ return postFailure(signal, outcome);
174
+ }
175
+ return undefined;
176
+ }
177
+ async function shipFile(run, { file, signal, start, aged }) {
178
+ let read;
179
+ try {
180
+ read = readNewRecords(join(run.telemetryDir, file), start, signal, aged);
181
+ }
182
+ catch (error) {
183
+ // The cursor holds and the other files still ship.
184
+ return { detail: `${signal} cannot read ${file}: ${shipperErrorDetail(error)}`, kind: shipperErrorKind(error) };
185
+ }
186
+ const { records, consumedEnd, discarded } = read;
187
+ if (discarded > 0)
188
+ addCount(run.discardedBySignal, signal, discarded);
189
+ const failure = await shipRecords(run, file, signal, records);
190
+ if (failure)
191
+ return failure;
192
+ if (records.length > 0 || discarded === 0 || aged) {
193
+ // Consume the tail only when something was sent or the window held no non-empty
194
+ // lines; otherwise unsent records would be consumed with nothing behind them (OTEL5-11).
195
+ // An aged file stopped growing, so no valid record will ever follow its junk (SHIP5).
196
+ run.cursor[file] = consumedEnd;
197
+ return undefined;
198
+ }
199
+ // Re-reported every run; the cursor holds, so the records stay recoverable.
200
+ return { detail: `${signal} ${discarded} unsendable record(s) in ${file}` };
201
+ }
202
+ /** The outcome, not the count, separates "nothing pending" from "rejected": earlier batches may have landed. */
203
+ function completedRunStatus(run) {
204
+ const shipped = sumCounts(run.shippedBySignal);
205
+ const perSignal = {
206
+ shippedBySignal: run.shippedBySignal,
207
+ ...(hasCounts(run.discardedBySignal) ? { discardedBySignal: run.discardedBySignal } : {}),
208
+ ...(hasCounts(run.withheldBySignal) ? { withheldBySignal: run.withheldBySignal } : {}),
209
+ retriedSocketErrors: run.retriedSocketErrors,
210
+ };
211
+ return run.failure
212
+ ? { outcome: 'export-failed', shipped, detail: run.failure.detail, failureKind: run.failure.kind, ...perSignal }
213
+ : { outcome: hasCounts(run.discardedBySignal) ? 'ok-with-discards' : 'ok', shipped, ...perSignal };
214
+ }
215
+ /** Safe to call concurrently (lock) and repeatedly (cursor). Never throws. */
216
+ export async function shipTelemetry(opts = {}) {
217
+ const telemetryDir = opts.telemetryDir ?? TELEMETRY_DIR;
218
+ const target = resolveShipTarget(opts, telemetryDir);
219
+ if ('skipped' in target)
220
+ return target;
221
+ const credentialFor = createCredentialResolver(opts, target.overrideHeaders);
222
+ const cursorPath = shipperCursorPath(telemetryDir);
223
+ const release = acquireShipperLock(telemetryDir, cursorPath);
224
+ if (!release)
225
+ return { shipped: 0, skipped: 'locked' };
226
+ const run = {
227
+ telemetryDir,
228
+ endpoint: target.endpoint,
229
+ credentialFor,
230
+ cursor: {},
231
+ shippedBySignal: {},
232
+ discardedBySignal: {},
233
+ withheldBySignal: {},
234
+ retriedSocketErrors: 0,
235
+ };
236
+ try {
237
+ run.cursor = loadCursor(cursorPath);
238
+ const files = candidateFiles(telemetryDir, run.cursor);
239
+ for (const candidate of files) {
240
+ // eslint-disable-next-line no-await-in-loop -- files ship one at a time so each cursor advances only past delivered records
241
+ const fileFailure = await shipFile(run, candidate);
242
+ run.failure ??= fileFailure;
243
+ }
244
+ saveCursor(cursorPath, run.cursor, files);
245
+ // The one place housekeeping costs no hook latency: the git cache and the session-state retention sweep.
246
+ pruneGitCache(telemetryDir);
247
+ pruneSessionState();
248
+ recordShipperStatus(completedRunStatus(run), telemetryDir);
249
+ }
250
+ catch (error) {
251
+ recordShipperStatus({
252
+ outcome: 'crashed',
253
+ shipped: sumCounts(run.shippedBySignal),
254
+ shippedBySignal: run.shippedBySignal,
255
+ detail: shipperErrorDetail(error),
256
+ }, telemetryDir);
257
+ }
258
+ finally {
259
+ release();
260
+ }
261
+ return { shipped: sumCounts(run.shippedBySignal), skipped: null };
262
+ }
263
+ /**
264
+ * Stamped records ship under their writing account's key (TKR6); the signed-in
265
+ * key is only named here and fetched when an unstamped batch needs it (HDF2).
266
+ */
267
+ export async function shipTelemetryWithAccountKeys() {
268
+ return shipTelemetry({
269
+ keyForRef: (s) => Promise.resolve(readMappedKey(s)),
270
+ signedInSecretName: resolveKeySecretName(),
271
+ });
272
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Detached telemetry shipper spawn, shared by Stop, SessionEnd and the quality
3
+ * evaluator. Detached and unref'd on purpose: SessionEnd runs under a
4
+ * hard 1.5 s ceiling for the whole event.
5
+ */
6
+ import { SHIP_TELEMETRY_ARG, TELEMETRY_DIR } from '../core/constants.js';
7
+ import { spawnDetachedRunner } from '../core/detached-runner.js';
8
+ import { canResolveIdentityKey } from '../core/identity-key-resolver.js';
9
+ import { resolveOtlpEndpoint } from '../core/settings-env.js';
10
+ import { hasOtlpAuth } from '../otel/otlp-headers.js';
11
+ import { hasUnshippedTelemetry } from './shipper-cursor.js';
12
+ import { recordShipperStatus, shipPreflight } from './shipper-status.js';
13
+ /**
14
+ * Start the detached shipper, or record why not. Every guard is a state in which
15
+ * telemetry stops arriving, so each writes a status record. The spawning path
16
+ * writes nothing (the child owns the outcome), nor does the nothing-to-ship
17
+ * path (HDF2): a stale `updatedAt` means no run was needed, not that shipping is broken.
18
+ */
19
+ export function spawnTelemetryShipper() {
20
+ const preflight = shipPreflight({
21
+ // Resolved exactly as `shipTelemetry` resolves it: a spawn guard stricter than
22
+ // the child's silently makes the child's resolution unreachable.
23
+ endpoint: resolveOtlpEndpoint(),
24
+ // Both auth sources, in the child's order, since checking one makes the other unreachable:
25
+ // identity map (TKR3; file-only, the child fetches the key from Doppler), then env auth
26
+ // (OBTOOL_API_KEY / OTLP header vars) for unmapped accounts and `doppler run` scripts.
27
+ hasAuth: () => canResolveIdentityKey() || hasOtlpAuth(),
28
+ });
29
+ if ('skipped' in preflight)
30
+ return;
31
+ // Cheap cursor check before a Node boot plus Doppler fetch; SessionEnd right
32
+ // after a Stop is the common empty case. A failed delivery holds the cursor, so it still spawns.
33
+ if (!hasUnshippedTelemetry(TELEMETRY_DIR))
34
+ return;
35
+ const result = spawnDetachedRunner([SHIP_TELEMETRY_ARG]);
36
+ if (!result.ok) {
37
+ recordShipperStatus({ outcome: result.reason, detail: result.detail });
38
+ }
39
+ }
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Per-invocation agent measures from a subagent's transcript. From the
3
+ * transcript, not the hook stream: no hook event marks an API response, and the
4
+ * PostToolUse success payload carries no duration, so measuring it there would
5
+ * put a store touch on every tool call.
6
+ *
7
+ * Same fold as the Stop checkpoint (transcript-fold.ts), driven from offset 0 with no
8
+ * persisted state, so a response, its model and its usage are counted by one rule on both
9
+ * paths: `inferenceCalls` counts distinct `message.id`s among lines carrying usage, not
10
+ * assistant lines (one response spans several JSONL entries).
11
+ */
12
+ import { statSync } from 'node:fs';
13
+ import { THRESHOLDS } from '../core/constants.js';
14
+ import { emptyAccumulator, foldTranscriptFrom, INITIAL_MODEL } from './transcript-fold.js';
15
+ /** Null when missing, unreadable or over the read budget: a zero would read as an agent that made no calls. */
16
+ export function readAgentTranscriptMeasures(path) {
17
+ const acc = emptyAccumulator();
18
+ try {
19
+ if (statSync(path).size > THRESHOLDS.AGENT_TRANSCRIPT_MAX_READ_BYTES)
20
+ return null;
21
+ foldTranscriptFrom(path, 0, acc);
22
+ }
23
+ catch {
24
+ return null;
25
+ }
26
+ const { stats, modelTotals, toolCalls, toolDurations } = acc;
27
+ return {
28
+ inferenceCalls: stats.messageCount,
29
+ toolCalls,
30
+ model: stats.model === INITIAL_MODEL ? undefined : stats.model,
31
+ tokenUsageByModel: Object.fromEntries([...modelTotals]),
32
+ toolDurations,
33
+ };
34
+ }
@@ -0,0 +1,134 @@
1
+ /**
2
+ * The split of a session's context by content type: which transcript records count toward which
3
+ * type, the first turn's measured overhead, and the immutable-head cache that spares re-reading it.
4
+ */
5
+ import { isJsonObject } from '../core/file-utils.js';
6
+ import { parseJsonLines } from '../core/jsonl-tail.js';
7
+ import { estimateTokenCount } from '../core/units.js';
8
+ import { transcriptCheckpointStore } from '../session/session-state.js';
9
+ import { CONVERSATION_RECORD_TYPES, promptTokens, responseUsage } from './transcript-entry.js';
10
+ /** `classifyRecords` output, cached once the head is immutable. */
11
+ const HEAD_CLASSIFICATION_FILE = 'head-classification.json';
12
+ /** Bump when the cached shape or `classifyRecords` changes. */
13
+ const HEAD_CLASSIFICATION_VERSION = 2;
14
+ /** Emission order. `messages` is the conversation plus attachments with no type of their own. */
15
+ export const CONTEXT_TYPES = [
16
+ 'system_prompt', 'system_tools', 'skills', 'agents', 'plugins', 'mcp', 'memory_files', 'messages',
17
+ ];
18
+ /** Present from the first request; `*_delta` attachments grow a type afterwards. */
19
+ const FIXED_CONTEXT_TYPES = CONTEXT_TYPES.filter((type) => type !== 'messages');
20
+ function mapBreakdown(valueOf) {
21
+ return Object.fromEntries(CONTEXT_TYPES.map(type => [type, valueOf(type)]));
22
+ }
23
+ function emptyBreakdown() {
24
+ return mapBreakdown(() => 0);
25
+ }
26
+ function sumFixed(breakdown) {
27
+ return FIXED_CONTEXT_TYPES.reduce((sum, type) => sum + breakdown[type], 0);
28
+ }
29
+ export function sumBreakdown(breakdown) {
30
+ return sumFixed(breakdown) + breakdown.messages;
31
+ }
32
+ const REQUEST_SHAPE_RECORD_TYPE = 'api-request-shape';
33
+ const ATTACHMENT_RECORD_TYPE = 'attachment';
34
+ /** Attachments with a context type of their own; the rest are conversation. */
35
+ const ATTACHMENT_CONTEXT_TYPES = new Map([
36
+ ['instructions', 'memory_files'],
37
+ ['skill_listing', 'skills'],
38
+ ['agent_listing_delta', 'agents'],
39
+ ['deferred_tools_delta', 'mcp'],
40
+ ['mcp_instructions_delta', 'mcp'],
41
+ ]);
42
+ function jsonChars(value) {
43
+ if (value === undefined)
44
+ return 0;
45
+ return typeof value === 'string' ? value.length : JSON.stringify(value).length;
46
+ }
47
+ /** `rendered` parts are the text sent to the model; none means bookkeeping. */
48
+ function renderedChars(rendered) {
49
+ if (!Array.isArray(rendered))
50
+ return 0;
51
+ return rendered.reduce((sum, part) => sum + (isJsonObject(part) ? jsonChars(part.content) : 0), 0);
52
+ }
53
+ function isValidContextBreakdown(v) {
54
+ return isJsonObject(v) && CONTEXT_TYPES.every((type) => typeof v[type] === 'number');
55
+ }
56
+ function isValidFirstTurn(v) {
57
+ return v === undefined || (isJsonObject(v) && typeof v.usageTokens === 'number' && isValidContextBreakdown(v.chars));
58
+ }
59
+ /** The head is immutable, so the cache never expires. */
60
+ export const headClassifications = transcriptCheckpointStore({
61
+ file: HEAD_CLASSIFICATION_FILE,
62
+ version: HEAD_CLASSIFICATION_VERSION,
63
+ isValidBody: (v) => isValidContextBreakdown(v.chars) && isValidFirstTurn(v.firstTurn),
64
+ });
65
+ /** Markers of the only records that change fixed types after the first turn. */
66
+ const FIXED_RECORD_MARKERS = [`"${REQUEST_SHAPE_RECORD_TYPE}"`, `"${ATTACHMENT_RECORD_TYPE}"`];
67
+ /**
68
+ * In-context characters per type; bookkeeping counts nowhere, only the latest request shape counts.
69
+ * `fixedOnlyAfterFirstTurn` skips later conversation, leaving `chars.messages` partial.
70
+ */
71
+ export function classifyRecords(content, fixedOnlyAfterFirstTurn) {
72
+ const chars = emptyBreakdown();
73
+ let firstTurn;
74
+ const accept = (line) => !fixedOnlyAfterFirstTurn || !firstTurn || FIXED_RECORD_MARKERS.some(marker => line.includes(marker));
75
+ for (const record of parseRecords(content, accept)) {
76
+ if (record.type === REQUEST_SHAPE_RECORD_TYPE && isJsonObject(record.shape)) {
77
+ chars.system_prompt = jsonChars(record.shape.system);
78
+ chars.system_tools = jsonChars(record.shape.tools);
79
+ }
80
+ else if (record.type === ATTACHMENT_RECORD_TYPE && isJsonObject(record.attachment)) {
81
+ const contextType = ATTACHMENT_CONTEXT_TYPES.get(record.attachment.type) ?? 'messages';
82
+ chars[contextType] += renderedChars(record.rendered);
83
+ }
84
+ else if (CONVERSATION_RECORD_TYPES.has(record.type) && isJsonObject(record.message)) {
85
+ firstTurn ??= firstTurnOf(record, chars);
86
+ chars.messages += jsonChars(record.message.content);
87
+ }
88
+ }
89
+ return { chars, firstTurn };
90
+ }
91
+ function* parseRecords(content, accept) {
92
+ for (const record of parseJsonLines(content, accept)) {
93
+ if (isJsonObject(record) && typeof record.type === 'string')
94
+ yield record;
95
+ }
96
+ }
97
+ function firstTurnOf(entry, chars) {
98
+ const usage = responseUsage(entry);
99
+ return usage && { usageTokens: promptTokens(usage), chars: { ...chars } };
100
+ }
101
+ /**
102
+ * Fixed overhead is what the first API call carried besides the conversation: its usage record
103
+ * gives the size in tokens, the head gives the split by type. With no usage record, or a failed
104
+ * measurement, the split is converted at the nominal rate, as is fixed context loaded after that
105
+ * call (deferred tools, agent listings). The remainder is conversation, floored at zero after a compaction.
106
+ */
107
+ export function usageBreakdownFrom(classified, totalContextTokens) {
108
+ const { chars, firstTurn } = classified;
109
+ const firstChars = firstTurn?.chars ?? emptyBreakdown();
110
+ const firstFixed = sumFixed(firstChars);
111
+ const nominalFixed = estimateTokenCount(firstFixed);
112
+ // A first turn denser than the nominal rate (base64, packed data) overshoots its estimate;
113
+ // a remainder at or below zero is a failed measurement, not free overhead.
114
+ const measuredFixed = firstTurn ? firstTurn.usageTokens - estimateTokenCount(firstChars.messages) : 0;
115
+ const fixedTokens = Math.min(measuredFixed > 0 ? measuredFixed : nominalFixed, totalContextTokens);
116
+ const breakdown = emptyBreakdown();
117
+ for (const type of FIXED_CONTEXT_TYPES) {
118
+ const measuredShare = firstFixed > 0 ? Math.floor((firstChars[type] * fixedTokens) / firstFixed) : 0;
119
+ const lateChars = chars[type] - firstChars[type];
120
+ breakdown[type] = measuredShare + estimateTokenCount(Math.max(0, lateChars));
121
+ }
122
+ breakdown.messages = Math.max(0, totalContextTokens - sumFixed(breakdown));
123
+ return breakdown;
124
+ }
125
+ /** Bytes past the head count as conversation at the head's density; fixed context is all in the head. */
126
+ export function categorizeTranscript(content, transcriptSize) {
127
+ const { chars } = classifyRecords(content, false);
128
+ // Bytes, not content.length: a non-ASCII head has fewer UTF-16 units than bytes.
129
+ const headBytes = Buffer.byteLength(content);
130
+ if (transcriptSize > headBytes && headBytes > 0) {
131
+ chars.messages += ((transcriptSize - headBytes) * chars.messages) / headBytes;
132
+ }
133
+ return mapBreakdown(type => estimateTokenCount(chars[type]));
134
+ }