@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
@@ -57,6 +57,13 @@ export class BackendCooldown {
57
57
  * End the cooldown after a successful send.
58
58
  */
59
59
  async clear() {
60
- await fs.rm(this.file, { force: true });
60
+ try {
61
+ await fs.rm(this.file, { force: true });
62
+ }
63
+ catch {
64
+ // Same rule as `trip`: this is awaited between a proven-healthy send and
65
+ // the drain, so an EACCES here would abort the deliver stage and leave the
66
+ // backlog unsent on the one hook that just proved the backend works.
67
+ }
61
68
  }
62
69
  }
@@ -1,4 +1,5 @@
1
1
  import type { ProductEvent } from '../events/product-event.js';
2
+ import type { BackendAuthBlock } from './auth-block.js';
2
3
  import type { BackendCooldown } from './cooldown.js';
3
4
  import type { DeliveryStats } from './delivery-stats.js';
4
5
  import type { EventQueue } from './queue.js';
@@ -9,11 +10,17 @@ export type { DeliveryOutcome } from './types/transport.types.js';
9
10
  * Hook-path delivery: one quick direct send, then whatever the backlog allows.
10
11
  *
11
12
  * Three properties this has to keep, in order of importance. It never loses a
12
- * product record — a failed send always ends in the queue, never in a discard.
13
- * It never blocks the agent for long — a backend that just failed is skipped
14
- * entirely for the cooldown window rather than costing every hook a full
15
- * timeout. And it keeps the backlog moving even on hooks that emit nothing,
16
- * because those are the majority.
13
+ * product record — a failed send always ends in the queue, never in a discard,
14
+ * and that holds for a refused credential too. It never blocks the agent for
15
+ * long — a backend that just failed is skipped entirely for the cooldown
16
+ * window, and one that refused the credential until the re-probe interval
17
+ * passes, rather than costing every hook a full timeout. And it keeps the backlog
18
+ * moving even on hooks that emit nothing, because those are the majority.
19
+ *
20
+ * Every path that skips a drain runs `queue.sweep` before returning, because
21
+ * the retention bound has to hold on exactly those paths: they are the
22
+ * week-long outages it exists for, a credential block only ends when a re-probe is accepted,
23
+ * and an endpoint the edge refuses is a state a machine can sit in for good.
17
24
  *
18
25
  * @param events - Product events this hook produced; often empty.
19
26
  * @param transport - Where to send, or undefined before setup configures one.
@@ -21,6 +28,7 @@ export type { DeliveryOutcome } from './types/transport.types.js';
21
28
  * @param drainBatchSize - Ceiling on events one drain pass may send.
22
29
  * @param cooldown - Persisted circuit breaker, when enabled.
23
30
  * @param stats - Sink for permanent losses, when enabled.
31
+ * @param authBlock - Persisted credential refusal, when enabled.
24
32
  * @returns What was delivered, queued, drained and rejected.
25
33
  */
26
- export declare function deliverEvents(events: readonly ProductEvent[], transport: EventTransport | undefined, queue: EventQueue, drainBatchSize: number, cooldown?: BackendCooldown, stats?: DeliveryStats): Promise<DeliveryOutcome>;
34
+ export declare function deliverEvents(events: readonly ProductEvent[], transport: EventTransport | undefined, queue: EventQueue, drainBatchSize: number, cooldown?: BackendCooldown, stats?: DeliveryStats, authBlock?: BackendAuthBlock): Promise<DeliveryOutcome>;
@@ -1,15 +1,30 @@
1
1
  import { debugLog } from '../core/logger.js';
