@agent-watch-ai/edge 0.2.5 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (348) hide show
  1. package/CHANGELOG.md +558 -0
  2. package/README.md +222 -97
  3. package/SECURITY.md +72 -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 +52 -4
  9. package/dist/cli/constants/cli.constants.js +56 -5
  10. package/dist/cli/context.d.ts +33 -2
  11. package/dist/cli/context.js +84 -14
  12. package/dist/cli/doctor.js +321 -33
  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 +553 -103
  26. package/dist/cli/status.js +82 -13
  27. package/dist/cli/toggle.d.ts +9 -0
  28. package/dist/cli/toggle.js +117 -0
  29. package/dist/cli/types/cli.types.d.ts +43 -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 +110 -12
  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 +116 -6
  41. package/dist/config/constants/config.constants.js +131 -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 +831 -84
  51. package/dist/config/schemas/config.schema.js +398 -16
  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 +119 -0
  71. package/dist/credentials/constants/credentials.constants.js +120 -0
  72. package/dist/credentials/credential-status.d.ts +14 -0
  73. package/dist/credentials/credential-status.js +38 -0
  74. package/dist/credentials/credentials.d.ts +86 -0
  75. package/dist/credentials/credentials.js +278 -0
  76. package/dist/credentials/device-api.d.ts +73 -0
  77. package/dist/credentials/device-api.js +161 -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 +73 -0
  81. package/dist/credentials/identity.js +101 -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 +31 -0
  93. package/dist/credentials/sign-in.js +105 -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 +206 -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 +64 -17
  104. package/dist/enforcement/enforcement.d.ts +23 -2
  105. package/dist/enforcement/enforcement.js +107 -17
  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 +66 -2
  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 +10 -0
  160. package/dist/pipeline/constants/pipeline.constants.js +10 -0
  161. package/dist/pipeline/hook-pipeline.js +410 -33
  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 +75 -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 +36 -3
  197. package/dist/providers/codex/codex.otel.js +199 -32
  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 +10 -0
  202. package/dist/providers/codex/constants/codex.otel.constants.js +10 -0
  203. package/dist/providers/constants/provider.constants.d.ts +8 -3
  204. package/dist/providers/constants/provider.constants.js +8 -3
  205. package/dist/providers/cursor/constants/cursor.constants.d.ts +9 -0
  206. package/dist/providers/cursor/constants/cursor.constants.js +9 -0
  207. package/dist/providers/cursor/cursor.adapter.d.ts +33 -1
  208. package/dist/providers/cursor/cursor.adapter.js +129 -4
  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 +9 -1
  215. package/dist/providers/gemini/constants/gemini.otel.constants.js +9 -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 +30 -21
  221. package/dist/providers/gemini/gemini.otel.js +166 -22
  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/bearer-rewrite.d.ts +19 -0
  232. package/dist/providers/shared/bearer-rewrite.js +46 -0
  233. package/dist/providers/shared/constants/hook-refusal.constants.d.ts +7 -0
  234. package/dist/providers/shared/constants/hook-refusal.constants.js +7 -0
  235. package/dist/providers/shared/constants/shell-directories.constants.d.ts +30 -0
  236. package/dist/providers/shared/constants/shell-directories.constants.js +39 -0
  237. package/dist/providers/shared/constants/tooling.constants.d.ts +24 -2
  238. package/dist/providers/shared/constants/tooling.constants.js +25 -3
  239. package/dist/providers/shared/event-builder.d.ts +12 -14
  240. package/dist/providers/shared/event-builder.js +20 -14
  241. package/dist/providers/shared/exporter-allowlist.d.ts +20 -0
  242. package/dist/providers/shared/exporter-allowlist.js +49 -0
  243. package/dist/providers/shared/hook-config.d.ts +2 -21
  244. package/dist/providers/shared/hook-config.js +5 -4
  245. package/dist/providers/shared/hook-refusal.d.ts +12 -0
  246. package/dist/providers/shared/hook-refusal.js +17 -1
  247. package/dist/providers/shared/install-record.d.ts +12 -2
  248. package/dist/providers/shared/install-record.js +5 -2
  249. package/dist/providers/shared/shell-directories.d.ts +24 -0
  250. package/dist/providers/shared/shell-directories.js +90 -0
  251. package/dist/providers/shared/tooling.d.ts +40 -1
  252. package/dist/providers/shared/tooling.js +70 -1
  253. package/dist/providers/shared/types/adapter.types.d.ts +1 -2
  254. package/dist/providers/types/provider.types.d.ts +81 -1
  255. package/dist/snapshot/constants/snapshot.constants.d.ts +32 -0
  256. package/dist/snapshot/constants/snapshot.constants.js +33 -0
  257. package/dist/snapshot/snapshot-event.js +52 -11
  258. package/dist/snapshot/snapshot-pipeline.js +1 -1
  259. package/dist/snapshot/types/snapshot.types.d.ts +2 -0
  260. package/dist/storage/atomic-file.d.ts +21 -0
  261. package/dist/storage/atomic-file.js +20 -1
  262. package/dist/storage/constants/storage.constants.d.ts +19 -0
  263. package/dist/storage/constants/storage.constants.js +19 -0
  264. package/dist/storage/disabled.d.ts +13 -0
  265. package/dist/storage/disabled.js +24 -0
  266. package/dist/storage/index.d.ts +2 -0
  267. package/dist/storage/index.js +2 -0
  268. package/dist/storage/paths.js +3 -2
  269. package/dist/storage/schemas/storage.schema.d.ts +72 -0
  270. package/dist/storage/schemas/storage.schema.js +6 -0
  271. package/dist/storage/sweep-marker.d.ts +19 -0
  272. package/dist/storage/sweep-marker.js +55 -0
  273. package/dist/storage/types/storage.types.d.ts +2 -0
  274. package/dist/storage/uninstalled.d.ts +58 -0
  275. package/dist/storage/uninstalled.js +107 -0
  276. package/dist/transport/auth-block.d.ts +66 -0
  277. package/dist/transport/auth-block.js +129 -0
  278. package/dist/transport/constants/transport.constants.d.ts +82 -3
  279. package/dist/transport/constants/transport.constants.js +83 -4
  280. package/dist/transport/cooldown.js +8 -1
  281. package/dist/transport/delivery.d.ts +14 -6
  282. package/dist/transport/delivery.js +80 -55
  283. package/dist/transport/http-transport.d.ts +1 -0
  284. package/dist/transport/http-transport.js +52 -10
  285. package/dist/transport/index.d.ts +6 -3
  286. package/dist/transport/index.js +3 -0
  287. package/dist/transport/queue-partition.d.ts +91 -0
  288. package/dist/transport/queue-partition.js +143 -0
  289. package/dist/transport/queue.d.ts +99 -20
  290. package/dist/transport/queue.js +210 -69
  291. package/dist/transport/response-body.d.ts +25 -0
  292. package/dist/transport/response-body.js +64 -0
  293. package/dist/transport/send.d.ts +11 -0
  294. package/dist/transport/send.js +17 -0
  295. package/dist/transport/types/delivery-flow.types.d.ts +19 -0
  296. package/dist/transport/types/delivery-flow.types.js +1 -0
  297. package/dist/transport/types/transport.types.d.ts +45 -0
  298. package/dist/turns/claude-transcript.d.ts +19 -1
  299. package/dist/turns/claude-transcript.js +46 -1
  300. package/dist/turns/codex-originator.d.ts +11 -0
  301. package/dist/turns/codex-originator.js +31 -0
  302. package/dist/turns/codex-transcript.d.ts +30 -0
  303. package/dist/turns/codex-transcript.js +88 -0
  304. package/dist/turns/constants/turns.constants.d.ts +141 -5
  305. package/dist/turns/constants/turns.constants.js +155 -5
  306. package/dist/turns/file-identity.d.ts +27 -0
  307. package/dist/turns/file-identity.js +48 -0
  308. package/dist/turns/gemini-transcript.d.ts +30 -0
  309. package/dist/turns/gemini-transcript.js +96 -0
  310. package/dist/turns/index.d.ts +3 -3
  311. package/dist/turns/index.js +1 -1
  312. package/dist/turns/inherited-checkout.d.ts +54 -0
  313. package/dist/turns/inherited-checkout.js +155 -0
  314. package/dist/turns/native-session-titles.d.ts +26 -0
  315. package/dist/turns/native-session-titles.js +102 -0
  316. package/dist/turns/transcript.d.ts +3 -2
  317. package/dist/turns/transcript.js +5 -1
  318. package/dist/turns/turn-state.d.ts +224 -3
  319. package/dist/turns/turn-state.js +456 -21
  320. package/dist/turns/turn-summary.d.ts +1 -14
  321. package/dist/turns/turn-summary.js +87 -51
  322. package/dist/turns/turn-tracker.d.ts +21 -2
  323. package/dist/turns/turn-tracker.js +379 -56
  324. package/dist/turns/types/transcript.types.d.ts +5 -0
  325. package/dist/turns/types/turn-state.types.d.ts +116 -5
  326. package/dist/turns/types/turn-summary.types.d.ts +64 -14
  327. package/dist/turns/types/turn-tracker.types.d.ts +27 -1
  328. package/dist/turns/work-checkout.d.ts +67 -0
  329. package/dist/turns/work-checkout.js +700 -0
  330. package/dist/untraced/constants/untraced.constants.d.ts +31 -0
  331. package/dist/untraced/constants/untraced.constants.js +63 -0
  332. package/dist/untraced/untraced.d.ts +35 -0
  333. package/dist/untraced/untraced.js +105 -0
  334. package/dist/update/constants/update.constants.d.ts +18 -0
  335. package/dist/update/constants/update.constants.js +20 -0
  336. package/dist/update/update-check.d.ts +52 -0
  337. package/dist/update/update-check.js +113 -0
  338. package/docs/AUDIT_PROMPT.md +129 -0
  339. package/docs/DATA_HANDLING.md +655 -0
  340. package/docs/ENTERPRISE_DEPLOYMENT.md +194 -0
  341. package/docs/PERFORMANCE.md +81 -0
  342. package/package.json +14 -4
  343. package/dist/enrollment/enrollment-provider.d.ts +0 -5
  344. package/dist/enrollment/manual-enrollment.d.ts +0 -32
  345. package/dist/enrollment/manual-enrollment.js +0 -72
  346. package/example/README.md +0 -43
  347. package/example/server.mjs +0 -240
  348. /package/dist/{enrollment/enrollment-provider.js → config/types/destination.types.js} +0 -0
