observability-toolkit-hooks 0.0.0-stage → 1.0.0

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 (305) hide show
  1. package/CONFIG.md +144 -0
  2. package/README.md +201 -2
  3. package/dist/handlers/compact.js +38 -0
  4. package/dist/handlers/mcp-status.js +66 -0
  5. package/dist/handlers/notification.js +45 -0
  6. package/dist/handlers/post-tool-agent.js +157 -0
  7. package/dist/handlers/post-tool-changelog-sync.js +148 -0
  8. package/dist/handlers/post-tool-code-structure.js +116 -0
  9. package/dist/handlers/post-tool-edit-ledger.js +15 -0
  10. package/dist/handlers/post-tool-failure.js +83 -0
  11. package/dist/handlers/post-tool-git.js +79 -0
  12. package/dist/handlers/post-tool-mcp.js +105 -0
  13. package/dist/handlers/post-tool-outcome.js +48 -0
  14. package/dist/handlers/post-tool-task-state.js +74 -0
  15. package/dist/handlers/post-tool.js +132 -0
  16. package/dist/handlers/pre-tool-agent.js +192 -0
  17. package/dist/handlers/pre-tool.js +218 -0
  18. package/dist/handlers/session-end.js +39 -0
  19. package/dist/handlers/session-start.js +262 -0
  20. package/dist/handlers/stop-error-reminder.js +195 -0
  21. package/dist/handlers/stop-quality-evaluation.js +58 -0
  22. package/dist/handlers/stop-session-summary.js +62 -0
  23. package/dist/handlers/stop-token-metrics.js +83 -0
  24. package/dist/handlers/stop.js +25 -0
  25. package/dist/handlers/subagent.js +105 -0
  26. package/dist/handlers/tool-event-router.js +39 -0
  27. package/dist/handlers/user-prompt.js +218 -0
  28. package/dist/hook-runner.js +10 -0
  29. package/dist/hook-runner.js.map +7 -0
  30. package/dist/lib/agent/agent-context.js +123 -0
  31. package/dist/lib/agent/agent-evaluations.js +155 -0
  32. package/dist/lib/agent/agent-file-budget.js +65 -0
  33. package/dist/lib/agent/agent-sources.js +165 -0
  34. package/dist/lib/agent/synth-spans.js +51 -0
  35. package/dist/lib/core/bounded-label.js +6 -0
  36. package/dist/lib/core/category-rules.js +11 -0
  37. package/dist/lib/core/child-result.js +19 -0
  38. package/dist/lib/core/config-dir-recovery.js +22 -0
  39. package/dist/lib/core/constants.js +171 -0
  40. package/dist/lib/core/detached-runner.js +55 -0
  41. package/dist/lib/core/file-utils.js +353 -0
  42. package/dist/lib/core/format-utils.js +51 -0
  43. package/dist/lib/core/http-utils.js +74 -0
  44. package/dist/lib/core/http1-fetch.js +14 -0
  45. package/dist/lib/core/identity-key-resolver.js +149 -0
  46. package/dist/lib/core/jsonl-tail.js +207 -0
  47. package/dist/lib/core/load-envrc.js +72 -0
  48. package/dist/lib/core/parsers.js +43 -0
  49. package/dist/lib/core/regex.js +27 -0
  50. package/dist/lib/core/settings-env.js +31 -0
  51. package/dist/lib/core/shell-command.js +122 -0
  52. package/dist/lib/core/units.js +97 -0
  53. package/dist/lib/git/git-cache.js +158 -0
  54. package/dist/lib/git/git-commit.js +189 -0
  55. package/dist/lib/git/git-exec.js +30 -0
  56. package/dist/lib/mcp/mcp-completeness.js +40 -0
  57. package/dist/lib/mcp/mcp-config.js +118 -0
  58. package/dist/lib/mcp/mcp-failure-latch.js +22 -0
  59. package/dist/lib/mcp/mcp-identity-launcher.js +43 -0
  60. package/dist/lib/otel/attributes.js +322 -0
  61. package/dist/lib/otel/evaluation-attrs.js +51 -0
  62. package/dist/lib/otel/file-exporters.js +169 -0
  63. package/dist/lib/otel/host-resource.js +61 -0
  64. package/dist/lib/otel/otel-headers-helper.js +26 -0
  65. package/dist/lib/otel/otel-monitor.js +181 -0
  66. package/dist/lib/otel/otel.js +235 -0
  67. package/dist/lib/otel/otlp-headers.js +101 -0
  68. package/dist/lib/otel/otlp-post.js +122 -0
  69. package/dist/lib/otel/otlp-serialize.js +142 -0
  70. package/dist/lib/otel/otlp-signal.js +2 -0
  71. package/dist/lib/otel/remote-spans.js +142 -0
  72. package/dist/lib/otel/service-identity.js +10 -0
  73. package/dist/lib/otel/telemetry-alerts.js +43 -0
  74. package/dist/lib/otel/token-metrics.js +122 -0
  75. package/dist/lib/otel/trace-context.js +81 -0
  76. package/dist/lib/quality/judge-meta-eval.js +70 -0
  77. package/dist/lib/quality/judge-prompts.js +104 -0
  78. package/dist/lib/quality/judge-providers.js +193 -0
  79. package/dist/lib/quality/judge-transport.js +93 -0
  80. package/dist/lib/quality/llm-judge.js +170 -0
  81. package/dist/lib/quality/quality-budget.js +99 -0
  82. package/dist/lib/quality/quality-degradation.js +156 -0
  83. package/dist/lib/quality/quality-eval-handoff.js +74 -0
  84. package/dist/lib/quality/quality-evaluator.js +178 -0
  85. package/dist/lib/quality/quality-sampler.js +43 -0
  86. package/dist/lib/quality/quality-signals.js +150 -0
  87. package/dist/lib/runtime/categorizers.js +101 -0
  88. package/dist/lib/runtime/hook-input.js +16 -0
  89. package/dist/lib/runtime/hook-output.js +50 -0
  90. package/dist/lib/runtime/output-analyzer.js +160 -0
  91. package/dist/lib/runtime/run-handlers.js +32 -0
  92. package/dist/lib/runtime/tool-input.js +111 -0
  93. package/dist/lib/runtime/tool-output.js +44 -0
  94. package/dist/lib/runtime/unknown-tool.js +32 -0
  95. package/dist/lib/session/edit-ledger.js +29 -0
  96. package/dist/lib/session/forked-skill.js +39 -0
  97. package/dist/lib/session/handoffs.js +77 -0
  98. package/dist/lib/session/session-state.js +169 -0
  99. package/dist/lib/session/skill-rules.js +196 -0
  100. package/dist/lib/session/task-tracker.js +83 -0
  101. package/dist/lib/shipper/shipper-credentials.js +38 -0
  102. package/dist/lib/shipper/shipper-cursor.js +89 -0
  103. package/dist/lib/shipper/shipper-status.js +174 -0
  104. package/dist/lib/shipper/span-shipper.js +272 -0
  105. package/dist/lib/shipper/telemetry-shipper.js +39 -0
  106. package/dist/lib/transcript/agent-transcript-metrics.js +34 -0
  107. package/dist/lib/transcript/context-breakdown.js +134 -0
  108. package/dist/lib/transcript/context-history.js +69 -0
  109. package/dist/lib/transcript/context-tracker.js +226 -0
  110. package/dist/lib/transcript/message-count.js +49 -0
  111. package/dist/lib/transcript/model-ids.js +36 -0
  112. package/dist/lib/transcript/model-pricing.js +153 -0
  113. package/dist/lib/transcript/token-metrics-checkpoint.js +152 -0
  114. package/dist/lib/transcript/tool-call-durations.js +64 -0
  115. package/dist/lib/transcript/transcript-entry.js +67 -0
  116. package/dist/lib/transcript/transcript-fold.js +130 -0
  117. package/dist/lib/transcript/transcript-layout.js +39 -0
  118. package/dist/lib/transcript/transcript-parser.js +117 -0
  119. package/dist/runner/agent-context-4XTCLMLZ.js +23 -0
  120. package/dist/runner/agent-context-4XTCLMLZ.js.map +7 -0
  121. package/dist/runner/agent-file-budget-Q33ESBBE.js +68 -0
  122. package/dist/runner/agent-file-budget-Q33ESBBE.js.map +7 -0
  123. package/dist/runner/agent-transcript-metrics-W5CZZFMI.js +39 -0
  124. package/dist/runner/agent-transcript-metrics-W5CZZFMI.js.map +7 -0
  125. package/dist/runner/chunk-2NTNAJZE.js +49 -0
  126. package/dist/runner/chunk-2NTNAJZE.js.map +7 -0
  127. package/dist/runner/chunk-4KWBQTTG.js +78 -0
  128. package/dist/runner/chunk-4KWBQTTG.js.map +7 -0
  129. package/dist/runner/chunk-52RY6LQT.js +699 -0
  130. package/dist/runner/chunk-52RY6LQT.js.map +7 -0
  131. package/dist/runner/chunk-7OM5CYES.js +8695 -0
  132. package/dist/runner/chunk-7OM5CYES.js.map +7 -0
  133. package/dist/runner/chunk-7PEOKGYR.js +1568 -0
  134. package/dist/runner/chunk-7PEOKGYR.js.map +7 -0
  135. package/dist/runner/chunk-AGSGKELQ.js +126 -0
  136. package/dist/runner/chunk-AGSGKELQ.js.map +7 -0
  137. package/dist/runner/chunk-AVM7PJFW.js +12 -0
  138. package/dist/runner/chunk-AVM7PJFW.js.map +7 -0
  139. package/dist/runner/chunk-C3WHUMU5.js +178 -0
  140. package/dist/runner/chunk-C3WHUMU5.js.map +7 -0
  141. package/dist/runner/chunk-DGB4NSSD.js +157 -0
  142. package/dist/runner/chunk-DGB4NSSD.js.map +7 -0
  143. package/dist/runner/chunk-DNSTWC26.js +151 -0
  144. package/dist/runner/chunk-DNSTWC26.js.map +7 -0
  145. package/dist/runner/chunk-FDJJ3TYU.js +449 -0
  146. package/dist/runner/chunk-FDJJ3TYU.js.map +7 -0
  147. package/dist/runner/chunk-FGKYDQHZ.js +137 -0
  148. package/dist/runner/chunk-FGKYDQHZ.js.map +7 -0
  149. package/dist/runner/chunk-GG2I4TGI.js +582 -0
  150. package/dist/runner/chunk-GG2I4TGI.js.map +7 -0
  151. package/dist/runner/chunk-GNNKUMRF.js +60 -0
  152. package/dist/runner/chunk-GNNKUMRF.js.map +7 -0
  153. package/dist/runner/chunk-I7TD2QVR.js +118 -0
  154. package/dist/runner/chunk-I7TD2QVR.js.map +7 -0
  155. package/dist/runner/chunk-IJ4SLUBV.js +78 -0
  156. package/dist/runner/chunk-IJ4SLUBV.js.map +7 -0
  157. package/dist/runner/chunk-IY7AP7NA.js +32 -0
  158. package/dist/runner/chunk-IY7AP7NA.js.map +7 -0
  159. package/dist/runner/chunk-J3F3Z3EQ.js +177 -0
  160. package/dist/runner/chunk-J3F3Z3EQ.js.map +7 -0
  161. package/dist/runner/chunk-JLEO5OHU.js +104 -0
  162. package/dist/runner/chunk-JLEO5OHU.js.map +7 -0
  163. package/dist/runner/chunk-JRNNLOPR.js +168 -0
  164. package/dist/runner/chunk-JRNNLOPR.js.map +7 -0
  165. package/dist/runner/chunk-KGSA5JYP.js +82 -0
  166. package/dist/runner/chunk-KGSA5JYP.js.map +7 -0
  167. package/dist/runner/chunk-LBCZAYFR.js +125 -0
  168. package/dist/runner/chunk-LBCZAYFR.js.map +7 -0
  169. package/dist/runner/chunk-LHWRXY2G.js +41 -0
  170. package/dist/runner/chunk-LHWRXY2G.js.map +7 -0
  171. package/dist/runner/chunk-LQ2LGUYJ.js +41 -0
  172. package/dist/runner/chunk-LQ2LGUYJ.js.map +7 -0
  173. package/dist/runner/chunk-LYY6RCIE.js +158 -0
  174. package/dist/runner/chunk-LYY6RCIE.js.map +7 -0
  175. package/dist/runner/chunk-M4R4QIQH.js +41 -0
  176. package/dist/runner/chunk-M4R4QIQH.js.map +7 -0
  177. package/dist/runner/chunk-MC75VXMX.js +207 -0
  178. package/dist/runner/chunk-MC75VXMX.js.map +7 -0
  179. package/dist/runner/chunk-NKZU4RRG.js +104 -0
  180. package/dist/runner/chunk-NKZU4RRG.js.map +7 -0
  181. package/dist/runner/chunk-PJHWHJ3K.js +56 -0
  182. package/dist/runner/chunk-PJHWHJ3K.js.map +7 -0
  183. package/dist/runner/chunk-RIGVYJ2O.js +114 -0
  184. package/dist/runner/chunk-RIGVYJ2O.js.map +7 -0
  185. package/dist/runner/chunk-RWRGC7ZK.js +93 -0
  186. package/dist/runner/chunk-RWRGC7ZK.js.map +7 -0
  187. package/dist/runner/chunk-SRMAJQMV.js +54 -0
  188. package/dist/runner/chunk-SRMAJQMV.js.map +7 -0
  189. package/dist/runner/chunk-TRMFD36J.js +47 -0
  190. package/dist/runner/chunk-TRMFD36J.js.map +7 -0
  191. package/dist/runner/chunk-U4IOZYQ3.js +21 -0
  192. package/dist/runner/chunk-U4IOZYQ3.js.map +7 -0
  193. package/dist/runner/chunk-UEXDE3WP.js +83 -0
  194. package/dist/runner/chunk-UEXDE3WP.js.map +7 -0
  195. package/dist/runner/chunk-UW3GQZSM.js +50 -0
  196. package/dist/runner/chunk-UW3GQZSM.js.map +7 -0
  197. package/dist/runner/chunk-V2GSP6VR.js +46 -0
  198. package/dist/runner/chunk-V2GSP6VR.js.map +7 -0
  199. package/dist/runner/chunk-VOV4Y5VU.js +81 -0
  200. package/dist/runner/chunk-VOV4Y5VU.js.map +7 -0
  201. package/dist/runner/chunk-VT5T6OEI.js +65 -0
  202. package/dist/runner/chunk-VT5T6OEI.js.map +7 -0
  203. package/dist/runner/chunk-VUYVFWIN.js +12 -0
  204. package/dist/runner/chunk-VUYVFWIN.js.map +7 -0
  205. package/dist/runner/chunk-VVGOPPEN.js +36 -0
  206. package/dist/runner/chunk-VVGOPPEN.js.map +7 -0
  207. package/dist/runner/chunk-VXFSLM6P.js +14 -0
  208. package/dist/runner/chunk-VXFSLM6P.js.map +7 -0
  209. package/dist/runner/chunk-W3EK7JUT.js +26125 -0
  210. package/dist/runner/chunk-W3EK7JUT.js.map +7 -0
  211. package/dist/runner/chunk-WJHNCOUF.js +52 -0
  212. package/dist/runner/chunk-WJHNCOUF.js.map +7 -0
  213. package/dist/runner/chunk-WU7ANGCW.js +269 -0
  214. package/dist/runner/chunk-WU7ANGCW.js.map +7 -0
  215. package/dist/runner/chunk-X7XLMSZX.js +44 -0
  216. package/dist/runner/chunk-X7XLMSZX.js.map +7 -0
  217. package/dist/runner/chunk-XSO3B4QN.js +124 -0
  218. package/dist/runner/chunk-XSO3B4QN.js.map +7 -0
  219. package/dist/runner/chunk-YGFN3LN2.js +174 -0
  220. package/dist/runner/chunk-YGFN3LN2.js.map +7 -0
  221. package/dist/runner/chunk-YHYDBLVB.js +33 -0
  222. package/dist/runner/chunk-YHYDBLVB.js.map +7 -0
  223. package/dist/runner/compact-36NP3PKT.js +60 -0
  224. package/dist/runner/compact-36NP3PKT.js.map +7 -0
  225. package/dist/runner/getMachineId-bsd-AGENNHN6.js +42 -0
  226. package/dist/runner/getMachineId-bsd-AGENNHN6.js.map +7 -0
  227. package/dist/runner/getMachineId-bsd-I5WZGCL4.js +33 -0
  228. package/dist/runner/getMachineId-bsd-I5WZGCL4.js.map +7 -0
  229. package/dist/runner/getMachineId-bsd-ZXK225P7.js +33 -0
  230. package/dist/runner/getMachineId-bsd-ZXK225P7.js.map +7 -0
  231. package/dist/runner/getMachineId-darwin-47GDLEXL.js +42 -0
  232. package/dist/runner/getMachineId-darwin-47GDLEXL.js.map +7 -0
  233. package/dist/runner/getMachineId-darwin-5CRLMDD6.js +33 -0
  234. package/dist/runner/getMachineId-darwin-5CRLMDD6.js.map +7 -0
  235. package/dist/runner/getMachineId-darwin-ADG4I32N.js +33 -0
  236. package/dist/runner/getMachineId-darwin-ADG4I32N.js.map +7 -0
  237. package/dist/runner/getMachineId-linux-5KVS3T2M.js +27 -0
  238. package/dist/runner/getMachineId-linux-5KVS3T2M.js.map +7 -0
  239. package/dist/runner/getMachineId-linux-GDFB5GSO.js +34 -0
  240. package/dist/runner/getMachineId-linux-GDFB5GSO.js.map +7 -0
  241. package/dist/runner/getMachineId-linux-NQMWCRO3.js +27 -0
  242. package/dist/runner/getMachineId-linux-NQMWCRO3.js.map +7 -0
  243. package/dist/runner/getMachineId-unsupported-5PFIGMVX.js +18 -0
  244. package/dist/runner/getMachineId-unsupported-5PFIGMVX.js.map +7 -0
  245. package/dist/runner/getMachineId-unsupported-DW27K3ZX.js +18 -0
  246. package/dist/runner/getMachineId-unsupported-DW27K3ZX.js.map +7 -0
  247. package/dist/runner/getMachineId-unsupported-XV3FHTHD.js +25 -0
  248. package/dist/runner/getMachineId-unsupported-XV3FHTHD.js.map +7 -0
  249. package/dist/runner/getMachineId-win-5JVMW3EI.js +44 -0
  250. package/dist/runner/getMachineId-win-5JVMW3EI.js.map +7 -0
  251. package/dist/runner/getMachineId-win-SNESQF7R.js +35 -0
  252. package/dist/runner/getMachineId-win-SNESQF7R.js.map +7 -0
  253. package/dist/runner/getMachineId-win-UJYHSBM2.js +35 -0
  254. package/dist/runner/getMachineId-win-UJYHSBM2.js.map +7 -0
  255. package/dist/runner/git-commit-BA53DOJQ.js +30 -0
  256. package/dist/runner/git-commit-BA53DOJQ.js.map +7 -0
  257. package/dist/runner/hook-runner-JHH6PGKE.js +220 -0
  258. package/dist/runner/hook-runner-JHH6PGKE.js.map +7 -0
  259. package/dist/runner/judge-transport-R4TF5LEH.js +91 -0
  260. package/dist/runner/judge-transport-R4TF5LEH.js.map +7 -0
  261. package/dist/runner/mcp-status-QEUH2KGX.js +89 -0
  262. package/dist/runner/mcp-status-QEUH2KGX.js.map +7 -0
  263. package/dist/runner/notification-FKMBCSXF.js +69 -0
  264. package/dist/runner/notification-FKMBCSXF.js.map +7 -0
  265. package/dist/runner/post-tool-3MRHTBKH.js +192 -0
  266. package/dist/runner/post-tool-3MRHTBKH.js.map +7 -0
  267. package/dist/runner/post-tool-agent-BB34MNHI.js +370 -0
  268. package/dist/runner/post-tool-agent-BB34MNHI.js.map +7 -0
  269. package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js +147 -0
  270. package/dist/runner/post-tool-changelog-sync-OP2TT2I7.js.map +7 -0
  271. package/dist/runner/post-tool-code-structure-LE7J2SC2.js +130 -0
  272. package/dist/runner/post-tool-code-structure-LE7J2SC2.js.map +7 -0
  273. package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js +30 -0
  274. package/dist/runner/post-tool-edit-ledger-IJMEYHKF.js.map +7 -0
  275. package/dist/runner/post-tool-failure-XTH2I2Z7.js +111 -0
  276. package/dist/runner/post-tool-failure-XTH2I2Z7.js.map +7 -0
  277. package/dist/runner/post-tool-git-E46HZGZO.js +94 -0
  278. package/dist/runner/post-tool-git-E46HZGZO.js.map +7 -0
  279. package/dist/runner/post-tool-mcp-AMCDY5GH.js +144 -0
  280. package/dist/runner/post-tool-mcp-AMCDY5GH.js.map +7 -0
  281. package/dist/runner/post-tool-task-state-TLDOI33H.js +100 -0
  282. package/dist/runner/post-tool-task-state-TLDOI33H.js.map +7 -0
  283. package/dist/runner/pre-tool-SQE2FZQO.js +245 -0
  284. package/dist/runner/pre-tool-SQE2FZQO.js.map +7 -0
  285. package/dist/runner/pre-tool-agent-OZUPVFUI.js +218 -0
  286. package/dist/runner/pre-tool-agent-OZUPVFUI.js.map +7 -0
  287. package/dist/runner/quality-evaluator-XYNDKDRG.js +901 -0
  288. package/dist/runner/quality-evaluator-XYNDKDRG.js.map +7 -0
  289. package/dist/runner/session-end-3MJTDLLA.js +57 -0
  290. package/dist/runner/session-end-3MJTDLLA.js.map +7 -0
  291. package/dist/runner/session-start-5ZMCLKBS.js +352 -0
  292. package/dist/runner/session-start-5ZMCLKBS.js.map +7 -0
  293. package/dist/runner/shipper-status-MADX6SPG.js +37 -0
  294. package/dist/runner/shipper-status-MADX6SPG.js.map +7 -0
  295. package/dist/runner/span-shipper-4HQDHC47.js +3408 -0
  296. package/dist/runner/span-shipper-4HQDHC47.js.map +7 -0
  297. package/dist/runner/stop-RTKSIYJV.js +596 -0
  298. package/dist/runner/stop-RTKSIYJV.js.map +7 -0
  299. package/dist/runner/subagent-CBCG4OLZ.js +116 -0
  300. package/dist/runner/subagent-CBCG4OLZ.js.map +7 -0
  301. package/dist/runner/token-metrics-AD2RAFGM.js +31 -0
  302. package/dist/runner/token-metrics-AD2RAFGM.js.map +7 -0
  303. package/dist/runner/user-prompt-T5NZ2UJD.js +376 -0
  304. package/dist/runner/user-prompt-T5NZ2UJD.js.map +7 -0
  305. package/package.json +68 -5
