@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,5 +1,5 @@
1
1
  import path from 'node:path';
2
- import { AGENTWATCH_DIR_NAME, AGENTWATCH_HOME_DIR_NAME, BACKUPS_DIR_NAME, CONFIG_DIR_VAR, CONFIG_FILE_NAME, DATA_DIR_VAR, INSTALL_STATE_FILE_NAME, LOCAL_APP_DATA_VAR, LOCKS_DIR_NAME, POSIX_DATA_FALLBACK, QUEUE_DIR_NAME, SNAPSHOTS_DIR_NAME, TURNS_DIR_NAME, XDG_DATA_HOME_VAR } from './constants/storage.constants.js';
2
+ import { AGENTWATCH_DIR_NAME, AGENTWATCH_HOME_DIR_NAME, BACKUPS_DIR_NAME, CHECKOUTS_DIR_NAME, CONFIG_DIR_VAR, CONFIG_FILE_NAME, DATA_DIR_VAR, INSTALL_STATE_FILE_NAME, LOCAL_APP_DATA_VAR, LOCKS_DIR_NAME, POSIX_DATA_FALLBACK, QUEUE_DIR_NAME, SNAPSHOTS_DIR_NAME, TURNS_DIR_NAME, XDG_DATA_HOME_VAR } from './constants/storage.constants.js';
3
3
  /**
4
4
  * Every path AgentWatch reads or writes, derived from the environment alone.
5
5
  *
@@ -22,7 +22,8 @@ export function resolvePaths(env) {
22
22
  locksDir: path.join(dataDir, LOCKS_DIR_NAME),
23
23
  backupsDir: path.join(dataDir, BACKUPS_DIR_NAME),
24
24
  turnsDir: path.join(dataDir, TURNS_DIR_NAME),
25
- snapshotsDir: path.join(dataDir, SNAPSHOTS_DIR_NAME)
25
+ snapshotsDir: path.join(dataDir, SNAPSHOTS_DIR_NAME),
26
+ checkoutsDir: path.join(dataDir, CHECKOUTS_DIR_NAME)
26
27
  };
27
28
  }
28
29
  /**
@@ -14,6 +14,12 @@ export declare const agentInstallSchema: z.ZodObject<{
14
14
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
15
15
  otelConfigPath: z.ZodOptional<z.ZodString>;
16
16
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
17
+ /**
18
+ * Permission bits the agent's own config file carried before AgentWatch
19
+ * tightened it, so uninstall can put them back. Absent when the file was
20
+ * never tightened, or when AgentWatch created it.
21
+ */
22
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
17
23
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
18
24
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
19
25
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -23,6 +29,12 @@ export declare const agentInstallSchema: z.ZodObject<{
23
29
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
24
30
  otelConfigPath: z.ZodOptional<z.ZodString>;
25
31
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
32
+ /**
33
+ * Permission bits the agent's own config file carried before AgentWatch
34
+ * tightened it, so uninstall can put them back. Absent when the file was
35
+ * never tightened, or when AgentWatch created it.
36
+ */
37
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
26
38
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
27
39
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
28
40
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -32,6 +44,12 @@ export declare const agentInstallSchema: z.ZodObject<{
32
44
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
33
45
  otelConfigPath: z.ZodOptional<z.ZodString>;
34
46
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
47
+ /**
48
+ * Permission bits the agent's own config file carried before AgentWatch
49
+ * tightened it, so uninstall can put them back. Absent when the file was
50
+ * never tightened, or when AgentWatch created it.
51
+ */
52
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
35
53
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
36
54
  }, z.ZodTypeAny, "passthrough">>;
37
55
  /** The whole install-state file: one entry per agent. */
@@ -45,6 +63,12 @@ export declare const installStateSchema: z.ZodObject<{
45
63
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
46
64
  otelConfigPath: z.ZodOptional<z.ZodString>;
47
65
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
66
+ /**
67
+ * Permission bits the agent's own config file carried before AgentWatch
68
+ * tightened it, so uninstall can put them back. Absent when the file was
69
+ * never tightened, or when AgentWatch created it.
70
+ */
71
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
48
72
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
49
73
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
50
74
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -54,6 +78,12 @@ export declare const installStateSchema: z.ZodObject<{
54
78
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
55
79
  otelConfigPath: z.ZodOptional<z.ZodString>;
56
80
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
81
+ /**
82
+ * Permission bits the agent's own config file carried before AgentWatch
83
+ * tightened it, so uninstall can put them back. Absent when the file was
84
+ * never tightened, or when AgentWatch created it.
85
+ */
86
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
57
87
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
58
88
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
59
89
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -63,6 +93,12 @@ export declare const installStateSchema: z.ZodObject<{
63
93
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
64
94
  otelConfigPath: z.ZodOptional<z.ZodString>;
65
95
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
96
+ /**
97
+ * Permission bits the agent's own config file carried before AgentWatch
98
+ * tightened it, so uninstall can put them back. Absent when the file was
99
+ * never tightened, or when AgentWatch created it.
100
+ */
101
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
66
102
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
67
103
  }, z.ZodTypeAny, "passthrough">>>>;
68
104
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -75,6 +111,12 @@ export declare const installStateSchema: z.ZodObject<{
75
111
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
76
112
  otelConfigPath: z.ZodOptional<z.ZodString>;
77
113
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
114
+ /**
115
+ * Permission bits the agent's own config file carried before AgentWatch
116
+ * tightened it, so uninstall can put them back. Absent when the file was
117
+ * never tightened, or when AgentWatch created it.
118
+ */
119
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
78
120
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
79
121
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
80
122
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -84,6 +126,12 @@ export declare const installStateSchema: z.ZodObject<{
84
126
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
85
127
  otelConfigPath: z.ZodOptional<z.ZodString>;
86
128
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
129
+ /**
130
+ * Permission bits the agent's own config file carried before AgentWatch
131
+ * tightened it, so uninstall can put them back. Absent when the file was
132
+ * never tightened, or when AgentWatch created it.
133
+ */
134
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
87
135
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
88
136
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
89
137
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -93,6 +141,12 @@ export declare const installStateSchema: z.ZodObject<{
93
141
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
94
142
  otelConfigPath: z.ZodOptional<z.ZodString>;
95
143
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
144
+ /**
145
+ * Permission bits the agent's own config file carried before AgentWatch
146
+ * tightened it, so uninstall can put them back. Absent when the file was
147
+ * never tightened, or when AgentWatch created it.
148
+ */
149
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
96
150
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
97
151
  }, z.ZodTypeAny, "passthrough">>>>;
98
152
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
@@ -105,6 +159,12 @@ export declare const installStateSchema: z.ZodObject<{
105
159
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
106
160
  otelConfigPath: z.ZodOptional<z.ZodString>;
107
161
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
162
+ /**
163
+ * Permission bits the agent's own config file carried before AgentWatch
164
+ * tightened it, so uninstall can put them back. Absent when the file was
165
+ * never tightened, or when AgentWatch created it.
166
+ */
167
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
108
168
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
109
169
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
110
170
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -114,6 +174,12 @@ export declare const installStateSchema: z.ZodObject<{
114
174
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
115
175
  otelConfigPath: z.ZodOptional<z.ZodString>;
116
176
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
177
+ /**
178
+ * Permission bits the agent's own config file carried before AgentWatch
179
+ * tightened it, so uninstall can put them back. Absent when the file was
180
+ * never tightened, or when AgentWatch created it.
181
+ */
182
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
117
183
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
118
184
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
119
185
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
@@ -123,6 +189,12 @@ export declare const installStateSchema: z.ZodObject<{
123
189
  otelConfiguredAt: z.ZodOptional<z.ZodString>;
124
190
  otelConfigPath: z.ZodOptional<z.ZodString>;
125
191
  otelOwnedKeys: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
192
+ /**
193
+ * Permission bits the agent's own config file carried before AgentWatch
194
+ * tightened it, so uninstall can put them back. Absent when the file was
195
+ * never tightened, or when AgentWatch created it.
196
+ */
197
+ otelPriorMode: z.ZodOptional<z.ZodNumber>;
126
198
  notes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
127
199
  }, z.ZodTypeAny, "passthrough">>>>;
128
200
  }, z.ZodTypeAny, "passthrough">>;
@@ -15,6 +15,12 @@ export const agentInstallSchema = z
15
15
  otelConfiguredAt: z.string().optional(),
16
16
  otelConfigPath: z.string().optional(),
17
17
  otelOwnedKeys: z.array(z.string()).default([]),
18
+ /**
19
+ * Permission bits the agent's own config file carried before AgentWatch
20
+ * tightened it, so uninstall can put them back. Absent when the file was
21
+ * never tightened, or when AgentWatch created it.
22
+ */
23
+ otelPriorMode: z.number().int().optional(),
18
24
  notes: z.array(z.string()).default([])
19
25
  })
20
26
  .passthrough();
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Whether a periodic cleanup is due, claiming it when it is.
3
+ *
4
+ * Both sweeps this gates — expired session state and expired queue entries —
5
+ * cost a directory walk plus a `stat` per file, and both run on the coding
6
+ * agent's hook path, where they were paid on *every* closing turn to discover
7
+ * that nothing had aged out yet. The marker's own mtime is the whole clock: one
8
+ * `stat` on the common path.
9
+ *
10
+ * Deliberately unlocked. Two hooks can both decide a sweep is due and both run
11
+ * it; every removal a sweep makes is idempotent, so the cost of the race is one
12
+ * redundant walk and the cost of a lock would be paid on every hook.
13
+ *
14
+ * @param marker - File whose mtime records the last sweep.
15
+ * @param intervalMs - Minimum gap between sweeps.
16
+ * @param nowMs - This invocation's clock reading.
17
+ * @returns True when the caller should sweep now.
18
+ */
19
+ export declare function claimSweep(marker: string, intervalMs: number, nowMs: number): Promise<boolean>;
@@ -0,0 +1,55 @@
1
+ import fs from 'node:fs/promises';
2
+ import { writeFileAtomic } from './atomic-file.js';
3
+ import { SECRET_FILE_MODE } from './constants/storage.constants.js';
4
+ /**
5
+ * Whether a periodic cleanup is due, claiming it when it is.
6
+ *
7
+ * Both sweeps this gates — expired session state and expired queue entries —
8
+ * cost a directory walk plus a `stat` per file, and both run on the coding
9
+ * agent's hook path, where they were paid on *every* closing turn to discover
10
+ * that nothing had aged out yet. The marker's own mtime is the whole clock: one
11
+ * `stat` on the common path.
12
+ *
13
+ * Deliberately unlocked. Two hooks can both decide a sweep is due and both run
14
+ * it; every removal a sweep makes is idempotent, so the cost of the race is one
15
+ * redundant walk and the cost of a lock would be paid on every hook.
16
+ *
17
+ * @param marker - File whose mtime records the last sweep.
18
+ * @param intervalMs - Minimum gap between sweeps.
19
+ * @param nowMs - This invocation's clock reading.
20
+ * @returns True when the caller should sweep now.
21
+ */
22
+ export async function claimSweep(marker, intervalMs, nowMs) {
23
+ const last = await lastSweptMs(marker);
24
+ if (last !== undefined && nowMs - last < intervalMs)
25
+ return false;
26
+ try {
27
+ // Through the same write every other file in the state directory uses: it
28
+ // renames a 0600 temp file over the target, so a marker somebody
29
+ // pre-created as a symlink is replaced rather than followed, and the state
30
+ // root — which `AGENTWATCH_DATA_DIR` can point at a shared temp directory —
31
+ // never holds a default-mode file this package created.
32
+ await writeFileAtomic(marker, '', SECRET_FILE_MODE);
33
+ return true;
34
+ }
35
+ catch {
36
+ // The state directory is unwritable, which every other write will report.
37
+ // Sweeping anyway would then run on every hook, which is the cost this
38
+ // exists to remove.
39
+ return false;
40
+ }
41
+ }
42
+ /**
43
+ * When the last sweep finished, by the marker's mtime.
44
+ *
45
+ * @param marker - The marker file.
46
+ * @returns Epoch milliseconds, or undefined when nothing has swept yet.
47
+ */
48
+ async function lastSweptMs(marker) {
49
+ try {
50
+ return (await fs.stat(marker)).mtimeMs;
51
+ }
52
+ catch {
53
+ return undefined;
54
+ }
55
+ }
@@ -16,6 +16,8 @@ export interface AgentWatchPaths {
16
16
  readonly turnsDir: string;
17
17
  /** Per-repository record of the last snapshot sent, so the next one is a diff. */
18
18
  readonly snapshotsDir: string;
19
+ /** Per-checkout record of what its remote is called, so the gate asks git once. */
20
+ readonly checkoutsDir: string;
19
21
  }
20
22
  /**
21
23
  * Outcome of a tolerant JSON read. `missing` and `invalid` are distinct on
@@ -0,0 +1,58 @@
1
+ import type { AgentWatchPaths } from './types/storage.types.js';
2
+ /**
3
+ * The marker `uninstall` leaves beside config.json.
4
+ *
5
+ * Uninstall without `--purge` keeps the config, install keys included, so a
6
+ * reinstall needs no answers again. Without this marker the next `status`,
7
+ * `doctor` or header-helper run would trade a key for a fresh device credential
8
+ * the person had just switched off, or send the key itself. Beside the config,
9
+ * so `--purge` takes it with the keys.
10
+ *
11
+ * @param paths - Resolved AgentWatch paths.
12
+ * @returns The marker path.
13
+ */
14
+ export declare function uninstalledFile(paths: AgentWatchPaths): string;
15
+ /**
16
+ * The marker's name for an entry of the config: the machine's, or a root's by
17
+ * its resolved path, as `selectRoot` names it.
18
+ *
19
+ * @param rootPath - The root, or undefined for the machine entry.
20
+ * @returns The scope.
21
+ */
22
+ export declare function uninstallScope(rootPath: string | undefined): string;
23
+ /**
24
+ * Every scope a config file holds: the machine's and each absolute root's.
25
+ *
26
+ * @param roots - The config's `roots` block.
27
+ * @returns The scopes, machine first.
28
+ */
29
+ export declare function configScopes(roots: Readonly<Record<string, unknown>> | undefined): readonly string[];
30
+ /**
31
+ * Whether this scope was uninstalled since its last setup. A marker that cannot
32
+ * be read, or names no scopes, counts for every scope: enrolling a device or
33
+ * sending a key by mistake is the worse error.
34
+ *
35
+ * @param paths - Resolved AgentWatch paths.
36
+ * @param scope - The entry asked about; the machine's when absent.
37
+ * @returns True while only setup may enroll or send for it.
38
+ */
39
+ export declare function isUninstalled(paths: AgentWatchPaths, scope?: string): Promise<boolean>;
40
+ /**
41
+ * Record an uninstall, before its credentials are removed, so no run in between
42
+ * enrolls an install key again or sends one.
43
+ *
44
+ * @param paths - Resolved AgentWatch paths.
45
+ * @param scopes - The entries uninstalled; every scope when unknown (an unreadable config).
46
+ * @param now - When.
47
+ */
48
+ export declare function markUninstalled(paths: AgentWatchPaths, scopes: readonly string[] | undefined, now: Date): Promise<void>;
49
+ /**
50
+ * Lift the marker for one scope: setup has just been run for it on purpose.
51
+ * The other scopes stay uninstalled until their own setup.
52
+ *
53
+ * @param paths - Resolved AgentWatch paths.
54
+ * @param scope - The entry setup ran for.
55
+ * @param known - Every scope the config holds, for a marker that names none.
56
+ * @returns The scopes still uninstalled, so setup can name them.
57
+ */
58
+ export declare function clearUninstalled(paths: AgentWatchPaths, scope: string, known: readonly string[]): Promise<readonly string[]>;
@@ -0,0 +1,107 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { writeFileAtomic } from './atomic-file.js';
4
+ import { MACHINE_SCOPE, UNINSTALLED_FILE_NAME } from './constants/storage.constants.js';
5
+ import { readJsonFile } from './json-file.js';
6
+ /**
7
+ * The marker `uninstall` leaves beside config.json.
8
+ *
9
+ * Uninstall without `--purge` keeps the config, install keys included, so a
10
+ * reinstall needs no answers again. Without this marker the next `status`,
11
+ * `doctor` or header-helper run would trade a key for a fresh device credential
12
+ * the person had just switched off, or send the key itself. Beside the config,
13
+ * so `--purge` takes it with the keys.
14
+ *
15
+ * @param paths - Resolved AgentWatch paths.
16
+ * @returns The marker path.
17
+ */
18
+ export function uninstalledFile(paths) {
19
+ return path.join(paths.configDir, UNINSTALLED_FILE_NAME);
20
+ }
21
+ /**
22
+ * The marker's name for an entry of the config: the machine's, or a root's by
23
+ * its resolved path, as `selectRoot` names it.
24
+ *
25
+ * @param rootPath - The root, or undefined for the machine entry.
26
+ * @returns The scope.
27
+ */
28
+ export function uninstallScope(rootPath) {
29
+ return rootPath === undefined ? MACHINE_SCOPE : path.resolve(rootPath);
30
+ }
31
+ /**
32
+ * Every scope a config file holds: the machine's and each absolute root's.
33
+ *
34
+ * @param roots - The config's `roots` block.
35
+ * @returns The scopes, machine first.
36
+ */
37
+ export function configScopes(roots) {
38
+ return [MACHINE_SCOPE, ...Object.keys(roots ?? {}).filter((key) => path.isAbsolute(key)).map(uninstallScope)];
39
+ }
40
+ /**
41
+ * Whether this scope was uninstalled since its last setup. A marker that cannot
42
+ * be read, or names no scopes, counts for every scope: enrolling a device or
43
+ * sending a key by mistake is the worse error.
44
+ *
45
+ * @param paths - Resolved AgentWatch paths.
46
+ * @param scope - The entry asked about; the machine's when absent.
47
+ * @returns True while only setup may enroll or send for it.
48
+ */
49
+ export async function isUninstalled(paths, scope = MACHINE_SCOPE) {
50
+ const scopes = await markedScopes(paths);
51
+ return scopes === 'all' || (scopes?.includes(scope) ?? false);
52
+ }
53
+ /**
54
+ * Record an uninstall, before its credentials are removed, so no run in between
55
+ * enrolls an install key again or sends one.
56
+ *
57
+ * @param paths - Resolved AgentWatch paths.
58
+ * @param scopes - The entries uninstalled; every scope when unknown (an unreadable config).
59
+ * @param now - When.
60
+ */
61
+ export async function markUninstalled(paths, scopes, now) {
62
+ await fs.mkdir(paths.configDir, { recursive: true });
63
+ await writeFileAtomic(uninstalledFile(paths), JSON.stringify({ uninstalledAt: now.toISOString(), ...(scopes ? { scopes } : {}) }) + '\n');
64
+ }
65
+ /**
66
+ * Lift the marker for one scope: setup has just been run for it on purpose.
67
+ * The other scopes stay uninstalled until their own setup.
68
+ *
69
+ * @param paths - Resolved AgentWatch paths.
70
+ * @param scope - The entry setup ran for.
71
+ * @param known - Every scope the config holds, for a marker that names none.
72
+ * @returns The scopes still uninstalled, so setup can name them.
73
+ */
74
+ export async function clearUninstalled(paths, scope, known) {
75
+ const scopes = await markedScopes(paths);
76
+ if (scopes === undefined)
77
+ return [];
78
+ const remaining = (scopes === 'all' ? known : scopes).filter((marked) => marked !== scope);
79
+ if (remaining.length === 0) {
80
+ await fs.rm(uninstalledFile(paths), { force: true });
81
+ return [];
82
+ }
83
+ const read = await readJsonFile(uninstalledFile(paths));
84
+ const at = read.state === 'ok' && typeof read.value.uninstalledAt === 'string' ? read.value.uninstalledAt : undefined;
85
+ await writeFileAtomic(uninstalledFile(paths), JSON.stringify({ ...(at ? { uninstalledAt: at } : {}), scopes: remaining }) + '\n');
86
+ return remaining;
87
+ }
88
+ /**
89
+ * The scopes the marker names: undefined without a marker, `all` for one that
90
+ * names none or cannot be read.
91
+ *
92
+ * @param paths - Resolved AgentWatch paths.
93
+ * @returns The marked scopes.
94
+ */
95
+ async function markedScopes(paths) {
96
+ try {
97
+ await fs.lstat(uninstalledFile(paths));
98
+ }
99
+ catch (error) {
100
+ return error.code === 'ENOENT' ? undefined : 'all';
101
+ }
102
+ const read = await readJsonFile(uninstalledFile(paths));
103
+ const scopes = read.state === 'ok' ? read.value?.scopes : undefined;
104
+ if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === 'string'))
105
+ return 'all';
106
+ return scopes;
107
+ }
@@ -0,0 +1,66 @@
1
+ import type { AuthBlockState } from './types/transport.types.js';
2
+ /**
3
+ * Persisted "this credential is rejected" flag for one identity.
4
+ *
5
+ * The state file lives in the identity's own state directory, whose name is
6
+ * already the token digest, so the block is keyed by
7
+ * `(destination, credential fingerprint)` without ever storing the token: a new
8
+ * token lands in a different directory and a new endpoint fails the destination
9
+ * check, which is exactly the "a change of fingerprint lifts the block" rule.
10
+ *
11
+ * It does **not** expire on a timer: it stands, and `status` reports it, until
12
+ * the backend accepts the credential. What it stops is the *retrying*, and only
13
+ * for {@link AUTH_BLOCK_REPROBE_MS} after each refusal — then one send asks
14
+ * again, because a token can become good again without changing on the machine
15
+ * (a token row restored server-side, a revocation undone). The records
16
+ * themselves stay queued, unconditionally.
17
+ */
18
+ export declare class BackendAuthBlock {
19
+ private readonly file;
20
+ private readonly now;
21
+ /**
22
+ * Bind the block to its state file.
23
+ *
24
+ * @param file - Where the block is persisted.
25
+ * @param now - Clock, injectable for tests.
26
+ */
27
+ constructor(file: string, now?: () => Date);
28
+ /**
29
+ * The block standing against one destination, if any.
30
+ *
31
+ * @param destination - The events URL this invocation would send to.
32
+ * @returns The block, or undefined when sends may proceed.
33
+ */
34
+ active(destination: string): Promise<AuthBlockState | undefined>;
35
+ /**
36
+ * Whether the block still suspends sends to a destination: it stands and its
37
+ * last refusal is younger than the re-probe interval.
38
+ *
39
+ * @param destination - The events URL this invocation would send to.
40
+ * @returns True while sends must wait.
41
+ */
42
+ holds(destination: string): Promise<boolean>;
43
+ /**
44
+ * Record that this destination refused the credential.
45
+ *
46
+ * A block already standing for the same destination keeps its original
47
+ * `since`: an administrator needs to know when the refusals started, not when
48
+ * the last hook ran. `lastRefusalAt` moves, and restarts the re-probe wait.
49
+ *
50
+ * @param destination - The events URL that refused.
51
+ * @param status - The refusing HTTP status.
52
+ * @param reason - The gateway's reason, when it gave one the edge acts on
53
+ * (`token_expired` makes the next run refresh at once).
54
+ */
55
+ raise(destination: string, status: number, reason?: string): Promise<void>;
56
+ /**
57
+ * Lift the block — the backend accepted the credential.
58
+ */
59
+ clear(): Promise<void>;
60
+ /**
61
+ * The persisted block, whatever destination it names.
62
+ *
63
+ * @returns The block, or undefined when there is none to read.
64
+ */
65
+ private read;
66
+ }
@@ -0,0 +1,129 @@
1
+ import fs from 'node:fs/promises';
2
+ import { asRecord } from '../core/object.js';
3
+ import { writeFileAtomic } from '../storage/atomic-file.js';
4
+ import { SECRET_FILE_MODE } from '../storage/constants/storage.constants.js';
5
+ import { AUTH_BLOCK_REPROBE_MS } from './constants/transport.constants.js';
6
+ /**
7
+ * Persisted "this credential is rejected" flag for one identity.
8
+ *
9
+ * The state file lives in the identity's own state directory, whose name is
10
+ * already the token digest, so the block is keyed by
11
+ * `(destination, credential fingerprint)` without ever storing the token: a new
12
+ * token lands in a different directory and a new endpoint fails the destination
13
+ * check, which is exactly the "a change of fingerprint lifts the block" rule.
14
+ *
15
+ * It does **not** expire on a timer: it stands, and `status` reports it, until
16
+ * the backend accepts the credential. What it stops is the *retrying*, and only
17
+ * for {@link AUTH_BLOCK_REPROBE_MS} after each refusal — then one send asks
18
+ * again, because a token can become good again without changing on the machine
19
+ * (a token row restored server-side, a revocation undone). The records
20
+ * themselves stay queued, unconditionally.
21
+ */
22
+ export class BackendAuthBlock {
23
+ file;
24
+ now;
25
+ /**
26
+ * Bind the block to its state file.
27
+ *
28
+ * @param file - Where the block is persisted.
29
+ * @param now - Clock, injectable for tests.
30
+ */
31
+ constructor(file, now = () => new Date()) {
32
+ this.file = file;
33
+ this.now = now;
34
+ }
35
+ /**
36
+ * The block standing against one destination, if any.
37
+ *
38
+ * @param destination - The events URL this invocation would send to.
39
+ * @returns The block, or undefined when sends may proceed.
40
+ */
41
+ async active(destination) {
42
+ const block = await this.read();
43
+ if (!block || block.destination !== destination)
44
+ return undefined;
45
+ return block;
46
+ }
47
+ /**
48
+ * Whether the block still suspends sends to a destination: it stands and its
49
+ * last refusal is younger than the re-probe interval.
50
+ *
51
+ * @param destination - The events URL this invocation would send to.
52
+ * @returns True while sends must wait.
53
+ */
54
+ async holds(destination) {
55
+ const block = await this.active(destination);
56
+ if (!block)
57
+ return false;
58
+ return this.now().getTime() - Date.parse(block.lastRefusalAt ?? block.since) < AUTH_BLOCK_REPROBE_MS;
59
+ }
60
+ /**
61
+ * Record that this destination refused the credential.
62
+ *
63
+ * A block already standing for the same destination keeps its original
64
+ * `since`: an administrator needs to know when the refusals started, not when
65
+ * the last hook ran. `lastRefusalAt` moves, and restarts the re-probe wait.
66
+ *
67
+ * @param destination - The events URL that refused.
68
+ * @param status - The refusing HTTP status.
69
+ * @param reason - The gateway's reason, when it gave one the edge acts on
70
+ * (`token_expired` makes the next run refresh at once).
71
+ */
72
+ async raise(destination, status, reason) {
73
+ const standing = await this.active(destination);
74
+ const block = {
75
+ destination,
76
+ status,
77
+ since: standing?.since ?? this.now().toISOString(),
78
+ lastRefusalAt: this.now().toISOString(),
79
+ ...(reason ? { reason } : {})
80
+ };
81
+ try {
82
+ await writeFileAtomic(this.file, JSON.stringify(block), SECRET_FILE_MODE);
83
+ }
84
+ catch {
85
+ // Same rule as the cooldown: this runs on the hook path, and failing to
86
+ // persist a diagnosis must never fail the agent's turn.
87
+ }
88
+ }
89
+ /**
90
+ * Lift the block — the backend accepted the credential.
91
+ */
92
+ async clear() {
93
+ try {
94
+ await fs.rm(this.file, { force: true });
95
+ }
96
+ catch {
97
+ // Awaited between a proven-good credential and the drain: a failure to
98
+ // remove the file must not abort the pass that would empty the backlog.
99
+ }
100
+ }
101
+ /**
102
+ * The persisted block, whatever destination it names.
103
+ *
104
+ * @returns The block, or undefined when there is none to read.
105
+ */
106
+ async read() {
107
+ try {
108
+ const raw = asRecord(JSON.parse(await fs.readFile(this.file, 'utf8')));
109
+ if (typeof raw?.['destination'] !== 'string' || typeof raw['status'] !== 'number' || typeof raw['since'] !== 'string')
110
+ return undefined;
111
+ // A block written before re-probing existed has no lastRefusalAt; `since`
112
+ // stands in for it, so an old block is probed on the next hook.
113
+ const lastRefusalAt = typeof raw['lastRefusalAt'] === 'string' ? raw['lastRefusalAt'] : undefined;
114
+ return {
115
+ destination: raw['destination'],
116
+ status: raw['status'],
117
+ since: raw['since'],
118
+ lastRefusalAt,
119
+ ...(typeof raw['reason'] === 'string' ? { reason: raw['reason'] } : {})
120
+ };
121
+ }
122
+ catch {
123
+ // No file, or one we cannot read: assume the credential is good. Failing
124
+ // open costs one refused send; failing closed would silence telemetry on
125
+ // an install that is working.
126
+ return undefined;
127
+ }
128
+ }
129
+ }