package/README.md CHANGED
@@ -3,157 +3,282 @@
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 package,
32
+ released together with its Node twin `@agent-watch-ai/otel`, for **production**
33
+ LLM spend rather than coding agents. One line
34
+ beside a Phoenix registration sends digests of your prompts — never the prompts —
35
+ to Agent Watch, including the `service.name` and `service.version` Phoenix drops.
22
36
 
23
- # 3. Verify status & diagnostics
24
- agentwatch status
25
- agentwatch doctor
37
+ ```python
38
+ tracer_provider.add_span_processor(AgentWatchSpanProcessor(token="..."))
26
39
  ```
27
40
 
28
41
  ---
29
42
 
30
- ## Supported Agents & Limitations
43
+ ## Supported Agents
31
44
 
32
- | Agent | Hook Configuration | Native OTel Signals | Status |
45
+ | Agent | Hooks configured in | Native OTel signals | Token usage |
33
46
  |---|---|---|---|
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.
47
+ | **Claude Code** | `~/.claude/settings.json` | Logs, Traces, Metrics | Yes |
48
+ | **OpenAI Codex** | `~/.codex/hooks.json` | Logs, Traces (`~/.codex/config.toml`) | Yes |
49
+ | **Gemini CLI** | `~/.gemini/settings.json` | Logs, Traces, Metrics | Yes |
50
+ | **Cursor** | `~/.cursor/hooks.json` | None | **No** |
51
+ | **Google Antigravity** | `~/.gemini/config/hooks.json` | None | **No** |
59
52
 