@@ -0,0 +1,157 @@
1
+ /** Agent PostToolUse; lazy-loaded by the router so builtin events never pay for its imports (HSF27). */
2
+ import { popPendingAgent } from '../lib/agent/agent-context.js';
3
+ import { tryInjectEvaluations } from '../lib/agent/agent-evaluations.js';
4
+ import { getAgentSourceType, agentInvocationAttributes } from '../lib/agent/agent-sources.js';
5
+ import { appendSynthSpans } from '../lib/agent/synth-spans.js';
6
+ import { writeStderr } from '../lib/core/format-utils.js';
7
+ import { TIME_MS, UNITS } from '../lib/core/units.js';
8
+ import { AGENT_ATTRS, ERROR_TYPE_ATTR, GENAI_AGENT_ATTRIBUTES, GENAI_DURATION_BUCKETS_S, GENAI_OPERATION, GENAI_PROVIDER_NAMES, SESSION_ATTRIBUTES, HOOK_TYPE_ATTR, HOOK_INSTRUMENTATION_ATTR, HOOK_INSTRUMENTATION_INTERNAL, GENAI_INVOKE_AGENT_DURATION_METRIC, HOOK_NAMES, } from '../lib/otel/attributes.js';
9
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
10
+ import { otelApi } from '../lib/otel/otel.js';
11
+ import { emitCoherenceHeuristic, extractCoherenceSignals } from '../lib/quality/quality-signals.js';
12
+ import { mentionsAgentError, mentionsRateLimit } from '../lib/runtime/output-analyzer.js';
13
+ import { spawnedAgentType } from '../lib/runtime/tool-input.js';
14
+ import { resolveOutputText } from '../lib/runtime/tool-output.js';
15
+ import { conversationIdOf } from '../lib/session/session-state.js';
16
+ const SYNTH_INSTANT_SPAN_DURATION_MS = TIME_MS.MS;
17
+ /** `error.type` values; `outputMentionsError` is deliberately not one — the invocation succeeded (AQ17). */
18
+ const AGENT_ERROR_TYPE = { RATE_LIMIT: 'rate_limit', AGENT_ERROR: 'agent_error' };
19
+ function agentErrorType(hasRateLimit, hasError) {
20
+ if (hasRateLimit)
21
+ return AGENT_ERROR_TYPE.RATE_LIMIT;
22
+ if (hasError)
23
+ return AGENT_ERROR_TYPE.AGENT_ERROR;
24
+ return undefined;
25
+ }
26
+ /** Builds the create_agent / invoke_agent synthetic spans and records the agent-duration metric. */
27
+ function emitAgentSynthSpans(ctx, pending, outcomeAttrs, invoc) {
28
+ const { attrs: invocAttrs, agentId } = invoc;
29
+ const errorType = agentErrorType(outcomeAttrs[AGENT_ATTRS.HAS_RATE_LIMIT], outcomeAttrs[AGENT_ATTRS.HAS_ERROR]);
30
+ const endTimeMs = Date.now();
31
+ const synthSpans = [];
32
+ // create_agent on the first invocation per session per agent. Identity attributes
33
+ // only: spreading invocAttrs here would overwrite the operation name with `invoke_agent`.
34
+ if (pending.isFirstSeen) {
35
+ synthSpans.push({
36
+ name: `${GENAI_OPERATION.CREATE_AGENT} ${pending.agentName}`,
37
+ kind: otelApi.SpanKind.CLIENT,
38
+ traceId: pending.traceId,
39
+ spanId: pending.createSpanId,
40
+ startTimeMs: pending.startTimeMs,
41
+ endTimeMs: pending.startTimeMs + SYNTH_INSTANT_SPAN_DURATION_MS,
42
+ attributes: {
43
+ [GENAI_AGENT_ATTRIBUTES.OPERATION_NAME]: GENAI_OPERATION.CREATE_AGENT,
44
+ [GENAI_AGENT_ATTRIBUTES.PROVIDER_NAME]: GENAI_PROVIDER_NAMES.ANTHROPIC,
45
+ [GENAI_AGENT_ATTRIBUTES.AGENT_NAME]: pending.agentName,
46
+ [GENAI_AGENT_ATTRIBUTES.AGENT_ID]: agentId,
47
+ [SESSION_ATTRIBUTES.SESSION_ID]: pending.sessionId,
48
+ },
49
+ });
50
+ }
51
+ // invoke_agent (pre-tool start → post-tool end). Parent is the dispatching agent's
52
+ // invokeSpanId under delegation (§12.10), else this agent's create_agent span.
53
+ const invokeParentSpanId = pending.parentAgentInvokeSpanId || pending.createSpanId;
54
+ const conversationId = conversationIdOf(pending.sessionId);
55
+ // OBP6: a link, not a parent, back to the dispatching span in the hook trace.
56
+ const dispatchLinks = pending.dispatchLink ? [pending.dispatchLink] : undefined;
57
+ synthSpans.push({
58
+ name: `${GENAI_OPERATION.INVOKE_AGENT} ${pending.agentName}`,
59
+ traceId: pending.traceId,
60
+ spanId: pending.invokeSpanId,
61
+ parentSpanId: invokeParentSpanId,
62
+ links: dispatchLinks,
63
+ startTimeMs: pending.startTimeMs,
64
+ endTimeMs,
65
+ attributes: {
66
+ ...invocAttrs,
67
+ [AGENT_ATTRS.INVOCATION_ID]: pending.invokeSpanId,
68
+ // After the spread, so the invocation span always says so.
69
+ [GENAI_AGENT_ATTRIBUTES.OPERATION_NAME]: GENAI_OPERATION.INVOKE_AGENT,
70
+ [SESSION_ATTRIBUTES.SESSION_ID]: pending.sessionId,
71
+ ...outcomeAttrs,
72
+ ...(conversationId ? { [SESSION_ATTRIBUTES.CONVERSATION_ID]: conversationId } : {}),
73
+ ...(errorType ? { [ERROR_TYPE_ATTR]: errorType } : {}),
74
+ },
75
+ ...(errorType ? { status: { code: otelApi.SpanStatusCode.ERROR, message: errorType } } : {}),
76
+ });
77
+ // No gen_ai.request.model: SHOULD NOT for agents with dynamic model selection.
78
+ ctx.recordMetric(GENAI_INVOKE_AGENT_DURATION_METRIC, (endTimeMs - pending.startTimeMs) / TIME_MS.SECOND, {
79
+ [GENAI_AGENT_ATTRIBUTES.AGENT_NAME]: pending.agentName,
80
+ ...(errorType ? { [ERROR_TYPE_ATTR]: errorType } : {}),
81
+ }, { unit: UNITS.SECOND, boundaries: GENAI_DURATION_BUCKETS_S.AGENT });
82
+ appendSynthSpans(synthSpans);
83
+ }
84
+ export async function handleAgentPostTool(input) {
85
+ const agentType = spawnedAgentType(input);
86
+ if (!agentType)
87
+ return;
88
+ const agentInfo = getAgentSourceType(agentType);
89
+ const invocation = agentInvocationAttributes(agentType, agentInfo, input.tool_input ?? {});
90
+ // Internal instrumentation; the GenAI-conformant span is the synthetic invoke_agent below (OBP6).
91
+ await instrumentHook(HOOK_NAMES.AGENT_FINALIZE, (ctx) => {
92
+ const sessionId = input.session_id;
93
+ const output = resolveOutputText(input);
94
+ const outputSize = output.length;
95
+ const hasRateLimit = mentionsRateLimit(output);
96
+ const hasError = !!input.is_error;
97
+ const outputMentionsError = !hasRateLimit && mentionsAgentError(output);
98
+ const coherenceSignals = extractCoherenceSignals(output);
99
+ const typeLabel = { [AGENT_ATTRS.TYPE]: agentType };
100
+ // Built once for this span and the synthetic invoke_agent span, so neither names nor values can drift.
101
+ const outcomeAttrs = {
102
+ [AGENT_ATTRS.OUTPUT_SIZE]: outputSize,
103
+ [AGENT_ATTRS.HAS_ERROR]: hasError,
104
+ [AGENT_ATTRS.HAS_RATE_LIMIT]: hasRateLimit,
105
+ [AGENT_ATTRS.OUTPUT_HAS_STRUCTURE]: coherenceSignals.hasStructure,
106
+ [AGENT_ATTRS.OUTPUT_HAS_CODE]: coherenceSignals.hasCode,
107
+ [AGENT_ATTRS.OUTPUT_TRUNCATED]: coherenceSignals.truncated,
108
+ [AGENT_ATTRS.OUTPUT_EMPTY]: coherenceSignals.empty,
109
+ };
110
+ ctx.addAttributes({
111
+ ...typeLabel,
112
+ ...outcomeAttrs,
113
+ [AGENT_ATTRS.OUTPUT_MENTIONS_ERROR]: outputMentionsError,
114
+ [AGENT_ATTRS.OUTPUT_HAS_ACTIONS]: coherenceSignals.hasActions,
115
+ // No `gen_ai.operation.name` (OBP6).
116
+ ...invocation.attrs,
117
+ });
118
+ emitCoherenceHeuristic(coherenceSignals, agentType, sessionId);
119
+ if (hasRateLimit) {
120
+ ctx.recordEvent('integritystudio.agent.rate_limit', typeLabel);
121
+ ctx.logger.warn('Agent hit rate limit', typeLabel);
122
+ writeStderr(`[Agent] ${agentType} hit rate limit — consider retry with backoff`);
123
+ }
124
+ else if (hasError) {
125
+ ctx.logger.warn('Agent completed with errors', {
126
+ ...typeLabel,
127
+ [AGENT_ATTRS.OUTPUT_SIZE]: outputSize,
128
+ });
129
+ writeStderr(`[Agent] ${agentType} completed with errors`);
130
+ }
131
+ else {
132
+ ctx.logger.info('Agent completed', {
133
+ ...typeLabel,
134
+ [AGENT_ATTRS.OUTPUT_SIZE]: outputSize,
135
+ ...(outputMentionsError ? { [AGENT_ATTRS.OUTPUT_MENTIONS_ERROR]: true } : {}),
136
+ });
137
+ writeStderr(`[Agent] ${agentType} completed`);
138
+ }
139
+ ctx.recordMetric('integritystudio.agent.completions', 1, {
140
+ ...typeLabel,
141
+ [AGENT_ATTRS.SOURCE_TYPE]: agentInfo.sourceType,
142
+ [AGENT_ATTRS.HAS_RATE_LIMIT]: String(hasRateLimit),
143
+ [AGENT_ATTRS.HAS_ERROR]: String(hasError),
144
+ [AGENT_ATTRS.OUTPUT_MENTIONS_ERROR]: String(outputMentionsError),
145
+ }, { unit: UNITS.COMPLETION });
146
+ ctx.recordMetric(AGENT_ATTRS.OUTPUT_SIZE, outputSize, typeLabel, { unit: UNITS.BYTE });
147
+ if (!hasError && !hasRateLimit) {
148
+ tryInjectEvaluations(agentType, output, sessionId);
149
+ }
150
+ const pending = popPendingAgent(sessionId, agentType, input.tool_use_id);
151
+ if (!pending)
152
+ return;
153
+ // Same id as the pre-tool span, so Q4 pairs the two by exact id, not FIFO (AGQ1).
154
+ ctx.addAttribute(AGENT_ATTRS.INVOCATION_ID, pending.invokeSpanId);
155
+ emitAgentSynthSpans(ctx, pending, outcomeAttrs, invocation);
156
+ }, { [HOOK_TYPE_ATTR]: 'agent', [HOOK_INSTRUMENTATION_ATTR]: HOOK_INSTRUMENTATION_INTERNAL });
157
+ }
@@ -0,0 +1,148 @@
1
+ /**
2
+ * Points README.md's [Changelog] link at the newest docs/changelog/<version>/
3
+ * when one appears via Write or `mkdir`.
4
+ */
5
+ import { readdir, readFile, writeFile } from 'node:fs/promises';
6
+ import { join } from 'node:path';
7
+ import { CHANGELOG_DIR_SEGMENT } from '../lib/core/constants.js';
8
+ import { escapeRegExp } from '../lib/core/regex.js';
9
+ import { commandInvocations, isOptionArg, programOf } from '../lib/core/shell-command.js';
10
+ import { UNITS } from '../lib/core/units.js';
11
+ import { HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
12
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
13
+ import { addAdditionalContext } from '../lib/runtime/hook-output.js';
14
+ import { getStringField } from '../lib/runtime/tool-input.js';
15
+ const CHANGELOG_FILE = 'CHANGELOG.md';
16
+ const CHANGELOG_DIR_SOURCE = escapeRegExp(CHANGELOG_DIR_SEGMENT);
17
+ /** The version segment of a changelog path, trailing slash optional (`mkdir docs/changelog/1.2`). */
18
+ const CHANGELOG_VERSION_PATTERN = new RegExp(`${CHANGELOG_DIR_SOURCE}([^/]+)`);
19
+ /** The Write form: a file follows the version directory, so `docs/changelog/README.md` names no version. */
20
+ const CHANGELOG_PATH_PATTERN = new RegExp(`${CHANGELOG_VERSION_PATTERN.source}/`);
21
+ const changelogLink = (version) => `[Changelog](${CHANGELOG_DIR_SEGMENT}${version}/${CHANGELOG_FILE})`;
22
+ const CHANGELOG_LINK_PATTERN = new RegExp(`\\[Changelog\\]\\(${CHANGELOG_DIR_SOURCE}([^/]+)/${escapeRegExp(CHANGELOG_FILE)}\\)`);
23
+ const MKDIR_PROGRAM = 'mkdir';
24
+ const VERSION_SEGMENT_PATTERN = /^[a-zA-Z0-9._-]+$/;
25
+ const README_FILE = 'README.md';
26
+ /** Which route produced the version directory; the span's `changelog.trigger`. */
27
+ const TRIGGER = { WRITE: 'write', MKDIR: 'mkdir' };
28
+ /** The version segment the README's changelog link points to, or undefined. */
29
+ export function getReadmeVersion(readme) {
30
+ return readme.match(CHANGELOG_LINK_PATTERN)?.[1];
31
+ }
32
+ const VERSION_PREFIX = /^v/i;
33
+ const compareNumericRuns = new Intl.Collator('en', { numeric: true }).compare;
34
+ /** Orders digit runs numerically and ignores a leading `v`, so "1.9" < "v1.10" < "2.0". */
35
+ function compareVersions(a, b) {
36
+ return compareNumericRuns(a.replace(VERSION_PREFIX, ''), b.replace(VERSION_PREFIX, ''));
37
+ }
38
+ function readmePathOf(projectRoot) {
39
+ return join(projectRoot, README_FILE);
40
+ }
41
+ async function findLatestVersion(changelogDir) {
42
+ try {
43
+ const entries = await readdir(changelogDir, { withFileTypes: true });
44
+ const versions = entries
45
+ .filter(d => d.isDirectory() && VERSION_SEGMENT_PATTERN.test(d.name))
46
+ .map(d => d.name)
47
+ .sort(compareVersions);
48
+ return versions[versions.length - 1];
49
+ }
50
+ catch {
51
+ return undefined;
52
+ }
53
+ }
54
+ /** The part of `path` before `docs/changelog/`, minus its trailing slash; '' when it starts there. */
55
+ function pathBeforeChangelogDir(path) {
56
+ return path.substring(0, path.indexOf(CHANGELOG_DIR_SEGMENT)).replace(/\/$/, '');
57
+ }
58
+ /** The well-formed version segment `pattern` captures from `path`; a match guarantees the path contains CHANGELOG_DIR_SEGMENT. */
59
+ function changelogVersionOf(path, pattern) {
60
+ const version = path.match(pattern)?.[1];
61
+ return version && VERSION_SEGMENT_PATTERN.test(version) ? version : undefined;
62
+ }
63
+ function parseWritePath(input) {
64
+ if (input.tool_name !== 'Write')
65
+ return;
66
+ const filePath = getStringField(input, 'file_path');
67
+ if (!filePath)
68
+ return;
69
+ const version = changelogVersionOf(filePath, CHANGELOG_PATH_PATTERN);
70
+ if (!version)
71
+ return;
72
+ return { version, projectRoot: pathBeforeChangelogDir(filePath) || '.', trigger: TRIGGER.WRITE };
73
+ }
74
+ /**
75
+ * Compared against the README, not the directory's entry count: a previously-synced
76
+ * dir still has one file and would falsely re-fire. Applied to both routes, or
77
+ * backfilling an older version rewrites the tracked README.
78
+ */
79
+ function isNewerThanReadme(version, readme) {
80
+ const currentVersion = readme === null ? undefined : getReadmeVersion(readme);
81
+ return !currentVersion || compareVersions(currentVersion, version) < 0;
82
+ }
83
+ export function parseMkdirCommand(input) {
84
+ if (input.tool_name !== 'Bash')
85
+ return;
86
+ const command = getStringField(input, 'command');
87
+ if (!command)
88
+ return;
89
+ // The path must be an argument of mkdir itself, not of a later command on the line (HSF18).
90
+ const fullPath = commandInvocations(command)
91
+ .filter((argv) => programOf(argv) === MKDIR_PROGRAM)
92
+ .flatMap((argv) => argv.slice(1))
93
+ .find((arg) => !isOptionArg(arg) && arg.includes(CHANGELOG_DIR_SEGMENT));
94
+ if (!fullPath)
95
+ return;
96
+ const version = changelogVersionOf(fullPath, CHANGELOG_VERSION_PATTERN);
97
+ if (!version)
98
+ return;
99
+ const projectRoot = pathBeforeChangelogDir(fullPath) || input.cwd;
100
+ return { version, projectRoot, trigger: TRIGGER.MKDIR };
101
+ }
102
+ /** `readme` is null when README.md is missing or unreadable. */
103
+ async function syncReadmeLink({ version, projectRoot, trigger }, readme) {
104
+ await instrumentHook(HOOK_NAMES.CHANGELOG_VERSION_BUMP, async (ctx) => {
105
+ ctx.addAttributes({
106
+ 'integritystudio.changelog.version': version,
107
+ 'integritystudio.changelog.trigger': trigger,
108
+ });
109
+ if (readme === null)
110
+ return;
111
+ // Undefined for a missing or unreadable changelog dir too.
112
+ const latestVersion = await findLatestVersion(join(projectRoot, CHANGELOG_DIR_SEGMENT));
113
+ if (!latestVersion)
114
+ return;
115
+ const changelogLinkMatch = readme.match(CHANGELOG_LINK_PATTERN);
116
+ if (!changelogLinkMatch) {
117
+ ctx.addAttribute('integritystudio.changelog.readme_link_found', false);
118
+ return;
119
+ }
120
+ const newLink = changelogLink(latestVersion);
121
+ if (changelogLinkMatch[0] === newLink) {
122
+ ctx.addAttribute('integritystudio.changelog.readme_already_current', true);
123
+ return;
124
+ }
125
+ const updatedReadme = readme.replace(CHANGELOG_LINK_PATTERN, newLink);
126
+ const readmePath = readmePathOf(projectRoot);
127
+ await writeFile(readmePath, updatedReadme, 'utf-8');
128
+ ctx.addAttributes({
129
+ 'integritystudio.changelog.readme_link_found': true,
130
+ 'integritystudio.changelog.readme_updated': true,
131
+ 'integritystudio.changelog.latest_version': latestVersion,
132
+ 'integritystudio.changelog.previous_link': changelogLinkMatch[0],
133
+ });
134
+ ctx.recordMetric('integritystudio.changelog.readme_syncs', 1, undefined, { unit: UNITS.SYNC });
135
+ // This edits a tracked file unasked; stderr at exit 0 reaches nobody (CCH0), so announce via additionalContext (HRV11).
136
+ addAdditionalContext(`[changelog-version-bump] Rewrote the changelog link in ${readmePath} ` +
137
+ `from ${changelogLinkMatch[0]} to ${newLink}. Include README.md in the commit, or revert it if unwanted.`);
138
+ }, { [HOOK_TYPE_ATTR]: 'changelog-version-bump' });
139
+ }
140
+ export async function handleChangelogVersionBump(input) {
141
+ const parsed = parseWritePath(input) ?? parseMkdirCommand(input);
142
+ if (!parsed)
143
+ return;
144
+ const readme = await readFile(readmePathOf(parsed.projectRoot), 'utf-8').catch(() => null);
145
+ if (!isNewerThanReadme(parsed.version, readme))
146
+ return;
147
+ await syncReadmeLink(parsed, readme);
148
+ }
@@ -0,0 +1,116 @@
1
+ /**
2
+ * Code structure score for written JS/TS, telemetry only. Write is scored whole;
3
+ * Edit/MultiEdit see only the new text, so they are scored `isPartial` on the two
4
+ * signals a fragment supports (nesting and types).
5
+ */
6
+ import { THRESHOLDS } from '../lib/core/constants.js';
7
+ import { roundTo } from '../lib/core/units.js';
8
+ import { CODE_STRUCTURE_SCORE, HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
9
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
10
+ import { isJsTsFile } from '../lib/runtime/categorizers.js';
11
+ import { getStringField, getWrittenText, isEditTool } from '../lib/runtime/tool-input.js';
12
+ /** Nesting bands: the first band whose `maxDepth` covers the file sets the score */
13
+ const NESTING_BANDS = [
14
+ { maxDepth: 3, score: 1.0 },
15
+ { maxDepth: 5, score: 0.7 },
16
+ { maxDepth: 8, score: 0.4 },
17
+ ];
18
+ const NESTING_FLOOR_SCORE = 0.2;
19
+ /** Whole-file weights; they sum to 1 */
20
+ const WEIGHTS = { modularity: 0.25, complexity: 0.25, types: 0.20, organization: 0.15, size: 0.15 };
21
+ /** Fragment weights: only nesting and types are meaningful on a partial edit */
22
+ const PARTIAL_WEIGHTS = { complexity: 0.5, types: 0.5 };
23
+ const TYPE_PATTERNS = [
24
+ /:\s*(string|number|boolean|void|any|unknown|never|Record|Array|Promise|null|undefined)\b/,
25
+ /\binterface\s/,
26
+ /\btype\s+\w+\s*=/,
27
+ ];
28
+ const SIZE = { minLines: 5, maxLines: 500, tooSmallScore: 0.3, tooLargeScore: 0.5, fitScore: 1.0 };
29
+ /** Scores are reported to two decimal places */
30
+ const SCORE_PRECISION = 100;
31
+ const OPEN_BRACE = '{'.charCodeAt(0);
32
+ const CLOSE_BRACE = '}'.charCodeAt(0);
33
+ const NEWLINE = '\n'.charCodeAt(0);
34
+ const countMatches = (content, pattern) => (content.match(pattern) ?? []).length;
35
+ /** Line count and max brace nesting depth in one pass; unbalanced `}` clamps at 0 */
36
+ function scanLinesAndNesting(content) {
37
+ let lines = 1;
38
+ let maxNesting = 0;
39
+ let current = 0;
40
+ for (let i = 0; i < content.length; i++) {
41
+ const code = content.charCodeAt(i);
42
+ if (code === NEWLINE)
43
+ lines++;
44
+ else if (code === OPEN_BRACE)
45
+ maxNesting = Math.max(maxNesting, ++current);
46
+ else if (code === CLOSE_BRACE)
47
+ current = Math.max(0, current - 1);
48
+ }
49
+ return { lines, maxNesting };
50
+ }
51
+ const sizeScore = (lines) => lines < SIZE.minLines ? SIZE.tooSmallScore
52
+ : lines > SIZE.maxLines ? SIZE.tooLargeScore
53
+ : SIZE.fitScore;
54
+ function wholeFileScore(counts, nestingScore, typeScore) {
55
+ const { exports, functions, imports, lines } = counts;
56
+ const modRatio = functions > 0 ? Math.min(exports / functions, 1) : Number(exports > 0);
57
+ return WEIGHTS.modularity * modRatio +
58
+ WEIGHTS.complexity * nestingScore +
59
+ WEIGHTS.types * typeScore +
60
+ WEIGHTS.organization * Number(imports > 0) +
61
+ WEIGHTS.size * sizeScore(lines);
62
+ }
63
+ export function computeStructureSignals(content, isPartial) {
64
+ if (content.length > THRESHOLDS.CODE_STRUCTURE_SKIP_ABOVE_BYTES) {
65
+ return {
66
+ lines: 0, exports: 0, functions: 0, imports: 0,
67
+ maxNesting: 0, hasTypes: false, isPartial, score: 0,
68
+ contentBytes: content.length,
69
+ };
70
+ }
71
+ const exports = countMatches(content, /\bexport\s/g);
72
+ const functions = countMatches(content, /\bfunction\b/g) + countMatches(content, /=>/g);
73
+ const imports = countMatches(content, /\bimport\s/g);
74
+ const { lines, maxNesting } = scanLinesAndNesting(content);
75
+ const hasTypes = TYPE_PATTERNS.some((pattern) => pattern.test(content));
76
+ const nestingScore = NESTING_BANDS.find((band) => maxNesting <= band.maxDepth)?.score ?? NESTING_FLOOR_SCORE;
77
+ const typeScore = Number(hasTypes);
78
+ const raw = isPartial
79
+ ? PARTIAL_WEIGHTS.complexity * nestingScore + PARTIAL_WEIGHTS.types * typeScore
80
+ : wholeFileScore({ exports, functions, imports, lines }, nestingScore, typeScore);
81
+ const score = roundTo(raw, SCORE_PRECISION);
82
+ return { lines, exports, functions, imports, maxNesting, hasTypes, isPartial, score };
83
+ }
84
+ export async function handleCodeStructure(input) {
85
+ const toolName = input.tool_name;
86
+ const filePath = getStringField(input, 'file_path');
87
+ if (!filePath || !isJsTsFile(filePath) || !isEditTool(toolName))
88
+ return;
89
+ const written = getWrittenText(input.tool_input, toolName);
90
+ if (!written)
91
+ return;
92
+ await instrumentHook(HOOK_NAMES.CODE_STRUCTURE, (ctx) => {
93
+ const signals = computeStructureSignals(written.text, written.isPartial);
94
+ const skippedForSize = signals.contentBytes !== undefined;
95
+ ctx.addAttributes({
96
+ 'integritystudio.code.structure.lines': signals.lines,
97
+ 'integritystudio.code.structure.exports': signals.exports,
98
+ 'integritystudio.code.structure.functions': signals.functions,
99
+ 'integritystudio.code.structure.imports': signals.imports,
100
+ 'integritystudio.code.structure.max_nesting': signals.maxNesting,
101
+ 'integritystudio.code.structure.has_types': signals.hasTypes,
102
+ 'integritystudio.code.structure.is_partial': signals.isPartial,
103
+ [CODE_STRUCTURE_SCORE]: signals.score,
104
+ 'integritystudio.code.structure.file': filePath,
105
+ 'integritystudio.code.structure.tool': toolName,
106
+ ...(skippedForSize ? { 'integritystudio.code.structure.content_bytes': signals.contentBytes } : {}),
107
+ });
108
+ // No unit: an arbitrary 0–1 index, not a measured fraction. No metric when skipped for size (HSF8).
109
+ if (!skippedForSize) {
110
+ ctx.recordMetric(CODE_STRUCTURE_SCORE, signals.score, {
111
+ 'integritystudio.code.structure.tool': toolName,
112
+ 'integritystudio.code.structure.is_partial': String(signals.isPartial),
113
+ });
114
+ }
115
+ }, { [HOOK_TYPE_ATTR]: 'code-structure' });
116
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Edit ledger: every Write/Edit/MultiEdit with the agent that made it.
3
+ * Main-loop edits carry no agent; a forked skill runs as
4
+ * `general-purpose`, so it is recorded as `skill:<name>` instead (CSV1).
5
+ */
6
+ import { getStringField } from '../lib/runtime/tool-input.js';
7
+ import { MAIN_LOOP_AGENT, logEdit } from '../lib/session/edit-ledger.js';
8
+ import { resolveAgentName } from '../lib/session/forked-skill.js';
9
+ export function handleEditLedger(input) {
10
+ const filePath = getStringField(input, 'file_path');
11
+ if (!filePath)
12
+ return;
13
+ const agent = resolveAgentName(input) ?? MAIN_LOOP_AGENT;
14
+ logEdit(input.session_id, input.tool_name, agent, filePath);
15
+ }
@@ -0,0 +1,83 @@
1
+ /**
2
+ * PostToolUseFailure (CCH4): Claude Code's own failure report, ground truth
3
+ * beside the `analyzeBuiltinOutput` heuristic that still runs on the success
4
+ * path — comparing the two is how the heuristic's error rate is measured.
5
+ */
6
+ import { ELLIPSIS, THRESHOLDS, UNKNOWN_TOOL_CATEGORY } from '../lib/core/constants.js';
7
+ import { truncate } from '../lib/core/format-utils.js';
8
+ import { UNITS } from '../lib/core/units.js';
9
+ import { GENAI_TOOL_NAME_ATTR, GENAI_TOOL_CALL_ID_ATTR, HOOK_NAMES, HOOK_TYPE_ATTR, TOOL_ATTRS } from '../lib/otel/attributes.js';
10
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
11
+ import { classifyError } from '../lib/runtime/output-analyzer.js';
12
+ import { mayRunGitCommit, spawnedAgentType } from '../lib/runtime/tool-input.js';
13
+ import { routeToolEvent } from './tool-event-router.js';
14
+ const INTERRUPT = 'interrupt';
15
+ /** An interrupt is not a tool defect; classifying its leftover text would inflate the failure rate. */
16
+ function classifyToolFailure(error, isInterrupt) {
17
+ if (isInterrupt)
18
+ return { errorType: INTERRUPT, errorCategory: INTERRUPT };
19
+ return classifyError(error, 'head-tail');
20
+ }
21
+ /** A failed dispatch never reaches post-tool-agent, and its record would be read as the next agent's parent until the TTL. */
22
+ async function discardPendingAgent(input) {
23
+ const agentType = spawnedAgentType(input);
24
+ if (!agentType)
25
+ return;
26
+ const { popPendingAgent } = await import('../lib/agent/agent-context.js');
27
+ popPendingAgent(input.session_id, agentType, input.tool_use_id);
28
+ }
29
+ async function instrumentFailure(input, category, agentPredispatch) {
30
+ await instrumentHook(HOOK_NAMES.POST_TOOL_FAILURE, async (ctx) => {
31
+ const toolName = input.tool_name;
32
+ const error = input.error ?? '';
33
+ const isInterrupt = !!input.is_interrupt;
34
+ const { errorType, errorCategory } = classifyToolFailure(error, isInterrupt);
35
+ const errorSnippet = truncate(error, THRESHOLDS.ERROR_MESSAGE_TRUNCATE, ELLIPSIS);
36
+ if (mayRunGitCommit(input)) {
37
+ const { discardCommitHeadSnapshot } = await import('../lib/git/git-commit.js');
38
+ discardCommitHeadSnapshot(input);
39
+ }
40
+ await agentPredispatch?.();
41
+ ctx.addAttributes({
42
+ [GENAI_TOOL_NAME_ATTR]: toolName,
43
+ [TOOL_ATTRS.ROUTER_CATEGORY]: category,
44
+ [GENAI_TOOL_CALL_ID_ATTR]: input.tool_use_id ?? '',
45
+ [TOOL_ATTRS.ERROR_TYPE]: errorType,
46
+ [TOOL_ATTRS.ERROR_CATEGORY]: errorCategory,
47
+ [TOOL_ATTRS.IS_INTERRUPT]: isInterrupt,
48
+ [TOOL_ATTRS.ERROR]: errorSnippet,
49
+ });
50
+ if (typeof input.duration_ms === 'number') {
51
+ ctx.addAttribute(TOOL_ATTRS.DURATION_MS, input.duration_ms);
52
+ // Claude Code's own timing: the one tool duration that is neither synthesised nor estimated.
53
+ ctx.recordMetric('integritystudio.tool.failure_duration', input.duration_ms, {
54
+ [GENAI_TOOL_NAME_ATTR]: toolName,
55
+ }, {
56
+ unit: UNITS.MILLISECOND,
57
+ });
58
+ }
59
+ ctx.logger.warn('Tool call failed', {
60
+ [GENAI_TOOL_NAME_ATTR]: toolName,
61
+ [TOOL_ATTRS.ERROR_TYPE]: errorType,
62
+ [TOOL_ATTRS.ERROR]: errorSnippet,
63
+ });
64
+ ctx.recordMetric('integritystudio.tool.failures', 1, {
65
+ [GENAI_TOOL_NAME_ATTR]: toolName,
66
+ [TOOL_ATTRS.ROUTER_CATEGORY]: category,
67
+ [TOOL_ATTRS.ERROR_CATEGORY]: errorCategory,
68
+ [TOOL_ATTRS.IS_INTERRUPT]: String(isInterrupt),
69
+ }, { unit: UNITS.FAILURE });
70
+ }, { [HOOK_TYPE_ATTR]: 'tool-failure' });
71
+ }
72
+ export async function handlePostToolFailure(input) {
73
+ await routeToolEvent(input, undefined, {
74
+ mcp: () => instrumentFailure(input, 'mcp'),
75
+ plugin: () => instrumentFailure(input, 'plugin'),
76
+ agent: () => instrumentFailure(input, 'agent', () => discardPendingAgent(input)),
77
+ builtin: () => instrumentFailure(input, 'builtin'),
78
+ // CCH7 drift signal already fires on PreToolUse and successful PostToolUse;
79
+ // skip it here so a failing unknown tool does not double-count.
80
+ signalDrift: false,
81
+ unknown: () => instrumentFailure(input, UNKNOWN_TOOL_CATEGORY),
82
+ });
83
+ }
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Post-commit handler, called by post-tool.ts only when a `git commit` landed
3
+ * (HSF11): the code-review prompt, once per commit SHA, skipped for commits of only
4
+ * Markdown.
5
+ * It reaches Claude via `additionalContext`; PostToolUse stdout is debug-log only.
6
+ */
7
+ import { join } from 'node:path';
8
+ import { UNITS } from '../lib/core/units.js';
9
+ // commandOf reads `command` without checking tool_name: only the Bash router arm
10
+ // reaches this handler, so the tool is already known.
11
+ import { commandOf, UNBORN_HEAD } from '../lib/git/git-commit.js';
12
+ import { GIT_ATTRIBUTES, GIT_METRICS, HOOK_NAMES, HOOK_TYPE_ATTR } from '../lib/otel/attributes.js';
13
+ import { instrumentHook } from '../lib/otel/otel-monitor.js';
14
+ import { addAdditionalContext } from '../lib/runtime/hook-output.js';
15
+ import { claimOnce, sessionMarkerPath } from '../lib/session/session-state.js';
16
+ /** The one extension a commit may consist solely of and still skip code review */
17
+ const DOCS_ONLY_EXTENSION = '.md';
18
+ /** Cap on file names carried on the commit span; `files_changed` still carries the full count. */
19
+ const MAX_COMMITTED_FILES_RECORDED = 200;
20
+ const isMarkdown = (file) => file.toLowerCase().endsWith(DOCS_ONLY_EXTENSION);
21
+ /** An empty list is NOT docs-only: it means git had no answer, and the review must still run. */
22
+ export function isDocsOnlyCommit(files) {
23
+ return files.length > 0 && files.every(isMarkdown);
24
+ }
25
+ /** Kept apart from the span name: renaming the span must not re-fire every past commit's review. */
26
+ const REVIEW_MARKER_DIRNAME = 'post-commit-review';
27
+ /** Leads the one-line prompt; tests detect the prompt by it. code-reviewer's own manifest carries the checklist. */
28
+ export const REVIEW_PROMPT_PREFIX = 'Post-commit review:';
29
+ /** git's well-known empty tree, so `git diff <it>..HEAD` shows a new repo's whole history. */
30
+ const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
31
+ /** The diff the reviewer reads: the last commit, or every commit the command made. */
32
+ function reviewDiffCommand(commit) {
33
+ if (commit.base === undefined)
34
+ return 'git diff HEAD~1';
35
+ const base = commit.base === UNBORN_HEAD ? EMPTY_TREE_SHA : commit.base;
36
+ return `git diff ${base}..HEAD`;
37
+ }
38
+ // No jitter here: this only queues text, and a sleep sits on the blocking path (CCH1b).
39
+ export async function handlePostCommitReview(input, commit) {
40
+ await instrumentHook(HOOK_NAMES.POST_COMMIT_REVIEW, (ctx) => {
41
+ const command = commandOf(input);
42
+ ctx.addAttributes({ [GIT_ATTRIBUTES.COMMAND]: command });
43
+ // Judged over every commit the command made: /git-commit-smart ends with a docs
44
+ // commit, so HEAD alone would read docs-only after a source commit.
45
+ const { commandFiles: files, outcome } = commit;
46
+ const docsOnly = isDocsOnlyCommit(files);
47
+ ctx.addAttributes({
48
+ [GIT_ATTRIBUTES.COMMIT_COUNT]: commit.commitCount,
49
+ [GIT_ATTRIBUTES.FILES_CHANGED]: files.length,
50
+ [GIT_ATTRIBUTES.FILES_OUTCOME]: outcome,
51
+ [GIT_ATTRIBUTES.DOCS_ONLY]: docsOnly,
52
+ // Names, not only the count: the one per-file record a Bash-driven edit leaves.
53
+ [GIT_ATTRIBUTES.FILES]: files.slice(0, MAX_COMMITTED_FILES_RECORDED),
54
+ [GIT_ATTRIBUTES.FILES_TRUNCATED]: files.length > MAX_COMMITTED_FILES_RECORDED,
55
+ });
56
+ const skip = (reason) => {
57
+ ctx.logger.info('Skipping post-commit code review', {
58
+ [GIT_ATTRIBUTES.COMMAND]: command,
59
+ [GIT_ATTRIBUTES.FILES_CHANGED]: files.length,
60
+ [GIT_ATTRIBUTES.REVIEW_SKIP_REASON]: reason,
61
+ });
62
+ ctx.recordMetric(GIT_METRICS.COMMITS_REVIEW_SKIPPED, 1, { [GIT_ATTRIBUTES.REVIEW_SKIP_REASON]: reason }, { unit: UNITS.SKIP });
63
+ };
64
+ if (docsOnly) {
65
+ skip('docs_only');
66
+ return;
67
+ }
68
+ // Keyed by HEAD's SHA, so a commit seen twice (fast path and quiet path, or a
69
+ // re-fired hook) is reviewed once. No SHA, or an unwritable marker, still reviews.
70
+ const markerName = commit.commit && join(REVIEW_MARKER_DIRNAME, commit.commit);
71
+ if (markerName && !claimOnce(sessionMarkerPath(input.session_id, markerName), { onWriteError: 'grant' })) {
72
+ skip('already_reviewed');
73
+ return;
74
+ }
75
+ ctx.logger.info('Git commit detected, requesting code review', { [GIT_ATTRIBUTES.COMMAND]: command });
76
+ ctx.recordMetric(GIT_METRICS.COMMITS_REVIEWED, 1, undefined, { unit: UNITS.COMMIT });
77
+ addAdditionalContext(`${REVIEW_PROMPT_PREFIX} run code-reviewer on \`${reviewDiffCommand(commit)}\`.`);
78
+ }, { [HOOK_TYPE_ATTR]: HOOK_NAMES.POST_COMMIT_REVIEW });
79
+ }