@agent-watch-ai/edge 0.2.5 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (346) hide show
  1. package/CHANGELOG.md +512 -0
  2. package/README.md +217 -96
  3. package/SECURITY.md +69 -0
  4. package/dist/billing/session-billing.d.ts +19 -0
  5. package/dist/billing/session-billing.js +52 -0
  6. package/dist/cli/args.d.ts +10 -0
  7. package/dist/cli/args.js +20 -0
  8. package/dist/cli/constants/cli.constants.d.ts +50 -4
  9. package/dist/cli/constants/cli.constants.js +54 -5
  10. package/dist/cli/context.d.ts +33 -2
  11. package/dist/cli/context.js +84 -14
  12. package/dist/cli/doctor.js +309 -32
  13. package/dist/cli/hook-check.d.ts +23 -0
  14. package/dist/cli/hook-check.js +114 -0
  15. package/dist/cli/hook.js +118 -7
  16. package/dist/cli/index.d.ts +3 -1
  17. package/dist/cli/index.js +3 -1
  18. package/dist/cli/misc.d.ts +11 -0
  19. package/dist/cli/misc.js +80 -4
  20. package/dist/cli/npx-install.d.ts +37 -0
  21. package/dist/cli/npx-install.js +79 -0
  22. package/dist/cli/open-browser.d.ts +39 -0
  23. package/dist/cli/open-browser.js +62 -0
  24. package/dist/cli/setup.d.ts +17 -8
  25. package/dist/cli/setup.js +439 -98
  26. package/dist/cli/status.js +82 -13
  27. package/dist/cli/toggle.d.ts +9 -0
  28. package/dist/cli/toggle.js +113 -0
  29. package/dist/cli/types/cli.types.d.ts +37 -3
  30. package/dist/cli/ui.d.ts +7 -0
  31. package/dist/cli/ui.js +10 -1
  32. package/dist/cli/uninstall.js +39 -2
  33. package/dist/cli/update.d.ts +17 -0
  34. package/dist/cli/update.js +76 -0
  35. package/dist/cli.js +100 -13
  36. package/dist/config/config-store.d.ts +57 -0
  37. package/dist/config/config-store.js +250 -12
  38. package/dist/config/config.d.ts +53 -6
  39. package/dist/config/config.js +66 -6
  40. package/dist/config/constants/config.constants.d.ts +113 -6
  41. package/dist/config/constants/config.constants.js +126 -8
  42. package/dist/config/destination.d.ts +24 -0
  43. package/dist/config/destination.js +33 -0
  44. package/dist/config/index.d.ts +7 -4
  45. package/dist/config/index.js +5 -3
  46. package/dist/config/repo-config.d.ts +11 -7
  47. package/dist/config/repo-config.js +64 -15
  48. package/dist/config/root-config.d.ts +72 -0
  49. package/dist/config/root-config.js +170 -0
  50. package/dist/config/schemas/config.schema.d.ts +721 -84
  51. package/dist/config/schemas/config.schema.js +388 -15
  52. package/dist/config/types/config.types.d.ts +15 -1
  53. package/dist/config/types/destination.types.d.ts +8 -0
  54. package/dist/core/async.d.ts +36 -0
  55. package/dist/core/async.js +68 -0
  56. package/dist/core/index.d.ts +1 -1
  57. package/dist/core/index.js +1 -1
  58. package/dist/core/object.d.ts +5 -0
  59. package/dist/core/object.js +9 -4
  60. package/dist/core/pipe.d.ts +0 -13
  61. package/dist/core/pipe.js +1 -9
  62. package/dist/core/types/core.types.d.ts +9 -0
  63. package/dist/core/types/core.types.js +0 -3
  64. package/dist/core/which.d.ts +14 -0
  65. package/dist/core/which.js +43 -3
  66. package/dist/credentials/budget.d.ts +9 -0
  67. package/dist/credentials/budget.js +16 -0
  68. package/dist/credentials/command-runner.d.ts +16 -0
  69. package/dist/credentials/command-runner.js +37 -0
  70. package/dist/credentials/constants/credentials.constants.d.ts +111 -0
  71. package/dist/credentials/constants/credentials.constants.js +112 -0
  72. package/dist/credentials/credential-status.d.ts +14 -0
  73. package/dist/credentials/credential-status.js +34 -0
  74. package/dist/credentials/credentials.d.ts +72 -0
  75. package/dist/credentials/credentials.js +253 -0
  76. package/dist/credentials/device-api.d.ts +64 -0
  77. package/dist/credentials/device-api.js +150 -0
  78. package/dist/credentials/device-state.d.ts +31 -0
  79. package/dist/credentials/device-state.js +51 -0
  80. package/dist/credentials/identity.d.ts +62 -0
  81. package/dist/credentials/identity.js +90 -0
  82. package/dist/credentials/index.d.ts +7 -0
  83. package/dist/credentials/index.js +5 -0
  84. package/dist/credentials/migration.d.ts +46 -0
  85. package/dist/credentials/migration.js +164 -0
  86. package/dist/credentials/schemas/device-api.schema.d.ts +77 -0
  87. package/dist/credentials/schemas/device-api.schema.js +33 -0
  88. package/dist/credentials/schemas/device-state.schema.d.ts +51 -0
  89. package/dist/credentials/schemas/device-state.schema.js +20 -0
  90. package/dist/credentials/secret-store.d.ts +54 -0
  91. package/dist/credentials/secret-store.js +217 -0
  92. package/dist/credentials/sign-in.d.ts +18 -0
  93. package/dist/credentials/sign-in.js +86 -0
  94. package/dist/credentials/token-refresher.d.ts +39 -0
  95. package/dist/credentials/token-refresher.js +185 -0
  96. package/dist/credentials/types/credentials.types.d.ts +195 -0
  97. package/dist/credentials/types/credentials.types.js +1 -0
  98. package/dist/enforcement/constants/enforcement.constants.d.ts +47 -1
  99. package/dist/enforcement/constants/enforcement.constants.js +56 -0
  100. package/dist/enforcement/decision-cache.d.ts +20 -1
  101. package/dist/enforcement/decision-cache.js +65 -2
  102. package/dist/enforcement/decision-client.d.ts +9 -8
  103. package/dist/enforcement/decision-client.js +62 -16
  104. package/dist/enforcement/enforcement.d.ts +23 -2
  105. package/dist/enforcement/enforcement.js +103 -15
  106. package/dist/enforcement/index.d.ts +4 -3
  107. package/dist/enforcement/index.js +3 -2
  108. package/dist/enforcement/types/enforcement.types.d.ts +64 -0
  109. package/dist/enrollment/constants/enrollment.constants.d.ts +2 -6
  110. package/dist/enrollment/constants/enrollment.constants.js +2 -6
  111. package/dist/enrollment/enrollment.d.ts +16 -0
  112. package/dist/enrollment/enrollment.js +54 -0
  113. package/dist/enrollment/index.d.ts +3 -7
  114. package/dist/enrollment/index.js +1 -1
  115. package/dist/enrollment/types/enrollment.types.d.ts +9 -13
  116. package/dist/events/constants/enrich.constants.d.ts +15 -0
  117. package/dist/events/constants/enrich.constants.js +15 -0
  118. package/dist/events/constants/events.constants.d.ts +6 -2
  119. package/dist/events/constants/events.constants.js +5 -1
  120. package/dist/events/enrich.js +92 -10
  121. package/dist/events/event-id.d.ts +0 -8
  122. package/dist/events/event-id.js +0 -10
  123. package/dist/events/index.d.ts +2 -2
  124. package/dist/events/index.js +1 -1
  125. package/dist/events/product-event.d.ts +9 -6
  126. package/dist/events/types/repo-snapshot.types.d.ts +7 -0
  127. package/dist/events/types/session-billing.types.d.ts +16 -0
  128. package/dist/events/types/session-billing.types.js +1 -0
  129. package/dist/feature/constants/feature.constants.d.ts +7 -0
  130. package/dist/feature/constants/feature.constants.js +7 -0
  131. package/dist/feature/index.d.ts +1 -1
  132. package/dist/feature/index.js +1 -1
  133. package/dist/feature/ticket-candidates.d.ts +14 -0
  134. package/dist/feature/ticket-candidates.js +26 -8
  135. package/dist/git/blob-hash.d.ts +21 -0
  136. package/dist/git/blob-hash.js +69 -0
  137. package/dist/git/checkout-root.d.ts +27 -0
  138. package/dist/git/checkout-root.js +75 -0
  139. package/dist/git/constants/git.constants.d.ts +160 -0
  140. package/dist/git/constants/git.constants.js +181 -0
  141. package/dist/git/fingerprint.d.ts +74 -0
  142. package/dist/git/fingerprint.js +219 -0
  143. package/dist/git/gate-checkout.d.ts +44 -0
  144. package/dist/git/gate-checkout.js +201 -0
  145. package/dist/git/git-context.d.ts +45 -0
  146. package/dist/git/git-context.js +61 -3
  147. package/dist/git/index.d.ts +4 -2
  148. package/dist/git/index.js +2 -1
  149. package/dist/git/manifest-repository.d.ts +13 -0
  150. package/dist/git/manifest-repository.js +92 -0
  151. package/dist/git/repo-snapshot.d.ts +29 -3
  152. package/dist/git/repo-snapshot.js +110 -7
  153. package/dist/git/repository-root.d.ts +39 -0
  154. package/dist/git/repository-root.js +131 -0
  155. package/dist/git/types/git.types.d.ts +55 -0
  156. package/dist/git/types/repository-root.types.d.ts +11 -0
  157. package/dist/git/types/repository-root.types.js +1 -0
  158. package/dist/git/types/snapshot.types.d.ts +9 -0
  159. package/dist/pipeline/constants/pipeline.constants.d.ts +7 -0
  160. package/dist/pipeline/constants/pipeline.constants.js +7 -0
  161. package/dist/pipeline/hook-pipeline.js +360 -32
  162. package/dist/pipeline/types/pipeline.types.d.ts +39 -4
  163. package/dist/privacy/constants/privacy.constants.js +15 -1
  164. package/dist/privacy/index.d.ts +1 -0
  165. package/dist/privacy/index.js +1 -0
  166. package/dist/privacy/product-capture.d.ts +12 -0
  167. package/dist/privacy/product-capture.js +73 -0
  168. package/dist/privacy/sanitizer.d.ts +21 -3
  169. package/dist/privacy/sanitizer.js +52 -8
  170. package/dist/process/ancestors.d.ts +39 -0
  171. package/dist/process/ancestors.js +121 -0
  172. package/dist/process/constants/process.constants.d.ts +34 -0
  173. package/dist/process/constants/process.constants.js +34 -0
  174. package/dist/process/index.d.ts +7 -0
  175. package/dist/process/index.js +2 -0
  176. package/dist/process/types/process.types.d.ts +23 -0
  177. package/dist/process/types/process.types.js +1 -0
  178. package/dist/providers/antigravity/antigravity.adapter.d.ts +12 -1
  179. package/dist/providers/antigravity/antigravity.adapter.js +21 -3
  180. package/dist/providers/antigravity/antigravity.detect.d.ts +0 -9
  181. package/dist/providers/antigravity/antigravity.detect.js +1 -1
  182. package/dist/providers/antigravity/antigravity.provider.js +3 -2
  183. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +2 -0
  184. package/dist/providers/antigravity/constants/antigravity.constants.js +2 -0
  185. package/dist/providers/claude/claude.adapter.d.ts +11 -1
  186. package/dist/providers/claude/claude.adapter.js +26 -5
  187. package/dist/providers/claude/claude.otel.d.ts +32 -18
  188. package/dist/providers/claude/claude.otel.js +81 -6
  189. package/dist/providers/claude/claude.provider.js +5 -2
  190. package/dist/providers/claude/constants/claude.constants.d.ts +2 -0
  191. package/dist/providers/claude/constants/claude.constants.js +2 -0
  192. package/dist/providers/claude/constants/claude.otel.constants.d.ts +4 -0
  193. package/dist/providers/claude/constants/claude.otel.constants.js +8 -0
  194. package/dist/providers/codex/codex.adapter.d.ts +15 -1
  195. package/dist/providers/codex/codex.adapter.js +29 -5
  196. package/dist/providers/codex/codex.otel.d.ts +24 -2
  197. package/dist/providers/codex/codex.otel.js +147 -30
  198. package/dist/providers/codex/codex.provider.js +5 -2
  199. package/dist/providers/codex/constants/codex.constants.d.ts +2 -0
  200. package/dist/providers/codex/constants/codex.constants.js +16 -0
  201. package/dist/providers/codex/constants/codex.otel.constants.d.ts +5 -0
  202. package/dist/providers/codex/constants/codex.otel.constants.js +5 -0
  203. package/dist/providers/constants/provider.constants.d.ts +0 -3
  204. package/dist/providers/constants/provider.constants.js +0 -3
  205. package/dist/providers/cursor/constants/cursor.constants.d.ts +7 -0
  206. package/dist/providers/cursor/constants/cursor.constants.js +7 -0
  207. package/dist/providers/cursor/cursor.adapter.d.ts +33 -1
  208. package/dist/providers/cursor/cursor.adapter.js +52 -3
  209. package/dist/providers/cursor/cursor.detect.d.ts +0 -7
  210. package/dist/providers/cursor/cursor.detect.js +1 -1
  211. package/dist/providers/cursor/cursor.provider.js +5 -2
  212. package/dist/providers/gemini/constants/gemini.constants.d.ts +9 -0
  213. package/dist/providers/gemini/constants/gemini.constants.js +9 -0
  214. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +3 -1
  215. package/dist/providers/gemini/constants/gemini.otel.constants.js +3 -0
  216. package/dist/providers/gemini/gemini.adapter.d.ts +14 -1
  217. package/dist/providers/gemini/gemini.adapter.js +25 -5
  218. package/dist/providers/gemini/gemini.detect.d.ts +0 -7
  219. package/dist/providers/gemini/gemini.detect.js +1 -1
  220. package/dist/providers/gemini/gemini.otel.d.ts +19 -20
  221. package/dist/providers/gemini/gemini.otel.js +121 -17
  222. package/dist/providers/gemini/gemini.provider.js +2 -1
  223. package/dist/providers/index.d.ts +1 -1
  224. package/dist/providers/index.js +1 -1
  225. package/dist/providers/loaders.d.ts +10 -0
  226. package/dist/providers/loaders.js +40 -0
  227. package/dist/providers/provider.d.ts +11 -0
  228. package/dist/providers/provider.js +1 -1
  229. package/dist/providers/registry.d.ts +11 -8
  230. package/dist/providers/registry.js +11 -15
  231. package/dist/providers/shared/constants/hook-refusal.constants.d.ts +7 -0
  232. package/dist/providers/shared/constants/hook-refusal.constants.js +7 -0
  233. package/dist/providers/shared/constants/shell-directories.constants.d.ts +30 -0
  234. package/dist/providers/shared/constants/shell-directories.constants.js +39 -0
  235. package/dist/providers/shared/constants/tooling.constants.d.ts +18 -2
  236. package/dist/providers/shared/constants/tooling.constants.js +19 -3
  237. package/dist/providers/shared/event-builder.d.ts +12 -14
  238. package/dist/providers/shared/event-builder.js +20 -14
  239. package/dist/providers/shared/exporter-allowlist.d.ts +20 -0
  240. package/dist/providers/shared/exporter-allowlist.js +49 -0
  241. package/dist/providers/shared/hook-config.d.ts +2 -21
  242. package/dist/providers/shared/hook-config.js +5 -4
  243. package/dist/providers/shared/hook-refusal.d.ts +12 -0
  244. package/dist/providers/shared/hook-refusal.js +17 -1
  245. package/dist/providers/shared/install-record.d.ts +12 -2
  246. package/dist/providers/shared/install-record.js +5 -2
  247. package/dist/providers/shared/shell-directories.d.ts +24 -0
  248. package/dist/providers/shared/shell-directories.js +90 -0
  249. package/dist/providers/shared/tooling.d.ts +12 -1
  250. package/dist/providers/shared/tooling.js +18 -0
  251. package/dist/providers/shared/types/adapter.types.d.ts +1 -2
  252. package/dist/providers/types/provider.types.d.ts +57 -1
  253. package/dist/snapshot/constants/snapshot.constants.d.ts +32 -0
  254. package/dist/snapshot/constants/snapshot.constants.js +33 -0
  255. package/dist/snapshot/snapshot-event.js +52 -11
  256. package/dist/snapshot/snapshot-pipeline.js +1 -1
  257. package/dist/snapshot/types/snapshot.types.d.ts +2 -0
  258. package/dist/storage/atomic-file.d.ts +7 -0
  259. package/dist/storage/atomic-file.js +1 -1
  260. package/dist/storage/constants/storage.constants.d.ts +17 -0
  261. package/dist/storage/constants/storage.constants.js +17 -0
  262. package/dist/storage/disabled.d.ts +13 -0
  263. package/dist/storage/disabled.js +24 -0
  264. package/dist/storage/index.d.ts +2 -0
  265. package/dist/storage/index.js +2 -0
  266. package/dist/storage/paths.js +3 -2
  267. package/dist/storage/schemas/storage.schema.d.ts +72 -0
  268. package/dist/storage/schemas/storage.schema.js +6 -0
  269. package/dist/storage/sweep-marker.d.ts +19 -0
  270. package/dist/storage/sweep-marker.js +55 -0
  271. package/dist/storage/types/storage.types.d.ts +2 -0
  272. package/dist/storage/uninstalled.d.ts +58 -0
  273. package/dist/storage/uninstalled.js +107 -0
  274. package/dist/transport/auth-block.d.ts +66 -0
  275. package/dist/transport/auth-block.js +129 -0
  276. package/dist/transport/constants/transport.constants.d.ts +82 -3
  277. package/dist/transport/constants/transport.constants.js +83 -4
  278. package/dist/transport/cooldown.js +8 -1
  279. package/dist/transport/delivery.d.ts +14 -6
  280. package/dist/transport/delivery.js +80 -55
  281. package/dist/transport/http-transport.d.ts +1 -0
  282. package/dist/transport/http-transport.js +52 -10
  283. package/dist/transport/index.d.ts +6 -3
  284. package/dist/transport/index.js +3 -0
  285. package/dist/transport/queue-partition.d.ts +91 -0
  286. package/dist/transport/queue-partition.js +143 -0
  287. package/dist/transport/queue.d.ts +99 -20
  288. package/dist/transport/queue.js +210 -69
  289. package/dist/transport/response-body.d.ts +25 -0
  290. package/dist/transport/response-body.js +64 -0
  291. package/dist/transport/send.d.ts +11 -0
  292. package/dist/transport/send.js +17 -0
  293. package/dist/transport/types/delivery-flow.types.d.ts +19 -0
  294. package/dist/transport/types/delivery-flow.types.js +1 -0
  295. package/dist/transport/types/transport.types.d.ts +45 -0
  296. package/dist/turns/claude-transcript.d.ts +19 -1
  297. package/dist/turns/claude-transcript.js +46 -1
  298. package/dist/turns/codex-originator.d.ts +11 -0
  299. package/dist/turns/codex-originator.js +31 -0
  300. package/dist/turns/codex-transcript.d.ts +30 -0
  301. package/dist/turns/codex-transcript.js +88 -0
  302. package/dist/turns/constants/turns.constants.d.ts +141 -5
  303. package/dist/turns/constants/turns.constants.js +155 -5
  304. package/dist/turns/file-identity.d.ts +27 -0
  305. package/dist/turns/file-identity.js +48 -0
  306. package/dist/turns/gemini-transcript.d.ts +30 -0
  307. package/dist/turns/gemini-transcript.js +96 -0
  308. package/dist/turns/index.d.ts +3 -3
  309. package/dist/turns/index.js +1 -1
  310. package/dist/turns/inherited-checkout.d.ts +54 -0
  311. package/dist/turns/inherited-checkout.js +155 -0
  312. package/dist/turns/native-session-titles.d.ts +26 -0
  313. package/dist/turns/native-session-titles.js +102 -0
  314. package/dist/turns/transcript.d.ts +3 -2
  315. package/dist/turns/transcript.js +5 -1
  316. package/dist/turns/turn-state.d.ts +224 -3
  317. package/dist/turns/turn-state.js +456 -21
  318. package/dist/turns/turn-summary.d.ts +1 -14
  319. package/dist/turns/turn-summary.js +87 -51
  320. package/dist/turns/turn-tracker.d.ts +21 -2
  321. package/dist/turns/turn-tracker.js +379 -56
  322. package/dist/turns/types/transcript.types.d.ts +5 -0
  323. package/dist/turns/types/turn-state.types.d.ts +116 -5
  324. package/dist/turns/types/turn-summary.types.d.ts +64 -14
  325. package/dist/turns/types/turn-tracker.types.d.ts +27 -1
  326. package/dist/turns/work-checkout.d.ts +65 -0
  327. package/dist/turns/work-checkout.js +666 -0
  328. package/dist/untraced/constants/untraced.constants.d.ts +31 -0
  329. package/dist/untraced/constants/untraced.constants.js +63 -0
  330. package/dist/untraced/untraced.d.ts +35 -0
  331. package/dist/untraced/untraced.js +105 -0
  332. package/dist/update/constants/update.constants.d.ts +18 -0
  333. package/dist/update/constants/update.constants.js +20 -0
  334. package/dist/update/update-check.d.ts +52 -0
  335. package/dist/update/update-check.js +113 -0
  336. package/docs/AUDIT_PROMPT.md +129 -0
  337. package/docs/DATA_HANDLING.md +648 -0
  338. package/docs/ENTERPRISE_DEPLOYMENT.md +179 -0
  339. package/docs/PERFORMANCE.md +81 -0
  340. package/package.json +14 -4
  341. package/dist/enrollment/enrollment-provider.d.ts +0 -5
  342. package/dist/enrollment/manual-enrollment.d.ts +0 -32
  343. package/dist/enrollment/manual-enrollment.js +0 -72
  344. package/example/README.md +0 -43
  345. package/example/server.mjs +0 -240
  346. /package/dist/{enrollment/enrollment-provider.js → config/types/destination.types.js} +0 -0