60
- ---
53
+ Cursor and Antigravity expose no token usage in hooks or transcripts, so their `turn.summary`
54
+ events stay `usage_status: "pending"` and carry no cost. Everything else — turns, tools, files,
55
+ branches, ticket keys — is reported for all five.
61
56
 
62
- ## CLI Commands
57
+ Per-agent notes:
63
58
 
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
- ```
59
+ * **OpenAI Codex** — new hooks must be trusted once: launch `codex`, type `/hooks`, approve the AgentWatch entries.
60
+ * **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`.
61
+ * **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.
62
+ * **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
63
 
84
64
  ---
85
65
 
86
- ## Parameters & Flags
66
+ ## CLI
67
+
68
+ ```bash
69
+ agentwatch setup --token <key> # install hooks and exporters
70
+ agentwatch status # backend, queue and agent health
71
+ agentwatch doctor # environment checks (--json for CI)
72
+ agentwatch config # active configuration, secrets redacted
73
+ agentwatch agents # detected agents and their state
74
+
75
+ agentwatch off # stop hooks, remove managed exporters
76
+ agentwatch on # put them back
77
+ agentwatch uninstall [--purge] # remove hooks, revoke this machine's credential; --purge also deletes ~/.agentwatch
78
+ agentwatch update [--check] # install the latest release from npm; --check only asks
79
+
80
+ agentwatch hook --agent claude [--dry-run] # invoked by the agents themselves
81
+ agentwatch otel-headers # print OTel headers for an agent
82
+ ```
87
83
 
