@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
@@ -1,12 +1,13 @@
1
1
  import fs from 'node:fs/promises';
2
2
  import path from 'node:path';
3
- import { pollUntil } from '../core/async.js';
4
3
  import { debugLog } from '../core/logger.js';
5
- import { PRODUCT_EVENT_TYPE_SET } from '../events/constants/events.constants.js';
4
+ import { isProductEvent } from '../events/product-event.js';
6
5
  import { writeFileAtomic } from '../storage/atomic-file.js';
7
6
  import { acquireLock } from '../storage/lock.js';
8
- import { SECRET_FILE_MODE } from '../storage/constants/storage.constants.js';
9
- import { ANY_DESTINATION, BACKOFF_BASE_MS, BACKOFF_JITTER_MIN, BACKOFF_JITTER_RANGE, BACKOFF_MAX_MS, MAX_ISOLATION_SENDS, MS_PER_DAY, QUEUE_DRAIN_LOCK, QUEUE_FILE_SUFFIX, RETARGET_LOCK_POLL_MS, RETARGET_LOCK_WAIT_MS, RE_UNSAFE_QUEUE_NAME } from './constants/transport.constants.js';
7
+ import { claimSweep } from '../storage/sweep-marker.js';
8
+ import { SECRET_FILE_MODE, SWEEP_MARKER_FILE } from '../storage/constants/storage.constants.js';
9
+ import { ANY_DESTINATION, AUTH_REJECTED_STATUSES, BACKOFF_BASE_MS, BACKOFF_JITTER_MIN, BACKOFF_JITTER_RANGE, BACKOFF_MAX_MS, MAX_ISOLATION_SENDS, MS_PER_DAY, QUEUE_DRAIN_LOCK, QUEUE_FILE_SUFFIX, QUEUE_SCAN_CURSOR_FILE, QUEUE_SWEEP_INTERVAL_MS, RE_UNSAFE_QUEUE_NAME } from './constants/transport.constants.js';
10
+ import { sendEvents } from './send.js';
10
11
  import { queueEntrySchema } from './schemas/queue.schema.js';
11
12
  export { ANY_DESTINATION } from './constants/transport.constants.js';
12
13
  /**
@@ -43,7 +44,7 @@ export class EventQueue {
43
44
  if (await exists(file))
44
45
  continue; // dedup by deterministic id
45
46
  const at = this.now().toISOString();
46
- // 0600: a queued turn summary holds prompt and response text.
47
+ // 0600: a queued turn summary holds developer identity, branches and file paths.
47
48
  await writeFileAtomic(file, JSON.stringify({ event, attempts: 0, firstQueuedAt: at, nextAttemptAt: at, destination }), SECRET_FILE_MODE);
48
49
  }
49
50
  await this.enforceBound();
@@ -88,23 +89,26 @@ export class EventQueue {
88
89
  * @param transport - Where to send.
89
90
  * @param maxBatch - Ceiling on events sent in one pass.
90
91
  * @param statsRecorder - Optional sink for what this pass lost.
92
+ * @param authBlock - Optional sink for a refused credential, so a rejected
93
+ * bearer suspends sending instead of spending the backlog's attempts on it.
91
94
  * @returns What the pass sent, failed, dropped and had rejected.
92
95
  */
