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,195 @@
1
+ /**
2
+ * Scans this session's edited files for the risky patterns the conformance audit
3
+ * found (CCH0b, CCH1c, CCH5) and delivers a self-check via `additionalContext`
4
+ * once per session. The latch is load-bearing: additionalContext on Stop resumes
5
+ * the session and the trigger stays true, so without it the session never stops.
6
+ */
7
+ import { existsSync } from 'node:fs';
8
+ import { OTHER_LABEL } from '../lib/core/bounded-label.js';
9
+ import { readTextOrNull } from '../lib/core/file-utils.js';
10
+ import { HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
11
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
12
+ import { getFileCategory, isJsTsFile, isJsTsNonSourceFile, } from '../lib/runtime/categorizers.js';
13
+ import { addAdditionalContext } from '../lib/runtime/hook-output.js';
14
+ import { loadEdits } from '../lib/session/edit-ledger.js';
15
+ import { sessionMarkerPath, sessionStateRoot, claimOnce } from '../lib/session/session-state.js';
16
+ const EXCLUDED_PATH_SUBSTRINGS = ['types/', '.styles.ts'];
17
+ function shouldCheckErrorHandling(filePath) {
18
+ if (!isJsTsFile(filePath) || isJsTsNonSourceFile(filePath))
19
+ return false;
20
+ return !EXCLUDED_PATH_SUBSTRINGS.some((sub) => filePath.includes(sub));
21
+ }
22
+ const SIGNAL_PATTERNS = {
23
+ hasConsoleLog: [/\bconsole\.log\(/],
24
+ // Four or more digits: a timeout that may exceed HOOK_TIMEOUT_MS and so never fire (CCH1c).
25
+ hasHardcodedTimeout: [/[,{]\s*timeout:\s*\d{4,}/, /setTimeout\s*\([^,]+,\s*\d{4,}/],
26
+ hasSilentCatch: [/catch\s*(?:\([^)]*\))?\s*\{\s*\}/],
27
+ hasApiCall: [/\bfetch\s*\(|axios\.|apiClient\./i],
28
+ };
29
+ function analyzeFileContent(filePath) {
30
+ const content = readTextOrNull(filePath);
31
+ if (content === null)
32
+ return null;
33
+ const analysis = {};
34
+ for (const [signal, patterns] of Object.entries(SIGNAL_PATTERNS)) {
35
+ analysis[signal] = patterns.some((re) => re.test(content));
36
+ }
37
+ return analysis;
38
+ }
39
+ /**
40
+ * No section for `'other'`, so such a file can neither trigger the reminder nor burn
41
+ * the session's single delivery slot on a bare header (CCH6b). A new `FileCategory`
42
+ * is a compile error until it gets a section.
43
+ */
44
+ const REMINDER_SECTIONS = {
45
+ 'hooks-handler': {
46
+ heading: 'Hooks Handler',
47
+ countAttribute: 'integritystudio.error_reminder.files.hooks_handler',
48
+ checks: [
49
+ {
50
+ signal: 'hasConsoleLog',
51
+ line: '- Plain stdout (`writePlainContext()`) does not reach Claude outside SessionStart/UserPromptSubmit/UserPromptExpansion — use `addAdditionalContext()` on Stop/PostToolUse (CCH0b).',
52
+ },
53
+ {
54
+ signal: 'hasSilentCatch',
55
+ line: '- Does the catch block swallow the error silently? A hook that fails open exits 0 with no delivery and no telemetry (CCH5).',
56
+ },
57
+ ],
58
+ bestPractice: 'Best practice: route output through the channel that reaches Claude at this event; let errors surface rather than hide them.',
59
+ },
60
+ 'hooks-lib': {
61
+ heading: 'Hooks Library',
62
+ countAttribute: 'integritystudio.error_reminder.files.hooks_lib',
63
+ checks: [
64
+ {
65
+ signal: 'hasHardcodedTimeout',
66
+ line: '- Is the hardcoded timeout below `HOOK_TIMEOUT_MS`? A timeout above the harness limit is unreachable — the process is killed first with no error, no telemetry, and no retry (CCH1c). Use `THRESHOLDS.*` constants.',
67
+ },
68
+ {
69
+ signal: 'hasSilentCatch',
70
+ line: '- Does the catch block swallow the error silently? A library that fails open hides the failure from the handler and from telemetry (CCH5).',
71
+ },
72
+ ],
73
+ bestPractice: 'Best practice: validate timeout values against `HOOK_TIMEOUT_MS`; propagate or log errors rather than silently catching them.',
74
+ },
75
+ scripts: {
76
+ heading: 'Scripts',
77
+ countAttribute: 'integritystudio.error_reminder.files.scripts',
78
+ checks: [
79
+ { signal: 'hasSilentCatch', line: '- Does the catch block swallow the error silently?' },
80
+ { signal: 'hasApiCall', line: '- Do network calls handle transient failures and log on exhaustion?' },
81
+ ],
82
+ },
83
+ };
84
+ /** `FileCategory` is a closed union, so every category but `other` keys a section. */
85
+ const isSectionCategory = (category) => category !== OTHER_LABEL;
86
+ /** Marker latching the error reminder to one delivery per session. */
87
+ const ERROR_REMINDER_MARKER = 'error-reminder';
88
+ const SKIP_ENV_VAR = 'SKIP_ERROR_REMINDER';
89
+ const SKIP_ENV_ON = '1';
90
+ const ATTR = {
91
+ FILES_EDITED: 'integritystudio.error_reminder.files.edited',
92
+ FILES_RENDERABLE: 'integritystudio.error_reminder.files.renderable',
93
+ FILES_TOTAL: 'integritystudio.error_reminder.files.total',
94
+ NEEDS_ATTENTION: 'integritystudio.error_reminder.needs_attention',
95
+ ALREADY_DELIVERED: 'integritystudio.error_reminder.already_delivered',
96
+ /** Section-category files the ledger names but that could not be read (deleted, moved, unreadable) */
97
+ FILES_UNREADABLE: 'integritystudio.error_reminder.files.unreadable',
98
+ };
99
+ const REMINDER_TITLE = '## Error Handling Self-Check';
100
+ const REMINDER_CLOSING = `Address whichever points apply, or state why they do not. Set \`${SKIP_ENV_VAR}=${SKIP_ENV_ON}\` to disable this check.`;
101
+ /** Atomic claim of the per-session delivery slot (see the module note). `stateRoot` keeps tests out of $HOME. */
102
+ export function claimErrorReminder(sessionId, stateRoot = sessionStateRoot()) {
103
+ return claimOnce(sessionMarkerPath(sessionId, ERROR_REMINDER_MARKER, stateRoot));
104
+ }
105
+ /** Non-claiming peek, so a Stop after delivery skips the file scan; the claim itself stays atomic. */
106
+ function errorReminderDelivered(sessionId) {
107
+ return existsSync(sessionMarkerPath(sessionId, ERROR_REMINDER_MARKER));
108
+ }
109
+ function groupAnalysesByCategory(editedFiles) {
110
+ // The ledger is append-only, so a file edited N times appears N times.
111
+ const analysesByCategory = new Map();
112
+ let unreadableCount = 0;
113
+ for (const path of new Set(editedFiles.map((file) => file.path))) {
114
+ if (!shouldCheckErrorHandling(path))
115
+ continue;
116
+ const category = getFileCategory(path);
117
+ if (!isSectionCategory(category))
118
+ continue;
119
+ const analysis = analyzeFileContent(path);
120
+ if (!analysis) {
121
+ unreadableCount++;
122
+ continue;
123
+ }
124
+ const bucket = analysesByCategory.get(category) ?? [];
125
+ bucket.push(analysis);
126
+ analysesByCategory.set(category, bucket);
127
+ }
128
+ return { analysesByCategory, unreadableCount };
129
+ }
130
+ function renderReminder(sections) {
131
+ const lines = [REMINDER_TITLE, ''];
132
+ for (const { section, analyses, tripped } of sections) {
133
+ if (analyses.length === 0)
134
+ continue;
135
+ lines.push(`**${section.heading}** — ${analyses.length} file(s) edited`, '');
136
+ lines.push(...tripped.map(({ line }) => line));
137
+ lines.push('');
138
+ if (section.bestPractice)
139
+ lines.push(section.bestPractice, '');
140
+ }
141
+ lines.push(REMINDER_CLOSING);
142
+ return lines.join('\n');
143
+ }
144
+ function reportAlreadyDelivered(ctx) {
145
+ ctx.addAttribute(ATTR.ALREADY_DELIVERED, true);
146
+ ctx.logger.debug('Error reminder already delivered this session');
147
+ }
148
+ export async function handleErrorReminder(input) {
149
+ if (process.env[SKIP_ENV_VAR] === SKIP_ENV_ON)
150
+ return;
151
+ await instrumentHook(HOOK_NAMES.ERROR_HANDLING_REMINDER, (ctx) => {
152
+ ctx.logger.debug('Error handling reminder starting');
153
+ const sessionId = input.session_id;
154
+ if (errorReminderDelivered(sessionId)) {
155
+ reportAlreadyDelivered(ctx);
156
+ return;
157
+ }
158
+ const editedFiles = loadEdits(sessionId);
159
+ ctx.addAttribute(ATTR.FILES_EDITED, editedFiles.length);
160
+ if (editedFiles.length === 0) {
161
+ ctx.logger.debug('No files edited this session');
162
+ return;
163
+ }
164
+ const { analysesByCategory, unreadableCount } = groupAnalysesByCategory(editedFiles);
165
+ const sections = Object.entries(REMINDER_SECTIONS)
166
+ .map(([category, section]) => {
167
+ const analyses = analysesByCategory.get(category) ?? [];
168
+ const tripped = section.checks.filter(({ signal }) => analyses.some((analysis) => analysis[signal]));
169
+ return { section, analyses, tripped };
170
+ });
171
+ const analyzedCount = sections.reduce((sum, { analyses }) => sum + analyses.length, 0);
172
+ const needsAttention = sections.some(({ tripped }) => tripped.length > 0);
173
+ ctx.addAttributes({
174
+ ...Object.fromEntries(sections.map(({ section, analyses }) => [section.countAttribute, analyses.length])),
175
+ [ATTR.NEEDS_ATTENTION]: needsAttention,
176
+ [ATTR.FILES_RENDERABLE]: analyzedCount,
177
+ [ATTR.FILES_UNREADABLE]: unreadableCount,
178
+ });
179
+ if (!needsAttention) {
180
+ ctx.logger.debug('No actionable patterns in a category the reminder renders', {
181
+ [ATTR.FILES_RENDERABLE]: analyzedCount,
182
+ });
183
+ return;
184
+ }
185
+ ctx.logger.info('Error handling patterns detected', {
186
+ [ATTR.FILES_TOTAL]: editedFiles.length,
187
+ [ATTR.FILES_RENDERABLE]: analyzedCount,
188
+ });
189
+ if (!claimErrorReminder(sessionId)) {
190
+ reportAlreadyDelivered(ctx);
191
+ return;
192
+ }
193
+ addAdditionalContext(renderReminder(sections));
194
+ }, { [HOOK_TYPE_ATTR]: 'error' });
195
+ }
@@ -0,0 +1,58 @@
1
+ /**
2
+ * T2 quality evaluation, Stop side: sampling and budget gates, a `stat` of the
3
+ * transcript, and a spawn of the detached evaluator (`hook-runner
4
+ * evaluate-quality`). The judge calls happen in that child, so nothing here
5
+ * waits on the network.
6
+ */
7
+ import { statSync } from 'node:fs';
8
+ import { writeStderr } from '../lib/core/format-utils.js';
9
+ import { HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
10
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
11
+ import { hasBudget } from '../lib/quality/quality-budget.js';
12
+ import { QUALITY_ATTRS, QUALITY_EVAL_SKIP_REASONS, QUALITY_EVAL_TYPE_LLM, QUALITY_EVALUATION_HOOK_TYPE, spawnQualityEvaluator, } from '../lib/quality/quality-eval-handoff.js';
13
+ import { getSessionSamplingInfo } from '../lib/quality/quality-sampler.js';
14
+ export async function handleQualityEvaluation(input) {
15
+ const { session_id: sessionId, transcript_path: transcriptPath } = input;
16
+ const samplingInfo = getSessionSamplingInfo(sessionId);
17
+ if (!samplingInfo.sampled)
18
+ return;
19
+ // A snapshot, not a reservation: the evaluator reserves per call under the lock.
20
+ if (!hasBudget()) {
21
+ writeStderr('[Quality] Daily evaluation budget exhausted');
22
+ return;
23
+ }
24
+ // No credential check: the key may live only in Doppler, which the detached
25
+ // evaluator resolves; a missing key surfaces there as llm_judge_failures (HRF6).
26
+ await instrumentHook(HOOK_NAMES.QUALITY_EVALUATION_QUEUE, (ctx) => {
27
+ const canary = samplingInfo.canary;
28
+ ctx.addAttributes({
29
+ [QUALITY_ATTRS.EVAL_TYPE]: QUALITY_EVAL_TYPE_LLM,
30
+ [QUALITY_ATTRS.CANARY]: canary,
31
+ });
32
+ let transcriptBytes;
33
+ try {
34
+ transcriptBytes = statSync(transcriptPath).size;
35
+ }
36
+ catch {
37
+ ctx.addAttribute(QUALITY_ATTRS.EVAL_SKIPPED_REASON, QUALITY_EVAL_SKIP_REASONS.NO_TRANSCRIPT);
38
+ return;
39
+ }
40
+ if (transcriptBytes === 0) {
41
+ ctx.addAttribute(QUALITY_ATTRS.EVAL_SKIPPED_REASON, QUALITY_EVAL_SKIP_REASONS.NO_TURNS);
42
+ return;
43
+ }
44
+ ctx.addAttribute(QUALITY_ATTRS.TRANSCRIPT_BYTES, transcriptBytes);
45
+ // The size bounds the evaluator's read to the transcript this Stop saw.
46
+ const spawned = spawnQualityEvaluator({
47
+ sessionId,
48
+ canary,
49
+ transcriptPath,
50
+ transcriptBytes,
51
+ });
52
+ ctx.addAttribute(QUALITY_ATTRS.EVAL_QUEUED, spawned.ok);
53
+ if (!spawned.ok) {
54
+ ctx.addAttribute(QUALITY_ATTRS.EVAL_SKIPPED_REASON, spawned.reason);
55
+ ctx.addAttribute(QUALITY_ATTRS.EVAL_SKIPPED_DETAIL, spawned.detail);
56
+ }
57
+ }, { [HOOK_TYPE_ATTR]: QUALITY_EVALUATION_HOOK_TYPE });
58
+ }
@@ -0,0 +1,62 @@
1
+ /** Session-level roll-ups: MCP failure summary, T1 task-completion signal, and the alert rules over both. */
2
+ import { formatPercent, UNITS } from '../lib/core/units.js';
3
+ import { loadInvocations, summarizeInvocations } from '../lib/mcp/mcp-completeness.js';
4
+ import { ALERT_ATTRS, SESSION_ATTRIBUTES, HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
5
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
6
+ import { evaluateTaskAlerts, evaluateScrapingAlerts } from '../lib/otel/telemetry-alerts.js';
7
+ import { emitTaskCompletion, appendEvaluation, EVALUATOR_KIND, EVALUATION_COHORT } from '../lib/quality/quality-signals.js';
8
+ import { activeTaskCompletion } from '../lib/session/task-tracker.js';
9
+ const PRODUCER = 'hook:stop-session-summary';
10
+ export async function handleSessionSummary(sessionId) {
11
+ // One read feeds the summary, the failure detail and the scraping alert.
12
+ const mcpInvocations = loadInvocations(sessionId);
13
+ const mcpSummary = summarizeInvocations(mcpInvocations);
14
+ const mcpEntries = Object.entries(mcpSummary);
15
+ const failedEntries = mcpEntries.filter(([, s]) => s.failed > 0);
16
+ const mcpTotalFailed = failedEntries.reduce((sum, [, s]) => sum + s.failed, 0);
17
+ const mcpTotalAll = mcpEntries.reduce((sum, [, s]) => sum + s.total, 0);
18
+ if (failedEntries.length > 0) {
19
+ const failedServers = failedEntries.map(([key]) => key).join(',');
20
+ await instrumentHook(HOOK_NAMES.MCP_SESSION_FAILURE_SUMMARY, (ctx) => {
21
+ ctx.addAttributes({
22
+ 'integritystudio.mcp.session_failed_count': mcpTotalFailed,
23
+ 'integritystudio.mcp.session_total_count': mcpTotalAll,
24
+ 'integritystudio.mcp.session_failed_servers': failedServers,
25
+ });
26
+ ctx.recordMetric('integritystudio.mcp.session_failures', mcpTotalFailed, {
27
+ [SESSION_ATTRIBUTES.SESSION_ID]: sessionId,
28
+ }, { unit: UNITS.FAILURE });
29
+ }, { [HOOK_TYPE_ATTR]: 'mcp-session-failure-summary' });
30
+ }
31
+ const triggered = [];
32
+ const tasks = activeTaskCompletion(sessionId);
33
+ if (tasks) {
34
+ const { active, ratio } = tasks;
35
+ triggered.push(...evaluateTaskAlerts(ratio));
36
+ emitTaskCompletion(ratio, sessionId);
37
+ appendEvaluation({
38
+ name: 'task_completion',
39
+ score: ratio,
40
+ kind: EVALUATOR_KIND.RULE,
41
+ cohort: EVALUATION_COHORT.NORMAL,
42
+ producer: PRODUCER,
43
+ sessionId,
44
+ explanation: `${active.length} active tasks, completion ratio: ${formatPercent(ratio)}`,
45
+ });
46
+ }
47
+ triggered.push(...evaluateScrapingAlerts(mcpTotalFailed, mcpTotalAll));
48
+ if (triggered.length > 0) {
49
+ await instrumentHook(HOOK_NAMES.TELEMETRY_ALERT_EVALUATION, (ctx) => {
50
+ ctx.addAttribute('integritystudio.alerts.triggered_count', triggered.length);
51
+ for (const alert of triggered) {
52
+ ctx.recordEvent(`integritystudio.alert.${alert.severity}`, {
53
+ [ALERT_ATTRS.NAME]: alert.name,
54
+ [ALERT_ATTRS.MESSAGE]: alert.message,
55
+ });
56
+ ctx.recordMetric(`integritystudio.alerts.${alert.severity}`, 1, {
57
+ [ALERT_ATTRS.NAME]: alert.name,
58
+ }, { unit: UNITS.ALERT });
59
+ }
60
+ }, { [HOOK_TYPE_ATTR]: 'alert-evaluation' });
61
+ }
62
+ }
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Token totals and main-loop tool durations from one incremental transcript read
3
+ * (`lib/transcript/token-metrics-checkpoint.ts`). Counters take the per-Stop delta (HRV1);
4
+ * cumulative totals go on the span.
5
+ */
6
+ import { UNITS } from '../lib/core/units.js';
7
+ import { GENAI_AGENT_ATTRIBUTES, HOOK_NAMES, HOOK_TYPE_ATTR, SESSION_METRICS, TOKEN_ATTRS } from '../lib/otel/attributes.js';
8
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
9
+ import { recordToolDurations, cacheHitRate, recordModelTotals } from '../lib/otel/token-metrics.js';
10
+ import { extractTokenStats } from '../lib/transcript/token-metrics-checkpoint.js';
11
+ import { inputTokensIncludingCache } from '../lib/transcript/transcript-entry.js';
12
+ /** Input + output tokens a session must pass before its summary metrics are recorded */
13
+ const SUMMARY_MIN_TOKENS = 1_000;
14
+ function effectiveInput(totals) {
15
+ return inputTokensIncludingCache(totals.totalInputTokens, totals.totalCacheCreationTokens, totals.totalCacheReadTokens);
16
+ }
17
+ /**
18
+ * `gen_ai.execute_tool.duration` here carries no `gen_ai.agent.name`; its absence
19
+ * is how a main-loop sample is told apart from subagent.ts's (OBP9b).
20
+ */
21
+ export async function handleTokenMetrics(input) {
22
+ const transcriptPath = input.transcript_path;
23
+ await instrumentHook(HOOK_NAMES.TOKEN_METRICS, (ctx) => {
24
+ ctx.logger.debug('Extracting token metrics from transcript', {
25
+ 'integritystudio.transcript.path': transcriptPath,
26
+ });
27
+ const result = extractTokenStats(transcriptPath, input.session_id);
28
+ // Before the `changed` gate: a turn can pair tool calls without moving the token totals.
29
+ const toolDurations = result?.toolDurations ?? [];
30
+ recordToolDurations(ctx.recordMetric, toolDurations);
31
+ ctx.addAttribute('integritystudio.transcript.tool_durations', toolDurations.length);
32
+ if (result && !result.changed) {
33
+ ctx.logger.debug('Transcript unchanged since last extraction');
34
+ ctx.addAttribute(TOKEN_ATTRS.UNCHANGED, true);
35
+ return;
36
+ }
37
+ if (!result?.stats.messageCount) {
38
+ ctx.logger.debug('No token data found in transcript');
39
+ ctx.addAttribute(TOKEN_ATTRS.FOUND, false);
40
+ return;
41
+ }
42
+ const { stats } = result;
43
+ ctx.addAttributes({
44
+ [TOKEN_ATTRS.FOUND]: true,
45
+ [TOKEN_ATTRS.INPUT]: stats.totalInputTokens,
46
+ [TOKEN_ATTRS.OUTPUT]: stats.totalOutputTokens,
47
+ [TOKEN_ATTRS.CACHE_READ]: stats.totalCacheReadTokens,
48
+ [TOKEN_ATTRS.CACHE_CREATION]: stats.totalCacheCreationTokens,
49
+ [TOKEN_ATTRS.MESSAGES]: stats.messageCount,
50
+ [TOKEN_ATTRS.MODEL]: stats.model,
51
+ });
52
+ // Counters take the delta: each Stop is a fresh process adding to a monotonic
53
+ // counter, so the cumulative figure re-summed the session every turn (HRV1).
54
+ const effectiveInputTokens = effectiveInput(stats);
55
+ const { delta } = result;
56
+ const deltaInputTokens = effectiveInput(delta);
57
+ // One datapoint set per model that answered since the last Stop: a `/model` switch
58
+ // mid-turn put both models' tokens under the last one's label (TMX1). No per-turn
59
+ // counts as labels: each distinct value opened a new series.
60
+ for (const [model, modelDelta] of result.deltaByModel) {
61
+ recordModelTotals(model, modelDelta, 'session');
62
+ }
63
+ ctx.logger.info('Token metrics recorded', {
64
+ 'integritystudio.tokens.effective_input': effectiveInputTokens,
65
+ [TOKEN_ATTRS.OUTPUT]: stats.totalOutputTokens,
66
+ [TOKEN_ATTRS.CACHE_READ]: stats.totalCacheReadTokens,
67
+ 'integritystudio.tokens.delta.input': deltaInputTokens,
68
+ 'integritystudio.tokens.delta.output': delta.totalOutputTokens,
69
+ 'integritystudio.tokens.delta.cache_read': delta.totalCacheReadTokens,
70
+ 'integritystudio.tokens.delta.cache_creation': delta.totalCacheCreationTokens,
71
+ [GENAI_AGENT_ATTRIBUTES.RESPONSE_MODEL]: stats.model,
72
+ [TOKEN_ATTRS.MESSAGES]: stats.messageCount,
73
+ });
74
+ if (stats.totalInputTokens + stats.totalOutputTokens > SUMMARY_MIN_TOKENS) {
75
+ const totalTokens = effectiveInputTokens + stats.totalOutputTokens;
76
+ // Cumulative 0–1 ratio; user-prompt.ts's per-prompt snapshot is a separate instrument.
77
+ const sessionCacheHitRate = cacheHitRate(stats.totalCacheReadTokens, stats.totalInputTokens) ?? 0;
78
+ // No model label: after a `/model` switch a whole-session figure belongs to neither model (TMX1).
79
+ ctx.recordMetric(SESSION_METRICS.TOTAL_TOKENS, totalTokens, {}, { unit: UNITS.TOKEN });
80
+ ctx.recordMetric(SESSION_METRICS.CACHE_HIT_RATE, sessionCacheHitRate, {}, { unit: UNITS.RATIO });
81
+ }
82
+ }, { [HOOK_TYPE_ATTR]: 'token-metrics' });
83
+ }
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Stop sequencer. Phase order is load-bearing: token metrics (always) →
3
+ * quality-evaluation handoff (sampled sessions; spawns the detached judge, HDF3) →
4
+ * error reminder → session summary.
5
+ */
6
+ import { errorMessage, writeStderr } from '../lib/core/format-utils.js';
7
+ import { spawnTelemetryShipper } from '../lib/shipper/telemetry-shipper.js';
8
+ import { handleErrorReminder } from './stop-error-reminder.js';
9
+ import { handleQualityEvaluation } from './stop-quality-evaluation.js';
10
+ import { handleSessionSummary } from './stop-session-summary.js';
11
+ import { handleTokenMetrics } from './stop-token-metrics.js';
12
+ export async function handleStop(input, subType) {
13
+ await handleTokenMetrics(input);
14
+ // The span records the failure; the judge must never fail the Stop hook.
15
+ await handleQualityEvaluation(input).catch((error) => {
16
+ writeStderr('[stop] Quality evaluation handoff failed:', errorMessage(error));
17
+ });
18
+ // The reminder's additionalContext resumes the session, so it never fires on a
19
+ // hook-caused resume (HSF4).
20
+ if ((!subType || subType === 'error') && !input.stop_hook_active) {
21
+ await handleErrorReminder(input);
22
+ }
23
+ await handleSessionSummary(input.session_id);
24
+ spawnTelemetryShipper();
25
+ }
@@ -0,0 +1,105 @@
1
+ /**
2
+ * SubagentStart / SubagentStop (CCH4): the agent's own lifecycle, as opposed to
3
+ * the dispatch view in pre-tool.ts and the tool-result view in post-tool-agent.ts.
4
+ *
5
+ * Claude Code also fires SubagentStop for its internal background-task
6
+ * sidechains: an agent_id, no agent_type, no SubagentStart, and a transcript
7
+ * path that never exists. Those are labeled `harness-internal` — a different
8
+ * population, not user agents — because counting them as completions inflated
9
+ * per-agent stats ~5×.
10
+ */
11
+ import { existsSync } from 'node:fs';
12
+ import { UNITS } from '../lib/core/units.js';
13
+ import { AGENT_ATTRS, GENAI_AGENT_ATTRIBUTES, GENAI_OPERATION, HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
14
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
15
+ import { agentTypeLabels } from '../lib/runtime/categorizers.js';
16
+ import { resolveAgentName } from '../lib/session/forked-skill.js';
17
+ const HARNESS_INTERNAL_AGENT_TYPE = 'harness-internal';
18
+ /** Span flag: whether the agent's transcript was read for the OBP9 metrics. */
19
+ const TRANSCRIPT_MEASURED_ATTR = 'integritystudio.agent.transcript_measured';
20
+ function agentLabels(input) {
21
+ return agentTypeLabels(resolveAgentName(input) ?? HARNESS_INTERNAL_AGENT_TYPE);
22
+ }
23
+ export async function handleSubagentStart(input) {
24
+ await instrumentHook(HOOK_NAMES.SUBAGENT_START, (ctx) => {
25
+ const labels = agentLabels(input);
26
+ ctx.addAttributes({ [AGENT_ATTRS.INSTANCE_ID]: input.agent_id ?? '', ...labels });
27
+ ctx.logger.info('Subagent started', {
28
+ [AGENT_ATTRS.TYPE]: labels[AGENT_ATTRS.TYPE],
29
+ [AGENT_ATTRS.INSTANCE_ID]: input.agent_id ?? '',
30
+ });
31
+ // `subagent.*`, not `agent.*`: `integritystudio.agent.*` are post-tool's per-tool-result metrics.
32
+ ctx.recordMetric('integritystudio.subagent.starts', 1, labels, { unit: UNITS.INVOCATION });
33
+ }, { [HOOK_TYPE_ATTR]: 'agent' });
34
+ }
35
+ /**
36
+ * The GenAI agent metrics (OBP9) from one transcript read. `gen_ai.response.model`,
37
+ * not `gen_ai.request.model`, which the spec says SHOULD NOT be set for agents with
38
+ * dynamic model selection. The `execute_tool.duration` samples here carry
39
+ * `gen_ai.agent.name`; main-loop samples (stop-token-metrics.ts, OBP9b) carry none,
40
+ * which is how the two populations are told apart.
41
+ */
42
+ async function recordAgentTranscriptMetrics(ctx, transcriptPath, agentName) {
43
+ // Loaded here, not at module top: SubagentStart and harness-internal stops never reach this branch.
44
+ const [{ readAgentTranscriptMeasures }, { recordModelTotals, recordToolDurations },] = await Promise.all([
45
+ import('../lib/transcript/agent-transcript-metrics.js'),
46
+ import('../lib/otel/token-metrics.js'),
47
+ ]);
48
+ const measures = readAgentTranscriptMeasures(transcriptPath);
49
+ // An unreadable or oversized transcript emits no samples, distinguishable from a genuine zero.
50
+ if (!measures) {
51
+ ctx.addAttribute(TRANSCRIPT_MEASURED_ATTR, false);
52
+ return;
53
+ }
54
+ const attrs = {
55
+ [GENAI_AGENT_ATTRIBUTES.AGENT_NAME]: agentName,
56
+ ...(measures.model ? { [GENAI_AGENT_ATTRIBUTES.RESPONSE_MODEL]: measures.model } : {}),
57
+ };
58
+ ctx.recordMetric('gen_ai.invoke_agent.inference_calls', measures.inferenceCalls, attrs, {
59
+ unit: UNITS.INFERENCE_CALL,
60
+ });
61
+ ctx.recordMetric('gen_ai.invoke_agent.tool_calls', measures.toolCalls, attrs, {
62
+ unit: UNITS.TOOL_CALL,
63
+ });
64
+ recordToolDurations(ctx.recordMetric, measures.toolDurations, {
65
+ [GENAI_AGENT_ATTRIBUTES.AGENT_NAME]: agentName,
66
+ });
67
+ ctx.addAttributes({
68
+ [TRANSCRIPT_MEASURED_ATTR]: true,
69
+ 'integritystudio.agent.inference_calls': measures.inferenceCalls,
70
+ 'integritystudio.agent.tool_calls': measures.toolCalls,
71
+ });
72
+ // Each datapoint carries its own model, unlike the agent-level signals above (gen-ai-token-metrics.md).
73
+ for (const [model, totals] of Object.entries(measures.tokenUsageByModel)) {
74
+ recordModelTotals(model, totals, GENAI_OPERATION.INVOKE_AGENT, {
75
+ [GENAI_AGENT_ATTRIBUTES.AGENT_NAME]: agentName,
76
+ });
77
+ }
78
+ }
79
+ /** The transcript path only when the file exists: harness-internal stops carry a path that is never written. */
80
+ function existingTranscriptPath(path) {
81
+ return path && existsSync(path) ? path : undefined;
82
+ }
83
+ export async function handleSubagentStop(input) {
84
+ await instrumentHook(HOOK_NAMES.SUBAGENT_STOP, async (ctx) => {
85
+ const labels = agentLabels(input);
86
+ const transcriptPath = existingTranscriptPath(input.agent_transcript_path);
87
+ ctx.addAttributes({
88
+ [AGENT_ATTRS.INSTANCE_ID]: input.agent_id ?? '',
89
+ ...labels,
90
+ [AGENT_ATTRS.TRANSCRIPT_PATH]: input.agent_transcript_path ?? '',
91
+ [AGENT_ATTRS.HAS_TRANSCRIPT]: transcriptPath !== undefined,
92
+ [AGENT_ATTRS.STOP_HOOK_ACTIVE]: !!input.stop_hook_active,
93
+ [AGENT_ATTRS.LAST_MESSAGE_LENGTH]: (input.last_assistant_message ?? '').length,
94
+ });
95
+ ctx.logger.info('Subagent stopped', {
96
+ [AGENT_ATTRS.TYPE]: labels[AGENT_ATTRS.TYPE],
97
+ [AGENT_ATTRS.INSTANCE_ID]: input.agent_id ?? '',
98
+ });
99
+ ctx.recordMetric('integritystudio.subagent.completions', 1, labels, { unit: UNITS.COMPLETION });
100
+ // OBP9: gated on a real agent_type so `harness-internal` never gets a series under a spec metric name.
101
+ if (transcriptPath && input.agent_type) {
102
+ await recordAgentTranscriptMetrics(ctx, transcriptPath, labels[AGENT_ATTRS.TYPE]);
103
+ }
104
+ }, { [HOOK_TYPE_ATTR]: 'agent' });
105
+ }
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Shared tool-category routing for pre-tool, post-tool and post-tool-failure.
3
+ * Sets event attributes once per event and dispatches to the matching category arm.
4
+ * Calls recordUnknownTool (CCH7 drift signal) for unrecognised tools unless signalDrift is false.
5
+ */
6
+ import { toolEventAttributes } from '../lib/agent/agent-sources.js';
7
+ import { setEventAttributes } from '../lib/otel/otel-monitor.js';
8
+ import { classifyToolCategory } from '../lib/runtime/tool-input.js';
9
+ import { recordUnknownTool } from '../lib/runtime/unknown-tool.js';
10
+ /**
11
+ * Sets event attributes, classifies the tool, and dispatches to the matching
12
+ * category handler. Falls back to recordUnknownTool (CCH7 drift signal) for
13
+ * unrecognised tools when `signalDrift` is true (the default).
14
+ * Pre-tool's scope guards must run before calling this.
15
+ */
16
+ export async function routeToolEvent(input, subType, handlers) {
17
+ setEventAttributes(toolEventAttributes(input));
18
+ const { tool_name: toolName } = input;
19
+ const category = classifyToolCategory(toolName, subType);
20
+ if (category === 'mcp') {
21
+ await handlers.mcp();
22
+ return;
23
+ }
24
+ if (category === 'plugin') {
25
+ await handlers.plugin();
26
+ return;
27
+ }
28
+ if (category === 'agent') {
29
+ await handlers.agent();
30
+ return;
31
+ }
32
+ if (category === 'builtin') {
33
+ await handlers.builtin();
34
+ return;
35
+ }
36
+ if (handlers.signalDrift !== false)
37
+ await recordUnknownTool(toolName, input.session_id);
38
+ await handlers.unknown?.();
39
+ }