88
- | Flag | Description | Default |
84
+ | Flag | Meaning | Default |
89
85
  |---|---|---|
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 | — |
86
+ | `--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` |
87
+ | `--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 |
88
+ | `--token <token>` | Bearer token for the backend | — |
89
+ | `--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` |
90
+ | `--root <path>` | File a second identity under a project root, so one machine can report to two tenants (needs its own `--token`) | — |
91
+ | `--otel <signals>` | Signals the agents export: `logs`, `traces`, `metrics`, `all`, `none` | `logs` |
92
+ | `--agent <id>` | Limit the command to one agent (`claude`, `codex`, `cursor`, `gemini`, `antigravity`) | all detected |
93
+ | `--dry-run` | With `hook`: print the events instead of sending them | `false` |
94
+ | `--json` | With `doctor`: machine-readable output | `false` |
95
+ | `--verbose` | Diagnostic logs on stderr | `false` |
96
+ | `--version` | Print the version | — |
101
97
 
102
98
  ---
103
99
 
104
100
  ## Configuration
105
101
 
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:
102
+ One global file: `~/.agentwatch/config.json`, written by `agentwatch setup`.
103
+
104
+ ### Content capture is opt-in
105
+
106
+ Prompt text, tool inputs, tool outputs and session titles are off by default. Turning one on takes **two** things —
107
+ the global `contentCaptureConsent` marker *and* the individual flag. The marker alone enables
108
+ nothing; a flag alone collects nothing. With all of them off a prompt or response is recorded only
109
+ as a length and a SHA-256, so turn counts and cost attribution work without the text. Ticket keys
110
+ named in the opening prompt are extracted on the machine and sent as `prompt_jira_ids`, unfiltered
111
+ (the platform keeps only keys it knows); the prompt text is not.
108
112
 
109
113
  ```json
110
114
  {
115
+ "contentCaptureConsent": true,
111
116
  "capture": {
112
- "prompts": true,
113
- "responses": false,
114
- "toolInput": true,
117
+ "promptText": false,
118
+ "toolInput": false,
115
119
  "toolOutput": false,
120
+ "sessionTitle": false,
116
121
  "git": true,
117
- "files": true
122
+ "files": true,
123
+ "mcpNames": true
118
124
  }
119
125
  }