93
- async drain(transport, maxBatch, statsRecorder) {
96
+ async drain(transport, maxBatch, statsRecorder, authBlock) {
94
97
  const release = await acquireLock(this.options.locksDir, QUEUE_DRAIN_LOCK, this.now);
95
98
  if (!release)
96
99
  return { sent: 0, failed: 0, dropped: 0, rejected: 0, skipped: true };
97
100
  try {
98
101
  const nowMs = this.now().getTime();
99
- const collected = await this.collectDue(transport, nowMs);
100
- // Oldest first: hash-ordered filenames would otherwise let a large
101
- // backlog defer the same late-sorting entries on every drain.
102
+ const swept = await this.sweepUnsendable(nowMs);
103
+ const collected = await this.collectDue(transport, nowMs, maxBatch);
104
+ // Oldest first among what was scanned: hash-ordered filenames would
105
+ // otherwise let a large backlog defer the same late-sorting entries.
102
106
  const batch = collected.due
103
107
  .slice()
104
108
  .sort((a, b) => Date.parse(a.entry.firstQueuedAt) - Date.parse(b.entry.firstQueuedAt))
105
109
  .slice(0, maxBatch);
106
- const sent = batch.length === 0 ? EMPTY_DELTA : await this.sendBatch(transport, batch, nowMs);
107
- const stats = { ...mergeDeltas(collected.delta, sent), skipped: false };
110
+ const sent = batch.length === 0 ? EMPTY_DELTA : await this.sendBatch(transport, batch, nowMs, authBlock);
111
+ const stats = { ...mergeDeltas(mergeDeltas(swept, collected.delta), sent), skipped: false };
108
112
  await report(statsRecorder, stats);
109
113
  return stats;
110
114
  }
@@ -113,38 +117,27 @@ export class EventQueue {
113
117
  }
114
118
  }
115
119
  /**
116
- * Re-pin entries queued for one destination to another.
120
+ * Enforce retention across the whole partition, without sending anything.
117
121
  *
118
- * Setup calls this — with the user's explicit consent — after the backend URL
119
- * changes, so the backlog follows instead of expiring pinned to a URL nothing
120
- * will ever drain. Entries pinned to any *other* backend stay untouched: this
121
- * re-routes one reconfigured destination, it is not a license to replay one
122
- * backend's data to another.
122
+ * `drain` sweeps too, but every early return in `deliverEvents` skips a drain
123
+ * — a tripped cooldown, and a credential the backend is refusing — and those
124
+ * are precisely the multi-day outages the age bound exists for. A block has no
125
+ * timer at all, so a revoked token used to mean nothing aged out until someone
126
+ * fixed the credential, while `enforceBound` quietly shed the oldest records
127
+ * at the ceiling. Sharing the marker with the drain's own sweep, so a hook
128
+ * that does reach a drain still pays for only one pass.
123
129
  *
124
- * Runs under the drain lock so a concurrent drain cannot resurrect the old
125
- * destination from a stale in-memory copy.
130
+ * Takes no lock: every removal is idempotent, which is the same reason
131
+ * `claimSweep` is unlocked.
126
132
  *
127
- * @param destination - The new events URL.
128
- * @param previousDestination - The URL being replaced.
129
- * @returns False when the lock never freed and nothing was re-pinned.
133
+ * @param statsRecorder - Optional sink for what aged out.
134
+ * @returns How many entries were removed.
130
135
  */
131
- async retarget(destination, previousDestination) {
132
- const release = await this.waitForDrainLock();
133
- if (!release)
134
- return false;
135
- try {
136
- for (const name of await this.listFiles()) {
137
- const file = path.join(this.options.queueDir, name);
138
- const entry = await this.readEntry(file);
139
- if (!entry || entry.destination !== previousDestination)
140
- continue;
141
- await writeFileAtomic(file, JSON.stringify({ ...entry, destination }), SECRET_FILE_MODE);
142
- }
143
- return true;
144
- }
145
- finally {
146
- await release();
147
- }
136
+ async sweep(statsRecorder) {
137
+ const { dropped } = await this.sweepUnsendable(this.now().getTime());
138
+ if (dropped > 0)
139
+ await statsRecorder?.recordDropped(dropped);
140
+ return dropped;
148
141
  }
149
142
  /**
150
143
  * Entries pinned to exactly this destination; legacy and ANY entries are not
@@ -165,20 +158,46 @@ export class EventQueue {
165
158
  /**
166
159
  * Entries due for this transport, dropping the ones that can never be sent.
167
160
  *
161
+ * Reads at most `maxBatch` entries, whatever the backlog holds and whatever it
162
+ * finds in them. Reading and zod-parsing the whole partition to find the few
163
+ * entries a pass may send is what made an outage cost the developer up to
164
+ * `maxQueueEvents` file reads on every hook, which AGENTS.md §3 forbids
165
+ * outright. The bound is on entries *read*, not on entries found due: a
166
+ * backlog where nothing is due — every entry in backoff, or every entry
167
+ * pinned to a destination this identity no longer sends to, which is what a
168
+ * changed endpoint leaves behind for a week — is exactly the case that would
169
+ * otherwise walk all of it and send nothing.
170
+ *
171
+ * A hard read bound needs the scan to move, or the head of the sorted list
172
+ * would be re-read on every pass and the tail never reached. So the scan
173
+ * starts where the last one stopped and wraps around: every entry is examined
174
+ * within `ceil(backlog / maxBatch)` passes, which is what FR-009 asks for —
175
+ * no entry deferred forever. Losing the cursor costs one pass starting at the
176
+ * head again.
177
+ *
178
+ * The batch is therefore the oldest of what this pass *scanned*, not of the
179
+ * whole backlog. Global oldest-first would need a due-time index, which is
180
+ * separate work.
181
+ *
168
182
  * @param transport - Where the pass will send.
169
183
  * @param nowMs - This pass's clock reading.
184
+ * @param maxBatch - Entries this pass may read; also its ceiling on sends.
170
185
  * @returns The due entries and what collecting them dropped.
171
186
  */
172
- async collectDue(transport, nowMs) {
187
+ async collectDue(transport, nowMs, maxBatch) {
188
+ const names = await this.listFiles();
189
+ const start = await this.scanStart(names);
190
+ const scan = [...names.slice(start), ...names.slice(0, start)].slice(0, maxBatch);
173
191
  const due = [];
174
192
  let dropped = 0;
175
- for (const name of await this.listFiles()) {
193
+ for (const name of scan) {
176
194
  const file = path.join(this.options.queueDir, name);
177
195
  const entry = await this.readEntry(file);
178
- if (!entry || this.isExpired(entry, nowMs) || !isProductEntry(entry)) {
196
+ if (!entry || this.isExpired(entry, nowMs) || !isProductEvent(entry.event)) {
179
197
  // Unreadable, aged out, or — for a backlog written by a pre-product
180
198
  // release — an internal lifecycle event the backend does not accept.
181
- // Draining one of those would poison every batch it rides in.
199
+ // Draining one of those would poison every batch it rides in. Entries
200
+ // past the scan are the throttled sweep's business, not this pass's.
182
201
  await fs.rm(file, { force: true });
183
202
  dropped += 1;
184
203
  continue;
@@ -188,25 +207,136 @@ export class EventQueue {
188
207
  if (Date.parse(entry.nextAttemptAt) <= nowMs)
189
208
  due.push({ file, entry });
190
209
  }
210
+ const last = scan.at(-1);
211
+ if (last !== undefined)
212
+ await this.rememberScan(last);
191
213
  return { due, delta: { ...EMPTY_DELTA, dropped } };
192
214
  }
215
+ /**
216
+ * Index the next bounded scan starts at.
217
+ *
218
+ * The first name *after* the one last scanned, so an entry that was sent and
219
+ * deleted in the meantime does not send the scan back to the head.
220
+ *
221
+ * @param names - This pass's sorted entry names.
222
+ * @returns The starting index; zero when there is no cursor to resume from.
223
+ */
224
+ async scanStart(names) {
225
+ const last = await this.lastScanned();
226
+ if (last === undefined)
227
+ return 0;
228
+ const next = names.findIndex((name) => name > last);
229
+ return next === -1 ? 0 : next;
230
+ }
231
+ /**
232
+ * The entry name the previous pass stopped on.
233
+ *
234
+ * @returns The name, or undefined when nothing has scanned yet.
235
+ */
236
+ async lastScanned() {
237
+ try {
238
+ return (await fs.readFile(this.cursorFile(), 'utf8')) || undefined;
239
+ }
240
+ catch {
241
+ // No cursor, or one we cannot read: start at the head. This is a hint for
242
+ // fairness, not state anything depends on.
243
+ return undefined;
244
+ }
245
+ }
246
+ /**
247
+ * Record where this pass stopped.
248
+ *
249
+ * @param name - The last entry name it read.
250
+ */
251
+ async rememberScan(name) {
252
+ try {
253
+ // The same write as every other file in the partition, for the same
254
+ // reason: it renames a 0600 temp file over the target, so a cursor
255
+ // somebody pre-created as a symlink is replaced rather than followed.
256
+ await writeFileAtomic(this.cursorFile(), name, SECRET_FILE_MODE);
257
+ }
258
+ catch {
259
+ // Same rule as the sweep marker: the drain runs on the hook path, and
260
+ // failing to remember a position must never fail the agent's turn.
261
+ }
262
+ }
263
+ /**
264
+ * Where the scan cursor lives.
265
+ *
266
+ * Not a `.json` name, so the entry listing never sees it.
267
+ *
268
+ * @returns Absolute path to the cursor file.
269
+ */
270
+ cursorFile() {
271
+ return path.join(this.options.queueDir, QUEUE_SCAN_CURSOR_FILE);
272
+ }
273
+ /**
274
+ * Remove everything that can never be sent, wherever it sits in the partition.
275
+ *
276
+ * The bounded scan only ever sees the head of the backlog, so the retention
277
+ * bound needs a pass that sees all of it. Throttled by a marker, because that
278
+ * pass is the expensive one — and it is an improvement on what it replaces:
279
+ * expiry used to be enforced only inside a drain, and a drain is skipped for
280
+ * the whole cooldown window, so during a backend outage nothing aged out at
281
+ * all. That was precisely the week-long case the bound exists for.
282
+ *
283
+ * @param nowMs - This pass's clock reading.
284
+ * @returns What the sweep dropped, or nothing when it was not due.
285
+ */
286
+ async sweepUnsendable(nowMs) {
287
+ // `Date.now()`, not `nowMs`: the throttle is a marker file's mtime, which is
288
+ // real wall-clock time, and `nowMs` comes from the injectable clock. Compared
289
+ // against each other a fixed test clock — or a backward NTP step in
290
+ // production — makes `nowMs - last` negative forever, which reads as "not
291
+ // due" and silences the retention pass for good. `TurnStateStore.sweep`
292
+ // passes the wall clock here for the same reason. Expiry below still uses
293
+ // `nowMs`, because that is a judgement about the entries, not about when this
294
+ // process last swept.
295
+ if (!(await claimSweep(path.join(this.options.queueDir, SWEEP_MARKER_FILE), QUEUE_SWEEP_INTERVAL_MS, Date.now())))
296
+ return EMPTY_DELTA;
297
+ let dropped = 0;
298
+ for (const name of await this.listFiles()) {
299
+ const file = path.join(this.options.queueDir, name);
300
+ const entry = await this.readEntry(file);
301
+ if (entry && !this.isExpired(entry, nowMs) && isProductEvent(entry.event))
302
+ continue;
303
+ await fs.rm(file, { force: true });
304
+ dropped += 1;
305
+ }
306
+ return { ...EMPTY_DELTA, dropped };
307
+ }
193
308
  /**
194
309
  * Send one batch, isolating a poison entry when the backend refuses it.
195
310
  *
196
311
  * @param transport - Where to send.
197
312
  * @param batch - Entries to send.
198
313
  * @param nowMs - This pass's clock reading.
314
+ * @param authBlock - Optional sink for a refused credential.
199
315
  * @returns What the send accomplished and cost.
200
316
  */
201
- async sendBatch(transport, batch, nowMs) {
202
- const result = await transport.send(batch.map(({ entry }) => entry.event));
317
+ async sendBatch(transport, batch, nowMs, authBlock) {
318
+ const result = await sendEvents(transport, batch.map(({ entry }) => entry.event));
203
319
  if (result.ok) {
204
320
  await Promise.all(batch.map(({ file }) => fs.rm(file, { force: true })));
321
+ // A 2xx is the backend accepting the credential: lift a standing block, or
322
+ // a `status` drain delivers one batch and leaves the hooks suspended.
323
+ await authBlock?.clear();
205
324
  return { ...EMPTY_DELTA, sent: batch.length, rejected: reportRejected(result.counters?.rejected, 'the drained batch') };
206
325
  }
326
+ if (result.deferred)
327
+ return { ...EMPTY_DELTA, failed: batch.length };
207
328
  debugLog('queue drain failed', result.error ?? `status ${result.status}`);
329
+ if (result.status !== undefined && AUTH_REJECTED_STATUSES.has(result.status)) {
330
+ // The credential was refused, so nothing in this batch is at fault and
331
+ // nothing about it may change: an attempt spent here would walk the whole
332
+ // backlog to maxAttempts and delete it, which is the one thing the queue
333
+ // exists to prevent. Raise the block instead and leave every entry due.
334
+ if (authBlock && transport.destination)
335
+ await authBlock.raise(transport.destination, result.status, result.refusal);
336
+ return { ...EMPTY_DELTA, failed: batch.length };
337
+ }
208
338
  if (!result.retryable && batch.length > 1)
209
- return this.isolateBatch(transport, batch, nowMs);
339
+ return this.isolateBatch(transport, batch, nowMs, authBlock);
210
340
  let delta = EMPTY_DELTA;
211
341
  for (const { file, entry } of batch) {
212
342
  delta = mergeDeltas(delta, await this.recordFailure(file, entry, nowMs));
@@ -225,9 +355,10 @@ export class EventQueue {
225
355
  * @param transport - Where to send.
226
356
  * @param batch - Entries the batch send refused.
227
357
  * @param nowMs - This pass's clock reading.
358
+ * @param authBlock - Persisted refusal, including one received by a single probe.
228
359
  * @returns What the probes accomplished and cost.
229
360
  */
230
- async isolateBatch(transport, batch, nowMs) {
361
+ async isolateBatch(transport, batch, nowMs, authBlock) {
231
362
  let delta = EMPTY_DELTA;
232
363
  let probes = 0;
233
364
  for (const { file, entry } of batch) {
@@ -236,24 +367,22 @@ export class EventQueue {
236
367
  continue;
237
368
  }
238
369
  probes += 1;
239
- const single = await transport.send([entry.event]);
370
+ const single = await sendEvents(transport, [entry.event]);
371
+ if (single.deferred || (single.status !== undefined && AUTH_REJECTED_STATUSES.has(single.status))) {
372
+ if (!single.deferred && single.status !== undefined && authBlock && transport.destination)
373
+ await authBlock.raise(transport.destination, single.status, single.refusal);
374
+ return mergeDeltas(delta, { ...EMPTY_DELTA, failed: batch.length - probes + 1 });
375
+ }
240
376
  if (!single.ok) {
241
377
  delta = mergeDeltas(delta, await this.recordFailure(file, entry, nowMs));
242
378
  continue;
243
379
  }
244
380
  await fs.rm(file, { force: true });
381
+ await authBlock?.clear();
245
382
  delta = mergeDeltas(delta, { ...EMPTY_DELTA, sent: 1, rejected: reportRejected(single.counters?.rejected, 'an isolation probe') });
246
383
  }
247
384
  return delta;
248
385
  }
249
- /**
250
- * Acquire the drain lock, waiting a bounded time.
251
- *
252
- * @returns The release function, or undefined on timeout.
253
- */
254
- waitForDrainLock() {
255
- return pollUntil(() => acquireLock(this.options.locksDir, QUEUE_DRAIN_LOCK, this.now), RETARGET_LOCK_WAIT_MS, RETARGET_LOCK_POLL_MS);
256
- }
257
386
  /**
258
387
  * Back a failed entry off, or drop it once its budget is spent.
259
388
  *
@@ -293,14 +422,8 @@ export class EventQueue {
293
422
  *
294
423
  * @returns The names, or an empty list when the directory is absent.
295
424
  */
296
- async listFiles() {
297
- try {
298
- const names = await fs.readdir(this.options.queueDir);
299
- return names.filter((name) => name.endsWith(QUEUE_FILE_SUFFIX)).sort();
300
- }
301
- catch {
302
- return [];
303
- }
425
+ listFiles() {
426
+ return listQueueFiles(this.options.queueDir);
304
427
  }
305
428
  /**
306
429
  * Read and validate one entry.
@@ -332,6 +455,11 @@ export class EventQueue {
332
455
  *
333
456
  * The oldest are the least likely to still be deliverable, and an unbounded
334
457
  * queue on a developer machine is a disk-space bug.
458
+ *
459
+ * Reported through `options.stats`, like every other permanent loss: these
460
+ * deletions used to be the one kind that left `totalDropped` at zero, so a
461
+ * machine steadily shedding records at the bound looked, in `status`, exactly
462
+ * like one that had never lost any.
335
463
  */
336
464
  async enforceBound() {
337
465
  const files = await this.listFiles();
@@ -349,6 +477,8 @@ export class EventQueue {
349
477
  for (const { full } of doomed) {
350
478
  await fs.rm(full, { force: true });
351
479
  }
480
+ if (doomed.length > 0)
481
+ await this.options.stats?.recordDropped(doomed.length);
352
482
  }
353
483
  /**
354
484
  * When an entry was first queued, falling back to the file clock.
@@ -421,7 +551,7 @@ async function report(recorder, stats) {
421
551
  * Whether an entry may be sent to this transport.
422
552
  *
423
553
  * Entries pinned to another backend are never re-routed at drain time; they wait
424
- * for their own backend, or for `retarget` when setup reconfigures the URL.
554
+ * for their own backend.
425
555
  * Legacy entries without destination metadata predate pinning, so they flow to
426
556
  * the first configured backend just like ANY_DESTINATION entries.
427
557
  *
@@ -440,10 +570,6 @@ function matchesDestination(entry, transport) {
440
570
  * @param entry - The entry.
441
571
  * @returns True for an llm.call or turn.summary.
442
572
  */
443
- function isProductEntry(entry) {
444
- const type = entry.event.event?.type;
445
- return typeof type === 'string' && PRODUCT_EVENT_TYPE_SET.has(type);
446
- }
447
573
  /**
448
574
  * Backoff for the nth attempt, with jitter.
449
575
  *
@@ -472,3 +598,18 @@ async function exists(file) {
472
598
  return false;
473
599
  }
474
600
  }
601
+ /**
602
+ * Queue entry filenames directly in a directory, sorted. Sub-directories are
603
+ * other identities' partitions and never entries.
604
+ *
605
+ * @param dir - Directory to list.
606
+ * @returns The names, or an empty list when the directory is absent.
607
+ */
608
+ export async function listQueueFiles(dir) {
609
+ try {
610
+ return (await fs.readdir(dir)).filter((name) => name.endsWith(QUEUE_FILE_SUFFIX)).sort();
611
+ }
612
+ catch {
613
+ return [];
614
+ }
615
+ }
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Read a small JSON body, refusing one too large to be the answer.
3
+ *
4
+ * Both bodies this guards — the batch's per-event counters and the enforcement
5
+ * decision — are a handful of integers, and both are decoded inside the coding
6
+ * agent's hook process. A compromised, misconfigured or proxy-intercepted
7
+ * endpoint can answer 200 with an arbitrarily large body, and the send timeout
8
+ * bounds the *request*, not the decode: without a cap the hook allocates
9
+ * whatever it is sent.
10
+ *
11
+ * `content-length` is checked first because it is free, and the stream is
12
+ * capped as well because a chunked response declares no length. Throwing is the
13
+ * right failure here: both call sites already treat an unreadable body as "no
14
+ * answer" and fail open.
15
+ *
16
+ * @param response - The response to decode.
17
+ * @returns The parsed body.
18
+ */
19
+ export declare function readCappedJson(response: Response): Promise<unknown>;
20
+ /**
21
+ * Release unread responses without making cleanup part of the hook's latency.
22
+ * @param response - A response whose body the caller will not consume.
23
+ * @returns Nothing; cancellation errors cannot affect delivery or enforcement.
24
+ */
25
+ export declare function discardResponseBody(response: Response): void;
@@ -0,0 +1,64 @@
1
+ import { BODY_TOO_LARGE, CONTENT_LENGTH_HEADER, MAX_RESPONSE_BYTES } from './constants/transport.constants.js';
2
+ /**
3
+ * Read a small JSON body, refusing one too large to be the answer.
4
+ *
5
+ * Both bodies this guards — the batch's per-event counters and the enforcement
6
+ * decision — are a handful of integers, and both are decoded inside the coding
7
+ * agent's hook process. A compromised, misconfigured or proxy-intercepted
8
+ * endpoint can answer 200 with an arbitrarily large body, and the send timeout
9
+ * bounds the *request*, not the decode: without a cap the hook allocates
10
+ * whatever it is sent.
11
+ *
12
+ * `content-length` is checked first because it is free, and the stream is
13
+ * capped as well because a chunked response declares no length. Throwing is the
14
+ * right failure here: both call sites already treat an unreadable body as "no
15
+ * answer" and fail open.
16
+ *
17
+ * @param response - The response to decode.
18
+ * @returns The parsed body.
19
+ */
20
+ export async function readCappedJson(response) {
21
+ if (Number(response.headers.get(CONTENT_LENGTH_HEADER)) > MAX_RESPONSE_BYTES) {
22
+ discardResponseBody(response);
23
+ throw new Error(BODY_TOO_LARGE);
24
+ }
25
+ return JSON.parse(await readCapped(response));
26
+ }
27
+ /**
28
+ * Decode a body, giving up once it passes the cap.
29
+ *
30
+ * @param response - The response whose stream to read.
31
+ * @returns The decoded text.
32
+ */
33
+ async function readCapped(response) {
34
+ if (!response.body)
35
+ return '';
36
+ const reader = response.body.getReader();
37
+ const decoder = new TextDecoder();
38
+ let text = '';
39
+ let total = 0;
40
+ try {
41
+ while (true) {
42
+ const { done, value } = await reader.read();
43
+ if (done)
44
+ return text + decoder.decode();
45
+ total += value.byteLength;
46
+ if (total > MAX_RESPONSE_BYTES) {
47
+ void reader.cancel().catch(() => undefined);
48
+ throw new Error(BODY_TOO_LARGE);
49
+ }
50
+ text += decoder.decode(value, { stream: true });
51
+ }
52
+ }
53
+ finally {
54
+ reader.releaseLock();
55
+ }
56
+ }
57
+ /**
58
+ * Release unread responses without making cleanup part of the hook's latency.
59
+ * @param response - A response whose body the caller will not consume.
60
+ * @returns Nothing; cancellation errors cannot affect delivery or enforcement.
61
+ */
62
+ export function discardResponseBody(response) {
63
+ void response.body?.cancel().catch(() => undefined);
64
+ }
@@ -0,0 +1,11 @@
1
+ import type { ProductEvent } from '../events/product-event.js';
2
+ import type { DeliveryResult, EventTransport } from './types/transport.types.js';
3
+ /**
4
+ * Convert adapter exceptions to retryable failures without exposing request data.
5
+ * HTTP status owns retry semantics: the gateway reports partial publish failure
6
+ * as 503; accepted-batch counters are diagnostic, not transport failures.
7
+ * @param transport - The selected destination adapter.
8
+ * @param events - Records whose delivery must be confirmed.
9
+ * @returns The adapter result, or a safe retryable failure.
10
+ */
11
+ export declare function sendEvents(transport: EventTransport, events: readonly ProductEvent[]): Promise<DeliveryResult>;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Convert adapter exceptions to retryable failures without exposing request data.
3
+ * HTTP status owns retry semantics: the gateway reports partial publish failure
4
+ * as 503; accepted-batch counters are diagnostic, not transport failures.
5
+ * @param transport - The selected destination adapter.
6
+ * @param events - Records whose delivery must be confirmed.
7
+ * @returns The adapter result, or a safe retryable failure.
8
+ */
9
+ export async function sendEvents(transport, events) {
10
+ try {
11
+ return await transport.send(events);
12
+ }
13
+ catch {
14
+ // Adapter errors can contain URLs, headers or captured content.
15
+ return { ok: false, retryable: true, error: 'transport failed' };
16
+ }
17
+ }
@@ -0,0 +1,19 @@
1
+ import type { ProductEvent } from '../../events/product-event.js';
2
+ import type { BackendAuthBlock } from '../auth-block.js';
3
+ import type { BackendCooldown } from '../cooldown.js';
4
+ import type { DeliveryStats } from '../delivery-stats.js';
5
+ import type { EventQueue } from '../queue.js';
6
+ import type { DeliveryOutcome, DeliveryResult, EventTransport } from './transport.types.js';
7
+ /** Immutable state for deciding, attempting, preserving and reporting delivery. */
8
+ export interface DeliveryFlowState {
9
+ readonly events: readonly ProductEvent[];
10
+ readonly transport: EventTransport | undefined;
11
+ readonly queue: EventQueue;
12
+ readonly drainBatchSize: number;
13
+ readonly cooldown: BackendCooldown | undefined;
14
+ readonly stats: DeliveryStats | undefined;
15
+ readonly authBlock: BackendAuthBlock | undefined;
16
+ readonly canSend: boolean;
17
+ readonly result?: DeliveryResult;
18
+ readonly outcome: DeliveryOutcome;
19
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -1,5 +1,6 @@
1
1
  import type { z } from 'zod';
2
2
  import type { ProductEvent } from '../../events/product-event.js';
3
+ import type { CaptureConfig } from '../../config/types/config.types.js';
3
4
  import type { queueEntrySchema } from '../schemas/queue.schema.js';
4
5
  /** Per-event outcome counters the backend reports for an accepted batch. */
5
6
  export interface DeliveryCounters {
@@ -14,8 +15,12 @@ export interface DeliveryResult {
14
15
  /** Whether a failure is worth retrying later (network error, 5xx, 429...). */
15
16
  readonly retryable: boolean;
16
17
  readonly error?: string;
18
+ /** The local pass budget prevented or curtailed a request; no retry is charged. */
19
+ readonly deferred?: boolean;
17
20
  /** Per-event outcomes from an accepted batch, when the backend sent them. */
18
21
  readonly counters?: DeliveryCounters;
22
+ /** The gateway's reason for a 401, when it gave one the edge acts on (AWT-355). */
23
+ readonly refusal?: string;
19
24
  }
20
25
  export interface EventTransport {
21
26
  send(events: readonly ProductEvent[]): Promise<DeliveryResult>;
@@ -29,11 +34,24 @@ export interface EventTransport {
29
34
  readonly destination?: string;
30
35
  }
31
36
  export interface HttpTransportOptions {
37
+ readonly capture?: CaptureConfig;
32
38
  readonly eventsUrl: string;
33
39
  readonly token?: string;
40
+ /**
41
+ * The identity has a credential but no bearer to send right now (a refresh
42
+ * failed or the device was refused): defer every send, so records queue
43
+ * instead of going out unauthenticated and raising a block nothing lifts.
44
+ */
45
+ readonly credentialPending?: boolean;
34
46
  readonly installationId?: string;
35
47
  readonly timeoutMs: number;
36
48
  readonly fetchFn?: typeof fetch;
49
+ /** Monotonic deadline shared by direct delivery, drain and isolation probes. */
50
+ readonly deadline?: number;
51
+ /** Hook-owned pass duration, started on first send; omit for reusable transports. */
52
+ readonly budgetMs?: number;
53
+ /** Clock in the same units as deadline; performance.now in production. */
54
+ readonly nowMs?: () => number;
37
55
  }
38
56
  /** What one hook-path delivery attempt did. */
39
57
  export interface DeliveryOutcome {
@@ -50,6 +68,16 @@ export interface QueueOptions {
50
68
  readonly maxAttempts: number;
51
69
  readonly maxEventAgeDays: number;
52
70
  readonly now?: () => Date;
71
+ /**
72
+ * Sink for the entries the bound sacrifices on enqueue.
73
+ *
74
+ * On the options rather than on `enqueue`, because `enforceBound` runs under
75
+ * every enqueue — including the snapshot pipeline's, which has no stats of
76
+ * its own — and a deletion nobody counts is exactly the invisibility
77
+ * `DeliveryStatsSnapshot` exists to remove. Drain reports its own losses
78
+ * through the recorder passed to it.
79
+ */
80
+ readonly stats?: DrainStatsRecorder;
53
81
  }
54
82
  export interface DrainStats {
55
83
  readonly sent: number;
@@ -60,6 +88,23 @@ export interface DrainStats {
60
88
  /** True when the drain lock was held elsewhere and this pass did nothing. */
61
89
  readonly skipped: boolean;
62
90
  }
91
+ /**
92
+ * A standing refusal of this identity's credential by one destination.
93
+ *
94
+ * `since` is when the refusals started, not when the last one happened: it is
95
+ * the number an administrator needs to tell "rotated an hour ago" from
96
+ * "revoked last week and nobody noticed".
97
+ */
98
+ export interface AuthBlockState {
99
+ readonly destination: string;
100
+ /** The refusing HTTP status, 401 or 403. */
101
+ readonly status: number;
102
+ readonly since: string;
103
+ /** The gateway's stated reason, e.g. `token_expired` or `device_revoked`. */
104
+ readonly reason?: string;
105
+ /** The latest refusal; the re-probe wait counts from here. */
106
+ readonly lastRefusalAt?: string;
107
+ }
63
108
  export interface DrainStatsRecorder {
64
109
  recordRejected(count: number): Promise<void>;
65
110
  recordDropped(count: number): Promise<void>;