@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,91 @@
1
+ import type { AgentWatchPaths } from '../storage/types/storage.types.js';
2
+ /** Everything on disk that belongs to one identity's delivery. */
3
+ export interface IdentityPaths {
4
+ /** Its queue partition. */
5
+ readonly queueDir: string;
6
+ /** Its backend circuit breaker. */
7
+ readonly cooldownFile: string;
8
+ /** Its permanent-loss tally. */
9
+ readonly statsFile: string;
10
+ /** Its standing credential refusal, when the backend raised one. */
11
+ readonly authBlockFile: string;
12
+ /** Its cached device access token (0600). */
13
+ readonly accessTokenFile: string;
14
+ /** Its device credential state: a refusal, the last exchange attempt. */
15
+ readonly deviceStateFile: string;
16
+ }
17
+ /**
18
+ * The queue directory one identity owns.
19
+ *
20
+ * A queue entry records a destination but never a bearer, so a single flat
21
+ * directory lets whichever hook happens to drain it send every tenant's backlog
22
+ * under its own token — the exact mis-attribution per-project roots exist to
23
+ * prevent, and unreachable only while the machine has one identity. Giving each
24
+ * identity its own directory makes a cross-tenant send impossible rather than
25
+ * unlikely: a drain lists one partition and cannot see another. The cost is that
26
+ * an idle tenant's backlog waits for that tenant's next hook, which is the right
27
+ * trade — late is recoverable, mis-attributed is not.
28
+ *
29
+ * The name is a digest, not the token: this path appears in `ls`, in backups and
30
+ * in every error message that quotes a file, none of which may carry a secret.
31
+ * The queue bound in `delivery.maxQueueEvents` therefore applies per identity.
32
+ *
33
+ * @param queueRoot - The machine's queue directory.
34
+ * @param token - Bearer this invocation would send with, when there is one.
35
+ * @returns Absolute directory this identity may read and write.
36
+ */
37
+ export declare function queuePartition(queueRoot: string, token: string | undefined): string;
38
+ /**
39
+ * Where one identity's delivery lives: queue partition, backend cooldown, loss
40
+ * tally and credential block. All four per identity for the same reason — one
41
+ * tenant's backend outage must not put the other tenant's hooks into cooldown,
42
+ * one tenant's revoked token must not suspend the other tenant's sends, and
43
+ * `status` must not report two tenants' losses as one number.
44
+ *
45
+ * @param paths - The machine's paths.
46
+ * @param token - Bearer this invocation would send with, when there is one.
47
+ * @returns Absolute paths for this identity.
48
+ */
49
+ export declare function identityPaths(paths: AgentWatchPaths, token: string | undefined): IdentityPaths;
50
+ /**
51
+ * Where a backlog nobody can claim waits for its owner to say what it is.
52
+ *
53
+ * @param queueRoot - The machine's queue directory.
54
+ * @returns Absolute directory.
55
+ */
56
+ export declare function unattributedQueue(queueRoot: string): string;
57
+ /**
58
+ * How many entries are waiting there, so `status` and `doctor` can say so.
59
+ *
60
+ * @param queueRoot - The machine's queue directory.
61
+ * @returns The entry count.
62
+ */
63
+ export declare function unattributedCount(queueRoot: string): Promise<number>;
64
+ /**
65
+ * Give the entries that belong to no partition a home, without guessing.
66
+ *
67
+ * Two sets qualify. A backlog written by a bridge that predates partitioning
68
+ * sits loose in the queue root, and upgrading must neither strand it in a
69
+ * directory nothing reads any more nor hand it to a tenant that may not own it.
70
+ * A backlog written before setup sits in `unconfigured/` pinned to
71
+ * ANY_DESTINATION, which is already a promise that the first identity
72
+ * configured here takes it.
73
+ *
74
+ * Those two obligations only conflict when the machine already serves several
75
+ * identities. When it serves one, that identity is provably the author of every
76
+ * entry, so it adopts them and the upgrade is invisible. When it serves more,
77
+ * the entries go to `unattributed/`, where they stay visible, intact and
78
+ * delivered to nobody until the operator says whose they are — AGENTS.md's "when
79
+ * ownership is unclear, refuse and tell the user", applied to a ledger rather
80
+ * than to an agent config.
81
+ *
82
+ * Moving is a rename, which is atomic, so no lock is needed: a hook that loses
83
+ * the race finds the entry already gone and moves on.
84
+ *
85
+ * @param queueRoot - The machine's queue directory.
86
+ * @param token - Bearer this invocation would send with; without one there is
87
+ * no partition worth moving anything into yet.
88
+ * @param sharedMachine - Whether other identities are configured here.
89
+ * @returns How many entries were moved.
90
+ */
91
+ export declare function settleLegacyQueue(queueRoot: string, token: string | undefined, sharedMachine: boolean): Promise<number>;
@@ -0,0 +1,143 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { debugLog } from '../core/logger.js';
4
+ import { identityFingerprint } from '../credentials/identity.js';
5
+ import { ACCESS_TOKEN_FILE_NAME, AUTH_BLOCK_FILE_NAME, COOLDOWN_FILE_NAME, DELIVERY_STATS_FILE_NAME, DEVICE_STATE_FILE_NAME, IDENTITY_STATE_DIR_NAME, UNATTRIBUTED_PARTITION, UNCONFIGURED_PARTITION } from './constants/transport.constants.js';
6
+ import { listQueueFiles } from './queue.js';
7
+ /**
8
+ * The queue directory one identity owns.
9
+ *
10
+ * A queue entry records a destination but never a bearer, so a single flat
11
+ * directory lets whichever hook happens to drain it send every tenant's backlog
12
+ * under its own token — the exact mis-attribution per-project roots exist to
13
+ * prevent, and unreachable only while the machine has one identity. Giving each
14
+ * identity its own directory makes a cross-tenant send impossible rather than
15
+ * unlikely: a drain lists one partition and cannot see another. The cost is that
16
+ * an idle tenant's backlog waits for that tenant's next hook, which is the right
17
+ * trade — late is recoverable, mis-attributed is not.
18
+ *
19
+ * The name is a digest, not the token: this path appears in `ls`, in backups and
20
+ * in every error message that quotes a file, none of which may carry a secret.
21
+ * The queue bound in `delivery.maxQueueEvents` therefore applies per identity.
22
+ *
23
+ * @param queueRoot - The machine's queue directory.
24
+ * @param token - Bearer this invocation would send with, when there is one.
25
+ * @returns Absolute directory this identity may read and write.
26
+ */
27
+ export function queuePartition(queueRoot, token) {
28
+ return path.join(queueRoot, partitionName(token));
29
+ }
30
+ /**
31
+ * Where one identity's delivery lives: queue partition, backend cooldown, loss
32
+ * tally and credential block. All four per identity for the same reason — one
33
+ * tenant's backend outage must not put the other tenant's hooks into cooldown,
34
+ * one tenant's revoked token must not suspend the other tenant's sends, and
35
+ * `status` must not report two tenants' losses as one number.
36
+ *
37
+ * @param paths - The machine's paths.
38
+ * @param token - Bearer this invocation would send with, when there is one.
39
+ * @returns Absolute paths for this identity.
40
+ */
41
+ export function identityPaths(paths, token) {
42
+ const stateDir = path.join(paths.dataDir, IDENTITY_STATE_DIR_NAME, partitionName(token));
43
+ return {
44
+ queueDir: queuePartition(paths.queueDir, token),
45
+ cooldownFile: path.join(stateDir, COOLDOWN_FILE_NAME),
46
+ statsFile: path.join(stateDir, DELIVERY_STATS_FILE_NAME),
47
+ authBlockFile: path.join(stateDir, AUTH_BLOCK_FILE_NAME),
48
+ accessTokenFile: path.join(stateDir, ACCESS_TOKEN_FILE_NAME),
49
+ deviceStateFile: path.join(stateDir, DEVICE_STATE_FILE_NAME)
50
+ };
51
+ }
52
+ /**
53
+ * The directory name standing for one identity.
54
+ *
55
+ * @param token - Install key or `device:<id>` (see `identityOf`), when there is one.
56
+ * @returns A digest prefix, or the shared name for "no token yet".
57
+ */
58
+ function partitionName(token) {
59
+ if (!token)
60
+ return UNCONFIGURED_PARTITION;
61
+ return identityFingerprint(token);
62
+ }
63
+ /**
64
+ * Where a backlog nobody can claim waits for its owner to say what it is.
65
+ *
66
+ * @param queueRoot - The machine's queue directory.
67
+ * @returns Absolute directory.
68
+ */
69
+ export function unattributedQueue(queueRoot) {
70
+ return path.join(queueRoot, UNATTRIBUTED_PARTITION);
71
+ }
72
+ /**
73
+ * How many entries are waiting there, so `status` and `doctor` can say so.
74
+ *
75
+ * @param queueRoot - The machine's queue directory.
76
+ * @returns The entry count.
77
+ */
78
+ export async function unattributedCount(queueRoot) {
79
+ return (await listQueueFiles(unattributedQueue(queueRoot))).length;
80
+ }
81
+ /**
82
+ * Give the entries that belong to no partition a home, without guessing.
83
+ *
84
+ * Two sets qualify. A backlog written by a bridge that predates partitioning
85
+ * sits loose in the queue root, and upgrading must neither strand it in a
86
+ * directory nothing reads any more nor hand it to a tenant that may not own it.
87
+ * A backlog written before setup sits in `unconfigured/` pinned to
88
+ * ANY_DESTINATION, which is already a promise that the first identity
89
+ * configured here takes it.
90
+ *
91
+ * Those two obligations only conflict when the machine already serves several
92
+ * identities. When it serves one, that identity is provably the author of every
93
+ * entry, so it adopts them and the upgrade is invisible. When it serves more,
94
+ * the entries go to `unattributed/`, where they stay visible, intact and
95
+ * delivered to nobody until the operator says whose they are — AGENTS.md's "when
96
+ * ownership is unclear, refuse and tell the user", applied to a ledger rather
97
+ * than to an agent config.
98
+ *
99
+ * Moving is a rename, which is atomic, so no lock is needed: a hook that loses
100
+ * the race finds the entry already gone and moves on.
101
+ *
102
+ * @param queueRoot - The machine's queue directory.
103
+ * @param token - Bearer this invocation would send with; without one there is
104
+ * no partition worth moving anything into yet.
105
+ * @param sharedMachine - Whether other identities are configured here.
106
+ * @returns How many entries were moved.
107
+ */
108
+ export async function settleLegacyQueue(queueRoot, token, sharedMachine) {
109
+ if (!token)
110
+ return 0;
111
+ const target = sharedMachine ? unattributedQueue(queueRoot) : queuePartition(queueRoot, token);
112
+ const sources = [queueRoot, path.join(queueRoot, UNCONFIGURED_PARTITION)];
113
+ const moved = (await Promise.all(sources.map((source) => moveEntries(source, target)))).reduce((sum, n) => sum + n, 0);
114
+ if (moved > 0)
115
+ debugLog(`queue: moved ${moved} unpartitioned entr(y|ies) to ${target}`);
116
+ return moved;
117
+ }
118
+ /**
119
+ * Move every entry of one directory into another, creating it on demand. A
120
+ * rename that fails is a race lost to a concurrent hook, or an entry that aged
121
+ * out from under us: either way not this call's to move and not its to lose.
122
+ *
123
+ * @param source - Directory to empty.
124
+ * @param target - Partition to fill.
125
+ * @returns How many entries this call moved.
126
+ */
127
+ async function moveEntries(source, target) {
128
+ const names = await listQueueFiles(source);
129
+ if (names.length === 0)
130
+ return 0;
131
+ await fs.mkdir(target, { recursive: true });
132
+ let moved = 0;
133
+ for (const name of names) {
134
+ try {
135
+ await fs.rename(path.join(source, name), path.join(target, name));
136
+ moved++;
137
+ }
138
+ catch {
139
+ // Claimed by a concurrent hook, or gone.
140
+ }
141
+ }
142
+ return moved;
143
+ }
@@ -1,4 +1,5 @@
1
- import type { ProductEvent } from '../events/product-event.js';
1
+ import { type ProductEvent } from '../events/product-event.js';
2
+ import type { BackendAuthBlock } from './auth-block.js';
2
3
  import type { DrainStats, DrainStatsRecorder, EventTransport, QueueOptions } from './types/transport.types.js';
