@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,179 @@
1
+ # Enterprise deployment: planned and deferred work
2
+
3
+ The delivered package remains a Node.js 20+ CLI with short-lived hooks, no daemon,
4
+ and no root requirement. The items below are **not implemented**.
5
+
6
+ | Status | Work and prerequisites |
7
+ | --- | --- |
8
+ | Planned | Standalone native binary without a separately installed Node.js runtime; verify all providers and hook protocols before distribution. |
9
+ | Deferred | macOS Developer ID signing, notarization, and a signed `.pkg`; require an approved Apple identity, release process, and actual verification. |
10
+ | Deferred | Windows MSI, only after Windows shell quoting, permissions, provider support, and installation/uninstallation are verified. Windows is not currently a verified deployment target. |
11
+ | Partial | Jamf and Intune deployment scripts plus a Claude Code managed-settings policy file ship in [examples/mdm](https://github.com/agent-watch-ai/agent-watch-edge/tree/main/examples/mdm), with a per-agent statement of what an administrator can and cannot lock. They install through npm, so they still depend on a Node.js runtime; the install line is the only part a signed native package changes. No configuration profile of our own is supplied, and none is needed — the fragment drops into Claude Code's `managed-settings.d/`, which is also the only agent with a managed policy file at all. |
12
+ | Planned | Separate binary delivery from managed tenant policy, credentials, and developer identity; define policy ownership, precedence, update and removal first. |
13
+ | Planned | Local signed enforcement policy, verified before use, so the blocking hook does not call the network. Current enforcement still uses a bounded network check and fails open on unexpected errors. |
14
+ | Planned | Pseudonymous developer identity using a tenant-specific HMAC; decide key provisioning, rotation, correlation and migration. Current identity is an email, not an HMAC. |
15
+ | Partial / deferred | SHA-256 checksums and an npm CycloneDX SBOM are generated by the release workflow. Signed release manifests and platform signing are deferred until credentials and verification procedures exist. Checksums alone do not authenticate a publisher. |
16
+ | Deferred | Independent penetration testing and remediation. No completed penetration test is claimed. |
17
+ | Deferred | SOC 2 readiness, evidence collection, and independent audit roadmap. No SOC 2 attestation is claimed. |
18
+
19
+ ## What the edge changes outside its own directory
20
+
21
+ A change-control board asks for this list before a pilot, and it is the same
22
+ list the package's ownership rules are built on. Everything else lives under
23
+ `~/.agentwatch/` and is removed by `uninstall --purge`.
24
+
25
+ | Path | Change | Reverted by |
26
+ | --- | --- | --- |
27
+ | `~/.claude/settings.json` | AgentWatch hook entries, and `otelHeadersHelper` plus OTel env keys when native telemetry is configured | `uninstall` removes exactly the entries recorded as owned; unrelated hooks and settings are preserved |
28
+ | `~/.codex/config.toml` | A managed `[otel]` block; the file is set to 0600 **only** when that block carries a bearer token | `uninstall` removes the block and restores the permission bits the file had before AgentWatch tightened it |
29
+ | `~/.gemini/settings.json` | AgentWatch hook entries and an `env` block including `OTEL_EXPORTER_OTLP_HEADERS`; 0600 **only** when that block carries a bearer token | as above — owned keys only, and the original mode is restored |
30
+ | Cursor / Antigravity hook configuration | AgentWatch hook entries only; neither has a managed native exporter | `uninstall` removes the entries it recorded |
31
+ | Nothing else | No daemon, no launchd/systemd unit, no PATH change, no shell profile edit, no root requirement, no file outside the paths above | — |
32
+
33
+ The device secret is the one thing the edge keeps outside `~/.agentwatch/` and
34
+ the data root: an item in the login keychain (macOS, service `agentwatch-device`)
35
+ or the Secret Service keyring (Linux with a desktop session). `uninstall` without
36
+ `--agent` removes it; a Windows DPAPI blob or the no-keychain fallback file lives
37
+ in `~/.agentwatch/credentials/` and goes with `--purge` as well.
38
+
39
+ An MDM rollout that sets `$AGENTWATCH_TOKEN` hands setup the install key as
40
+ before; the edge exchanges it for a device credential during that setup run, or
41
+ on the first later run that reaches the backend. The key stays in `config.json`
42
+ (0600) beside the device until AWT-357, because Codex and Gemini still present
43
+ it; re-running setup with the same key keeps the existing device rather than
44
+ enrolling a new one. On Windows the exchange happens in setup only. Headless Linux has no keychain: the secret is a 0600 file and
45
+ `agentwatch doctor` reports the credential check as a warning.
46
+
47
+ Every write to a file the edge does not own is preceded by a timestamped copy
48
+ into `~/.agentwatch/backups/`, which preserves the source permissions and can
49
+ therefore contain credentials — treat that directory as sensitive and note that
50
+ `uninstall --purge` is what removes it.
51
+
52
+ ## Verifying a rollback
53
+
54
+ The point of this section is that "we removed it" is checkable rather than
55
+ asserted. On one machine, in this order:
56
+
57
+ 1. `agentwatch uninstall` — reports what it removed per agent. It removes
58
+ exactly the keys and hook entries the install state recorded as owned, so a
59
+ setting a developer added themselves is never touched. (The refuse-rather-
60
+ than-guess check runs at *install* time: a native-telemetry key already set
61
+ to a foreign value makes `setup` skip that agent's exporter and say so,
62
+ rather than overwriting it.)
63
+ 2. `agentwatch doctor --json` — the `backend connectivity` check reads
64
+ `no backend configured yet` only after a `--purge`; before that the
65
+ configuration is intentionally retained. Every `agent … hooks` check must
66
+ report the hooks as absent.
67
+ 3. Inspect each agent file in the table above: no `agentwatch` string should
68
+ remain, the agent's own settings must be intact, and
69
+ `stat -f '%Lp' ~/.codex/config.toml` (Linux: `stat -c '%a'`) must show the
70
+ mode the file had before installation, not `600`.
71
+ 4. Confirm the agent still starts and runs a turn. A configuration the edge left
72
+ unparseable is the failure this step exists to catch. For Codex's TOML,
73
+ removal is explicitly guarded: a file that parsed before removal and would
74
+ not parse after it is refused with nothing written. The JSON files are
75
+ re-serialized from a parsed document and the serialization is parsed again
76
+ before the write, so an unparseable result is not reachable — but the agent
77
+ itself starting is the only end-to-end check, which is why it is a step here.
78
+ 5. `agentwatch uninstall --purge` — then `~/.agentwatch/` is gone, including
79
+ queued records and backups. Anything already delivered to the backend is the
80
+ backend's to delete; the edge cannot recall it.
81
+
82
+ The npm package itself is never removed by `uninstall`; `npm rm -g
83
+ @agent-watch-ai/edge` is a separate, deliberate step.
84
+
85
+ ## Release operation
86
+
87
+ Nothing runs on pushes or PRs. A release starts with a `workflow_dispatch` of
88
+ `release.yml`, which verifies and builds artifacts; locally the same is: run
89
+ `npm ci`, the test/lint/typecheck/build checks, then `npm run release:artifacts`
90
+ to create a verified tarball, production dependency SBOM, and `SHA256SUMS`.
91
+ Verify with `sha256sum --check SHA256SUMS` from `artifacts` (macOS:
92
+ `shasum -a 256 --check SHA256SUMS`).
93
+
94
+ Publishing is a separate, explicit `workflow_dispatch` choice on `main`, gated
95
+ by the `npm-release` GitHub environment. Repository administrators must configure
96
+ environment approval rules and the npm trusted publisher for this repository,
97
+ `release.yml` workflow, and environment before use. Use npm >=11.5.1 with
98
+ Node >=22.14 for OIDC support. No long-lived npm token is required. The workflow
99
+ publishes the verified artifact; it does not create a GitHub release or attach
100
+ npm provenance, which npm issues only for public repositories.
101
+ See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
102
+
103
+ The version must be deliberately selected before triggering publication;
104
+ publishing an already released version is not supported. Signing with a real release identity is a later step,
105
+ not a simulated signature.
106
+
107
+ Without npm provenance nothing public ties the published tarball to the commit
108
+ it was built from, so **release tags must be signed**: `git tag -s vX.Y.Z -m 'vX.Y.Z'`
109
+ and push the tag, with `git tag -v vX.Y.Z` as the check. A maintainer can make
110
+ that the default for this repository with `git config tag.gpgSign true`. This is
111
+ a process requirement rather than something the workflow can enforce, and it is
112
+ recorded here because a signed tag is what makes "the commit this release came
113
+ from" checkable at all.
114
+
115
+ The workflow's own supply-chain controls, so a reviewer does not have to read
116
+ the YAML to find them: every action is pinned to a commit SHA rather than a
117
+ mutable tag; `npm ci` runs with `--ignore-scripts`, as pack and publish already
118
+ did, so no dependency lifecycle script executes in the job that builds the
119
+ published tarball; `npm audit --omit=dev --audit-level=high` gates on advisories
120
+ in what actually ships; the release workflow is dispatch-only, nothing runs on pull requests; and Dependabot
121
+ opens grouped weekly updates for both npm and the pinned actions. Package verification permits built JS/types and public
122
+ documentation only, with a 2 MB unpacked review ceiling. Hundreds of small files
123
+ are expected from the existing module layout and declarations; bundling solely
124
+ to reduce the file count is deferred.
125
+
126
+ ## Destination changes and project roots
127
+
128
+ Setup treats `endpoint` as the backend identity and explicit `eventsUrl`,
129
+ `otlpUrl`, and machine `enforcementUrl` as routes belonging to it. The same
130
+ transition applies to machine setup and `setup --root`:
131
+
132
+ | Previous base | Selected base | Existing live routes |
133
+ | --- | --- | --- |
134
+ | Usable, equal after removing trailing slashes | Same backend | Preserved, including token rotation |
135
+ | Usable, different | Another backend | Cleared and each old URL printed before saving |
136
+ | Missing or refused | Usable replacement | Cleared and each old URL printed before saving |
137
+
138
+ Refused routes remain on disk and continue to produce warnings until repaired.
139
+ For an existing root, omitting `--endpoint` keeps its stored base. Only an absent
140
+ root base inherits the machine base; a refused base requires an explicit repair.
141
+ The root's token is never inherited from the machine during enrollment.
142
+
143
+ At runtime a root naming no different destination shares the machine's routes.
144
+ A root naming a different or refused base never inherits its telemetry or explicit
145
+ enforcement routes. A root naming only one telemetry route cannot inherit the
146
+ other telemetry route; it still uses machine enforcement. Configure `endpoint`
147
+ on that root if its budget checks belong to a separate backend. `agentwatch config`
148
+ and `doctor` explain unavailable routes. Backlog moves remain opt-in and target
149
+ an existing identity with an exclusive token, regardless of the directory setup
150
+ is run from. New roots inherit no backlog. If another configured identity shares
151
+ the source or destination token, setup keeps the queue in place instead of offering
152
+ a migration and warns when records are pending, including when only the destination
153
+ URL changes. Consent names the capturing machine or root, the target URL, and the
154
+ possible change in tenant attribution. Empty token flags fall back to environment
155
+ or stored credentials; tokenless configurations cannot own a migration. Queue
156
+ inspection before consent does not adopt legacy records. Existing symlink root keys are
157
+ updated in place; duplicate keys for one canonical path require consolidation.
158
+ Doctor names the decision host and warns if it differs from the root’s own base
159
+ host, or explicit telemetry hosts when no base is given. Token-only roots compare
160
+ against the machine base. A different path on the same host does not warn. This
161
+ check reports the configured route; it does not change enforcement routing.
162
+ A refused root base has no usable enforcement route: budget checks allow turns,
163
+ and doctor reports this as an explicit budget-enforcement failure. Repair the
164
+ root endpoint to restore checks; the root bearer is never sent to machine policy
165
+ as a fallback.
166
+
167
+ ## Verification scope and performance
168
+
169
+ The release workflow runs lint, type checking, coverage and build on Linux and
170
+ macOS with Node 20 and 24. Provider configuration is tested in isolated temporary homes; this does
171
+ not replace a managed-fleet pilot with the real agent versions. Windows remains
172
+ unverified. The release artifact is produced once on Linux/Node 24.
173
+
174
+ Run `npm run benchmark` for fresh-process hook latency and queue scan timings at
175
+ 0, 100 and 2,000 entries. CI publishes a separate benchmark JSON artifact for
176
+ Linux and macOS on Node 24. Measurements include the runtime and hardware, and
177
+ report full queue sweeps separately from bounded scans. See
178
+ [performance methodology](PERFORMANCE.md). Timing distributions are diagnostic;
179
+ correctness tests assert the network deadline, bounded scans and record retention.
@@ -0,0 +1,81 @@
1
+ # Performance verification
2
+
3
+ Run `npm run benchmark` after installing dependencies. It builds the package,
4
+ starts a fresh CLI process for each hook sample, and measures real filesystem
5
+ queue scans with batches of 25. Everything lives in a temporary directory which
6
+ is removed afterwards. No actual agent configuration or external backend is used.
7
+ Set `AGENTWATCH_BENCH_SAMPLES` to an integer from 5 to 1000 (default 30).
8
+
9
+ The hook scenario is a small Claude `PostToolUse` payload with content capture,
10
+ git capture and enforcement off, and no backend. It measures Node startup,
11
+ configuration loading and local processing. It does not measure a Stop hook's
12
+ transcript settling, repository enrichment, snapshots or network latency.
13
+
14
+ Queue scenarios contain 0, 100 or 2,000 records in backoff. The initial full
15
+ retention sweep is timed separately, then the bounded rotating scans are measured.
16
+ This distinction matters: the hourly sweep still reads the partition and can cost
17
+ more than an ordinary pass. A batch-size bound is not constant total filesystem
18
+ cost: directory listing and sorting still depend on backlog size.
19
+
20
+ Example local run, September 10, 2026: Apple M3 Pro, macOS arm64, Node v24.13.1,
21
+ 30 samples, warm filesystem, interactive machine. Values in milliseconds:
22
+
23
+ | Scenario | p50 | p95 | Maximum | Initial full sweep |
24
+ | --- | ---: | ---: | ---: | ---: |
25
+ | Fresh CLI, small PostToolUse, no backend | 53.34 | 58.07 | 58.84 | — |
26
+ | Empty queue | 0.24 | 0.38 | 1.05 | 2.46 |
27
+ | 100 queued records | 5.14 | 6.16 | 6.20 | 9.64 |
28
+ | 2,000 queued records | 6.99 | 8.04 | 13.80 | 124.11 |
29
+
30
+ Untraced-run notice (AWT-310), October 7, 2026: same machine, 60 samples, other agent
31
+ sessions running, so noisy. A Claude `PostToolUse` shell run (`node -e 1`) in a repository
32
+ declaring an LLM SDK and no tracing, a fresh session per sample so the notice is shown every
33
+ time. The warm verdict is a `readdir`, a few `stat`s and one small read; the cold one also
34
+ reads the manifests and writes the cache. Acceptance: p50 within 10 ms of the notice-off run.
35
+
36
+ | Scenario | p50 | p95 | Maximum |
37
+ | --- | ---: | ---: | ---: |
38
+ | Shell run, notice off | 73.25 | 129.09 | 160.71 |
39
+ | Shell run, notice on, warm verdict | 75.99 | 137.69 | 164.91 |
40
+ | Shell run, notice on, cold verdict | 74.56 | 89.08 | 119.19 |
41
+
42
+ Commit files in `repo.snapshot` (AWT-323), October 7, 2026: same machine. Each branch a
43
+ snapshot describes now costs one more `git log -z --name-status` over the same range as its
44
+ commit delta, inside the existing one-second snapshot budget; an ordinary turn describes only
45
+ the branch that moved. Measured by building a full ten-branch snapshot of four real
46
+ repositories twice, with and without `files` (JSON bytes after sanitizing):
47
+
48
+ | Repository | Branches | Commits | Files sent | Bytes before | Bytes after | Growth | Files listing per branch |
49
+ | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
50
+ | agent-watch-core | 10 | 18 | 118 | 5,132 | 14,524 | +9,392 | 14–19 ms |
51
+ | infra-live | 10 | 26 | 65 | 6,544 | 9,985 | +3,441 | 11–13 ms |
52
+ | agent-watch-edge | 10 | 13 | 56 | 4,134 | 7,419 | +3,285 | 11–13 ms |
53
+ | coding-tools | 4 | 4 | 4 | 1,713 | 1,977 | +264 | 11–12 ms |
54
+
55
+ A file costs 53–80 bytes. The bound is the per-branch cap of 200 files and 16 KiB of path:
56
+ a ten-branch snapshot whose every branch is at the cap carries at most ~210 KB of files, so
57
+ 25 such snapshots in one drain pass stay under the gateway's 8 MiB body limit. If the output
58
+ ceiling (1 MiB) cuts a listing short, the commits it did not reach are sent without `files`.
59
+
60
+ These are observations, not an SLA or a cross-machine comparison. At 30 samples,
61
+ p99 is effectively the maximum. CI retains its own JSON measurements on Linux
62
+ and macOS rather than enforcing unstable absolute timing thresholds on shared
63
+ runners.
64
+
65
+ `delivery.timeoutMs` is a shared monotonic network deadline for one delivery
66
+ hook pass, starting at its first send: a request gets only the remaining time.
67
+ Later sends defer when less than 10 ms remains (or the configured timeout, if
68
+ smaller). A shortened request timing out against the remainder also defers. Deferral keeps queued records and their retry counters intact.
69
+ This is not an end-to-end hook deadline: startup, filesystem work, transcript
70
+ settling, enforcement and snapshots have additional costs. Tests exercise
71
+ gateway 503, accepted-batch rejections, exhausted budgets and authentication failures independently
72
+ of machine speed.
73
+
74
+ Upgrade note: existing `delivery.timeoutMs` values parse unchanged but previously
75
+ gave drain batches and isolation probes a fresh timeout each. Low values can now
76
+ leave backlog pending after a direct send. Review tuned values on upgrade; later
77
+ hooks without new records can drain it. `agentwatch status` keeps its separate
78
+ 3-second per-request timeout, including isolation, and CLI-built transports do
79
+ not expire while idle. This shared hook budget intentionally avoids a separate
80
+ drain setting; it limits network latency but does not guarantee backlog progress
81
+ on every hook.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@agent-watch-ai/edge",
3
- "version": "0.2.5",
4
- "description": "Connect Claude Code, Codex and Cursor telemetry to your backend with turn, Git and ticket-key attribution.",
3
+ "version": "0.3.1",
4
+ "description": "Usage and cost telemetry for Claude Code, Codex, Cursor, Gemini CLI and Antigravity. No daemon, no proxy.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "engines": {
@@ -34,18 +34,25 @@
34
34
  },