120
126
  ```
121
127
 
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.*
128
+ * `promptText` sends the turn's first prompt as `prompt_text`: blocks the agent's harness injected
129
+ (Claude Desktop's `<system-reminder>`) removed, secrets scrubbed over the whole text, then cut at
130
+ 4,000 characters. It is what lets the backend tell what a session with no repository was about.
131
+ * `toolInput` sends, per shell or connector (MCP) call, the command text or the server, tool and
132
+ arguments, as `tool_inputs`: at most 50 calls a turn, each string cut at 2,000 characters after
133
+ scrubbing.
134
+ * `sessionTitle` sends a Claude Code, Codex or Cursor session's native title on every turn:
135
+ `session_name` when the agent keeps a separate person-set name, and `session_title` for its
136
+ generated/display title, which can paraphrase the first prompt. Each is scrubbed, then cut at 200
137
+ characters. Reading Codex and Cursor's SQLite indexes requires Node 22.12 or newer; older runtimes
138
+ omit those optional fields. Gemini CLI and Antigravity expose neither, so the edge does not invent one.
139
+ * `mcpNames` (on by default) names each MCP call in `tools_used` as `mcp__<server>__<tool>`, no
140
+ arguments. Off, every MCP call counts under `mcp`. A repository file can turn it off, never on.
141
+ * The agent's response text has no flag: it never leaves the machine.
142
+
143
+ `git` and `files` are on because they carry metadata, not content: remote, branch, SHA, and the
144
+ *path* of a file the agent touched — which is what feature and project attribution is built from.
145
+ A file outside every checkout (`~/Documents/Sample Budget.xlsx`) goes in its own
146
+ `external_files_touched` / `external_files_read` lists (while `git` is also on), home-relative: the home directory's name
147
+ is never sent.
148
+
149
+ **Upgrading from an earlier release?** `capture.prompts` and `capture.responses` no longer exist. A
150
+ config that still sets them collects nothing — `prompts: true` does not turn on `promptText`; the next `agentwatch setup` removes them and says so,
151
+ and `agentwatch doctor` names them until it does. Summaries an older release queued with text in
152
+ them are sent without it. The two tool flags without the consent marker read as `false`, are kept as
153
+ written, and `setup` names the ones that are set but inert.
154
+
155
+ **Native exporters never log prompts.** Setup forces prompt and response logging off in every agent
156
+ it configures (Claude `OTEL_LOG_USER_PROMPTS=0`, Codex `log_user_prompt = false`, Gemini
157
+ `GEMINI_TELEMETRY_LOG_PROMPTS=false`), whatever the consent state, and never enables Gemini traces,
158
+ which can carry prompts. Codex and Gemini usage logs can carry tool arguments and results with no
159
+ per-field filter, so setup configures them only when consent covers both `toolInput` and
160
+ `toolOutput` — which can leave `llm.call` usage unavailable for those two in metadata-only mode.
161
+
162
+ ### Untraced-run notice
163
+
164
+ After a shell run (`python`, `node`, `npm test`, …) in a repository whose dependency manifests
165
+ declare an LLM SDK and no tracing package, Claude Code and Codex show the developer one line saying
166
+ the run's spend is invisible. At most once per repository per session; decided on the laptop from
167
+ `package.json`, `pyproject.toml`, `requirements*.txt` and `Pipfile` only, and nothing is sent.
168
+ Turn it off in the global file (a repository's `.agentwatch.json` cannot change it):
125
169
 
126
- ### Budget enforcement (pre-turn check)
170
+ ```json
171
+ { "untracedNotices": false }
172
+ ```
127
173
 
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.
174
+ ### Repository overrides
175
+
176
+ A `.agentwatch.json` in a repository root can only turn capture **down** for that repository:
177
+
178
+ ```json
179
+ { "capture": { "toolOutput": false, "files": false } }
180
+ ```
181
+
182
+ A committed file that asks for *more* than the machine allows is ignored with a warning, so
183
+ checking a repository out can never start collecting content on someone else's machine. `endpoint`,
184
+ `token`, `developerEmail`, `enforcementUrl`, `roots` and the `delivery` / `otel` / `enforcement`
185
+ blocks are global-only: a repository file cannot redirect delivery or switch off a budget cap.
186
+
187
+ ### Two tenants on one machine
188
+
189
+ `roots` maps an absolute project root to the identity used beneath it; work outside every root keeps
190
+ the machine's own. Set the machine up first, then
191
+ `agentwatch setup --root ~/dev/acme --token <tenant token>` — a root never inherits the machine's
192
+ token — or by hand:
131
193
 
132
194
  ```json
133
195
  {
134
- "enforcement": { "enabled": true, "timeoutMs": 300, "cacheTtlMs": 60000 }
196
+ "endpoint": "https://backend.example.com",
197
+ "token": "<machine default>",
198
+ "roots": {
199
+ "/Users/me/dev/tripPlanner": { "token": "<tenant A>" },
200
+ "/Users/me/dev/acme": { "token": "<tenant B>", "developerEmail": "me@acme.com" }
201
+ }
135
202
  }