package/README.md CHANGED
@@ -3,157 +3,278 @@
3
3
  [![npm](https://img.shields.io/npm/v/@agent-watch-ai/edge)](https://www.npmjs.com/package/@agent-watch-ai/edge)
4
4
  [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
5
 
6
- A lightweight, zero-daemon telemetry edge for AI coding agents (**Claude Code**, **OpenAI Codex**, **Cursor**, **Gemini CLI**, and **Google Antigravity**).
6
+ **See what your AI coding agents cost — per developer, repository and ticket.**
7
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.
8
+ It reads the agents' own hooks and their native OpenTelemetry export, and sends usage, cost and Git
9
+ context to your backend. Nothing sits in front of the model: no proxy, no MITM certificate, no
10
+ daemon, no root.
11
+
12
+ Supports **Claude Code**, **OpenAI Codex**, **Cursor**, **Gemini CLI** and **Google Antigravity**.
9
13
 
10
14
  ---
11
15
 
12
16
  ## Quick Start
13
17
 
14
- **Requirements:** Node.js 20+
18
+ **Requirements:** Node.js 20+ — every release runs the whole suite on Node 20 and Node 24 on Linux and macOS. Windows deployment remains unverified.
15
19
 
16
20
  ```bash
17
- # 1. Install globally
18
- npm install -g @agent-watch-ai/edge
21
+ npx -y @agent-watch-ai/edge setup --token YOUR_TOKEN
22
+ agentwatch doctor # is this machine actually reporting?
23
+ ```
24
+
25
+ Run through npx, setup installs this version globally (`npm install -g`) and finishes from there, so the hooks point at the permanent install. Restart any running agent afterwards: hooks and exporters are read at startup.
26
+
27
+ ---
28
+
29
+ ## Also here: `agent-watch-otel` (Python)
19
30
 
20
- # 2. Configure with your backend
21
- agentwatch setup --endpoint https://backend.example.com --token YOUR_TOKEN
31
+ [`python/agent-watch-otel/`](python/agent-watch-otel) is a separate, separately
32
+ released package for **production** LLM spend rather than coding agents. One line
33
+ beside a Phoenix registration sends digests of your prompts — never the prompts —
34
+ to Agent Watch, including the `service.name` and `service.version` Phoenix drops.
22
35
 
23
- # 3. Verify status & diagnostics
24
- agentwatch status
25
- agentwatch doctor
36
+ ```python
37
+ tracer_provider.add_span_processor(AgentWatchSpanProcessor(token="..."))
26
38
  ```
27
39
 
28
40
  ---
29
41
 
30
- ## Supported Agents & Limitations
42
+ ## Supported Agents
31
43
 
32
- | Agent | Hook Configuration | Native OTel Signals | Status |
44
+ | Agent | Hooks configured in | Native OTel signals | Token usage |
33
45
  |---|---|---|---|
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.
46
+ | **Claude Code** | `~/.claude/settings.json` | Logs, Traces, Metrics | Yes |
47
+ | **OpenAI Codex** | `~/.codex/hooks.json` | Logs, Traces (`~/.codex/config.toml`) | Yes |
48
+ | **Gemini CLI** | `~/.gemini/settings.json` | Logs, Traces, Metrics | Yes |
49
+ | **Cursor** | `~/.cursor/hooks.json` | None | **No** |
50
+ | **Google Antigravity** | `~/.gemini/config/hooks.json` | None | **No** |
59
51
 
60
- ---
52
+ Cursor and Antigravity expose no token usage in hooks or transcripts, so their `turn.summary`
53
+ events stay `usage_status: "pending"` and carry no cost. Everything else — turns, tools, files,
54
+ branches, ticket keys — is reported for all five.
61
55
 
62
- ## CLI Commands
56
+ Per-agent notes:
63
57
 
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
- ```
58
+ * **OpenAI Codex** — new hooks must be trusted once: launch `codex`, type `/hooks`, approve the AgentWatch entries.
59
+ * **Gemini CLI** — telemetry runs through `GEMINI_TELEMETRY_ENABLED` with `GEMINI_TELEMETRY_TARGET=local`, and the ingest token travels in `OTEL_EXPORTER_OTLP_HEADERS`; Gemini has no `otelHeadersHelper`.
60
+ * **Google Antigravity** — a turn is one *execution*: `PreInvocation`/`PostInvocation` bracket the model calls inside it and only `Stop` closes it. The prompt comes from `common.lastUserInput`; there is no user-prompt hook.
61
+ * **Cursor** — the CLI emits shell hooks only; the full lifecycle exists in IDE sessions. Cloud agents need a committed `.cursor/hooks.json` and the package installed in the cloud environment. Accepted tab edits (`afterTabFileEdit`) are monitored; high-frequency `beforeTabFileRead` is ignored.
83
62
 
84
63
  ---
85
64
 
86
- ## Parameters & Flags
65
+ ## CLI
66
+
67
+ ```bash
68
+ agentwatch setup --token <key> # install hooks and exporters
69
+ agentwatch status # backend, queue and agent health
70
+ agentwatch doctor # environment checks (--json for CI)
71
+ agentwatch config # active configuration, secrets redacted
72
+ agentwatch agents # detected agents and their state
73
+
74
+ agentwatch off # stop hooks, remove managed exporters
75
+ agentwatch on # put them back
76
+ agentwatch uninstall [--purge] # remove hooks, revoke this machine's credential; --purge also deletes ~/.agentwatch
77
+ agentwatch update [--check] # install the latest release from npm; --check only asks
78
+
79
+ agentwatch hook --agent claude [--dry-run] # invoked by the agents themselves
80
+ agentwatch otel-headers # print OTel headers for an agent
81
+ ```
87
82
 
88
- | Flag | Description | Default |
83
+ | Flag | Meaning | Default |
89
84
  |---|---|---|
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 | — |
85
+ | `--endpoint <url>` | Backend base URL: an Agent Watch host (`https://api.agent-watch.ai`), or loopback (`http:` allowed). Setup never prompts | `https://api.agent-watch.ai` |
86
+ | `--allow-custom-endpoint` | Trust the origin of this run's `--endpoint` when it is outside the Agent Watch hosts, such as a self-hosted backend. Only that origin is stored, in `customEndpoints`, and `status` and `doctor` show it. A re-run naming an origin already trusted needs no flag. Without it, setup refuses such a URL and writes nothing, and a config that names one sends nothing there: records stay queued and `doctor` names the fix. A config written before this release keeps its backends: they are added to `customEndpoints` once, on first load. A native exporter AgentWatch wrote into an agent's own config that points at a refused host is removed by `setup`, by `doctor`, and by the hooks at most once a day; `otel-headers` gives Claude Code's exporter the bearer only when it sends to the configured, allowed host. TLS is still checked against the system trust store, with no pinning | off |
87
+ | `--token <token>` | Bearer token for the backend | — |
88
+ | `--developer-email <email>` | Identity on turn summaries, and what per-developer budgets key on. Setup refuses to write a config when neither this flag nor git names a developer | `git config user.email` |
89
+ | `--root <path>` | File a second identity under a project root, so one machine can report to two tenants (needs its own `--token`) | — |
90
+ | `--otel <signals>` | Signals the agents export: `logs`, `traces`, `metrics`, `all`, `none` | `logs` |
91
+ | `--agent <id>` | Limit the command to one agent (`claude`, `codex`, `cursor`, `gemini`, `antigravity`) | all detected |
92
+ | `--dry-run` | With `hook`: print the events instead of sending them | `false` |
93
+ | `--json` | With `doctor`: machine-readable output | `false` |
94
+ | `--verbose` | Diagnostic logs on stderr | `false` |
95
+ | `--version` | Print the version | — |
101
96
 
102
97
  ---
103
98
 
104
99
  ## Configuration
105
100
 
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:
101
+ One global file: `~/.agentwatch/config.json`, written by `agentwatch setup`.
102
+
103
+ ### Content capture is opt-in
104
+
105
+ Prompt text, tool inputs, tool outputs and session titles are off by default. Turning one on takes **two** things —
106
+ the global `contentCaptureConsent` marker *and* the individual flag. The marker alone enables
107
+ nothing; a flag alone collects nothing. With all of them off a prompt or response is recorded only
108
+ as a length and a SHA-256, so turn counts and cost attribution work without the text. Ticket keys
109
+ named in the opening prompt are extracted on the machine and sent as `prompt_jira_ids`, unfiltered
110
+ (the platform keeps only keys it knows); the prompt text is not.
108
111
 
109
112
  ```json
110
113
  {
114
+ "contentCaptureConsent": true,
111
115
  "capture": {
112
- "prompts": true,
113
- "responses": false,
114
- "toolInput": true,
116
+ "promptText": false,
117
+ "toolInput": false,
115
118
  "toolOutput": false,
119
+ "sessionTitle": false,
116
120
  "git": true,
117
121
  "files": true
118
122
  }
119
123
  }
120
124
  ```
121
125
 
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.*
126
+ * `promptText` sends the turn's first prompt as `prompt_text`: blocks the agent's harness injected
127
+ (Claude Desktop's `<system-reminder>`) removed, secrets scrubbed over the whole text, then cut at
128
+ 4,000 characters. It is what lets the backend tell what a session with no repository was about.
129
+ * `toolInput` sends, per shell or connector (MCP) call, the command text or the server, tool and
130
+ arguments, as `tool_inputs`: at most 50 calls a turn, each string cut at 2,000 characters after
131
+ scrubbing.
132
+ * `sessionTitle` sends a Claude Code, Codex or Cursor session's native title on every turn:
133
+ `session_name` when the agent keeps a separate person-set name, and `session_title` for its
134
+ generated/display title, which can paraphrase the first prompt. Each is scrubbed, then cut at 200
135
+ characters. Reading Codex and Cursor's SQLite indexes requires Node 22.12 or newer; older runtimes
136
+ omit those optional fields. Gemini CLI and Antigravity expose neither, so the edge does not invent one.
137
+ * The agent's response text has no flag: it never leaves the machine.
138
+
139
+ `git` and `files` are on because they carry metadata, not content: remote, branch, SHA, and the
140
+ *path* of a file the agent touched — which is what feature and project attribution is built from.
141
+ A file outside every checkout (`~/Documents/Sample Budget.xlsx`) goes in its own
142
+ `external_files_touched` / `external_files_read` lists (while `git` is also on), home-relative: the home directory's name
143
+ is never sent.
144
+
145
+ **Upgrading from an earlier release?** `capture.prompts` and `capture.responses` no longer exist. A
146
+ config that still sets them collects nothing — `prompts: true` does not turn on `promptText`; the next `agentwatch setup` removes them and says so,
147
+ and `agentwatch doctor` names them until it does. Summaries an older release queued with text in
148
+ them are sent without it. The two tool flags without the consent marker read as `false`, are kept as
149
+ written, and `setup` names the ones that are set but inert.
150
+
151
+ **Native exporters never log prompts.** Setup forces prompt and response logging off in every agent
152
+ it configures (Claude `OTEL_LOG_USER_PROMPTS=0`, Codex `log_user_prompt = false`, Gemini
153
+ `GEMINI_TELEMETRY_LOG_PROMPTS=false`), whatever the consent state, and never enables Gemini traces,
154
+ which can carry prompts. Codex and Gemini usage logs can carry tool arguments and results with no
155
+ per-field filter, so setup configures them only when consent covers both `toolInput` and
156
+ `toolOutput` — which can leave `llm.call` usage unavailable for those two in metadata-only mode.
157
+
158
+ ### Untraced-run notice
159
+
160
+ After a shell run (`python`, `node`, `npm test`, …) in a repository whose dependency manifests
161
+ declare an LLM SDK and no tracing package, Claude Code and Codex show the developer one line saying
162
+ the run's spend is invisible. At most once per repository per session; decided on the laptop from
163
+ `package.json`, `pyproject.toml`, `requirements*.txt` and `Pipfile` only, and nothing is sent.
164
+ Turn it off in the global file (a repository's `.agentwatch.json` cannot change it):
125
165
 
126
- ### Budget enforcement (pre-turn check)
166
+ ```json
167
+ { "untracedNotices": false }
168
+ ```
127
169
 
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.
170
+ ### Repository overrides
171
+
172
+ A `.agentwatch.json` in a repository root can only turn capture **down** for that repository:
173
+
174
+ ```json
175
+ { "capture": { "toolOutput": false, "files": false } }
176
+ ```
177
+
178
+ A committed file that asks for *more* than the machine allows is ignored with a warning, so
179
+ checking a repository out can never start collecting content on someone else's machine. `endpoint`,
180
+ `token`, `developerEmail`, `enforcementUrl`, `roots` and the `delivery` / `otel` / `enforcement`
181
+ blocks are global-only: a repository file cannot redirect delivery or switch off a budget cap.
182
+
183
+ ### Two tenants on one machine
184
+
185
+ `roots` maps an absolute project root to the identity used beneath it; work outside every root keeps
186
+ the machine's own. Set the machine up first, then
187
+ `agentwatch setup --root ~/dev/acme --token <tenant token>` — a root never inherits the machine's
188
+ token — or by hand:
131
189
 
132
190
  ```json
133
191
  {
134
- "enforcement": { "enabled": true, "timeoutMs": 300, "cacheTtlMs": 60000 }
192
+ "endpoint": "https://backend.example.com",
193
+ "token": "<machine default>",
194
+ "roots": {
195
+ "/Users/me/dev/tripPlanner": { "token": "<tenant A>" },
196
+ "/Users/me/dev/acme": { "token": "<tenant B>", "developerEmail": "me@acme.com" }
197
+ }
135
198
  }
136
199
  ```
137
200
 
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.
201
+ Longest match wins. Point a root at the directory the agent actually opens: a session started one
202
+ level above it does not match. Only identity varies per root — capture and OTel signals stay
203
+ machine-wide, so `--otel` is refused together with `--root`. A session started above its
204
+ repositories reports the repository each turn worked in, but that changes nothing here: the start
205
+ folder decides which root, and therefore which tenant, a session belongs to — except that a session
206
+ started in no root, working in a checkout it inherited from the process that started the agent, sends
207
+ as the root that claims that checkout; if none does, the checkout is not reported. With roots configured and the start folder in none, a
208
+ checkout that no root claims is also reported, whatever its location. A repository
209
+ beneath it that another root claims is refused outright — its name, branch, commit and paths
210
+ belong to that root's tenant — and a repository's own `.agentwatch.json` narrows what a turn
211
+ reports about it, as it would for a session started inside.
212
+
213
+ The offline queue is partitioned to match (`<data>/queue/<digest-of-token>/`), as are the backend
214
+ cooldown and the loss tally, so a drain only ever sends the backlog belonging to the token it signs
215
+ with. Agents export native OTLP to one machine-wide endpoint, so under a root pointing at a
216
+ *different* backend `otel-headers` sends no bearer rather than the wrong tenant's — that tenant then
217
+ gets hook-path events only. Roots on the same backend, the usual case, differ only in bearer.
218
+
219
+ Upgrading from a version without partitions adopts an existing backlog when the machine has one
220
+ identity; when it already has several, those entries name no tenant and are moved to
221
+ `<data>/queue/unattributed/`, where `status` and `doctor` report them. Move them into a partition to
222
+ deliver them, or delete the directory to discard them.
223
+
224
+ ### Stopping collection without uninstalling
225
+
226
+ `agentwatch off` stops the hooks before they read stdin, withholds the OTLP bearer, and removes the
227
+ exporters AgentWatch installed — keeping config and queued events. `agentwatch on` restores it.
228
+ Restart running agents either way. See [docs/DATA_HANDLING.md](docs/DATA_HANDLING.md) for what the
229
+ off switch does and does not reach.
230
+
231
+ ### Fleet deployment
232
+
233
+ [`examples/mdm/`](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm) has a
234
+ Jamf/Kandji script, an Intune script, a Claude Code `managed-settings.json` policy file, and a
235
+ per-agent answer about what an administrator can lock — which for every agent but Claude Code is
236
+ currently "the developer can remove the hooks".
237
+
238
+ ### Budget enforcement
239
+
240
+ When a backend budget is set to **block** and the developer has breached it, the turn is refused
241
+ before the agent's first LLM call, in the agent's own protocol (Claude Code, Codex, Cursor, Gemini
242
+ CLI), with the backend's explanation shown to the developer.
142
243
 
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.
244
+ ```json
245
+ { "enforcement": { "enabled": true, "timeoutMs": 300, "cacheTtlMs": 5000 } }
246
+ ```
247
+
248
+ The check **fails open, always.** A turn stops only on an explicit
249
+ `{"decision":"block","message":"…"}` from `GET <backend>/v1/enforcement/decision`; an unreachable
250
+ backend, a timeout, any other status and any unreadable body let the turn proceed silently — so an
251
+ outage un-enforces budgets rather than stopping anyone. Set `enabled: false` to opt out.
252
+
253
+ Decisions are cached for `cacheTtlMs`, so a flat cap costs at most one bounded request per turn. A
254
+ feature-scoped cap costs one per gated prompt: the backend answers `cache_ttl_ms: 0` and the edge
255
+ honours that by not storing the answer. Antigravity is not gated — its pre-invocation hook carries
256
+ no decision field — and its turns are reported without token usage, so no cap advances on them.
145
257
 
146
- To try it locally: `BLOCK=1 npm run example` answers every check with a refusal.
258
+ To try it locally: `BLOCK=1 npm run example` refuses every check.
147
259
 
148
260
  ---
149
261
 
150
- ## Data Flow & Backend Integration
262
+ ## What reaches the backend
263
+
264
+ | Record | How | Contents |
265
+ |---|---|---|
266
+ | `turn.summary` | Edge hooks → `POST <backend>/v1/events` | One completed turn: prompt/response length and hash, tool counts, file paths (repo-relative, and home-relative outside a checkout), Git branch, ticket keys from the branch name and the opening prompt. Prompt text and shell/connector inputs only when opted in. Never response text. |
267
+ | `llm.call` | The agent's own OTLP → `POST <backend>/v1/otlp/v1/logs` | Token usage, cost and latency per model request. The edge does not proxy this. |
268
+ | `repo.snapshot` | Edge hooks, after a closed turn | Changed branch/commit metadata, including commit subjects, when Git capture is on. |
269
+
270
+ The backend joins `llm.call` to `turn.summary` on conversation and turn ids.
151
271
 
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.
272
+ Exact fields, local retention, privacy migration and off-switch behaviour:
273
+ [docs/DATA_HANDLING.md](docs/DATA_HANDLING.md). Release artifacts, rollback verification and the
274
+ explicitly deferred enterprise work (Windows, native binaries, signing, SOC 2):
275
+ [docs/ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md).
155
276
 
156
- ### Backend SDK Helpers
277
+ ### Backend SDK helpers
157
278
 
158
279
  ```ts
159
280
  import type { ProductEvent } from '@agent-watch-ai/edge/events';
package/SECURITY.md ADDED
@@ -0,0 +1,69 @@
1
+ # Security Policy
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Please report vulnerabilities privately via GitHub Security Advisories on this repository
6
+ (Security → "Report a vulnerability"). Do not open public issues for security reports. You can
7
+ expect an acknowledgement within a few business days.
8
+
9
+ ## Scope & design guarantees
10
+
11
+ AgentWatch Edge handles developer activity metadata, so the following are treated as security
12
+ bugs of the highest priority:
13
+
14
+ - response text leaving the machine, or reaching the queue or turn state, under any configuration;
15
+ prompt text or tool content leaving the machine while its capture flag or the global consent
16
+ marker is off; captured text leaving unscrubbed or beyond its bound; a path naming the home
17
+ directory
18
+ - setup enabling any agent's native prompt or response logging
19
+ - secrets (tokens, keys, credentials, URL-embedded credentials) surviving the sanitizer in
20
+ events, logs, queue files, or diagnostics output
21
+ - credentials written into agent config files beyond the two sanctioned places: Claude Code
22
+ gets a short-lived access token via `otelHeadersHelper` (never written to its settings), while
23
+ Codex has no headers-helper mechanism, so its OTel exporter carries the Bearer token inside
24
+ `~/.codex/config.toml` — which setup therefore keeps at mode 0600. Gemini also stores static
25
+ OTLP bearer headers in `~/.gemini/settings.json` (0600); it has no headers helper.
26
+ - a long-lived credential on disk in plaintext where an OS keychain exists. The edge exchanges
27
+ the organization install key for a per-device credential on its first run after setup or
28
+ upgrade, records the device beside the install key in `~/.agentwatch/config.json` (the key
29
+ stays there, 0600, while Codex and Gemini still present it; AWT-357), and keeps the device
30
+ secret in the macOS Keychain, the Secret Service keyring (libsecret) or a Windows
31
+ DPAPI-protected file. Only where none of those is usable (for example headless Linux) does
32
+ it fall back to a 0600 file under `~/.agentwatch/credentials/`, and `status` and `doctor`
33
+ say so. The secret is handed to the keychain tool on stdin, never in argv or the
34
+ environment, and the tool is run from the system directories, never found on `PATH`. What goes on the wire is a one-hour access token, cached 0600 per identity in
35
+ the data directory and refreshed by one process per machine under a lock.
36
+ - destructive or non-mergeful writes to `~/.claude` / `~/.codex` configuration
37
+ - the hook process breaking or blocking the host coding agent
38
+
39
+ ## Every line that runs on the developer's machine is open
40
+
41
+ There is no closed on-device component. What the Edge does on a laptop — which
42
+ hooks it registers, what it reads, what it sends, what the sanitizer strips — is
43
+ this repository, MIT-licensed, and a reviewer can read it rather than take our
44
+ word for it. The closed half is the backend that receives the records.
45
+
46
+ That is also the honest limit: a local administrator can read, edit or remove
47
+ any of it. The Edge does not self-protect and does not re-apply itself on a
48
+ schedule; a machine that stops reporting is the signal, and it is visible on the
49
+ platform side. See [MDM deployment](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm) for what an
50
+ administrator can and cannot lock per agent.
51
+
52
+ ## Data handling summary
53
+
54
+ - The public contract contains `llm.call`, `turn.summary`, and `repo.snapshot`. Raw lifecycle/tool hooks stay
55
+ local; tool I/O is never a third outbound event stream. If config is missing or corrupt, the
56
+ runtime fails safe to metadata-only summary capture.
57
+ - Git remote URLs are credential-stripped and normalized; hashes are available,
58
+ but summaries and snapshots also disclose normalized repository names.
59
+ - Local queue files live under the user's data directory and contain already-sanitized events.
60
+ - `doctor`/`status` never print token values.
61
+
62
+ The [data handling contract](docs/DATA_HANDLING.md) specifies collection defaults,
63
+ global consent migration, native OTLP boundaries, credentials, retention and the
64
+ local off switch. Native exporters require setup and an agent restart after an
65
+ upgrade; the hook consent gate cannot filter traffic sent directly by an agent.
66
+ To check that contract against the source with your own coding agent, use the
67
+ [audit prompt](docs/AUDIT_PROMPT.md).
68
+ No compliance attestation or completed penetration test is claimed. See
69
+ [deferred enterprise work](docs/ENTERPRISE_DEPLOYMENT.md).
@@ -0,0 +1,19 @@
1
+ import type { Env } from '../core/types/core.types.js';
2
+ import type { AgentWatchEvent } from '../events/types/events.types.js';
3
+ import type { SessionBillingEvent } from '../events/types/session-billing.types.js';
4
+ import type { TurnStateStore } from '../turns/turn-state.js';
5
+ /**
6
+ * The session's billing fact, the first time it is asked for.
7
+ *
8
+ * The id is derived from provider and session alone, so a resend (a resumed
9
+ * session, a queue retry) is the same record to the backend.
10
+ *
11
+ * @param store - Per-session state store; remembers that the fact was taken.
12
+ * @param events - The hook's canonical events.
13
+ * @param agentId - Internal provider id.
14
+ * @param env - Environment supplying HOME and the relevant variables.
15
+ * @param surface - Product surface the session runs on.
16
+ * @returns The event, or undefined when the session already has one, this hook
17
+ * does not open anything, or the mode cannot be told.
18
+ */
19
+ export declare function sessionBillingFact(store: TurnStateStore, events: readonly AgentWatchEvent[], agentId: string, env: Env, surface: string): Promise<SessionBillingEvent | undefined>;
@@ -0,0 +1,52 @@
1
+ import { compact } from '../core/object.js';
2
+ import { deriveEventId } from '../events/event-id.js';
3
+ import { EVENT_SCHEMA_VERSION } from '../events/constants/events.constants.js';
4
+ import { PROVIDER_LABELS } from '../turns/constants/turns.constants.js';
5
+ import { detectBillingMode } from './billing-mode.js';
6
+ /** The hooks that open a session or a turn: the earliest a collector hears from it. */
7
+ const OPENING_TYPES = new Set(['session.started', 'prompt.submitted']);
8
+ /**
9
+ * The session's billing fact, the first time it is asked for.
10
+ *
11
+ * The id is derived from provider and session alone, so a resend (a resumed
12
+ * session, a queue retry) is the same record to the backend.
13
+ *
14
+ * @param store - Per-session state store; remembers that the fact was taken.
15
+ * @param events - The hook's canonical events.
16
+ * @param agentId - Internal provider id.
17
+ * @param env - Environment supplying HOME and the relevant variables.
18
+ * @param surface - Product surface the session runs on.
19
+ * @returns The event, or undefined when the session already has one, this hook
20
+ * does not open anything, or the mode cannot be told.
21
+ */
22
+ export async function sessionBillingFact(store, events, agentId, env, surface) {
23
+ const opening = events.find((event) => OPENING_TYPES.has(event.event.type) && event.session.id);
24
+ if (!opening?.session.id)
25
+ return undefined;
26
+ const mode = await detectBillingMode(agentId, env);
27
+ // Unknown is not a fact, and must not use up the session's one send.
28
+ if (mode === 'unknown')
29
+ return undefined;
30
+ // A session that inherited its checkout may belong to another root's tenant,
31
+ // which only its turn summary resolves. Sent from here it would reach the
32
+ // machine's tenant and spend the session's one send; its summary carries the mode.
33
+ if (await store.readInherited(opening.session.id))
34
+ return undefined;
35
+ if (!(await store.takeBillingFact(opening.session.id)))
36
+ return undefined;
37
+ const timestamp = env.now().toISOString();
38
+ // The public label, as the turn summary and the calls carry it.
39
+ const provider = PROVIDER_LABELS[opening.agent.provider] ?? opening.agent.provider;
40
+ return compact({
41
+ schemaVersion: EVENT_SCHEMA_VERSION,
42
+ id: deriveEventId({ provider: opening.agent.provider, providerEventType: 'session.billing', sessionId: opening.session.id }),
43
+ timestamp,
44
+ event: { type: 'session.billing', providerEventType: 'session.billing' },
45
+ agent: { ...opening.agent, provider },
46
+ session: { id: opening.session.id, providerId: opening.session.id },
47
+ provider,
48
+ surface,
49
+ session_id: opening.session.id,
50
+ billing_mode: mode
51
+ });
52
+ }
@@ -11,6 +11,16 @@ export type { ParsedArgs } from './types/cli.types.js';
11
11
  * @returns The command, positionals and flags.
12
12
  */
13
13
  export declare function parseArgs(argv: readonly string[]): ParsedArgs;
14
+ /**
15
+ * The value flags given with no value, such as `--endpoint --token KEY`.
16
+ *
17
+ * Those parse as booleans and would read as absent, and an absent endpoint
18
+ * means the default backend: a typo must fail instead.
19
+ *
20
+ * @param parsed - Parsed arguments.
21
+ * @returns The flag names, without the `--`.
22
+ */
23
+ export declare function valuelessFlags(parsed: ParsedArgs): string[];
14
24
  /**
15
25
  * A flag's value when it was given as a string.
16
26
  *
package/dist/cli/args.js CHANGED
@@ -27,6 +27,14 @@ export function parseArgs(argv) {
27
27
  continue;
28
28
  }
29
29
  const name = arg.slice(FLAG_PREFIX.length);
30
+ const equals = name.indexOf('=');
31
+ // `--endpoint=https://…`: read as the flag and its value, never as an
32
+ // unknown flag that leaves the endpoint absent and the default in force.
33
+ if (equals > 0 && VALUE_FLAGS.has(name.slice(0, equals))) {
34
+ flags[name.slice(0, equals)] = name.slice(equals + 1) || true;
35
+ index += 1;
36
+ continue;
37
+ }
30
38
  const value = argv[index + 1];
31
39
  if (VALUE_FLAGS.has(name) && value !== undefined && !value.startsWith(FLAG_PREFIX)) {
32
40
  flags[name] = value;
@@ -38,6 +46,18 @@ export function parseArgs(argv) {
38
46
  }
39
47
  return { command, positional, flags };
40
48
  }
49
+ /**
50
+ * The value flags given with no value, such as `--endpoint --token KEY`.
51
+ *
52
+ * Those parse as booleans and would read as absent, and an absent endpoint
53
+ * means the default backend: a typo must fail instead.
54
+ *
55
+ * @param parsed - Parsed arguments.
56
+ * @returns The flag names, without the `--`.
57
+ */
58
+ export function valuelessFlags(parsed) {
59
+ return [...VALUE_FLAGS].filter((name) => parsed.flags[name] === true);
60
+ }
41
61
  /**
42
62
  * A flag's value when it was given as a string.
43
63
  *