@agent-watch-ai/edge 0.2.5

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 (364) hide show
  1. package/CHANGELOG.md +251 -0
  2. package/LICENSE +21 -0
  3. package/README.md +168 -0
  4. package/dist/billing/billing-mode.d.ts +16 -0
  5. package/dist/billing/billing-mode.js +139 -0
  6. package/dist/billing/constants/billing.constants.d.ts +37 -0
  7. package/dist/billing/constants/billing.constants.js +38 -0
  8. package/dist/billing/index.d.ts +6 -0
  9. package/dist/billing/index.js +6 -0
  10. package/dist/cli/args.d.ts +29 -0
  11. package/dist/cli/args.js +61 -0
  12. package/dist/cli/constants/cli.constants.d.ts +60 -0
  13. package/dist/cli/constants/cli.constants.js +60 -0
  14. package/dist/cli/context.d.ts +51 -0
  15. package/dist/cli/context.js +108 -0
  16. package/dist/cli/doctor.d.ts +15 -0
  17. package/dist/cli/doctor.js +416 -0
  18. package/dist/cli/hook.d.ts +20 -0
  19. package/dist/cli/hook.js +166 -0
  20. package/dist/cli/index.d.ts +13 -0
  21. package/dist/cli/index.js +8 -0
  22. package/dist/cli/misc.d.ts +31 -0
  23. package/dist/cli/misc.js +63 -0
  24. package/dist/cli/setup.d.ts +32 -0
  25. package/dist/cli/setup.js +298 -0
  26. package/dist/cli/status.d.ts +11 -0
  27. package/dist/cli/status.js +174 -0
  28. package/dist/cli/types/cli.types.d.ts +69 -0
  29. package/dist/cli/types/cli.types.js +1 -0
  30. package/dist/cli/ui.d.ts +41 -0
  31. package/dist/cli/ui.js +78 -0
  32. package/dist/cli/uninstall.d.ts +13 -0
  33. package/dist/cli/uninstall.js +83 -0
  34. package/dist/cli.d.ts +2 -0
  35. package/dist/cli.js +124 -0
  36. package/dist/config/config-store.d.ts +29 -0
  37. package/dist/config/config-store.js +75 -0
  38. package/dist/config/config.d.ts +73 -0
  39. package/dist/config/config.js +115 -0
  40. package/dist/config/constants/config.constants.d.ts +62 -0
  41. package/dist/config/constants/config.constants.js +70 -0
  42. package/dist/config/index.d.ts +10 -0
  43. package/dist/config/index.js +5 -0
  44. package/dist/config/repo-config.d.ts +37 -0
  45. package/dist/config/repo-config.js +178 -0
  46. package/dist/config/schemas/config.schema.d.ts +409 -0
  47. package/dist/config/schemas/config.schema.js +97 -0
  48. package/dist/config/types/config.types.d.ts +33 -0
  49. package/dist/config/types/config.types.js +1 -0
  50. package/dist/core/async.d.ts +20 -0
  51. package/dist/core/async.js +32 -0
  52. package/dist/core/constants/core.constants.d.ts +18 -0
  53. package/dist/core/constants/core.constants.js +18 -0
  54. package/dist/core/env.d.ts +12 -0
  55. package/dist/core/env.js +20 -0
  56. package/dist/core/index.d.ts +13 -0
  57. package/dist/core/index.js +8 -0
  58. package/dist/core/logger.d.ts +27 -0
  59. package/dist/core/logger.js +82 -0
  60. package/dist/core/number.d.ts +33 -0
  61. package/dist/core/number.js +47 -0
  62. package/dist/core/object.d.ts +78 -0
  63. package/dist/core/object.js +127 -0
  64. package/dist/core/pipe.d.ts +55 -0
  65. package/dist/core/pipe.js +81 -0
  66. package/dist/core/types/core.types.d.ts +54 -0
  67. package/dist/core/types/core.types.js +4 -0
  68. package/dist/core/version.d.ts +19 -0
  69. package/dist/core/version.js +35 -0
  70. package/dist/core/which.d.ts +13 -0
  71. package/dist/core/which.js +57 -0
  72. package/dist/enforcement/constants/enforcement.constants.d.ts +23 -0
  73. package/dist/enforcement/constants/enforcement.constants.js +22 -0
  74. package/dist/enforcement/decision-cache.d.ts +57 -0
  75. package/dist/enforcement/decision-cache.js +138 -0
  76. package/dist/enforcement/decision-client.d.ts +14 -0
  77. package/dist/enforcement/decision-client.js +84 -0
  78. package/dist/enforcement/enforcement.d.ts +17 -0
  79. package/dist/enforcement/enforcement.js +90 -0
  80. package/dist/enforcement/index.d.ts +11 -0
  81. package/dist/enforcement/index.js +10 -0
  82. package/dist/enforcement/schemas/enforcement.schema.d.ts +30 -0
  83. package/dist/enforcement/schemas/enforcement.schema.js +36 -0
  84. package/dist/enforcement/types/enforcement.types.d.ts +59 -0
  85. package/dist/enforcement/types/enforcement.types.js +1 -0
  86. package/dist/enrollment/constants/enrollment.constants.d.ts +6 -0
  87. package/dist/enrollment/constants/enrollment.constants.js +6 -0
  88. package/dist/enrollment/enrollment-provider.d.ts +5 -0
  89. package/dist/enrollment/enrollment-provider.js +1 -0
  90. package/dist/enrollment/index.d.ts +7 -0
  91. package/dist/enrollment/index.js +1 -0
  92. package/dist/enrollment/manual-enrollment.d.ts +32 -0
  93. package/dist/enrollment/manual-enrollment.js +72 -0
  94. package/dist/enrollment/types/enrollment.types.d.ts +25 -0
  95. package/dist/enrollment/types/enrollment.types.js +1 -0
  96. package/dist/events/canonical-event.d.ts +10 -0
  97. package/dist/events/canonical-event.js +9 -0
  98. package/dist/events/constants/enrich.constants.d.ts +14 -0
  99. package/dist/events/constants/enrich.constants.js +15 -0
  100. package/dist/events/constants/events.constants.d.ts +35 -0
  101. package/dist/events/constants/events.constants.js +57 -0
  102. package/dist/events/enrich.d.ts +16 -0
  103. package/dist/events/enrich.js +226 -0
  104. package/dist/events/event-id.d.ts +32 -0
  105. package/dist/events/event-id.js +49 -0
  106. package/dist/events/index.d.ts +14 -0
  107. package/dist/events/index.js +5 -0
  108. package/dist/events/llm-call.d.ts +14 -0
  109. package/dist/events/llm-call.js +84 -0
  110. package/dist/events/product-event.d.ts +39 -0
  111. package/dist/events/product-event.js +19 -0
  112. package/dist/events/types/enrich.types.d.ts +25 -0
  113. package/dist/events/types/enrich.types.js +1 -0
  114. package/dist/events/types/events.types.d.ts +112 -0
  115. package/dist/events/types/events.types.js +1 -0
  116. package/dist/events/types/llm-call.types.d.ts +79 -0
  117. package/dist/events/types/llm-call.types.js +1 -0
  118. package/dist/events/types/repo-snapshot.types.d.ts +32 -0
  119. package/dist/events/types/repo-snapshot.types.js +1 -0
  120. package/dist/feature/constants/feature.constants.d.ts +10 -0
  121. package/dist/feature/constants/feature.constants.js +10 -0
  122. package/dist/feature/index.d.ts +6 -0
  123. package/dist/feature/index.js +6 -0
  124. package/dist/feature/ticket-candidates.d.ts +13 -0
  125. package/dist/feature/ticket-candidates.js +26 -0
  126. package/dist/git/constants/git.constants.d.ts +84 -0
  127. package/dist/git/constants/git.constants.js +113 -0
  128. package/dist/git/git-context.d.ts +52 -0
  129. package/dist/git/git-context.js +226 -0
  130. package/dist/git/index.d.ts +9 -0
  131. package/dist/git/index.js +3 -0
  132. package/dist/git/remote-sanitize.d.ts +26 -0
  133. package/dist/git/remote-sanitize.js +92 -0
  134. package/dist/git/repo-snapshot.d.ts +40 -0
  135. package/dist/git/repo-snapshot.js +95 -0
  136. package/dist/git/types/git.types.d.ts +36 -0
  137. package/dist/git/types/git.types.js +1 -0
  138. package/dist/git/types/snapshot.types.d.ts +25 -0
  139. package/dist/git/types/snapshot.types.js +1 -0
  140. package/dist/otlp/constants/otlp.constants.d.ts +84 -0
  141. package/dist/otlp/constants/otlp.constants.js +99 -0
  142. package/dist/otlp/http.d.ts +24 -0
  143. package/dist/otlp/http.js +37 -0
  144. package/dist/otlp/index.d.ts +9 -0
  145. package/dist/otlp/index.js +3 -0
  146. package/dist/otlp/normalize.d.ts +14 -0
  147. package/dist/otlp/normalize.js +404 -0
  148. package/dist/otlp/types/otlp.types.d.ts +69 -0
  149. package/dist/otlp/types/otlp.types.js +1 -0
  150. package/dist/pipeline/constants/pipeline.constants.d.ts +23 -0
  151. package/dist/pipeline/constants/pipeline.constants.js +22 -0
  152. package/dist/pipeline/hook-pipeline.d.ts +14 -0
  153. package/dist/pipeline/hook-pipeline.js +297 -0
  154. package/dist/pipeline/index.d.ts +6 -0
  155. package/dist/pipeline/index.js +1 -0
  156. package/dist/pipeline/types/pipeline.types.d.ts +48 -0
  157. package/dist/pipeline/types/pipeline.types.js +1 -0
  158. package/dist/privacy/constants/privacy.constants.d.ts +23 -0
  159. package/dist/privacy/constants/privacy.constants.js +38 -0
  160. package/dist/privacy/index.d.ts +7 -0
  161. package/dist/privacy/index.js +2 -0
  162. package/dist/privacy/sanitizer.d.ts +20 -0
  163. package/dist/privacy/sanitizer.js +52 -0
  164. package/dist/privacy/types/privacy.types.d.ts +13 -0
  165. package/dist/privacy/types/privacy.types.js +1 -0
  166. package/dist/providers/antigravity/antigravity.adapter.d.ts +54 -0
  167. package/dist/providers/antigravity/antigravity.adapter.js +311 -0
  168. package/dist/providers/antigravity/antigravity.detect.d.ts +25 -0
  169. package/dist/providers/antigravity/antigravity.detect.js +64 -0
  170. package/dist/providers/antigravity/antigravity.hooks.d.ts +24 -0
  171. package/dist/providers/antigravity/antigravity.hooks.js +126 -0
  172. package/dist/providers/antigravity/antigravity.provider.d.ts +2 -0
  173. package/dist/providers/antigravity/antigravity.provider.js +22 -0
  174. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +72 -0
  175. package/dist/providers/antigravity/constants/antigravity.constants.js +75 -0
  176. package/dist/providers/antigravity/schemas/antigravity.schema.d.ts +521 -0
  177. package/dist/providers/antigravity/schemas/antigravity.schema.js +64 -0
  178. package/dist/providers/antigravity/types/antigravity.types.d.ts +13 -0
  179. package/dist/providers/antigravity/types/antigravity.types.js +1 -0
  180. package/dist/providers/claude/claude.adapter.d.ts +15 -0
  181. package/dist/providers/claude/claude.adapter.js +141 -0
  182. package/dist/providers/claude/claude.detect.d.ts +20 -0
  183. package/dist/providers/claude/claude.detect.js +57 -0
  184. package/dist/providers/claude/claude.hooks.d.ts +23 -0
  185. package/dist/providers/claude/claude.hooks.js +94 -0
  186. package/dist/providers/claude/claude.otel.d.ts +95 -0
  187. package/dist/providers/claude/claude.otel.js +331 -0
  188. package/dist/providers/claude/claude.provider.d.ts +2 -0
  189. package/dist/providers/claude/claude.provider.js +26 -0
  190. package/dist/providers/claude/constants/claude.constants.d.ts +34 -0
  191. package/dist/providers/claude/constants/claude.constants.js +54 -0
  192. package/dist/providers/claude/constants/claude.otel.constants.d.ts +17 -0
  193. package/dist/providers/claude/constants/claude.otel.constants.js +17 -0
  194. package/dist/providers/claude/schemas/claude.schema.d.ts +72 -0
  195. package/dist/providers/claude/schemas/claude.schema.js +32 -0
  196. package/dist/providers/claude/types/claude.types.d.ts +3 -0
  197. package/dist/providers/claude/types/claude.types.js +1 -0
  198. package/dist/providers/codex/codex.adapter.d.ts +11 -0
  199. package/dist/providers/codex/codex.adapter.js +106 -0
  200. package/dist/providers/codex/codex.detect.d.ts +30 -0
  201. package/dist/providers/codex/codex.detect.js +58 -0
  202. package/dist/providers/codex/codex.hooks.d.ts +27 -0
  203. package/dist/providers/codex/codex.hooks.js +129 -0
  204. package/dist/providers/codex/codex.otel.d.ts +51 -0
  205. package/dist/providers/codex/codex.otel.js +325 -0
  206. package/dist/providers/codex/codex.provider.d.ts +2 -0
  207. package/dist/providers/codex/codex.provider.js +25 -0
  208. package/dist/providers/codex/constants/codex.constants.d.ts +41 -0
  209. package/dist/providers/codex/constants/codex.constants.js +62 -0
  210. package/dist/providers/codex/constants/codex.otel.constants.d.ts +22 -0
  211. package/dist/providers/codex/constants/codex.otel.constants.js +22 -0
  212. package/dist/providers/codex/schemas/codex.schema.d.ts +70 -0
  213. package/dist/providers/codex/schemas/codex.schema.js +32 -0
  214. package/dist/providers/codex/types/codex.types.d.ts +3 -0
  215. package/dist/providers/codex/types/codex.types.js +1 -0
  216. package/dist/providers/constants/provider.constants.d.ts +33 -0
  217. package/dist/providers/constants/provider.constants.js +33 -0
  218. package/dist/providers/cursor/constants/cursor.constants.d.ts +58 -0
  219. package/dist/providers/cursor/constants/cursor.constants.js +95 -0
  220. package/dist/providers/cursor/cursor.adapter.d.ts +11 -0
  221. package/dist/providers/cursor/cursor.adapter.js +331 -0
  222. package/dist/providers/cursor/cursor.detect.d.ts +23 -0
  223. package/dist/providers/cursor/cursor.detect.js +66 -0
  224. package/dist/providers/cursor/cursor.hooks.d.ts +25 -0
  225. package/dist/providers/cursor/cursor.hooks.js +95 -0
  226. package/dist/providers/cursor/cursor.provider.d.ts +2 -0
  227. package/dist/providers/cursor/cursor.provider.js +27 -0
  228. package/dist/providers/cursor/schemas/cursor.schema.d.ts +130 -0
  229. package/dist/providers/cursor/schemas/cursor.schema.js +62 -0
  230. package/dist/providers/cursor/types/cursor.types.d.ts +3 -0
  231. package/dist/providers/cursor/types/cursor.types.js +1 -0
  232. package/dist/providers/gemini/constants/gemini.constants.d.ts +36 -0
  233. package/dist/providers/gemini/constants/gemini.constants.js +58 -0
  234. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +34 -0
  235. package/dist/providers/gemini/constants/gemini.otel.constants.js +48 -0
  236. package/dist/providers/gemini/gemini.adapter.d.ts +15 -0
  237. package/dist/providers/gemini/gemini.adapter.js +146 -0
  238. package/dist/providers/gemini/gemini.detect.d.ts +23 -0
  239. package/dist/providers/gemini/gemini.detect.js +78 -0
  240. package/dist/providers/gemini/gemini.hooks.d.ts +22 -0
  241. package/dist/providers/gemini/gemini.hooks.js +93 -0
  242. package/dist/providers/gemini/gemini.otel.d.ts +62 -0
  243. package/dist/providers/gemini/gemini.otel.js +274 -0
  244. package/dist/providers/gemini/gemini.provider.d.ts +2 -0
  245. package/dist/providers/gemini/gemini.provider.js +22 -0
  246. package/dist/providers/gemini/schemas/gemini.schema.d.ts +81 -0
  247. package/dist/providers/gemini/schemas/gemini.schema.js +35 -0
  248. package/dist/providers/gemini/types/gemini.types.d.ts +3 -0
  249. package/dist/providers/gemini/types/gemini.types.js +1 -0
  250. package/dist/providers/index.d.ts +14 -0
  251. package/dist/providers/index.js +8 -0
  252. package/dist/providers/provider.d.ts +16 -0
  253. package/dist/providers/provider.js +149 -0
  254. package/dist/providers/registry.d.ts +12 -0
  255. package/dist/providers/registry.js +23 -0
  256. package/dist/providers/shared/constants/hook-refusal.constants.d.ts +6 -0
  257. package/dist/providers/shared/constants/hook-refusal.constants.js +6 -0
  258. package/dist/providers/shared/constants/tooling.constants.d.ts +25 -0
  259. package/dist/providers/shared/constants/tooling.constants.js +25 -0
  260. package/dist/providers/shared/event-builder.d.ts +85 -0
  261. package/dist/providers/shared/event-builder.js +166 -0
  262. package/dist/providers/shared/hook-config.d.ts +80 -0
  263. package/dist/providers/shared/hook-config.js +164 -0
  264. package/dist/providers/shared/hook-refusal.d.ts +16 -0
  265. package/dist/providers/shared/hook-refusal.js +33 -0
  266. package/dist/providers/shared/install-record.d.ts +75 -0
  267. package/dist/providers/shared/install-record.js +113 -0
  268. package/dist/providers/shared/tooling.d.ts +58 -0
  269. package/dist/providers/shared/tooling.js +103 -0
  270. package/dist/providers/shared/types/adapter.types.d.ts +54 -0
  271. package/dist/providers/shared/types/adapter.types.js +1 -0
  272. package/dist/providers/shared/types/hook-config.types.d.ts +32 -0
  273. package/dist/providers/shared/types/hook-config.types.js +1 -0
  274. package/dist/providers/types/provider.types.d.ts +98 -0
  275. package/dist/providers/types/provider.types.js +1 -0
  276. package/dist/snapshot/branch-selection.d.ts +37 -0
  277. package/dist/snapshot/branch-selection.js +69 -0
  278. package/dist/snapshot/budget.d.ts +41 -0
  279. package/dist/snapshot/budget.js +67 -0
  280. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +11 -0
  281. package/dist/snapshot/constants/snapshot-stages.constants.js +11 -0
  282. package/dist/snapshot/constants/snapshot.constants.d.ts +56 -0
  283. package/dist/snapshot/constants/snapshot.constants.js +56 -0
  284. package/dist/snapshot/index.d.ts +16 -0
  285. package/dist/snapshot/index.js +6 -0
  286. package/dist/snapshot/snapshot-event.d.ts +17 -0
  287. package/dist/snapshot/snapshot-event.js +66 -0
  288. package/dist/snapshot/snapshot-pipeline.d.ts +14 -0
  289. package/dist/snapshot/snapshot-pipeline.js +163 -0
  290. package/dist/snapshot/snapshot-state.d.ts +55 -0
  291. package/dist/snapshot/snapshot-state.js +100 -0
  292. package/dist/snapshot/types/snapshot.types.d.ts +86 -0
  293. package/dist/snapshot/types/snapshot.types.js +1 -0
  294. package/dist/storage/atomic-file.d.ts +25 -0
  295. package/dist/storage/atomic-file.js +76 -0
  296. package/dist/storage/constants/storage.constants.d.ts +34 -0
  297. package/dist/storage/constants/storage.constants.js +35 -0
  298. package/dist/storage/index.d.ts +10 -0
  299. package/dist/storage/index.js +5 -0
  300. package/dist/storage/install-state.d.ts +20 -0
  301. package/dist/storage/install-state.js +40 -0
  302. package/dist/storage/json-file.d.ts +13 -0
  303. package/dist/storage/json-file.js +31 -0
  304. package/dist/storage/lock.d.ts +15 -0
  305. package/dist/storage/lock.js +70 -0
  306. package/dist/storage/paths.d.ts +14 -0
  307. package/dist/storage/paths.js +42 -0
  308. package/dist/storage/schemas/storage.schema.d.ts +128 -0
  309. package/dist/storage/schemas/storage.schema.js +27 -0
  310. package/dist/storage/types/storage.types.d.ts +36 -0
  311. package/dist/storage/types/storage.types.js +1 -0
  312. package/dist/transport/constants/transport.constants.d.ts +47 -0
  313. package/dist/transport/constants/transport.constants.js +47 -0
  314. package/dist/transport/cooldown.d.ts +35 -0
  315. package/dist/transport/cooldown.js +62 -0
  316. package/dist/transport/delivery-stats.d.ts +65 -0
  317. package/dist/transport/delivery-stats.js +186 -0
  318. package/dist/transport/delivery.d.ts +26 -0
  319. package/dist/transport/delivery.js +80 -0
  320. package/dist/transport/headers.d.ts +12 -0
  321. package/dist/transport/headers.js +19 -0
  322. package/dist/transport/http-transport.d.ts +39 -0
  323. package/dist/transport/http-transport.js +106 -0
  324. package/dist/transport/index.d.ts +13 -0
  325. package/dist/transport/index.js +7 -0
  326. package/dist/transport/queue.d.ts +177 -0
  327. package/dist/transport/queue.js +474 -0
  328. package/dist/transport/schemas/queue.schema.d.ts +30 -0
  329. package/dist/transport/schemas/queue.schema.js +18 -0
  330. package/dist/transport/transport.d.ts +6 -0
  331. package/dist/transport/transport.js +1 -0
  332. package/dist/transport/types/transport.types.d.ts +102 -0
  333. package/dist/transport/types/transport.types.js +1 -0
  334. package/dist/turns/aggregate-usage.d.ts +20 -0
  335. package/dist/turns/aggregate-usage.js +269 -0
  336. package/dist/turns/claude-transcript.d.ts +18 -0
  337. package/dist/turns/claude-transcript.js +80 -0
  338. package/dist/turns/constants/turns.constants.d.ts +69 -0
  339. package/dist/turns/constants/turns.constants.js +86 -0
  340. package/dist/turns/cursor-transcript.d.ts +21 -0
  341. package/dist/turns/cursor-transcript.js +66 -0
  342. package/dist/turns/index.d.ts +17 -0
  343. package/dist/turns/index.js +7 -0
  344. package/dist/turns/transcript.d.ts +74 -0
  345. package/dist/turns/transcript.js +188 -0
  346. package/dist/turns/turn-state.d.ts +94 -0
  347. package/dist/turns/turn-state.js +234 -0
  348. package/dist/turns/turn-summary.d.ts +27 -0
  349. package/dist/turns/turn-summary.js +164 -0
  350. package/dist/turns/turn-tracker.d.ts +14 -0
  351. package/dist/turns/turn-tracker.js +521 -0
  352. package/dist/turns/types/aggregate-usage.types.d.ts +26 -0
  353. package/dist/turns/types/aggregate-usage.types.js +1 -0
  354. package/dist/turns/types/transcript.types.d.ts +41 -0
  355. package/dist/turns/types/transcript.types.js +1 -0
  356. package/dist/turns/types/turn-state.types.d.ts +37 -0
  357. package/dist/turns/types/turn-state.types.js +1 -0
  358. package/dist/turns/types/turn-summary.types.d.ts +106 -0
  359. package/dist/turns/types/turn-summary.types.js +1 -0
  360. package/dist/turns/types/turn-tracker.types.d.ts +27 -0
  361. package/dist/turns/types/turn-tracker.types.js +1 -0
  362. package/example/README.md +43 -0
  363. package/example/server.mjs +240 -0
  364. package/package.json +89 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,251 @@
