@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
@@ -0,0 +1,648 @@
1
+ # Data handling contract
2
+
3
+ This document describes `0.3.0`, not every previously published package. **Every
4
+ release up to and including npm `0.2.5` enabled content capture by default**;
5
+ `0.3.0` is the release that turns it off and puts it behind explicit consent.
6
+ Check the installed version — `agentwatch --version` — and run `agentwatch config`
7
+ and `agentwatch doctor` during deployment. To check this document against the source
8
+ with your own coding agent, use [AUDIT_PROMPT.md](AUDIT_PROMPT.md).
9
+ AgentWatch is a user-level, hook-only Node.js program. It does not install a daemon,
10
+ require root, proxy model requests, or enforce an administrator-proof policy.
11
+
12
+ ## Defaults and upgrade consent
13
+
14
+ **Prompt text and tool content are opt-in; response text is never collected.**
15
+ By default a prompt or response is represented only by its length and SHA-256.
16
+ Ticket keys named in a prompt are the one exception: they are extracted on the
17
+ machine and sent as `prompt_jira_ids`, unfiltered (the platform keeps only keys it
18
+ knows); the prompt text is not.
19
+ There is no capture flag for response text.
20
+
21
+ Prompt text, tool input and tool output bodies, and session titles, are not collected by default.
22
+ Default capture is:
23
+
24
+ ```json
25
+ {
26
+ "contentCaptureConsent": false,
27
+ "capture": {
28
+ "promptText": false,
29
+ "toolInput": false,
30
+ "toolOutput": false,
31
+ "sessionTitle": false,
32
+ "git": true,
33
+ "files": true
34
+ }
35
+ }
36
+ ```
37
+
38
+ To find which checkout a turn worked in, the hook inspects a shell command's text
39
+ in memory for directory names and discards it. This applies to the shell calls of
40
+ every agent the edge supports: Claude Code, Codex, Cursor, Gemini CLI and
41
+ Antigravity. The command's working directory is used as a candidate when the agent
42
+ reports it (Cursor's shell `cwd`, Gemini's `dir_path`, Antigravity's `Cwd`), and so
43
+ are the folders a Cursor window has open. Only checkout roots confirmed on disk
44
+ are kept, in local turn state, until the turn closes. The command is never stored,
45
+ queued, logged or sent for that purpose. This happens only while `capture.git` is
46
+ on. Separately, with `toolInput` on, the command text itself is sent on the turn
47
+ summary (see `tool_inputs` below).
48
+
49
+ Configurations written by earlier releases may still carry `capture.prompts` or
50
+ `capture.responses`. Those keys are ignored on load whatever their value —
51
+ `prompts: true` does not turn on `promptText`, a new name chosen for that reason — the next
52
+ `agentwatch setup` removes them from the file and says so once, and `doctor`
53
+ reports them while they remain.
54
+
55
+ Old configurations with content flags explicitly `true` are interpreted as
56
+ metadata-only unless the global `contentCaptureConsent` marker is exactly `true`.
57
+ Neither loading nor `agentwatch setup` rewrites those flags: the gate is applied in
58
+ memory on every read, so adding the marker later restores the values already on
59
+ disk rather than finding them erased. Missing, unreadable, invalid, and corrupt
60
+ global configuration do not authorize content capture. Git and file-path capture
61
+ remain enabled unless separately disabled.
62
+
63
+ Intentional content opt-in requires editing the **global**
64
+ `~/.agentwatch/config.json`: set `contentCaptureConsent` to `true` and explicitly
65
+ set `promptText`, `toolInput`, `toolOutput` and/or `sessionTitle` to `true`. The marker alone does not enable
66
+ fields that are false. Set the marker to `false` to revoke consent. `config`,
67
+ `status`, and `doctor` report consent and capture state without printing captured
68
+ content. Repository `.agentwatch.json` files cannot grant consent, increase any
69
+ capture field, alter identity, redirect delivery, or change
70
+ enforcement/delivery/native OTel settings. They may reduce individual capture
71
+ fields.
72
+
73
+ Current policy is reapplied to old turn state before queueing, and to every queued
74
+ record before HTTP delivery: summaries always lose `prompt` and `response` text an
75
+ older release may have written, lose `prompt_text`, `tool_inputs`, `session_name` and `session_title` unless their
76
+ flag is on with consent, lose every path list once `capture.files` is off, and repository snapshots are dropped entirely once
77
+ `capture.git` is off. Old files are not erased by an upgrade; their original content
78
+ may remain locally until consumed or expired, but it is never sent.
79
+
80
+ **Upgrade native telemetry separately:** rerun `agentwatch setup` after upgrading,
81
+ then restart every running coding agent. Existing native exporter configuration
82
+ and in-memory exporters do not change merely because npm replaces the CLI.
83
+ Use `agentwatch off` and close agents before upgrading if export must be stopped
84
+ during the transition. Setup always disables native prompt logging (Claude
85
+ `OTEL_LOG_USER_PROMPTS=0`, Codex `log_user_prompt = false`, Gemini
86
+ `GEMINI_TELEMETRY_LOG_PROMPTS=false`) and Claude tool detail/content logging,
87
+ whatever the consent state, and never enables Gemini detailed traces, which can
88
+ carry prompts. Codex and Gemini usage logs can contain tool arguments/results
89
+ without a reliable per-field filter, so the Edge configures those logs only when
90
+ global consent exists and both `toolInput` and `toolOutput` are enabled. Gemini
91
+ metrics may run without content consent. This can leave `llm.call` usage
92
+ unavailable by default for Codex and Gemini. Codex turns still carry token
93
+ counts: the Edge reads only the `token_count` and `turn_context` rows of the
94
+ Codex rollout file locally (per-request token numbers and the model name) and
95
+ puts the totals on the turn summary; no rollout content is read into it or sent.
96
+
97
+ ## Outbound records
98
+
99
+ There are three public event types, not a raw lifecycle or tool event stream:
100
+
101
+ | Type | Source and purpose |
102
+ | --- | --- |
103
+ | `turn.summary` | Edge hooks assemble one completed turn and send it to the events endpoint, or queue it. |
104
+ | `llm.call` | Agents export native OTLP directly. The backend/library normalizes supported completed request records into per-call usage. Edge does not proxy native OTLP. |
105
+ | `repo.snapshot` | Edge queues changed repository branch/commit metadata after a closed turn when Git capture is enabled. |
106
+
107
+ Generated records share `schemaVersion`, `id`, `timestamp`, `event.type`,
108
+ `event.providerEventType`, `agent.provider`, `agent.name`, session identifiers,
109
+ and optional `developer.installationId`. Absent fields are omitted. Provider
110
+ availability determines which identifiers and usage values exist.
111
+
112
+ ### `turn.summary`
113
+
114
+ The hook-generated flat fields are `provider`, `surface`, `session_id`, `turn_id`,
115
+ `developer_id`, `repository`, `branch`, `commit`, `jira_ids`, `prompt_jira_ids`, `work_evidence`,
116
+ `parent_session_id`, `content_hashes`, `manifest_repository`, `files_changed`, `files_touched`, `files_read`, `external_files_touched`,
117
+ `external_files_read`, `prompt_evidence`, `prompt_text`, `session_name`, `session_title`, `tool_inputs`, `response_evidence`,
118
+ `tool_calls`, `tools_used`, `model`, `billing_mode`, `input_tokens`,
119
+ `cached_input_tokens`, `cache_creation_input_tokens`, `output_tokens`,
120
+ `usage_status`, `started_at`, and `ended_at`. The nested `session` contains `id`,
121
+ `providerId`, and optionally `turnId`.
122
+
123
+ `prompt_jira_ids` are the ticket keys (same syntax as the branch keys in `jira_ids`)
124
+ found in the session's opening prompt, extracted on the machine and sent on every
125
+ turn at every tier, with no consent step. Only the keys are sent, never the prompt
126
+ text. `capture.git: false` withholds them, as it does `jira_ids`.
127
+
128
+ A prompt is free text, so a string like `INV-204391`, `MRN-123456` or `UTF-8`
129
+ matches the key syntax too. The edge sends every candidate unfiltered, in order,
130
+ deduplicated and capped at 50; the platform matches them against the keys it knows
131
+ (branch names, connected trackers) and ignores the rest, so an unknown key is inert.
132
+
133
+ On the machine the keys are kept in `prompt-tickets.json` in the session's local
134
+ turn state (mode 0600): keys only, written once by the opening prompt, and an
135
+ empty list when `capture.git` is off for that prompt. Unlike the rest of the turn
136
+ state it is not deleted at SessionEnd, so a session resumed under the same id
137
+ keeps its keys instead of taking "continue" as its opening prompt. The memo keeps
138
+ every key the prompt named. The 24-hour
139
+ sweep deletes it, counted from SessionEnd, so a session resumed within a day of
140
+ ending keeps its keys.
141
+
142
+ No field carries response text. Evidence contains `length` and `sha256` of the
143
+ text the developer typed and the agent answered; it is not raw text, but hashes
144
+ and lengths can still reveal information about short or guessable text. The
145
+ prompt evidence hashes the prompt as the agent reported it.
146
+
147
+ - `prompt_text` (only under `promptText` with consent): the turn's first prompt,
148
+ with `<system-reminder>` blocks the agent's harness injected removed, secrets
149
+ scrubbed over the whole text, then cut at 4,000 characters.
150
+ - `session_name` and `session_title` (only under `sessionTitle` with consent):
151
+ the native session titles read from Claude Code's transcript, Codex's local
152
+ state database or Cursor's local conversation search index. `session_name` is
153
+ a separate person-set name where the agent keeps one; `session_title` is the
154
+ generated/display title. A generated
155
+ title is written by the agent from the conversation and can paraphrase the first
156
+ prompt. Secrets are scrubbed over each whole title, then it is cut to 200
157
+ characters without splitting an emoji. Both are sent on every turn, so a renamed
158
+ session's next turn carries the new name. The edge never derives a title from
159
+ the prompt itself. Gemini CLI and Antigravity expose no native title and send
160
+ neither. While the flag is on, Claude Code's last name and generated title seen
161
+ are kept, each on its own, in local turn state (mode 0600) for a turn whose
162
+ transcript tail no longer reaches one, and deleted with the session. Codex and
163
+ Cursor's SQLite indexes are opened read-only through Node's standard library;
164
+ Node versions before 22.12 omit those optional title fields.
165
+ - `tool_inputs` (only under `toolInput` with consent): per shell or connector (MCP)
166
+ call, `{tool, command}` or `{tool, server, name, arguments}` with the arguments as
167
+ JSON text; sensitive argument keys are redacted before that, every string is cut
168
+ at 2,000 characters after scrubbing, and at most 50 calls are sent per turn.
169
+ Tool output bodies are not sent on the summary; enabling tool flags does not add
170
+ a tool event stream.
171
+ - `external_files_touched` / `external_files_read` (under `files`, and only while
172
+ `git` is on, since that is what tells inside a checkout from outside): files outside
173
+ every checkout, home-relative (`~/Documents/a.xlsx`); a path outside the home
174
+ directory is sent as it is. `files_touched` and `files_read` are unchanged:
175
+ repo-relative, or a bare basename for a file in no checkout, as before.
176
+
177
+ Between the prompt hook and the turn's close, the scrubbed prompt text and tool
178
+ inputs sit in local turn state (mode 0600), and only while their flag is on; the
179
+ close consumes them, and a session's end or the 24-hour expiry deletes the rest.
180
+
181
+ The public summary type additionally supports backend-derived `llm_calls`,
182
+ `agent_usage`, `reasoning_output_tokens`, `total_tokens`, and `cost_usd`.
183
+ `agent_usage` holds agent/parent/type identifiers, call count, token counts and
184
+ cost. Hooks initially report usage as `pending` or transcript-based `provisional`;
185
+ backend aggregation may mark it `partial` or `complete`.
186
+
187
+ ### OTLP and `llm.call`
188
+
189
+ Normalized calls carry `provider`, `surface`, `call_id`, `provider_request_id`,
190
+ `provider_session_id`, `provider_turn_id`, `session_id`, `turn_id`, `agent_id`,
191
+ `parent_agent_id`, `agent_type`, `model`, `billing_mode`, `status`, `correlation`,
192
+ `input_tokens`, `cached_input_tokens`, `cache_creation_input_tokens`,
193
+ `output_tokens`, `reasoning_output_tokens`, `total_tokens`, `cost_usd`,
194
+ `duration_ms`, `started_at`, `ended_at`, and optional joined `repository`, `branch`,
195
+ `commit`, `jira_ids`. Common envelope fields and optional Git/feature attribution
196
+ also apply. These are identity, usage, timing and development metadata; the
197
+ normalized call schema does not include prompt/response text or tool bodies.
198
+
199
+ Two request headers are added to the managed native exporters, and nothing else
200
+ on that route is ours: `Authorization`, carrying the one-hour device access token
201
+ (or, until it is exchanged, the install key), and
202
+ `x-agentwatch-installation`, carrying this installation's id. That id is a random
203
+ UUID generated locally on first use; it is not derived from a user, a machine
204
+ name or any account, and it identifies nothing without the backend that issued
205
+ the token. It is what lets measured per-call usage be traced back to a sender
206
+ when the turn summary that would have named a developer never arrives. Claude
207
+ Code receives both through its `otelHeadersHelper`, so neither is written to its
208
+ settings file; Codex and Gemini receive them in the config files described under
209
+ "Identity, local storage, and credentials". No developer identity is placed in a
210
+ native exporter header or resource attribute.
211
+
212
+ Native OTLP is a separate trust boundary: provider logs, resource attributes,
213
+ trace/span IDs, and optional traces/metrics reach the receiver **before** this
214
+ normalization. The Edge hook sanitizer and consent marker cannot filter that
215
+ traffic. AgentWatch does not claim the normalized schema describes every raw
216
+ OTLP attribute emitted by every provider version. Provider settings, ambient
217
+ environment, or custom exporters can change what is sent. Validate the actual
218
+ provider version and receiver filtering for a pilot; do not assume a backend
219
+ dropping a field means it never left the machine. Logs are requested by default,
220
+ but the content gate above can prevent their provider configuration; traces and
221
+ metrics default off. See [Claude telemetry](https://code.claude.com/docs/en/monitoring-usage)
222
+ and [Gemini telemetry](https://geminicli.com/docs/cli/telemetry/) for provider gates.
223
+
224
+ ### `repo.snapshot` and Git metadata
225
+
226
+ Snapshots contain `provider`, `surface`, `repository`, optional `developer_id`,
227
+ `default_branch`, `captured_at`, and `branches`. Each branch has `name`,
228
+ `head_sha`, optional `last_commit_at`, and `commits`; each commit has `sha`,
229
+ `subject`, optional `authored_at`, and optional `files`. `files` lists the files
230
+ that commit changed as `{ path, status }`: `path` is repository-relative as git
231
+ names it, and `status` is git's name-status letter (`A`, `M`, `D` or `T`; a
232
+ rename is sent as its delete and its add). **Names only, never file contents.**
233
+ Files named like credentials (`.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `*.pfx`,
234
+ `id_rsa`/`id_ed25519`/`id_ecdsa`, `credentials`, `credentials.*`, `.npmrc`, `.netrc`), paths
235
+ over 1,024 characters and paths holding control characters are left out. A
236
+ branch names at most 200 files and 16 KiB of path across its commits, newest
237
+ commit first; the rest are dropped without a marker. Only commits the branch has
238
+ that its trunk does not are listed, so trunk work never appears as a branch's
239
+ files. `files` is absent when the listing failed, ran out of the snapshot's time
240
+ budget or was cut short, on a commit the branch's cap had no room left for, and
241
+ on a commit whose every file was left out; an empty `files` means git listed none
242
+ (a merge or an empty commit). `capture.files: false`, global or set by the
243
+ repository, withholds `files` like every other path list: the listing does not
244
+ run, and a snapshot queued before the change loses `files` at delivery. Lists and subjects are bounded by the
245
+ snapshot implementation. Git capture includes commit subjects, which can contain
246
+ sensitive business information even though they are classified as metadata.
247
+ Set global `capture.git: false` to disable new snapshots; already-queued snapshots
248
+ are then discarded at delivery rather than sent.
249
+
250
+ Remote URL userinfo is removed before normalization. Normalization yields
251
+ `host/org/repo`, omitting scheme, query, fragment and `.git` suffix. A SHA-256 hash
252
+ of that normalized identity is available for Git attribution. **Repository names
253
+ are not hash-only:** current summaries and snapshots send the normalized
254
+ repository identity, or the checkout basename when no remote is available.
255
+ Branches, commit SHAs, ticket keys and file paths are metadata, not anonymous data.
256
+ Paths are made repository-relative where possible; paths outside the repository
257
+ can remain absolute, with the home prefix abbreviated to `~`.
258
+
259
+ Each turn reports the checkout its work changed, wherever the session started.
260
+ Agents often sit in one folder and work in a worktree beside it through shell
261
+ commands. A tool hook names candidate checkouts — the one it runs in, a file
262
+ tool's file's, those a shell command names or runs in, and Cursor's open
263
+ workspace folders — and records each candidate's
264
+ root with a fingerprint of it (HEAD, branch, and the dirty paths' status letters,
265
+ sizes and modification times). The turn's closing hook fingerprints them again and
266
+ reports, in order: the checkout the turn changed most; else the session's last
267
+ changed checkout; else the one it named most; else the folder it ended in, as
268
+ before; and, for a session started in a folder that is no checkout, a fifth
269
+ fallback, the checkout inherited from the process that started the agent (see
270
+ "Sessions that start outside a checkout" below). `work_evidence` says which of
271
+ the five (`changed`, `carried`, `referenced`, `cwd`, `inherited`). `files_changed` lists only the files this turn changed
272
+ there (at most 500), no longer the checkout's whole dirty tree, and
273
+ `files_touched` / `files_read` carry that checkout's paths only; paths in other
274
+ checkouts are dropped, while the calls still count. No new class of data is
275
+ collected: repository, branch, commit and paths were already sent for a session
276
+ started inside a repository.
277
+
278
+ Which checkouts may be reported is decided by the folder the session started in.
279
+ With project roots configured, only checkouts that the start folder's root
280
+ claims, or, when the start folder is in no root, checkouts that no root claims
281
+ either; without roots, only checkouts beneath the start folder. A checkout
282
+ another root claims is refused outright: it gets no record and is never
283
+ fingerprinted. Checkouts are judged by where they really are, not through symlinks.
284
+ Local turn state keeps the candidate roots, the fingerprints, the start folder
285
+ and the session's last changed checkout's root (`work-checkout.json`); none of it
286
+ is sent, and it goes with the session's other turn state. The prompt gate reads
287
+ that file to ask about that checkout's repository and branch instead of the
288
+ folder the agent sits in; the same two fields travel as before, and never for a
289
+ checkout the asking folder's root does not govern.
290
+
291
+ That file also keeps the branch the session changed there and the
292
+ repository-relative files its turns changed on it. When several sessions share a
293
+ checkout, a closing turn reads the other active sessions' files of this kind and
294
+ their open turns' edit-tool paths and the branch each open turn first saw a
295
+ checkout on, on the same machine, so that another session's
296
+ branch switch or files are not reported as this turn's. Nothing of it is sent, and
297
+ no git process is added for it.
298
+
299
+ What is reported about that repository follows *its* effective config, not the
300
+ start folder's: a `.agentwatch.json` committed inside it narrows the turn exactly
301
+ as it would a session started there — `capture.git: false` withholds the
302
+ repository, branch, commit and ticket keys, `capture.files: false` its paths.
303
+ And a repository that a project root of its own claims (see README, "Two
304
+ tenants on one machine") is never a candidate: the start folder decides which tenant a
305
+ session sends as (a session started in no root may send as the root that claims
306
+ an inherited checkout, below), so that repository's name, branch, commit and paths are
307
+ dropped rather than delivered to another tenant.
308
+
309
+ This resolution reads the file paths the agent's tools named, so it follows
310
+ `capture.files`: with `capture.files: false` no path is captured, and a session
311
+ started above its repositories then reports no repository or branch — as it did
312
+ before. A session started inside a repository is unaffected, since its
313
+ repository comes from the start folder rather than from any path.
314
+
315
+ ### Sessions that start outside a checkout
316
+
317
+ An agent is sometimes started by another process, such as a review bot, an
318
+ orchestrator or an SDK app, in a folder with no Git context. The hook then
319
+ cannot name a repository from its own folder. These paths add local reads and
320
+ three summary fields (`parent_session_id`, `content_hashes`,
321
+ `manifest_repository`); they are designed to support a review of what leaves the
322
+ machine and are not a compliance claim. Except for recording the agent's own
323
+ process id and start time at every session's first hook, each applies only to a
324
+ turn whose own folder has no Git context.
325
+
326
+ **Inherited checkout (`work_evidence: inherited`, `parent_session_id`).** At
327
+ every session's first hook the edge reads, with `ps`, the agent's own process id
328
+ and start time (the hook's parent, or that parent's parent when a shell wraps the
329
+ hook) and records them locally, so a later session started by this agent can find
330
+ it. Only when the folder is no checkout and `capture.git` is on does it go
331
+ further: it lists every process's id and parent id on the machine (`ps -A`) in
332
+ memory, and keeps the chain of at most 8 processes above the agent: process id and
333
+ parent id only. A start time is asked for (one `ps -p`) only for an ancestor
334
+ already recorded as an agent, to rule out a reused process id. Working folders
335
+ (`lsof -b` on macOS, `/proc` on Linux) are read only when no live parent agent
336
+ session already supplies the checkout. All of it runs once per session under one 100 ms overall deadline, which also
337
+ stops any `ps` or `lsof` still running, and any
338
+ failure or timeout leaves the session as it was. The result is the nearest live
339
+ parent agent session's last work checkout; when no live parent agent session is
340
+ found at walk time, or the one found has no work checkout yet, the checkout the
341
+ nearest ancestor's folder lies in. A parent
342
+ found at walk time whose session has since ended still answers with the checkout
343
+ it had at walk time: the walk does not run again, and the ancestors' folders are
344
+ not looked up then. `inherited` is the last resort, behind every other
345
+ `work_evidence` value. Process ids, parent ids, start times and ancestor folders
346
+ never leave the machine and are not logged. They are kept in local turn state
347
+ (mode 0600): `agent-process.json` (the agent's pid and start time),
348
+ `inherited-checkout.json` (the resolved checkout root and the parent session id)
349
+ and `agent-pids/<pid>.json` (an index from a live agent's pid to its session).
350
+ They expire with the other turn state (24 hours). What is sent is what any
351
+ checkout report carries: `repository`, `branch`, `commit` and ticket keys,
352
+ labelled `inherited`, plus `parent_session_id`, the parent agent's own session
353
+ id. `capture.git: false` withholds all of it, and the ancestor walk does not
354
+ run.
355
+
356
+ **Declared parent (`AGENTWATCH_PARENT_SESSION`).** A launcher that starts an
357
+ agent on another agent's behalf (a spinoff in a new terminal tab, a review bot,
358
+ your own orchestrator) can name the launching session by setting
359
+ `AGENTWATCH_PARENT_SESSION=<parent session id>` in the child agent's
360
+ environment. Hooks inherit it, and every turn summary of the child then carries
361
+ it as `parent_session_id`, whatever its `work_evidence`, ahead of any parent the
362
+ ancestor walk finds. A value that is not a plain session id (letters, digits,
363
+ `.`, `_`, `:`, `-`, at most 200 characters) or that equals the child's own
364
+ session id is ignored. Nothing is stored locally for it. `capture.git: false`
365
+ withholds it.
366
+
367
+ **Tenant.** With project roots configured, a session whose start folder is in no
368
+ root sends an inherited checkout only if a root claims that checkout, and then
369
+ under that root's token, destination and developer. A checkout no root claims is
370
+ not sent, and is never sent as the machine default. Without roots there is one
371
+ tenant and nothing is re-routed.
372
+
373
+ **File content ids (`content_hashes`).** Only with both `capture.files` and
374
+ `capture.git` on, and only when the folder has no Git context and the closing hook's own folder
375
+ reported no repository, the edge reads up to 20 files that the agent's own tools
376
+ named (files it edited first, then files it read), within a 100 ms budget past which
377
+ the remaining files are skipped, in memory, to compute Git's
378
+ blob id: the SHA-1 Git itself assigns the content (`git hash-object`). A file over
379
+ 1 MB, a file whose name is exactly `.env` or `.env.<anything>`, `credentials` or
380
+ `credentials.<anything>`, `id_rsa`, `id_ed25519`, `id_ecdsa`, `.npmrc` or
381
+ `.netrc`, or ends in `.pem`, `.key`, `.p12` or `.pfx` (matched case-insensitively,
382
+ on both the named path and its real target; other names such as `.envrc` or
383
+ `credentials-prod.json` are not skipped), and a file whose real path lies
384
+ outside the session folder, symlinks included, is skipped. The summary carries up
385
+ to 20 `{path, blob_sha}` pairs, the path relative to the session folder. This feature adds no file content and no path from outside the session folder: a file whose real path lies outside it is skipped, and only its name can appear, under `external_files_touched` or `external_files_read` when `files` is on, as described above. With debug logging on, a failed read can log that file's path on this machine. A blob id is an object id of the same kind as the commit SHAs already
386
+ sent, but a guessable file's id can still be confirmed by someone who has that
387
+ file.
388
+
389
+ **Manifest repository (`manifest_repository`).** Under the same conditions and within the same 100 ms budget (past it no address is sent), the
390
+ edge reads the nearest `package.json`, `composer.json`, `go.mod`, `Cargo.toml` or
391
+ `pyproject.toml` at or above the folder (stopping before the home directory, or, for a folder outside it, at the filesystem root), in
392
+ memory, and keeps only one field from it: `repository` in `package.json`
393
+ (a string, or its `url`), `support.source` in `composer.json`, the module path in
394
+ `go.mod` (a host with a dot, then owner and repository), `package.repository` in
395
+ `Cargo.toml`, and in `pyproject.toml` a `repository`, `source`, `source code`,
396
+ `sourcecode`, `github` or `code` entry under `project.urls`, else `repository` under
397
+ `tool.poetry`. The address is cleaned like
398
+ a Git remote (credentials and scheme removed, `.git` suffix dropped, form
399
+ `host/owner/repo`) and cut at 500 characters, and is sent as `manifest_repository`. The rest of the manifest is discarded.
400
+
401
+ These reads happen locally and in memory, next to the existing rule that tool
402
+ input and output bodies are not collected by default: a named file or manifest is
403
+ read whole, but only the fields above are kept. No new class of outbound data is
404
+ added, because the fields are Git and operational metadata. On the receiving side, hashes and
405
+ manifest addresses are matched only against that tenant's own repositories and
406
+ are not stored in the database or logged; only the resolution result and its source are kept. Like every
407
+ summary field they do travel in the Pub/Sub message, and an event that is dead-lettered keeps
408
+ them, with the rest of the message, in the dead-letter topic until Pub/Sub expires the message.
409
+
410
+ ## Identity, local storage, and credentials
411
+
412
+ Developer identity is the configured `developerEmail`, falling back to Git email
413
+ resolution. Setup requires an identity. The email is sent as `developer_id` and
414
+ used for enforcement. It is not currently pseudonymized with a tenant HMAC.
415
+ An installation UUID also identifies the installation. Native providers may send
416
+ their own session/account/resource identifiers independently.
417
+
418
+ Global configuration is stored in `~/.agentwatch/config.json` (0600). The
419
+ organization install key written by setup (from `--token`, `$AGENTWATCH_TOKEN`
420
+ or the prompt) is exchanged once through `POST /v1/devices/enroll` for a device
421
+ credential of this machine's own, and the config records `device: { id, store }`
422
+ beside the key. The key stays in the file only because Codex and Gemini still
423
+ present it (moving them to short-lived tokens, and the key out of the file, is
424
+ AWT-357); the Claude hooks and header helper send the device's access token
425
+ and never the key once the device is recorded. The device reference is an id
426
+ derived from the install key's digest and the name of the store that holds the
427
+ secret. The device secret lives in the macOS Keychain (service
428
+ `agentwatch-device`), the Secret Service keyring through `secret-tool` (only
429
+ with a D-Bus session), or a Windows DPAPI blob under
430
+ `~/.agentwatch/credentials/`; with none of those it is a 0600 file in the same
431
+ directory, reported by `status` and `doctor`. A failed exchange keeps the install
432
+ key, which goes on working, and is retried an hour later. The one-hour access
433
+ token the backend accepts is cached in `identity/<id>/access-token.json` (0600)
434
+ in the data root and refreshed through `POST /v1/devices/token` when under a
435
+ quarter of its life remains; the secret is read from the keychain only then.
436
+ On Windows a hook never starts PowerShell itself: setup makes the exchange,
437
+ and a DPAPI-held device's due refresh runs in one detached
438
+ `agentwatch refresh-credential` (at most one every five minutes), while that
439
+ hook sends with the token it has or queues. A refresh or exchange in a hook
440
+ spends at most half the delivery budget and is skipped while the backend
441
+ cooldown stands. Only the refresh route's own refusals (device unknown,
442
+ revoked or secret expired) are permanent; anything else is retried after the
443
+ cooldown. A refused refresh stops sends for that identity,
444
+ queues every record, is said once on stderr and stays visible in `status` and
445
+ `doctor` until the machine is enrolled again: by itself when the secret only
446
+ expired (hourly backoff), and only by `setup --token <install key>` when the
447
+ device was revoked or is unknown, so a hook never undoes a revocation. `uninstall` (all agents)
448
+ first revokes the device on the platform (`POST /v1/devices/revoke`, the
449
+ secret in the body), then removes the device secret, the cached token and the
450
+ reference. When the platform cannot be reached or does not confirm, uninstall
451
+ still finishes locally and says the credential is still active; an
452
+ administrator revokes the machine in Settings → Install. Uninstall also leaves
453
+ `uninstalled.json` beside the config, naming the machine and each root: until
454
+ `setup` runs again for one of them, nothing exchanges or sends the install key
455
+ kept in the config for it, and `status` and `doctor` say it is uninstalled. Ownership records are in
456
+ `~/.agentwatch/install-state.json`. `AGENTWATCH_CONFIG_DIR` overrides this root.
457
+ The data root is `$XDG_DATA_HOME/agentwatch`, falling back to
458
+ `~/.local/share/agentwatch`. On Windows, when present, `%LOCALAPPDATA%/agentwatch`
459
+ is used; Windows deployment is not verified. `AGENTWATCH_DATA_DIR` overrides it.
460
+
461
+ The data root contains `queue/`, `turns/`, `backups/`, `locks/`, `snapshots/`,
462
+ `checkouts/`, delivery/cooldown/enforcement state, and `disabled.json` when off.
463
+ The queue contains sanitized product records and their destination, attempts,
464
+ and retry timestamps. Defaults are 2,000 events, 20 attempts, and 7 days.
465
+ Expiration is processed during activity, not by a daemon or scheduled erasure.
466
+ Capacity pressure removes oldest entries. Turn state has a 24-hour stale-state
467
+ cleanup bound, and queued records a `maxEventAgeDays` bound (7 by default). Both
468
+ sweeps are activity-driven and run at most hourly. On an active installation,
469
+ removal happens at the next eligible sweep after expiration; an idle machine
470
+ retains the files until activity resumes. Backups and other local caches have no
471
+ guaranteed automatic deletion deadline. The package does not delete provider-owned
472
+ transcripts; it can read them locally for usage attribution.
473
+
474
+ Config, queues, turn state and the off marker use POSIX mode 0600.
475
+
476
+ **Codex and Gemini hold a static bearer token in their own configuration file
477
+ (still the install key setup wrote; moving them to short-lived tokens is
478
+ tracked separately),
479
+ and this is a property of those agents rather than a choice made here.** Neither
480
+ CLI has a mechanism for fetching a credential at request time, so the only way
481
+ to authenticate their native OTLP exporters is to write the bearer into the file
482
+ they read at startup: `~/.codex/config.toml` for Codex, and
483
+ `OTEL_EXPORTER_OTLP_HEADERS` inside `~/.gemini/settings.json` for Gemini. Claude
484
+ Code does have such a mechanism — `otelHeadersHelper`, which calls
485
+ `agentwatch otel-headers` at runtime — so no Claude configuration file ever
486
+ contains a token. Cursor and Antigravity have no managed native exporter, so the
487
+ question does not arise for them.
488
+
489
+ Because those two files then contain a credential, AgentWatch sets them to 0600
490
+ when — and only when — the block it writes actually carries the token. The files
491
+ belong to those agents, not to AgentWatch, so the permission bits each one had
492
+ beforehand are recorded in the install state and restored by `uninstall`: a file
493
+ that was 0644 before does not stay 0600 after the token is gone. A file that was
494
+ already private stays private, and nothing is tightened when no credential is
495
+ written. Backups preserve source permissions and can contain
496
+ credentials, including historical copies. Other directories/files use existing
497
+ permissions or process defaults; POSIX modes are not a verified Windows ACL
498
+ guarantee. Local data is not encrypted by this package. Passing a token on the
499
+ setup command line can expose it through shell history/process inspection.
500
+
501
+ ## Endpoints and failure behavior
502
+
503
+ The operator configures the backend; there is no hard-coded hosted destination.
504
+ Defaults derived from that endpoint are `POST /v1/events`, native OTLP base
505
+ `/v1/otlp` with `/v1/logs`, `/v1/traces`, `/v1/metrics` signal suffixes, and
506
+ `GET /v1/enforcement/decision`. Global `eventsUrl`, `otlpUrl`, and
507
+ `enforcementUrl` may override those routes. Authentication uses a bearer token
508
+ when configured. Every URL in the configuration is validated on every *read* of
509
+ the file, not only when `setup` writes it: `https://` anywhere, and `http://`
510
+ only to `localhost`, `127.0.0.1` or `::1`. A configuration naming any other
511
+ scheme — or plain `http://` to a remote host — refuses that URL and `doctor`
512
+ reports it. The remaining valid configuration and identity stay loaded; a
513
+ refused root destination does not inherit machine telemetry routes.
514
+ Enforcement sends developer and checkout attribution, and the session's
515
+ model when the agent named one, not prompt/tool bodies.
516
+ Doctor probes connectivity with an empty events batch carrying the same
517
+ credentials a real delivery uses, so its verdict describes the configured
518
+ install: it distinguishes a backend that accepted the credential, one that
519
+ rejected it (a failure, with a non-zero exit code), one that is unreachable, and
520
+ an install with no backend configured yet. It always performs that probe, even
521
+ while sends are suspended — the diagnostic is a direct question to the backend
522
+ and is never answered from local state. Status can drain the queue. Both stop
523
+ network activity while disabled.
524
+
525
+ The one request that goes to a host other than the backend is the update check:
526
+ at most once a day a session-start hook starts a detached `agentwatch update
527
+ --check`, which sends a plain `GET https://registry.npmjs.org/@agent-watch-ai/edge/latest`
528
+ with no headers or data of ours, and caches the answer in
529
+ `<data dir>/update-check.json`. The hook itself only reads that cache. Global
530
+ `"updateNotices": false` stops both the request and the notice.
531
+
532
+ Hook errors return the provider's passive response/exit zero. Unknown inputs,
533
+ missing configuration, parser failures and unexpected exceptions must not crash
534
+ the coding agent. One exit is not zero: when a file read under the 100 ms budget
535
+ (content ids or the manifest) is still hung, as on a stuck network mount, after
536
+ the turn is queued and the answer is written, the hook ends itself with SIGKILL,
537
+ because Node cannot exit while that read is pending. The agent sees a failed
538
+ hook, as it would at its own hook timeout, only sooner. A delivery pass shares a default 1,500 ms monotonic network budget across
539
+ its direct send, backlog batch and isolation probes. Each request uses the
540
+ remaining budget. Exhaustion defers unsent records without consuming their retry
541
+ attempts or marking the backend unavailable. Filesystem work, transcript settling,
542
+ enforcement and snapshots have separate costs; this is not a hard deadline for
543
+ the entire hook. Failed records are queued before diagnostic writes, with bounded
544
+ retries and eventual loss reported by status.
545
+
546
+ The gateway reports partial publish failures as HTTP 503, so the entire batch
547
+ is retried with its original IDs. A 2xx acknowledges the batch; its `rejected`
548
+ counter records permanent per-event rejection without a retry or cooldown.
549
+ Receivers must handle replay safely: the gateway's dedupe cache lasts 10 minutes,
550
+ while edge backoff can reach 6 hours. Later retries require durable idempotency
551
+ in downstream storage; the gateway cache alone is insufficient. A thrown transport
552
+ error also queues the records. Unread response bodies are cancelled and stream
553
+ readers are released.
554
+
555
+ A backend that answers 401 or 403 is refusing the credential, not failing
556
+ transiently. The records stay queued — a product record is never discarded on a
557
+ failed send, and that does not change — but automatic sends for that
558
+ (destination, credential) pair are suspended rather than re-presenting a
559
+ rejected bearer on every hook for the whole retention window, which reads to a
560
+ backend's security monitoring as low-rate credential stuffing and to the
561
+ operator as nothing at all. No queued entry spends a retry attempt while the
562
+ refusal stands, including when it first occurs during an isolation probe.
563
+ Normal age and size retention limits still apply. `status` reports the refusing status, when the refusals started and how
564
+ many records are held. The suspension is lifted by configuring a different
565
+ credential or endpoint, or by `doctor` proving the credential good again; it
566
+ never expires on a timer. This is
567
+ not a guarantee of lossless delivery. Native exporter retry behavior is owned by
568
+ the provider, not the Edge queue. Sanitization is unconditional for Edge records;
569
+ it redacts known credential patterns/sensitive keys and bounds string/depth sizes.
570
+ Pattern matching cannot guarantee discovery of every possible secret.
571
+
572
+ Enforcement is fail-open on unexpected errors, timeouts, invalid responses and
573
+ unreachable services. A refused root base has no usable decision route; doctor
574
+ reports that budget caps are not enforced, with a failure and a repair instruction.
575
+ It does not send that root's bearer to machine enforcement as a fallback. A supported hook blocks only on an explicit backend block
576
+ decision. Defaults are a 300 ms request timeout and 60-second local decision
577
+ cache. Antigravity has no verified blocking response. This is not a local signed
578
+ enforcement policy or tamper-resistant control.
579
+
580
+ The request may also carry the model the session is on, so a budget can be set
581
+ on one model. Codex, Cursor, Gemini and Antigravity all name their
582
+ model on every hook they send, so for those the payload the gate already holds
583
+ names it. Claude Code names it only when a session starts, so
584
+ that one event writes it to `session.json` in that session's own `turns/`
585
+ directory (mode 0600, beside that session's turn records) to be read back at the
586
+ gate.
587
+ That file lives as long as the session does: it is deleted with the session's
588
+ state at SessionEnd, and by the 24-hour sweep for a session that crashed without
589
+ one. The model is stated exactly as reported usage spells it, and it is part of
590
+ the local decision cache key — an answer about one model is never reused for a
591
+ prompt on another. A collector that never learned a model states none and is
592
+ answered as it is today.
593
+
594
+ **The gate makes a network request.** Before a turn starts, the pre-prompt hook
595
+ reads a local decision cache and, on a miss, asks the platform — one bounded
596
+ request, 300 ms ceiling, every failure allowing the turn. Stating the model adds
597
+ one read of a small local file to that, and nothing else: no subprocess, no
598
+ second request, and a file that cannot be read means no model is stated rather
599
+ than a gate that waits. Two consequences are worth stating rather than leaving
600
+ to be discovered. A platform outage does not stop developers; it un-enforces
601
+ every budget for as long as it lasts, which at the default cache TTL means
602
+ decisions go unmade for up to a minute past recovery. And the cache is not
603
+ always a saving: an organization with a feature-scoped policy receives
604
+ `cache_ttl_ms: 0` on every answer, because a
605
+ reuse key cannot distinguish one checkout from another, so those turns each pay
606
+ a request. A gate that evaluates a locally held policy without a network call is
607
+ planned; it requires the platform to send a policy rather than a verdict, and it
608
+ is not what ships today.
609
+
610
+ ## Off, uninstall, and provider limitations
611
+
612
+ `agentwatch off` writes a local marker before changing native configuration.
613
+ Disabled hooks return before stdin processing, do not enforce, send, or queue
614
+ events; they still write the provider's payload-less passive response, because a
615
+ provider whose protocol expects a decision would otherwise stall. `otel-headers`
616
+ returns no authorization header. Configuration and queued data are retained.
617
+ Managed native exporter settings are removed using the same ownership and backup
618
+ mechanisms as uninstall. Failures are reported, with the marker retained, and
619
+ running `agentwatch off` again re-runs the removal for the recorded providers. **Restart/close existing agents:** static headers, exporters,
620
+ and pending native batches may remain in memory until then. Off cannot recall
621
+ requests already in flight or control independently configured exporters.
622
+
623
+ `agentwatch on` restores previously suspended managed exporters and removes the
624
+ marker only on success. It does not add hooks or undo an intervening uninstall.
625
+ Foreign exporter conflicts require repair and a retry. `uninstall` removes owned
626
+ hooks/settings and keeps local state; `uninstall --purge` also removes AgentWatch
627
+ configuration and data, including queued records and backups. Unrelated user
628
+ hooks/settings are preserved. AgentWatch does not remove the globally installed
629
+ npm package itself.
630
+
631
+ Codex and Gemini static token storage is a current limitation, not an encrypted
632
+ credential-store integration; see *Identity, local storage, and credentials*
633
+ above for why those two agents differ from Claude Code, and for what `uninstall`
634
+ restores. Cursor has no native usage exporter/readable usage;
635
+ its CLI currently exposes only shell hooks, while IDE hooks cover more lifecycle
636
+ events. Antigravity has neither native token telemetry nor readable transcript
637
+ usage. Their summaries can remain `pending` without cost; no usage is fabricated.
638
+
639
+ A local administrator—and ordinarily the owning user—can remove or modify hooks,
640
+ configuration, credentials, and the off marker. Every line of code that runs on
641
+ the machine is in this MIT-licensed repository; the closed half is the backend
642
+ that receives the records. No signing, notarization, penetration-test completion,
643
+ or SOC 2 attestation is claimed. MDM templates and a per-agent statement of what
644
+ an administrator can and cannot lock are in
645
+ [examples/mdm](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm); Claude Code is currently the only
646
+ agent with a managed policy file, and Codex requires one manual per-machine
647
+ approval (`/hooks`) that no script can perform.
648
+ See [deferred enterprise work](ENTERPRISE_DEPLOYMENT.md).