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