136
203
  ```
137
204
 
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.
205
+ Longest match wins. Point a root at the directory the agent actually opens: a session started one
206
+ level above it does not match. Only identity varies per root — capture and OTel signals stay
207
+ machine-wide, so `--otel` is refused together with `--root`. A session started above its
208
+ repositories reports the repository each turn worked in, but that changes nothing here: the start
209
+ folder decides which root, and therefore which tenant, a session belongs to — except that a session
210
+ started in no root, working in a checkout it inherited from the process that started the agent, sends
211
+ 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
212
+ checkout that no root claims is also reported, whatever its location. A repository
213
+ beneath it that another root claims is refused outright — its name, branch, commit and paths
214
+ belong to that root's tenant — and a repository's own `.agentwatch.json` narrows what a turn
215
+ reports about it, as it would for a session started inside.
216
+
217
+ The offline queue is partitioned to match (`<data>/queue/<digest-of-token>/`), as are the backend
218
+ cooldown and the loss tally, so a drain only ever sends the backlog belonging to the token it signs
219
+ with. Agents export native OTLP to one machine-wide endpoint, so under a root pointing at a
220
+ *different* backend `otel-headers` sends no bearer rather than the wrong tenant's — that tenant then
221
+ gets hook-path events only. Roots on the same backend, the usual case, differ only in bearer.
222
+
223
+ Upgrading from a version without partitions adopts an existing backlog when the machine has one
224
+ identity; when it already has several, those entries name no tenant and are moved to
225
+ `<data>/queue/unattributed/`, where `status` and `doctor` report them. Move them into a partition to
226
+ deliver them, or delete the directory to discard them.
227
+
228
+ ### Stopping collection without uninstalling
229
+
230
+ `agentwatch off` stops the hooks before they read stdin, withholds the OTLP bearer, and removes the
231
+ exporters AgentWatch installed — keeping config and queued events. `agentwatch on` restores it.
232
+ Restart running agents either way. See [docs/DATA_HANDLING.md](docs/DATA_HANDLING.md) for what the
233
+ off switch does and does not reach.
234
+
235
+ ### Fleet deployment
236
+
237
+ [`examples/mdm/`](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm) has a
238
+ Jamf/Kandji script, an Intune script, a Claude Code `managed-settings.json` policy file, and a
239
+ per-agent answer about what an administrator can lock — which for every agent but Claude Code is
240
+ currently "the developer can remove the hooks".
241
+
242
+ ### Budget enforcement
243
+
244
+ When a backend budget is set to **block** and the developer has breached it, the turn is refused
245
+ before the agent's first LLM call, in the agent's own protocol (Claude Code, Codex, Cursor, Gemini
246
+ CLI), with the backend's explanation shown to the developer.
142
247
 
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.
248
+ ```json
249
+ { "enforcement": { "enabled": true, "timeoutMs": 300, "cacheTtlMs": 5000 } }
250
+ ```
251
+
252
+ The check **fails open, always.** A turn stops only on an explicit
253
+ `{"decision":"block","message":"…"}` from `GET <backend>/v1/enforcement/decision`; an unreachable
254
+ backend, a timeout, any other status and any unreadable body let the turn proceed silently — so an
255
+ outage un-enforces budgets rather than stopping anyone. Set `enabled: false` to opt out.
256
+
257
+ Decisions are cached for `cacheTtlMs`, so a flat cap costs at most one bounded request per turn. A
258
+ feature-scoped cap costs one per gated prompt: the backend answers `cache_ttl_ms: 0` and the edge
259
+ honours that by not storing the answer. Antigravity is not gated — its pre-invocation hook carries
260
+ no decision field — and its turns are reported without token usage, so no cap advances on them.
145
261
 
146
- To try it locally: `BLOCK=1 npm run example` answers every check with a refusal.
262
+ To try it locally: `BLOCK=1 npm run example` refuses every check.
147
263
 
148
264
  ---
149
265
 
150
- ## Data Flow & Backend Integration
266
+ ## What reaches the backend
267
+
268
+ | Record | How | Contents |
269
+ |---|---|---|
270
+ | `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. |
271
+ | `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. |
272
+ | `repo.snapshot` | Edge hooks, after a closed turn | Changed branch/commit metadata, including commit subjects, when Git capture is on. |
273
+
274
+ The backend joins `llm.call` to `turn.summary` on conversation and turn ids.
151
275
 
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.
276
+ Exact fields, local retention, privacy migration and off-switch behaviour:
277
+ [docs/DATA_HANDLING.md](docs/DATA_HANDLING.md). Release artifacts, rollback verification and the
278
+ explicitly deferred enterprise work (Windows, native binaries, signing, SOC 2):
279
+ [docs/ENTERPRISE_DEPLOYMENT.md](docs/ENTERPRISE_DEPLOYMENT.md).
155
280
 
156
- ### Backend SDK Helpers
281
+ ### Backend SDK helpers
157
282
 
158
283
  ```ts