3
4
  export { ANY_DESTINATION } from './constants/transport.constants.js';
4
5
  export type { DrainStats, DrainStatsRecorder, QueueEntry, QueueOptions } from './types/transport.types.js';
@@ -50,26 +51,29 @@ export declare class EventQueue {
50
51
  * @param transport - Where to send.
51
52
  * @param maxBatch - Ceiling on events sent in one pass.
52
53
  * @param statsRecorder - Optional sink for what this pass lost.
54
+ * @param authBlock - Optional sink for a refused credential, so a rejected
55
+ * bearer suspends sending instead of spending the backlog's attempts on it.
53
56
  * @returns What the pass sent, failed, dropped and had rejected.
54
57
  */
55
- drain(transport: EventTransport, maxBatch: number, statsRecorder?: DrainStatsRecorder): Promise<DrainStats>;
58
+ drain(transport: EventTransport, maxBatch: number, statsRecorder?: DrainStatsRecorder, authBlock?: BackendAuthBlock): Promise<DrainStats>;
56
59
  /**
57
- * Re-pin entries queued for one destination to another.
60
+ * Enforce retention across the whole partition, without sending anything.
58
61
  *
59
- * Setup calls this — with the user's explicit consent — after the backend URL
60
- * changes, so the backlog follows instead of expiring pinned to a URL nothing
61
- * will ever drain. Entries pinned to any *other* backend stay untouched: this
62
- * re-routes one reconfigured destination, it is not a license to replay one
63
- * backend's data to another.
62
+ * `drain` sweeps too, but every early return in `deliverEvents` skips a drain
63
+ * — a tripped cooldown, and a credential the backend is refusing — and those
64
+ * are precisely the multi-day outages the age bound exists for. A block has no
65
+ * timer at all, so a revoked token used to mean nothing aged out until someone
66
+ * fixed the credential, while `enforceBound` quietly shed the oldest records
67
+ * at the ceiling. Sharing the marker with the drain's own sweep, so a hook
68
+ * that does reach a drain still pays for only one pass.
64
69
  *
65
- * Runs under the drain lock so a concurrent drain cannot resurrect the old
66
- * destination from a stale in-memory copy.
70
+ * Takes no lock: every removal is idempotent, which is the same reason
71
+ * `claimSweep` is unlocked.
67
72
  *
68
- * @param destination - The new events URL.
69
- * @param previousDestination - The URL being replaced.
70
- * @returns False when the lock never freed and nothing was re-pinned.
73
+ * @param statsRecorder - Optional sink for what aged out.
74
+ * @returns How many entries were removed.
71
75
  */
72
- retarget(destination: string, previousDestination: string): Promise<boolean>;
76
+ sweep(statsRecorder?: DrainStatsRecorder): Promise<number>;
73
77
  /**
74
78
  * Entries pinned to exactly this destination; legacy and ANY entries are not
75
79
  * counted, because they are not stranded.
@@ -81,17 +85,84 @@ export declare class EventQueue {
81
85
  /**
82
86
  * Entries due for this transport, dropping the ones that can never be sent.
83
87
  *
88
+ * Reads at most `maxBatch` entries, whatever the backlog holds and whatever it
89
+ * finds in them. Reading and zod-parsing the whole partition to find the few
90
+ * entries a pass may send is what made an outage cost the developer up to
91
+ * `maxQueueEvents` file reads on every hook, which AGENTS.md §3 forbids
92
+ * outright. The bound is on entries *read*, not on entries found due: a
93
+ * backlog where nothing is due — every entry in backoff, or every entry
94
+ * pinned to a destination this identity no longer sends to, which is what a
95
+ * changed endpoint leaves behind for a week — is exactly the case that would
96
+ * otherwise walk all of it and send nothing.
97
+ *
98
+ * A hard read bound needs the scan to move, or the head of the sorted list
99
+ * would be re-read on every pass and the tail never reached. So the scan
100
+ * starts where the last one stopped and wraps around: every entry is examined
101
+ * within `ceil(backlog / maxBatch)` passes, which is what FR-009 asks for —
102
+ * no entry deferred forever. Losing the cursor costs one pass starting at the
103
+ * head again.
104
+ *
105
+ * The batch is therefore the oldest of what this pass *scanned*, not of the
106
+ * whole backlog. Global oldest-first would need a due-time index, which is
107
+ * separate work.
108
+ *
84
109
  * @param transport - Where the pass will send.
85
110
  * @param nowMs - This pass's clock reading.
111
+ * @param maxBatch - Entries this pass may read; also its ceiling on sends.
86
112
  * @returns The due entries and what collecting them dropped.
87
113
  */
88
114
  private collectDue;
115
+ /**
116
+ * Index the next bounded scan starts at.
117
+ *
118
+ * The first name *after* the one last scanned, so an entry that was sent and
119
+ * deleted in the meantime does not send the scan back to the head.
120
+ *
121
+ * @param names - This pass's sorted entry names.
122
+ * @returns The starting index; zero when there is no cursor to resume from.
123
+ */
124
+ private scanStart;
125
+ /**
126
+ * The entry name the previous pass stopped on.
127
+ *
128
+ * @returns The name, or undefined when nothing has scanned yet.
129
+ */
130
+ private lastScanned;
131
+ /**
132
+ * Record where this pass stopped.
133
+ *
134
+ * @param name - The last entry name it read.
135
+ */
136
+ private rememberScan;
137
+ /**
138
+ * Where the scan cursor lives.
139
+ *
140
+ * Not a `.json` name, so the entry listing never sees it.
141
+ *
142
+ * @returns Absolute path to the cursor file.
143
+ */
144
+ private cursorFile;
145
+ /**
146
+ * Remove everything that can never be sent, wherever it sits in the partition.
147
+ *
148
+ * The bounded scan only ever sees the head of the backlog, so the retention
149
+ * bound needs a pass that sees all of it. Throttled by a marker, because that
150
+ * pass is the expensive one — and it is an improvement on what it replaces:
151
+ * expiry used to be enforced only inside a drain, and a drain is skipped for
152
+ * the whole cooldown window, so during a backend outage nothing aged out at
153
+ * all. That was precisely the week-long case the bound exists for.
154
+ *
155
+ * @param nowMs - This pass's clock reading.
156
+ * @returns What the sweep dropped, or nothing when it was not due.
157
+ */
158
+ private sweepUnsendable;
89
159
  /**
90
160
  * Send one batch, isolating a poison entry when the backend refuses it.
91
161
  *
92
162
  * @param transport - Where to send.
93
163
  * @param batch - Entries to send.
94
164
  * @param nowMs - This pass's clock reading.
165
+ * @param authBlock - Optional sink for a refused credential.
95
166
  * @returns What the send accomplished and cost.
96
167
  */
97
168
  private sendBatch;
@@ -107,15 +178,10 @@ export declare class EventQueue {
107
178
  * @param transport - Where to send.
108
179
  * @param batch - Entries the batch send refused.
109
180
  * @param nowMs - This pass's clock reading.
181
+ * @param authBlock - Persisted refusal, including one received by a single probe.
110
182
  * @returns What the probes accomplished and cost.
111
183
  */
112
184
  private isolateBatch;
113
- /**
114
- * Acquire the drain lock, waiting a bounded time.
115
- *
116
- * @returns The release function, or undefined on timeout.
117
- */
118
- private waitForDrainLock;
119
185
  /**
120
186
  * Back a failed entry off, or drop it once its budget is spent.
121
187
  *
@@ -162,6 +228,11 @@ export declare class EventQueue {
162
228
  *
163
229
  * The oldest are the least likely to still be deliverable, and an unbounded
164
230
  * queue on a developer machine is a disk-space bug.
231
+ *
232
+ * Reported through `options.stats`, like every other permanent loss: these
233
+ * deletions used to be the one kind that left `totalDropped` at zero, so a
234
+ * machine steadily shedding records at the bound looked, in `status`, exactly
235
+ * like one that had never lost any.
165
236
  */
166
237
  private enforceBound;
167
238
  /**
@@ -175,3 +246,11 @@ export declare class EventQueue {
175
246
  */
176
247
  private queuedAt;
177
248
  }
249
+ /**
250
+ * Queue entry filenames directly in a directory, sorted. Sub-directories are
251
+ * other identities' partitions and never entries.
252
+ *
253
+ * @param dir - Directory to list.
254
+ * @returns The names, or an empty list when the directory is absent.
255
+ */
256
+ export declare function listQueueFiles(dir: string): Promise<string[]>;