35
35
  "files": [
36
36
  "dist",
37
- "example",
38
37
  "README.md",
38
+ "SECURITY.md",
39
+ "docs/AUDIT_PROMPT.md",
40
+ "docs/DATA_HANDLING.md",
41
+ "docs/ENTERPRISE_DEPLOYMENT.md",
42
+ "docs/PERFORMANCE.md",
39
43
  "LICENSE",
40
44
  "CHANGELOG.md"
41
45
  ],
42
46
  "scripts": {
43
47
  "build": "tsc -p tsconfig.build.json",
44
48
  "typecheck": "tsc --noEmit",
49
+ "coverage": "vitest run --coverage",
50
+ "benchmark": "npm run build && node scripts/benchmark.mjs",
45
51
  "lint": "eslint src tests",
46
52
  "lint:fix": "eslint src tests --fix",
47
53
  "test": "vitest run",
48
54
  "test:watch": "vitest",
55
+ "release:artifacts": "node scripts/release-artifacts.mjs",
49
56
  "example": "node example/server.mjs",
50
57
  "prepack": "npm run build",
51
58
  "prepare": "npm run build"
@@ -63,6 +70,9 @@
63
70
  "opentelemetry",
64
71
  "claude-code",
65
72
  "codex",
73
+ "cursor",
74
+ "gemini-cli",
75
+ "antigravity",
66
76
  "ai-coding-agents",
67
77
  "ai-cost",
68
78
  "cost-attribution",
@@ -78,10 +88,10 @@
78
88
  "@eslint/js": "^9.17.0",
79
89
  "@stylistic/eslint-plugin": "^5.10.0",
80
90
  "@types/node": "^22.10.0",
91
+ "@vitest/coverage-v8": "^2.1.9",
81
92
  "eslint": "^9.17.0",
82
93
  "eslint-plugin-import-x": "^4.17.1",
83
94
  "eslint-plugin-jsdoc": "^63.3.3",
84
- "patch-package": "^8.0.1",
85
95
  "typescript": "^5.7.0",
86
96
  "typescript-eslint": "^8.19.0",
87
97
  "vitest": "^2.1.8"
@@ -1,5 +0,0 @@
1
- /**
2
- * The enrollment contract. Kept as its own module so `setup` depends on the
3
- * abstraction rather than on the manual implementation it happens to ship with.
4
- */
5
- export type { EnrollmentInput, EnrollmentProvider, EnrollmentResult } from './types/enrollment.types.js';
@@ -1,32 +0,0 @@
1
- import type { EnrollmentInput, EnrollmentProvider, EnrollmentResult } from './types/enrollment.types.js';
2
- /**
3
- * Enrollment by asking the developer.
4
- *
5
- * Fails loudly rather than guessing: an install pointed at the wrong backend
6
- * would send this repository's prompts and tool output somewhere the user never
7
- * chose, so a missing endpoint is an error, not a default.
8
- */
9
- export declare class ManualEnrollmentProvider implements EnrollmentProvider {
10
- /**
11
- * Resolve the backend endpoint and token.
12
- *
13
- * @param input - Flags, existing configuration and the interactive prompt.
14
- * @returns The endpoint and token to configure.
15
- * @throws When no usable endpoint can be obtained.
16
- */
17
- enroll(input: EnrollmentInput): Promise<EnrollmentResult>;
18
- /**
19
- * The endpoint from the flag, the existing config, or the prompt.
20
- *
21
- * @param input - Enrollment input.
22
- * @returns The endpoint, or undefined when there is none.
23
- */
24
- private resolveEndpoint;
25
- /**
26
- * The token from the flag, the existing config, or the prompt.
27
- *
28
- * @param input - Enrollment input.
29
- * @returns The token, or undefined when the backend needs none.
30
- */
31
- private resolveToken;
32
- }
@@ -1,72 +0,0 @@
1
- import { ALLOWED_PROTOCOLS, ENDPOINT_PROMPT, RE_TRAILING_SLASHES, TOKEN_PROMPT } from './constants/enrollment.constants.js';
2
- /**
3
- * Enrollment by asking the developer.
4
- *
5
- * Fails loudly rather than guessing: an install pointed at the wrong backend
6
- * would send this repository's prompts and tool output somewhere the user never
7
- * chose, so a missing endpoint is an error, not a default.
8
- */
9
- export class ManualEnrollmentProvider {
10
- /**
11
- * Resolve the backend endpoint and token.
12
- *
13
- * @param input - Flags, existing configuration and the interactive prompt.
14
- * @returns The endpoint and token to configure.
15
- * @throws When no usable endpoint can be obtained.
16
- */
17
- async enroll(input) {
18
- if (input.setupUrl) {
19
- throw new Error('enrollment URLs are not supported yet; pass the backend base URL via --endpoint or the prompt');
20
- }
21
- const endpoint = await this.resolveEndpoint(input);
22
- if (!endpoint) {
23
- throw new Error('no backend endpoint provided (use --endpoint or run interactively)');
24
- }
25
- assertHttpUrl(endpoint);
26
- return { endpoint: endpoint.replace(RE_TRAILING_SLASHES, ''), token: await this.resolveToken(input) };
27
- }
28
- /**
29
- * The endpoint from the flag, the existing config, or the prompt.
30
- *
31
- * @param input - Enrollment input.
32
- * @returns The endpoint, or undefined when there is none.
33
- */
34
- async resolveEndpoint(input) {
35
- if (input.endpoint)
36
- return input.endpoint;
37
- if (!input.ask)
38
- return undefined;
39
- return (await input.ask(ENDPOINT_PROMPT)).trim();
40
- }
41
- /**
42
- * The token from the flag, the existing config, or the prompt.
43
- *
44
- * @param input - Enrollment input.
45
- * @returns The token, or undefined when the backend needs none.
46
- */
47
- async resolveToken(input) {
48
- if (input.token !== undefined)
49
- return input.token;
50
- if (!input.ask)
51
- return undefined;
52
- return (await input.ask(TOKEN_PROMPT)).trim() || undefined;
53
- }
54
- }
55
- /**
56
- * Reject anything that is not an http(s) URL.
57
- *
58
- * @param value - The endpoint as entered.
59
- * @throws When the value is not a usable http(s) URL.
60
- */
61
- function assertHttpUrl(value) {
62
- let url;
63
- try {
64
- url = new URL(value);
65
- }
66
- catch {
67
- throw new Error(`invalid URL: ${value}`);
68
- }
69
- if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
70
- throw new Error(`backend URL must be http(s), got ${url.protocol}`);
71
- }
72
- }
package/example/README.md DELETED
@@ -1,43 +0,0 @@
1
- # Example backend
2
-
3
- A zero-dependency logging server for trying AgentWatch Edge locally. It accepts
4
- `turn.summary` on `/v1/events` and native agent OTLP on
5
- `/v1/otlp/v1/{logs,traces,metrics}`. A production receiver must normalize completed requests
6
- to `llm.call` and durably upsert before acknowledging OTLP.
7
-
8
- ## Try it end to end
9
-
10
- Terminal 1 — start the backend:
11
-
12
- ```bash
13
- npm run build
14
- npm run example # http://127.0.0.1:8787
15
- # JSON=1 npm run example — also print each event as full JSON
16
- ```
17
-
18
- Terminal 2 — point the edge at it:
19
-
20
- ```bash
21
- node dist/cli.js setup --endpoint http://127.0.0.1:8787 --yes
22
- # or, with a global install/npm link: agentwatch setup --endpoint http://127.0.0.1:8787 --yes
23
- ```
24
-
25
- Then open a **new** Claude Code, Codex or Cursor session in any repository and do something.
26
- Terminal 1 prints a `TURN.SUMMARY` for each completed turn. Claude Code and Codex also produce
27
- normalized `LLM.CALL` records and `OTLP:*` diagnostics; Cursor has no native OTel export.
28
-
29
- For Codex, remember the one-time trust step: run `codex`, type `/hooks`, trust the AgentWatch
30
- entries.
31
-
32
- Check edge health anytime:
33
-
34
- ```bash
35
- node dist/cli.js status
36
- node dist/cli.js doctor
37
- ```
38
-
39
- Cleanup when done:
40
-
41
- ```bash
42
- node dist/cli.js uninstall # removes hooks + OTel config (add --purge for local data)
43
- ```