2
- import { ANY_DESTINATION, BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
2
+ import { next, runFlow, step } from '../core/pipe.js';
3
+ import { ANY_DESTINATION, AUTH_REJECTED_STATUSES, BACKEND_COOLDOWN_MS, DELIVERY_STAGE_NAMES } from './constants/transport.constants.js';
4
+ import { sendEvents } from './send.js';
3
5
  export { BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
6
+ const DELIVERY_STAGES = [
7
+ step(DELIVERY_STAGE_NAMES.select, selectDelivery),
8
+ step(DELIVERY_STAGE_NAMES.send, sendCurrent),
9
+ step(DELIVERY_STAGE_NAMES.preserve, preserveUnsent),
10
+ step(DELIVERY_STAGE_NAMES.report, reportBackend),
11
+ step(DELIVERY_STAGE_NAMES.maintain, maintainQueue)
12
+ ];
4
13
  /**
5
14
  * Hook-path delivery: one quick direct send, then whatever the backlog allows.
6
15
  *
7
16
  * Three properties this has to keep, in order of importance. It never loses a
8
- * product record — a failed send always ends in the queue, never in a discard.
9
- * It never blocks the agent for long — a backend that just failed is skipped
10
- * entirely for the cooldown window rather than costing every hook a full
11
- * timeout. And it keeps the backlog moving even on hooks that emit nothing,
12
- * because those are the majority.
17
+ * product record — a failed send always ends in the queue, never in a discard,
18
+ * and that holds for a refused credential too. It never blocks the agent for
19
+ * long — a backend that just failed is skipped entirely for the cooldown
20
+ * window, and one that refused the credential until the re-probe interval
21
+ * passes, rather than costing every hook a full timeout. And it keeps the backlog
22
+ * moving even on hooks that emit nothing, because those are the majority.
23
+ *
24
+ * Every path that skips a drain runs `queue.sweep` before returning, because
25
+ * the retention bound has to hold on exactly those paths: they are the
26
+ * week-long outages it exists for, a credential block only ends when a re-probe is accepted,
27
+ * and an endpoint the edge refuses is a state a machine can sit in for good.
13
28
  *
14
29
  * @param events - Product events this hook produced; often empty.
15
30
  * @param transport - Where to send, or undefined before setup configures one.
@@ -17,64 +32,74 @@ export { BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
17
32
  * @param drainBatchSize - Ceiling on events one drain pass may send.
18
33
  * @param cooldown - Persisted circuit breaker, when enabled.
19
34
  * @param stats - Sink for permanent losses, when enabled.
35
+ * @param authBlock - Persisted credential refusal, when enabled.
20
36
  * @returns What was delivered, queued, drained and rejected.
21
37
  */
22
- export async function deliverEvents(events, transport, queue, drainBatchSize, cooldown, stats) {
23
- if (!transport) {
24
- // No endpoint configured yet: keep the events for whatever backend setup
25
- // configures first.
26
- if (events.length > 0)
27
- await queue.enqueue(events, ANY_DESTINATION);
28
- return { delivered: 0, queued: events.length, drained: 0, rejected: 0 };
29
- }
30
- if (await isCoolingDown(cooldown)) {
31
- // Circuit breaker: a recently-dead backend must not cost every hook the
32
- // full send timeout. Skip straight to the queue.
33
- if (events.length > 0)
34
- await queue.enqueue(events, transport.destination);
35
- return { delivered: 0, queued: events.length, drained: 0, rejected: 0 };
36
- }
37
- if (events.length === 0) {
38
- // Hooks that emit no summary still keep the offline queue moving; there is
39
- // just no direct request to make.
40
- const drained = await queue.drain(transport, drainBatchSize, stats);
41
- return { delivered: 0, queued: 0, drained: drained.sent, rejected: drained.rejected };
42
- }
43
- const result = await transport.send(events);
38
+ export async function deliverEvents(events, transport, queue, drainBatchSize, cooldown, stats, authBlock) {
39
+ const flow = await runFlow(DELIVERY_STAGES, {
40
+ events, transport, queue, drainBatchSize, cooldown, stats, authBlock,
41
+ canSend: false,
42
+ outcome: { delivered: 0, queued: 0, drained: 0, rejected: 0 }
43
+ });
44
+ // A failed filesystem write must remain observable to the enclosing hook
45
+ // flow; returning a successful outcome would falsely claim durable delivery.
46
+ if (!flow.completed)
47
+ throw new Error(`delivery failed at ${flow.stoppedAt}: ${flow.reason}`, { cause: flow.cause });
48
+ return flow.state.outcome;
49
+ }
50
+ async function selectDelivery(state) {
51
+ const { transport, authBlock, cooldown } = state;
52
+ if (!transport)
53
+ return next(state);
54
+ if (transport.destination && authBlock && await authBlock.holds(transport.destination))
55
+ return next(state);
56
+ if (cooldown && await cooldown.active())
57
+ return next(state);
58
+ return next({ ...state, canSend: true });
59
+ }
60
+ async function sendCurrent(state) {
61
+ if (!state.canSend || !state.transport || state.events.length === 0)
62
+ return next(state);
63
+ const result = await sendEvents(state.transport, state.events);
64
+ const outcome = result.ok ? { ...state.outcome, delivered: state.events.length, rejected: result.counters?.rejected ?? 0 } : state.outcome;
65
+ return next({ ...state, result, outcome });
66
+ }
67
+ async function preserveUnsent(state) {
68
+ if (state.events.length === 0 || state.result?.ok)
69
+ return next(state);
70
+ // One queue path for absence, auth block, cooldown and transport failures.
71
+ // It precedes diagnostic writes so a stats failure cannot discard a record.
72
+ await state.queue.enqueue(state.events, state.transport?.destination ?? ANY_DESTINATION);
73
+ return next({ ...state, outcome: { ...state.outcome, queued: state.events.length } });
74
+ }
75
+ async function reportBackend(state) {
76
+ const { result, cooldown, stats, authBlock, transport } = state;
77
+ if (!result || result.deferred)
78
+ return next(state);
44
79
  if (!result.ok) {
45
80
  debugLog('direct send failed', result.error ?? `status ${result.status}`);
46
- if (result.retryable && cooldown)
81
+ if (result.retryable && (result.status === undefined || result.status >= 400) && cooldown)
47
82
  await cooldown.trip(BACKEND_COOLDOWN_MS);
48
- // A refusal the transport will not retry is the whole diagnosis: without it
49
- // a developer sees only a backlog that grows and then empties itself when
50
- // the entries age out.
51
83
  if (!result.retryable && stats)
52
84
  await stats.recordRefusal(result.status);
53
- // Product records are never discarded on the direct path. A permanent
54
- // response can be caused by a temporarily incompatible route or schema, and
55
- // the queued copy may succeed once the backend is corrected.
56
- await queue.enqueue(events, transport.destination);
57
- return { delivered: 0, queued: events.length, drained: 0, rejected: 0 };
58
- }
59
- const rejected = result.counters?.rejected ?? 0;
60
- if (rejected > 0) {
61
- debugLog(`backend permanently rejected ${rejected} event(s) from the direct send`);
62
- if (stats)
63
- await stats.recordRejected(rejected);
85
+ if (result.status !== undefined && AUTH_REJECTED_STATUSES.has(result.status) && authBlock && transport?.destination) {
86
+ await authBlock.raise(transport.destination, result.status, result.refusal);
87
+ }
88
+ return next(state);
64
89
  }
90
+ if (state.outcome.rejected > 0 && stats)
91
+ await stats.recordRejected(state.outcome.rejected);
65
92
  if (cooldown)
66
93
  await cooldown.clear();
67
- const drained = await queue.drain(transport, drainBatchSize, stats);
68
- return { delivered: events.length, queued: 0, drained: drained.sent, rejected: rejected + drained.rejected };
94
+ if (authBlock)
95
+ await authBlock.clear();
96
+ return next(state);
69
97
  }
70
- /**
71
- * Whether the backend is inside its cooldown window.
72
- *
73
- * @param cooldown - The breaker, when one is configured.
74
- * @returns True when direct sends should be skipped.
75
- */
76
- async function isCoolingDown(cooldown) {
77
- if (!cooldown)
78
- return false;
79
- return cooldown.active();
98
+ async function maintainQueue(state) {
99
+ if (!state.canSend || !state.transport || (state.result && !state.result.ok)) {
100
+ await state.queue.sweep(state.stats);
101
+ return next(state);
102
+ }
103
+ const drained = await state.queue.drain(state.transport, state.drainBatchSize, state.stats, state.authBlock);
104
+ return next({ ...state, outcome: { ...state.outcome, drained: drained.sent, rejected: state.outcome.rejected + drained.rejected } });
80
105
  }
@@ -10,6 +10,7 @@ export type { HttpTransportOptions } from './types/transport.types.js';
10
10
  export declare class HttpTransport implements EventTransport {
11
11
  private readonly options;
12
12
  private readonly fetchFn;
13
+ private deadline;
13
14
  /**
14
15
  * Bind the transport to one backend.
15
16
  *
@@ -1,5 +1,9 @@
1
- import { CONTENT_TYPE_HEADER, JSON_CONTENT_TYPE, RETRYABLE_STATUSES } from './constants/transport.constants.js';
1
+ import { performance } from 'node:perf_hooks';
2
+ import { applyProductCapture } from '../privacy/product-capture.js';
3
+ import { readRefusal } from '../credentials/device-api.js';
4
+ import { CONTENT_TYPE_HEADER, JSON_CONTENT_TYPE, MIN_VIABLE_SEND_MS, RETRYABLE_STATUSES } from './constants/transport.constants.js';
2
5
  import { edgeHeaders } from './headers.js';
6
+ import { discardResponseBody, readCappedJson } from './response-body.js';
3
7
  /**
4
8
  * POST `{events: [...]}` to the configured backend.
5
9
  *
@@ -9,6 +13,7 @@ import { edgeHeaders } from './headers.js';
9
13
  export class HttpTransport {
10
14
  options;
11
15
  fetchFn;
16
+ deadline;
12
17
  /**
13
18
  * Bind the transport to one backend.
14
19
  *
@@ -17,6 +22,7 @@ export class HttpTransport {
17
22
  constructor(options) {
18
23
  this.options = options;
19
24
  this.fetchFn = options.fetchFn ?? fetch;
25
+ this.deadline = options.deadline;
20
26
  }
21
27
  /**
22
28
  * Where this transport sends events.
@@ -36,19 +42,51 @@ export class HttpTransport {
36
42
  async send(events) {
37
43
  if (events.length === 0)
38
44
  return { ok: true, retryable: false };
45
+ // Current policy, not the policy the record was written under: a queued
46
+ // event may predate a revoked consent or capture flag.
47
+ const payload = [];
48
+ for (const event of events) {
49
+ const captured = applyProductCapture(event, this.options.capture);
50
+ if (captured)
51
+ payload.push(captured);
52
+ }
53
+ if (payload.length === 0)
54
+ return { ok: true, retryable: false };
55
+ if (this.options.credentialPending)
56
+ return { ok: false, retryable: true, deferred: true };
57
+ const now = this.options.nowMs?.() ?? performance.now();
58
+ // Only hook-owned transports opt into a pass budget. Start on first use,
59
+ // after selection and capture, so construction and local checks cost none.
60
+ if (this.deadline === undefined && this.options.budgetMs !== undefined)
61
+ this.deadline = now + this.options.budgetMs;
62
+ const remaining = this.deadline === undefined ? this.options.timeoutMs : this.deadline - now;
63
+ if (remaining < Math.min(MIN_VIABLE_SEND_MS, this.options.timeoutMs))
64
+ return { ok: false, retryable: true, deferred: true };
65
+ const requestMs = Math.min(this.options.timeoutMs, remaining);
39
66
  try {
40
67
  const response = await this.fetchFn(this.options.eventsUrl, {
41
68
  method: 'POST',
42
69
  headers: this.headers(),
43
- body: JSON.stringify({ events }),
44
- signal: AbortSignal.timeout(this.options.timeoutMs)
70
+ body: JSON.stringify({ events: payload }),
71
+ // A redirect would move a batch that carries a bearer to an endpoint
72
+ // nothing configured; refusing is the only safe answer.
73
+ redirect: 'error',
74
+ signal: AbortSignal.timeout(Math.max(1, Math.floor(requestMs)))
45
75
  });
46
76
  if (response.ok) {
47
77
  return { ok: true, status: response.status, retryable: false, counters: await readCounters(response) };
48
78
  }
49
- return { ok: false, status: response.status, retryable: isRetryableStatus(response.status), error: `HTTP ${response.status}` };
79
+ const refusal = response.status === 401 ? await readRefusal(response) : undefined;
80
+ if (response.status !== 401)
81
+ discardResponseBody(response);
82
+ return { ok: false, status: response.status, retryable: isRetryableStatus(response.status), error: `HTTP ${response.status}`, ...(refusal ? { refusal } : {}) };
50
83
  }
51
84
  catch (error) {
85
+ // A shortened request exhausting the remainder of a pass is local
86
+ // scheduling pressure, not evidence that the backend is unhealthy.
87
+ if (requestMs < this.options.timeoutMs && error instanceof Error && error.name === 'TimeoutError') {
88
+ return { ok: false, retryable: true, deferred: true };
89
+ }
52
90
  // Never include response or request bodies in errors: they carry event
53
91
  // content, and this string ends up in logs.
54
92
  return { ok: false, retryable: true, error: error.name || 'network error' };
@@ -71,15 +109,18 @@ export class HttpTransport {
71
109
  *
72
110
  * A 202 can still carry per-event rejections, and the batch "succeeding" while
73
111
  * events inside it were dropped is exactly the case the caller must see. A
74
- * backend that returns no JSON body is treated as counter-less, not failed.
112
+ * backend that returns no JSON body — or one too large to be counters — is
113
+ * treated as counter-less, not failed.
75
114
  *
76
115
  * @param response - The backend's response.
77
116
  * @returns The counters, or undefined when the body carried none.
78
117
  */
79
118
  async function readCounters(response) {
80
119
  try {
81
- const body = (await response.json());
82
- const numeric = (key) => (typeof body[key] === 'number' ? body[key] : 0);
120
+ const body = (await readCappedJson(response));
121
+ // Own properties only: this object came off the network, so a `__proto__`
122
+ // in the body must not answer for a counter nobody sent.
123
+ const numeric = (key) => (Object.hasOwn(body, key) && Number.isSafeInteger(body[key]) && body[key] >= 0 ? body[key] : 0);
83
124
  return {
84
125
  accepted: numeric('accepted'),
85
126
  duplicate: numeric('duplicate'),
@@ -94,9 +135,10 @@ async function readCounters(response) {
94
135
  /**
95
136
  * Whether a failing status is worth retrying.
96
137
  *
97
- * Auth and rate-limit problems are usually transient misconfiguration, so they
98
- * count as retryable; retries are capped by `delivery.maxAttempts`, so they
99
- * cannot accumulate forever.
138
+ * A rate limit or a timeout is transient, so those count as retryable and are
139
+ * capped by `delivery.maxAttempts`. A refused *credential* is deliberately not
140
+ * here: see `AUTH_REJECTED_STATUSES` and `BackendAuthBlock` — the records stay
141
+ * queued, but re-presenting a rejected bearer on every hook does not.
100
142
  *
101
143
  * @param status - HTTP status.
102
144
  * @returns True when the batch should be queued for another attempt.
@@ -1,13 +1,16 @@
1
1
  /**
2
- * Getting product records to the backend without ever losing one and without
3
- * ever making the coding agent wait: one bounded direct send, a persisted
4
- * circuit breaker, and a file-per-event offline queue behind it.
2
+ * Bounded delivery with durable retries: failed sends stay queued until
3
+ * delivered or removed by the configured retention and retry limits.
5
4
  */
6
5
  export type { DeliveryCounters, DeliveryOutcome, DeliveryResult, DeliveryStatsSnapshot, DrainStats, DrainStatsRecorder, EventTransport, HttpTransportOptions, QueueEntry, QueueOptions } from './types/transport.types.js';
7
6
  export { ANY_DESTINATION, BACKEND_COOLDOWN_MS } from './constants/transport.constants.js';
8
7
  export { HttpTransport } from './http-transport.js';
9
8
  export { edgeHeaders } from './headers.js';
10
9
  export { EventQueue } from './queue.js';
10
+ export { identityPaths, queuePartition, settleLegacyQueue, unattributedCount, unattributedQueue } from './queue-partition.js';
11
+ export type { IdentityPaths } from './queue-partition.js';
11
12
  export { BackendCooldown } from './cooldown.js';
12
13
  export { DeliveryStats } from './delivery-stats.js';
13
14
  export { deliverEvents } from './delivery.js';
15
+ export { sendEvents } from './send.js';
16
+ export { discardResponseBody, readCappedJson } from './response-body.js';
@@ -2,6 +2,9 @@ export { ANY_DESTINATION, BACKEND_COOLDOWN_MS } from './constants/transport.cons
2
2
  export { HttpTransport } from './http-transport.js';
3
3
  export { edgeHeaders } from './headers.js';
4
4
  export { EventQueue } from './queue.js';
5
+ export { identityPaths, queuePartition, settleLegacyQueue, unattributedCount, unattributedQueue } from './queue-partition.js';
5
6
  export { BackendCooldown } from './cooldown.js';
6
7
  export { DeliveryStats } from './delivery-stats.js';
7
8
  export { deliverEvents } from './delivery.js';
9
+ export { sendEvents } from './send.js';
10
+ export { discardResponseBody, readCappedJson } from './response-body.js';
@@ -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
+ }