159
284
  import type { ProductEvent } from '@agent-watch-ai/edge/events';
package/SECURITY.md ADDED
@@ -0,0 +1,72 @@
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 device's one-hour
24
+ access token inside `~/.codex/config.toml` — which setup therefore keeps at mode 0600, and
25
+ every hook rewrites as the token rotates. Gemini stores the same access token in
26
+ `~/.gemini/settings.json` (0600); it has no headers helper. The device secret is never written
27
+ to either file, and the install key only while the machine has no device yet: the
28
+ first hook with a device token replaces it, and on Windows the next successful setup does (docs/NATIVE_OTLP_TOKENS.md).
29
+ - a long-lived credential on disk in plaintext where an OS keychain exists. The edge exchanges
30
+ the organization install key for a per-device credential on its first run after setup or
31
+ upgrade, records the device beside the install key in `~/.agentwatch/config.json` (the key
32
+ stays there, 0600, to enroll again when the secret expires), and keeps the device
33
+ secret in the macOS Keychain, the Secret Service keyring (libsecret) or a Windows
34
+ DPAPI-protected file. Only where none of those is usable (for example headless Linux) does
35
+ it fall back to a 0600 file under `~/.agentwatch/credentials/`, and `status` and `doctor`
36
+ say so. The secret is handed to the keychain tool on stdin, never in argv or the
37
+ 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
38
+ the data directory and refreshed by one process per machine under a lock.
39
+ - destructive or non-mergeful writes to `~/.claude` / `~/.codex` configuration
40
+ - the hook process breaking or blocking the host coding agent
41
+
42
+ ## Every line that runs on the developer's machine is open
43
+
44
+ There is no closed on-device component. What the Edge does on a laptop — which
45
+ hooks it registers, what it reads, what it sends, what the sanitizer strips — is
46
+ this repository, MIT-licensed, and a reviewer can read it rather than take our
47
+ word for it. The closed half is the backend that receives the records.
48
+
49
+ That is also the honest limit: a local administrator can read, edit or remove
50
+ any of it. The Edge does not self-protect and does not re-apply itself on a
51
+ schedule; a machine that stops reporting is the signal, and it is visible on the
52
+ platform side. See [MDM deployment](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm) for what an
53
+ administrator can and cannot lock per agent.
54
+
55
+ ## Data handling summary
56
+
57
+ - The public contract contains `llm.call`, `turn.summary`, and `repo.snapshot`. Raw lifecycle/tool hooks stay
58
+ local; tool I/O is never a third outbound event stream. If config is missing or corrupt, the
59
+ runtime fails safe to metadata-only summary capture.
60
+ - Git remote URLs are credential-stripped and normalized; hashes are available,
61
+ but summaries and snapshots also disclose normalized repository names.
62
+ - Local queue files live under the user's data directory and contain already-sanitized events.
63
+ - `doctor`/`status` never print token values.
64
+
65
+ The [data handling contract](docs/DATA_HANDLING.md) specifies collection defaults,
66
+ global consent migration, native OTLP boundaries, credentials, retention and the
67
+ local off switch. Native exporters require setup and an agent restart after an
68
+ upgrade; the hook consent gate cannot filter traffic sent directly by an agent.
69
+ To check that contract against the source with your own coding agent, use the
70
+ [audit prompt](docs/AUDIT_PROMPT.md).
71
+ No compliance attestation or completed penetration test is claimed. See
72
+ [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
  *