1
+ # Changelog
2
+
3
+ ## Unreleased
4
+
5
+ - `agentwatch setup` now refuses an install it cannot attribute: with no `--developer-email` and no
6
+ `git config user.email`, it exits non-zero with the two remedies on stderr and writes no config
7
+ file. An unknown identity is allowed silently by the enforcement gate, so an unattributable
8
+ install used to report success while enforcing nothing.
9
+ - `--yes` / `--non-interactive` now suppresses every setup prompt, including the developer-email
10
+ one, and the prompt itself only appears when nothing else names the developer. `--developer-email`
11
+ still overrides the machine's git identity.
12
+ - `agentwatch doctor` reports the same condition as a `developer identity` failure, in the human
13
+ report and in `--json`, so a scripted rollout can fail a machine instead of shipping it broken.
14
+
15
+ - Budget enforcement: before a turn starts, the Edge asks the backend
16
+ (`GET <backend>/v1/enforcement/decision?developer_id=…`) whether this developer may make an LLM
17
+ call, and refuses the prompt in the agent's own protocol when the backend answers `block` —
18
+ Claude Code (`{"decision":"block","reason":…}`), Codex (`{"continue":false,"stopReason":…}`),
19
+ Cursor (`{"continue":false,"user_message":…}`) and Gemini CLI (`{"decision":"deny","reason":…}`).
20
+ The backend's sentence is what the developer is shown. Antigravity has no prompt-level refusal
21
+ contract and is not gated.
22
+ - The check fails open in every other case: not configured, `enforcement.enabled: false`, no
23
+ developer identity, a 300 ms timeout, a network error, any non-2xx status, and any body that is
24
+ not a `block` carrying a message. Exit code stays 0 throughout — a refusal travels in the hook
25
+ protocol, never as a failed hook.
26
+ - Decisions are cached locally (`<dataDir>/enforcement-cache.json`, 60 s, keyed by a hash of URL,
27
+ token and identity, mode 0600); failures are never cached. New config: the `enforcement` block
28
+ (`enabled`, `timeoutMs`, `cacheTtlMs`) and the `enforcementUrl` override, both global-only.
29
+ - A refused prompt records no turn state — it never reached a model — while the offline queue still
30
+ drains on that hook. `agentwatch status` reports whether enforcement is on, and the example
31
+ backend gained the route (`BLOCK=1 npm run example` refuses everything).
32
+
33
+ ## 0.2.0
34
+
35
+ - Package/documentation: public helpers now ship TypeScript declarations, and the
36
+ README clearly separates sanitized hook summaries from direct native OTLP traffic
37
+ and provisional summaries from backend-finalized usage.
38
+ - Example backend: malformed OTLP/JSON payloads now return `400` instead of being
39
+ acknowledged and silently dropped; only the documented logs, traces and metrics
40
+ endpoints are accepted, and the example is included in the npm package so its
41
+ published `npm run example` script works.
42
+ - Cursor support: new `cursor` provider — lifecycle hooks in `~/.cursor/hooks.json`
43
+ (sessions, prompts, tools, shell, MCP, file edits, subagents, compaction, accepted tab
44
+ edits), `conversation_id`/`generation_id` as session/turn correlation, and turn
45
+ summaries with prompt, response, tools, files and git context. Cursor has no OTel
46
+ export and no usage in hooks or transcripts yet, so its summaries stay
47
+ `usage_status=pending`; the bundled transcript reader picks up tokens automatically
48
+ once Cursor enriches the format. `agentwatch doctor` reports both limitations (the
49
+ pending usage and the cursor-agent CLI emitting only shell hook events).
50
+ - Turn state gained a `response` record kind: providers that deliver the response text
51
+ outside the Stop event (Cursor's `afterAgentResponse`) still produce summaries with
52
+ the response; a Stop-supplied response keeps priority.
53
+ - BREAKING: `aggregateTurnUsage` marks a turn `usage_status=complete` only when the
54
+ caller passes `complete: true` — an explicit terminal signal (watermark / quiet
55
+ period / session end). OTLP batches arrive asynchronously and are retried, so the
56
+ previous default (`complete` on the first non-empty batch) could stamp completeness
57
+ while late batches were still in flight; without the signal the result is `partial`.
58
+ - BREAKING/semantics: `turn.summary.files_touched` now contains only files the agent's
59
+ tools MODIFIED, as documented; files that were only read moved to the new
60
+ `files_read` field. (Legacy turn-state records without an access marker stay in
61
+ `files_touched`.)
62
+ - Fixed: `agentwatch setup --otel <signals>` was silently ignored — `--otel` was
63
+ missing from the CLI's value-flag list, so its value parsed as a stray positional.
64
+ Argument parsing moved to `src/cli/args.ts` and is covered by tests.
65
+ - Cursor: tool calls covered by dedicated hooks (shell, MCP, file read/edit) are no
66
+ longer double-counted — Cursor fires both the generic `postToolUse` and the dedicated
67
+ hook for the same invocation, and only the dedicated hook now produces the completion
68
+ record; generic completions remain for tools without a dedicated hook, and failures
69
+ always flow through `postToolUseFailure`.
70
+ - Cursor: the transcript usage reader bails out after one read when the transcript
71
+ carries no usage rows (today's format), removing ~1.25 s of retry/settle latency
72
+ from every Cursor Stop; the settle loop still guards flushes once usage rows exist.
73
+ - Cursor: the structured `model_id` now supersedes the legacy `model` slug,
74
+ `model_params` (thinking/context/effort selections) are preserved as structured
75
+ `provider.modelParams`, and prompt attachments are recorded (count always, file
76
+ paths gated by `capture.files`).
77
+ - Performance: hooks on the agent's critical path (tool events) resolve only the git
78
+ repository root (one git process) for path rewriting; the full git context —
79
+ branch, commit, remote, and the expensive `status --porcelain` — is collected only
80
+ when a turn closes, where the summary actually consumes it.
81
+ - Durability: atomic file writes fsync before rename, so a crash right after the
82
+ rename can no longer leave queue entries, config, or turn state truncated.
83
+
84
+ - BREAKING: the public model now has exactly two records: atomic `llm.call` and aggregate
85
+ `turn.summary`. Raw hook lifecycle events, telemetry opt-out flags, and offline drop policies
86
+ were removed.
87
+ - BREAKING: `aggregateTurnUsage` performs the time-window join only when
88
+ `options.sessionSummaries` (the session's full summary set) is provided. Per-summary
89
+ containment alone cannot arbitrate overlapping turn windows, so the previous no-context join
90
+ could double-count the same call's tokens and cost across successive finalizations. Without
91
+ the set, calls now match only through an exact turn id.
92
+ - Fixed `repository`, added `homepage` and `bugs` in `package.json` — now pointing to
93
+ <https://github.com/agent-watch-ai/agent-watch-edge>.
94
+ - Simplified README; product record examples now use mock data.
95
+ - Correctness: one malformed OTLP log record (e.g. an unparseable timestamp attribute combined
96
+ with `duration_ms`) no longer throws and aborts normalization of the entire batch — the
97
+ record is skipped and every other `llm.call` in the batch is still ingested.
98
+ - Correctness: ticket candidates are extracted from the branch name as-is instead of
99
+ uppercasing it first, which fabricated Jira ids from ordinary words (`bump-node-20` produced
100
+ `NODE-20`). Only keys that are uppercase in the branch itself are reported.
101
+ - Correctness: `turn.summary.model` now reports the model that produced the most tokens in the
102
+ turn's transcript window instead of the last one written — a small subagent or
103
+ title-generation side-call can no longer mislabel (and misprice) the whole turn.
104
+ - Correctness: on old Claude versions without `prompt_id`, two identical prompt submissions no
105
+ longer collapse into one turn-state record (the second turn used to close with no summary,
106
+ losing its prompt, tools, and token usage).
107
+ - Git: userless scp-like remotes (`github.com:org/repo.git`) normalize correctly instead of
108
+ parsing as a URL scheme and being dropped; an scp userinfo with an embedded password is
109
+ stripped before matching and can never leak into the normalized remote.
110
+ - Git: branch detection uses `symbolic-ref --short -q HEAD` instead of
111
+ `branch --show-current`, which does not exist before git 2.22 and silently dropped branch
112
+ and ticket attribution on older machines.
113
+ - Git: a `status --porcelain` output larger than 1 MB now yields a truncated `changedFiles`
114
+ list (bounded by `maxChangedFiles`) instead of dropping the list entirely.
115
+ - Git: quoted porcelain paths (`core.quotePath`) are C-style-unescaped, so file names with
116
+ non-ASCII or special characters appear in `files_changed` as real paths instead of
117
+ `r\303\251sum\303\251.txt`-style escape strings.
118
+ - Native OTLP signal selection is configurable: `otel: {logs, traces, metrics}` in the global
119
+ config, or `agentwatch setup --otel <all|none|logs,traces,metrics>`. The default exports logs
120
+ only — the per-request usage/cost ledger behind `llm.call`; traces (TTFT/subagent attribution)
121
+ and metrics (active time, aggregates) are opt-in. `--otel none` removes the agents' telemetry
122
+ config entirely. The selection is global-only: a committed `.agentwatch.json` cannot change it.
123
+ Setup still fails on exporter conflicts, and doctor fails when per-request coverage is missing.
124
+ - Added exported TypeScript contracts, OTLP/JSON normalization, idempotent call aggregation,
125
+ `usage_status`, `llm_calls`, `cost_usd`, and per-agent `agent_usage[]`.
126
+ - Delivery and queue APIs accept only `ProductEvent` and retain both types.
127
+
128
+ - Fix: the first entry of `files_changed` no longer loses its leading character
129
+ (`CHANGELOG.md` arrived as `HANGELOG.md`) — the git runner trimmed the significant leading
130
+ space off the first `status --porcelain` line.
131
+
132
+ - Correctness: transcript usage allocation is serialized per session across the complete
133
+ claim/read/settle/write transaction, then persisted by stable message id. This prevents
134
+ double attribution for overlapping turns in any close order, including an equal-timestamp
135
+ boundary; transcript entries without `message.id` use a stable content hash.
136
+ - Safety: hook ownership now parses quoted argv and accepts only the two forms setup installs:
137
+ an `agentwatch` executable, or `node <agentwatch-install>/dist/cli.js`, immediately followed
138
+ by `hook --agent <supported-provider>`. Compound commands and foreign executables are never
139
+ claimed.
140
+
141
+ - Safety: repo overrides are ignored entirely while the global config is missing or corrupt —
142
+ a committed `.agentwatch.json` cannot re-enable content capture over the fail-safe.
143
+ - Privacy: path rewriting inside captured content is boundary-aware (`/x/repo` no longer
144
+ fires inside `/x/repository`); `git config user.email` honors the injected home, keeping
145
+ tests and sandboxes away from the real global gitconfig.
146
+ - `agentwatch doctor` reports the privacy posture from the EFFECTIVE config for the current
147
+ directory (repo overrides included), not the global one.
148
+
149
+ - Reliability: persisted circuit breaker for the direct send — after a failed delivery, hooks
150
+ skip the send (and its 1.5 s timeout) for 60 s and queue events instead, so a dead backend
151
+ costs at most one timeout per minute instead of stalling every hook.
152
+ - Safety: install/uninstall now own individual hook HANDLERS, not whole matcher groups — a
153
+ user handler sharing a group with AgentWatch survives both operations; Codex uninstall
154
+ preserves the top-level `description`.
155
+ - Safety: a missing or corrupt global config now fails safe to metadata-only capture at
156
+ runtime (setup still writes full-capture defaults on a deliberate install).
157
+ - Privacy: captured tool input/output and shell commands get path prefixes rewritten
158
+ (repo root → relative, home → `~`); `capture.files=false` now also drops per-file
159
+ `filePath`/`files_touched`, not just Git changedFiles.
160
+ - Correctness: the turn-close lock is keyed by session+turn, so two different prompts of one
161
+ session can close concurrently without losing a summary.
162
+ - Performance: transcript usage parsing reads only the last 4 MB of the JSONL instead of the
163
+ whole file on every retry.
164
+ - Codex: `PreCompact`/`PostCompact` hooks are now registered.
165
+ - `agentwatch doctor` reports repo-config overrides and their warnings for the current
166
+ directory.
167
+
168
+ - Robustness: turn closing is serialized per session (duplicate/racing Stops emit exactly one
169
+ summary), records landing during the transcript settle wait are re-collected into the
170
+ summary, and transcript usage is bounded by the Stop timestamp so a racing next prompt's
171
+ tokens don't leak into the previous turn.
172
+ - `agentwatch doctor` verifies Claude Code >= 2.1.196 (required for `prompt_id` turn
173
+ correlation) and warns when turn tracking would degrade to session-scoped.
174
+ - Correlation: Claude `prompt_id` now flows into `session.turnId` on every event of the turn
175
+ and into `turn.summary.turn_id`, matching OTel `prompt.id` — context and provider cost can
176
+ be joined precisely (`session_id` + `turn_id`).
177
+ - Turn state is prompt-scoped: Stop consumes only records of its own prompt (racing next-turn
178
+ records survive for their own Stop), and a repeated Stop with nothing new emits no empty
179
+ duplicate summary.
180
+ - Security: legacy queue entries without a recorded destination are quarantined instead of
181
+ being grandfathered into the next configured backend; pre-setup entries are explicitly
182
+ marked for the first backend `setup` configures.
183
+ - Security: `developerEmail` is global-only — a committed `.agentwatch.json` cannot spoof
184
+ developer attribution.
185
+ - Accuracy: transcript usage reads honor a settle window (500 ms) so early-stable usage in
186
+ multi-tool turns doesn't end the read before the final entry lands.
187
+ - Billing detection no longer guesses: unrecognized Claude `billingType` values report
188
+ `unknown` instead of `api`.
189
+
190
+ - Security: `endpoint`/`eventsUrl`/`otlpUrl` are global-only — a committed `.agentwatch.json`
191
+ can no longer redirect telemetry (and the global bearer token) to a repo-controlled
192
+ backend.
193
+ - Security: offline queue entries are pinned to the events URL they were queued for; after
194
+ an endpoint change, old entries are never replayed to the new backend (they wait for
195
+ their own backend or expire).
196
+ - Privacy: turn-state files (raw prompt/response text) are written with mode 0600, and
197
+ orphaned session state (crash without Stop/SessionEnd) is swept after 24 h.
198
+ - Accuracy: transcript usage reads now wait for a stable snapshot (two consecutive
199
+ identical reads) instead of stopping at the first usage entry, so late-flushed final
200
+ entries in multi-tool turns are not undercounted.
201
+ - Example backend: OTLP responses now echo the request encoding (JSON in → JSON out), as
202
+ the OTLP/HTTP spec requires.
203
+ - Capture defaults flipped to full capture: `capture.prompts/responses/toolInput/toolOutput`
204
+ now default to `true` so turn summaries carry prompt/response text and tool I/O out of the
205
+ box; each category can still be disabled per machine or per repo. The secret sanitizer
206
+ applies regardless.
207
+ - Reliable token usage on `Stop`: Claude Code flushes its transcript asynchronously, so the
208
+ final assistant entry could be missing when the hook read it, dropping `model` and
209
+ `*_tokens` from the summary. Usage reads now retry (up to 6 attempts, 250 ms apart) until
210
+ the entry appears.
211
+ - Billing mode detection: turn summaries carry `billing_mode` and the `generation.completed`
212
+ event carries `ai.billingMode` — `subscription` (Claude Pro/Max seat, ChatGPT plan) vs
213
+ `api` (per-token billing: `ANTHROPIC_API_KEY`, Bedrock/Vertex, Codex API key). Detected
214
+ from the agent's local auth state (`~/.claude.json` `oauthAccount.billingType`,
215
+ `~/.codex/auth.json` `auth_mode`); degrades to omitting the field when undetectable.
216
+ - Everything on the wire is JSON now: native OTel export switched from binary protobuf to
217
+ OTLP/JSON for both agents (Claude Code `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`, Codex
218
+ `protocol = "json"`). The example backend pretty-prints OTLP/JSON log records (event name,
219
+ session, model, tokens, cost) and metric names.
220
+ - Turn summaries: one flat `turn.summary` event per prompt→response turn, emitted on `Stop`.
221
+ Carries developer email, repo/branch/commit, Jira ticket ids from the branch name,
222
+ prompt/response (per capture flags), tool-call counts and touched files. Transcript usage is
223
+ provisional until the backend finalizes it from `llm.call` rows.
224
+ - `agentwatch setup --developer-email <email>` and interactive prompt (defaults to
225
+ `git config user.email`); stored as `developerEmail` in `~/.agentwatch/config.json`.
226
+ - New `emit` config block: `{ "turnSummaries": true, "llmCalls": true }`; `llmCalls` is
227
+ mandatory and repo overrides cannot disable it.
228
+ - Per-repository configuration: `.agentwatch.json` in the repo root overrides the global
229
+ `~/.agentwatch/config.json` (scalars replace; `capture`/`emit`/`delivery` merge per field;
230
+ `token`/`installationId`/`endpoint`/`eventsUrl`/`otlpUrl` are global-only and ignored).
231
+ `agentwatch config` now prints the
232
+ effective merged configuration.
233
+ - CLI: `--non-interactive` alias for `--yes`; `--help` documents every flag and the
234
+ configuration layers.
235
+ - Offline delivery retains every product record it receives; there is no drop policy.
236
+
237
+ ## 0.1.0 (2026-08-07)
238
+
239
+ Initial MVP.
240
+
241
+ - CLI: `setup`, `status`, `doctor`, `uninstall`, `hook`, `agents`, `config`, `otel-headers`.
242
+ - Providers: Claude Code (hooks in `~/.claude/settings.json`, native OTel via env block +
243
+ `otelHeadersHelper`), OpenAI Codex (hooks in `~/.codex/hooks.json`, native OTel via managed
244
+ `[otel]` block in `config.toml`).
245
+ - Canonical event schema v1 with provider-independent event types and deterministic event IDs.
246
+ - Git enrichment (repo, hashed credential-free remote, branch, commit, changed files) and
247
+ ticket-key feature candidates from branch names.
248
+ - Privacy-first capture defaults + recursive secret sanitizer.
249
+ - Offline-tolerant delivery: bounded file queue, exponential backoff, dedup by event ID.
250
+ - Idempotent, merge-only config writes with backups; uninstall removes only AgentWatch-owned
251
+ entries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AgentWatch contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,168 @@
1
+ # AgentWatch Edge
2
+
3
+ [![npm](https://img.shields.io/npm/v/@agent-watch-ai/edge)](https://www.npmjs.com/package/@agent-watch-ai/edge)
4
+ [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
+
6
+ A lightweight, zero-daemon telemetry edge for AI coding agents (**Claude Code**, **OpenAI Codex**, **Cursor**, **Gemini CLI**, and **Google Antigravity**).
7
+
8
+ It connects agent lifecycle hooks and native OpenTelemetry (OTLP) to your observability backend to attribute LLM usage, costs, tool calls, Git branches, and ticket keys (e.g., `PAY-142`) — without model proxies, MITM intercepts, or background daemons.
9
+
10
+ ---
11
+
12
+ ## Quick Start
13
+
14
+ **Requirements:** Node.js 20+
15
+
16
+ ```bash
17
+ # 1. Install globally
18
+ npm install -g @agent-watch-ai/edge
19
+
20
+ # 2. Configure with your backend
21
+ agentwatch setup --endpoint https://backend.example.com --token YOUR_TOKEN
22
+
23
+ # 3. Verify status & diagnostics
24
+ agentwatch status
25
+ agentwatch doctor
26
+ ```
27
+
28
+ ---
29
+
30
+ ## Supported Agents & Limitations
31
+
32
+ | Agent | Hook Configuration | Native OTel Signals | Status |
33
+ |---|---|---|---|
34
+ | **Claude Code** | `~/.claude/settings.json` | Logs, Traces, Metrics | Full support |
35
+ | **OpenAI Codex** | `~/.codex/hooks.json` | Logs, Traces (`~/.codex/config.toml`) | Full support |
36
+ | **Gemini CLI** | `~/.gemini/settings.json` | Logs, Traces, Metrics | Full support |
37
+ | **Cursor** | `~/.cursor/hooks.json` | None | Partial support |
38
+ | **Google Antigravity** | `~/.gemini/config/hooks.json` | None | Partial support |
39
+
40
+ ### Agent Limitations & Notes
41
+
42
+ * **Claude Code**:
43
+ * Running sessions must be restarted after `agentwatch setup` to apply telemetry environment variables.
44
+ * **OpenAI Codex**:
45
+ * Requires trusting new hooks: launch `codex`, type `/hooks`, and approve AgentWatch entries.
46
+ * **Gemini CLI**:
47
+ * Running sessions must be restarted after setup to load new hooks and OpenTelemetry configuration.
48
+ * Telemetry is enabled through `GEMINI_TELEMETRY_ENABLED` with `GEMINI_TELEMETRY_TARGET=local`, and the ingest token travels in `OTEL_EXPORTER_OTLP_HEADERS`. Gemini CLI does not support Claude Code's `otelHeadersHelper`.
49
+ * **Google Antigravity**:
50
+ * **No native token usage**: Antigravity exposes no OpenTelemetry exporter configuration and no readable transcript usage, so `turn.summary` events remain `usage_status: "pending"` and carry no cost.
51
+ * **Turns, not model calls**: a turn is one *execution*. `PreInvocation`/`PostInvocation` bracket the individual model calls inside an execution, and only the `Stop` hook closes a turn.
52
+ * The prompt is read from `common.lastUserInput` — Antigravity has no user-prompt hook of its own.
53
+ * Running sessions must be restarted after `agentwatch setup` to load new hooks.
54
+ * **Cursor**:
55
+ * **No native token usage**: Cursor exposes no token usage in hooks or transcripts, so `turn.summary` events remain `usage_status: "pending"`.
56
+ * **Cursor CLI**: Currently emits only shell hook events. Full hook lifecycle is available only in Cursor IDE sessions.
57
+ * **Cloud VMs**: Cloud agents do not have access to the local user hook or binary by default; they require an explicit committed `.cursor/hooks.json` and package installation in the cloud environment.
58
+ * **Tab suggestions**: AgentWatch monitors accepted edits (`afterTabFileEdit`) and intentionally ignores high-frequency `beforeTabFileRead` events.
59
+
60
+ ---
61
+
62
+ ## CLI Commands
63
+
64
+ ```bash
65
+ # Setup & Configuration
66
+ agentwatch setup --endpoint https://backend.example.com # Interactive / automated setup
67
+ agentwatch config # Print active configuration (secrets redacted)
68
+ agentwatch agents # List detected agents & status
69
+
70
+ # Diagnostics & Status
71
+ agentwatch status # Backend, queue, and agent health
72
+ agentwatch doctor # Run environment checks (use --json for CI)
73
+
74
+ # Hook Execution (invoked automatically by agents)
75
+ agentwatch hook --agent claude # Process stdin payload from agent
76
+ agentwatch hook --agent codex --dry-run # Test hook output without sending
77
+
78
+ # Telemetry & Teardown
79
+ agentwatch otel-headers # Output formatted OTel headers
80
+ agentwatch uninstall # Remove hooks and restore backups
81
+ agentwatch uninstall --purge # Also delete ~/.agentwatch and queues
82
+ ```
83
+
84
+ ---
85
+
86
+ ## Parameters & Flags
87
+
88
+ | Flag | Description | Default |
89
+ |---|---|---|
90
+ | `--endpoint <url>` | Backend base URL for event ingestion | — |
91
+ | `--token <token>` | Bearer token for backend authentication | — |
92
+ | `--developer-email <email>` | Identity attached to turn summaries and keyed on by per-developer enforcement. Setup refuses to write a config when neither this flag nor git names a developer | `git config user.email` |
93
+ | `--otel <signals>` | OTLP signals exported by agents: `logs`, `traces`, `metrics`, `all`, or `none` | `logs` |
94
+ | `--agent <id>` | Limit command to a single agent (`claude`, `codex`, `cursor`, `gemini`, `antigravity`) | All detected |
95
+ | `--yes`, `--non-interactive` | Non-interactive mode (fail instead of prompting on missing args) | `false` |
96
+ | `--purge` | Used with `uninstall`: removes `~/.agentwatch` and local queues | `false` |
97
+ | `--dry-run` | Used with `hook`: prints canonical events to stdout instead of sending | `false` |
98
+ | `--json` | Used with `doctor`: output machine-readable JSON | `false` |
99
+ | `--verbose` | Print verbose diagnostic logs to stderr | `false` |
100
+ | `--version` | Display edge version | — |
101
+
102
+ ---
103
+
104
+ ## Configuration
105
+
106
+ * **Global configuration**: `~/.agentwatch/config.json` (managed via `agentwatch setup`).
107
+ * **Repository overrides**: Place a `.agentwatch.json` in any repository root to adjust content capture:
108
+
109
+ ```json
110
+ {
111
+ "capture": {
112
+ "prompts": true,
113
+ "responses": false,
114
+ "toolInput": true,
115
+ "toolOutput": false,
116
+ "git": true,
117
+ "files": true
118
+ }
119
+ }
120
+ ```
121
+
122
+ *Note: Infrastructure settings (`endpoint`, `token`, `developerEmail`, `enforcementUrl`) and the
123
+ `delivery`, `otel` and `enforcement` blocks are global-only — a committed repo file cannot redirect
124
+ delivery or switch off a budget cap for everyone who clones the repository.*
125
+
126
+ ### Budget enforcement (pre-turn check)
127
+
128
+ When a backend budget policy is set to **block** and the developer has breached it, the Edge stops
129
+ the turn before the agent's first LLM call: the prompt is refused in the agent's own protocol
130
+ (Claude Code, Codex, Cursor, Gemini CLI) with the backend's explanation shown to the developer.
131
+
132
+ ```json
133
+ {
134
+ "enforcement": { "enabled": true, "timeoutMs": 300, "cacheTtlMs": 60000 }
135
+ }
136
+ ```
137
+
138
+ The check **fails open, always**. A turn stops only on an explicit `{"decision":"block","message":"…"}`
139
+ from `GET <backend>/v1/enforcement/decision`; an unreachable backend, a timeout, any other status and
140
+ any body the Edge cannot read all let the turn proceed silently. Decisions are cached locally for
141
+ `cacheTtlMs`, so the check costs one bounded request per turn at most. Set `enabled: false` to opt out.
142
+
143
+ Antigravity is not gated: its pre-invocation hook carries no decision field, so there is no
144
+ prompt-level refusal to send. Its usage is still reported and still raises alerts.
145
+
146
+ To try it locally: `BLOCK=1 npm run example` answers every check with a refusal.
147
+
148
+ ---
149
+
150
+ ## Data Flow & Backend Integration
151
+
152
+ 1. **`turn.summary`**: Generated via agent hooks (`POST <backend>/v1/events`). Captures user prompt, tools executed, files touched, Git branch, and ticket keys.
153
+ 2. **`llm.call`**: Emitted via native OTLP (`POST <backend>/v1/otlp/v1/logs`). Contains token usage, cost, and latency per model request.
154
+ 3. The backend joins `llm.call` to `turn.summary` records using conversation/turn IDs.
155
+
156
+ ### Backend SDK Helpers
157
+
158
+ ```ts
159
+ import type { ProductEvent } from '@agent-watch-ai/edge/events';
160
+ import { normalizeOtlpLogs } from '@agent-watch-ai/edge/otlp';
161
+ import { aggregateTurnUsage } from '@agent-watch-ai/edge/aggregate-turn';
162
+ ```
163
+
164
+ ---
165
+
166
+ ## License
167
+
168
+ MIT © [Aleksandr Repetskyi](https://github.com/alexrepetskyi)
@@ -0,0 +1,16 @@
1
+ import type { Env } from '../core/types/core.types.js';
2
+ import type { UsageBillingMode } from '../events/types/events.types.js';
3
+ /**
4
+ * How the developer pays for this agent.
5
+ *
6
+ * A flat subscription (Claude Pro/Max, a ChatGPT plan) and per-token API billing
7
+ * price the same turn completely differently, so a summary that guessed would be
8
+ * worse than one that admits it does not know. Only positively recognized states
9
+ * are classified; every read problem, and every value we do not recognize,
10
+ * degrades to 'unknown'.
11
+ *
12
+ * @param agentId - Internal provider id.
13
+ * @param env - Environment supplying HOME and the relevant variables.
14
+ * @returns The billing mode.
15
+ */
16
+ export declare function detectBillingMode(agentId: string, env: Env): Promise<UsageBillingMode>;
@@ -0,0 +1,139 @@
1
+ import path from 'node:path';
2
+ import { asRecord, firstString } from '../core/object.js';
3
+ import { sha256Hex } from '../events/event-id.js';
4
+ import { readJsonFile } from '../storage/json-file.js';
5
+ import { ANTHROPIC_API_KEY_VAR, API_MARKER, CLAUDE_API_KEY_RESPONSES_FIELD, CLAUDE_APPROVED_FIELD, CLAUDE_BEDROCK_VAR, CLAUDE_BILLING_TYPE_FIELD, CLAUDE_OAUTH_FIELD, CLAUDE_STATE_FILE, CLAUDE_VERTEX_VAR, CODEX_API_KEY_FIELD, CODEX_API_MODE, CODEX_AUTH_FILE, CODEX_AUTH_MODE_FIELD, CODEX_SUBSCRIPTION_MODE, FALSY_ENV_VALUES, GEMINI_API_KEY_FIELDS, GEMINI_API_KEY_VARS, GEMINI_MODE_FIELDS, GEMINI_OAUTH_FILE, GEMINI_SETTINGS_FILE, GOOGLE_ACCOUNT_AGENTS, MIN_APPROVAL_ENTRY_LENGTH, SUBSCRIPTION_MARKER } from './constants/billing.constants.js';
6
+ /**
7
+ * How the developer pays for this agent.
8
+ *
9
+ * A flat subscription (Claude Pro/Max, a ChatGPT plan) and per-token API billing
10
+ * price the same turn completely differently, so a summary that guessed would be
11
+ * worse than one that admits it does not know. Only positively recognized states
12
+ * are classified; every read problem, and every value we do not recognize,
13
+ * degrades to 'unknown'.
14
+ *
15
+ * @param agentId - Internal provider id.
16
+ * @param env - Environment supplying HOME and the relevant variables.
17
+ * @returns The billing mode.
18
+ */
19
+ export async function detectBillingMode(agentId, env) {
20
+ try {
21
+ if (agentId === 'claude')
22
+ return await detectClaude(env);
23
+ if (agentId === 'codex')
24
+ return await detectCodex(env);
25
+ if (GOOGLE_ACCOUNT_AGENTS.has(agentId))
26
+ return await detectGoogleAccount(env);
27
+ }
28
+ catch {
29
+ // Any read or parse failure: we simply do not know.
30
+ }
31
+ return 'unknown';
32
+ }
33
+ /**
34
+ * Claude Code's billing arrangement.
35
+ *
36
+ * @param env - Environment supplying HOME and the relevant variables.
37
+ * @returns The billing mode.
38
+ */
39
+ async function detectClaude(env) {
40
+ // Bedrock and Vertex sessions always bill per token.
41
+ if (isSet(env.vars[CLAUDE_BEDROCK_VAR]) || isSet(env.vars[CLAUDE_VERTEX_VAR]))
42
+ return 'api';
43
+ const state = await readRecord(path.join(env.home, CLAUDE_STATE_FILE));
44
+ const apiKey = env.vars[ANTHROPIC_API_KEY_VAR];
45
+ if (isSet(apiKey) && envApiKeyUsed(state, apiKey))
46
+ return 'api';
47
+ const billingType = asRecord(state?.[CLAUDE_OAUTH_FIELD])?.[CLAUDE_BILLING_TYPE_FIELD];
48
+ if (typeof billingType === 'string' && billingType.includes(SUBSCRIPTION_MARKER))
49
+ return 'subscription';
50
+ return 'unknown';
51
+ }
52
+ /**
53
+ * Whether an environment API key is what Claude Code actually bills through.
54
+ *
55
+ * Claude Code only bills through an environment `ANTHROPIC_API_KEY` after the
56
+ * user approves it (recorded in `customApiKeyResponses`); a key merely exported
57
+ * for other tooling leaves the login's billing untouched. Approval entries have
58
+ * varied across releases — a key hash prefix, or a key tail — so both forms are
59
+ * recognized.
60
+ *
61
+ * @param state - Decoded `~/.claude.json`, when it exists.
62
+ * @param apiKey - The exported key.
63
+ * @returns True when the key is the effective credential.
64
+ */
65
+ function envApiKeyUsed(state, apiKey) {
66
+ // No local Claude state at all: the key is the only auth there is.
67
+ if (!state)
68
+ return true;
69
+ const responses = asRecord(state[CLAUDE_API_KEY_RESPONSES_FIELD]);
70
+ const approved = responses?.[CLAUDE_APPROVED_FIELD];
71
+ if (!Array.isArray(approved))
72
+ return false;
73
+ const hash = sha256Hex(apiKey);
74
+ return approved.some((entry) => typeof entry === 'string' && entry.length >= MIN_APPROVAL_ENTRY_LENGTH && (hash.startsWith(entry) || apiKey.endsWith(entry)));
75
+ }
76
+ /**
77
+ * Codex's billing arrangement.
78
+ *
79
+ * @param env - Environment supplying HOME.
80
+ * @returns The billing mode.
81
+ */
82
+ async function detectCodex(env) {
83
+ const auth = await readRecord(path.join(env.home, CODEX_AUTH_FILE));
84
+ if (!auth)
85
+ return 'unknown';
86
+ const mode = auth[CODEX_AUTH_MODE_FIELD];
87
+ if (mode === CODEX_SUBSCRIPTION_MODE)
88
+ return 'subscription';
89
+ if (mode === CODEX_API_MODE)
90
+ return 'api';
91
+ if (typeof auth[CODEX_API_KEY_FIELD] === 'string' && auth[CODEX_API_KEY_FIELD] !== '')
92
+ return 'api';
93
+ return 'unknown';
94
+ }
95
+ /**
96
+ * The billing arrangement of an agent signed in through the shared Google
97
+ * account state (Gemini CLI, Antigravity).
98
+ *
99
+ * @param env - Environment supplying HOME and the relevant variables.
100
+ * @returns The billing mode.
101
+ */
102
+ async function detectGoogleAccount(env) {
103
+ if (GEMINI_API_KEY_VARS.some((name) => isSet(env.vars[name])))
104
+ return 'api';
105
+ const state = (await readRecord(path.join(env.home, GEMINI_SETTINGS_FILE))) ?? (await readRecord(path.join(env.home, GEMINI_OAUTH_FILE)));
106
+ if (!state)
107
+ return 'unknown';
108
+ const mode = firstString(state, GEMINI_MODE_FIELDS);
109
+ if (mode?.includes(SUBSCRIPTION_MARKER))
110
+ return 'subscription';
111
+ if (mode?.includes(API_MARKER))
112
+ return 'api';
113
+ if (GEMINI_API_KEY_FIELDS.some((field) => typeof state[field] === 'string'))
114
+ return 'api';
115
+ return 'unknown';
116
+ }
117
+ /**
118
+ * Read a JSON object, treating anything unusable as absent.
119
+ *
120
+ * @param filePath - File to read.
121
+ * @returns The object, or undefined.
122
+ */
123
+ async function readRecord(filePath) {
124
+ const read = await readJsonFile(filePath);
125
+ if (read.state !== 'ok')
126
+ return undefined;
127
+ return asRecord(read.value);
128
+ }
129
+ /**
130
+ * Whether an environment variable is meaningfully set.
131
+ *
132
+ * @param value - The variable's value.
133
+ * @returns True when it is set to something that is not a disabling value.
134
+ */
135
+ function isSet(value) {
136
+ if (value === undefined)
137
+ return false;
138
+ return !FALSY_ENV_VALUES.has(value.toLowerCase());
139
+ }
@@ -0,0 +1,37 @@
1
+ /** Local auth state each agent records its billing arrangement in. */
2
+ export declare const CLAUDE_STATE_FILE = ".claude.json";
3
+ export declare const CODEX_AUTH_FILE: string;
4
+ export declare const GEMINI_SETTINGS_FILE: string;
5
+ export declare const GEMINI_OAUTH_FILE: string;
6
+ /** Environment variables that put an agent on per-token API billing. */
7
+ export declare const CLAUDE_BEDROCK_VAR = "CLAUDE_CODE_USE_BEDROCK";
8
+ export declare const CLAUDE_VERTEX_VAR = "CLAUDE_CODE_USE_VERTEX";
9
+ export declare const ANTHROPIC_API_KEY_VAR = "ANTHROPIC_API_KEY";
10
+ export declare const GEMINI_API_KEY_VARS: readonly ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENAI_USE_VERTEXAI"];
11
+ /** Fields the agents' own auth state uses. */
12
+ export declare const CLAUDE_OAUTH_FIELD = "oauthAccount";
13
+ export declare const CLAUDE_BILLING_TYPE_FIELD = "billingType";
14
+ export declare const CLAUDE_API_KEY_RESPONSES_FIELD = "customApiKeyResponses";
15
+ export declare const CLAUDE_APPROVED_FIELD = "approved";
16
+ export declare const CODEX_AUTH_MODE_FIELD = "auth_mode";
17
+ export declare const CODEX_API_KEY_FIELD = "OPENAI_API_KEY";
18
+ export declare const GEMINI_MODE_FIELDS: readonly ["auth_mode", "billingType"];
19
+ export declare const GEMINI_API_KEY_FIELDS: readonly ["GEMINI_API_KEY", "GOOGLE_API_KEY"];
20
+ /** Auth-mode values Codex reports. */
21
+ export declare const CODEX_SUBSCRIPTION_MODE = "chatgpt";
22
+ export declare const CODEX_API_MODE = "apikey";
23
+ /** Substrings that positively identify a billing arrangement. */
24
+ export declare const SUBSCRIPTION_MARKER = "subscription";
25
+ export declare const API_MARKER = "api";
26
+ /**
27
+ * Shortest approval entry we will match a key against.
28
+ *
29
+ * Claude Code records an approved environment key as a hash prefix or a key
30
+ * tail; anything shorter than this would match far too many keys to mean
31
+ * anything.
32
+ */
33
+ export declare const MIN_APPROVAL_ENTRY_LENGTH = 8;
34
+ /** Environment values that mean "not set", beyond an absent variable. */
35
+ export declare const FALSY_ENV_VALUES: ReadonlySet<string>;
36
+ /** Agent ids that authenticate through the shared ~/.gemini Google account. */
37
+ export declare const GOOGLE_ACCOUNT_AGENTS: ReadonlySet<string>;