@agent-watch-ai/edge 0.2.5

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 (364) hide show
  1. package/CHANGELOG.md +251 -0
  2. package/LICENSE +21 -0
  3. package/README.md +168 -0
  4. package/dist/billing/billing-mode.d.ts +16 -0
  5. package/dist/billing/billing-mode.js +139 -0
  6. package/dist/billing/constants/billing.constants.d.ts +37 -0
  7. package/dist/billing/constants/billing.constants.js +38 -0
  8. package/dist/billing/index.d.ts +6 -0
  9. package/dist/billing/index.js +6 -0
  10. package/dist/cli/args.d.ts +29 -0
  11. package/dist/cli/args.js +61 -0
  12. package/dist/cli/constants/cli.constants.d.ts +60 -0
  13. package/dist/cli/constants/cli.constants.js +60 -0
  14. package/dist/cli/context.d.ts +51 -0
  15. package/dist/cli/context.js +108 -0
  16. package/dist/cli/doctor.d.ts +15 -0
  17. package/dist/cli/doctor.js +416 -0
  18. package/dist/cli/hook.d.ts +20 -0
  19. package/dist/cli/hook.js +166 -0
  20. package/dist/cli/index.d.ts +13 -0
  21. package/dist/cli/index.js +8 -0
  22. package/dist/cli/misc.d.ts +31 -0
  23. package/dist/cli/misc.js +63 -0
  24. package/dist/cli/setup.d.ts +32 -0
  25. package/dist/cli/setup.js +298 -0
  26. package/dist/cli/status.d.ts +11 -0
  27. package/dist/cli/status.js +174 -0
  28. package/dist/cli/types/cli.types.d.ts +69 -0
  29. package/dist/cli/types/cli.types.js +1 -0
  30. package/dist/cli/ui.d.ts +41 -0
  31. package/dist/cli/ui.js +78 -0
  32. package/dist/cli/uninstall.d.ts +13 -0
  33. package/dist/cli/uninstall.js +83 -0
  34. package/dist/cli.d.ts +2 -0
  35. package/dist/cli.js +124 -0
  36. package/dist/config/config-store.d.ts +29 -0
  37. package/dist/config/config-store.js +75 -0
  38. package/dist/config/config.d.ts +73 -0
  39. package/dist/config/config.js +115 -0
  40. package/dist/config/constants/config.constants.d.ts +62 -0
  41. package/dist/config/constants/config.constants.js +70 -0
  42. package/dist/config/index.d.ts +10 -0
  43. package/dist/config/index.js +5 -0
  44. package/dist/config/repo-config.d.ts +37 -0
  45. package/dist/config/repo-config.js +178 -0
  46. package/dist/config/schemas/config.schema.d.ts +409 -0
  47. package/dist/config/schemas/config.schema.js +97 -0
  48. package/dist/config/types/config.types.d.ts +33 -0
  49. package/dist/config/types/config.types.js +1 -0
  50. package/dist/core/async.d.ts +20 -0
  51. package/dist/core/async.js +32 -0
  52. package/dist/core/constants/core.constants.d.ts +18 -0
  53. package/dist/core/constants/core.constants.js +18 -0
  54. package/dist/core/env.d.ts +12 -0
  55. package/dist/core/env.js +20 -0
  56. package/dist/core/index.d.ts +13 -0
  57. package/dist/core/index.js +8 -0
  58. package/dist/core/logger.d.ts +27 -0
  59. package/dist/core/logger.js +82 -0
  60. package/dist/core/number.d.ts +33 -0
  61. package/dist/core/number.js +47 -0
  62. package/dist/core/object.d.ts +78 -0
  63. package/dist/core/object.js +127 -0
  64. package/dist/core/pipe.d.ts +55 -0
  65. package/dist/core/pipe.js +81 -0
  66. package/dist/core/types/core.types.d.ts +54 -0
  67. package/dist/core/types/core.types.js +4 -0
  68. package/dist/core/version.d.ts +19 -0
  69. package/dist/core/version.js +35 -0
  70. package/dist/core/which.d.ts +13 -0
  71. package/dist/core/which.js +57 -0
  72. package/dist/enforcement/constants/enforcement.constants.d.ts +23 -0
  73. package/dist/enforcement/constants/enforcement.constants.js +22 -0
  74. package/dist/enforcement/decision-cache.d.ts +57 -0
  75. package/dist/enforcement/decision-cache.js +138 -0
  76. package/dist/enforcement/decision-client.d.ts +14 -0
  77. package/dist/enforcement/decision-client.js +84 -0
  78. package/dist/enforcement/enforcement.d.ts +17 -0
  79. package/dist/enforcement/enforcement.js +90 -0
  80. package/dist/enforcement/index.d.ts +11 -0
  81. package/dist/enforcement/index.js +10 -0
  82. package/dist/enforcement/schemas/enforcement.schema.d.ts +30 -0
  83. package/dist/enforcement/schemas/enforcement.schema.js +36 -0
  84. package/dist/enforcement/types/enforcement.types.d.ts +59 -0
  85. package/dist/enforcement/types/enforcement.types.js +1 -0
  86. package/dist/enrollment/constants/enrollment.constants.d.ts +6 -0
  87. package/dist/enrollment/constants/enrollment.constants.js +6 -0
  88. package/dist/enrollment/enrollment-provider.d.ts +5 -0
  89. package/dist/enrollment/enrollment-provider.js +1 -0
  90. package/dist/enrollment/index.d.ts +7 -0
  91. package/dist/enrollment/index.js +1 -0
  92. package/dist/enrollment/manual-enrollment.d.ts +32 -0
  93. package/dist/enrollment/manual-enrollment.js +72 -0
  94. package/dist/enrollment/types/enrollment.types.d.ts +25 -0
  95. package/dist/enrollment/types/enrollment.types.js +1 -0
  96. package/dist/events/canonical-event.d.ts +10 -0
  97. package/dist/events/canonical-event.js +9 -0
  98. package/dist/events/constants/enrich.constants.d.ts +14 -0
  99. package/dist/events/constants/enrich.constants.js +15 -0
  100. package/dist/events/constants/events.constants.d.ts +35 -0
  101. package/dist/events/constants/events.constants.js +57 -0
  102. package/dist/events/enrich.d.ts +16 -0
  103. package/dist/events/enrich.js +226 -0
  104. package/dist/events/event-id.d.ts +32 -0
  105. package/dist/events/event-id.js +49 -0
  106. package/dist/events/index.d.ts +14 -0
  107. package/dist/events/index.js +5 -0
  108. package/dist/events/llm-call.d.ts +14 -0
  109. package/dist/events/llm-call.js +84 -0
  110. package/dist/events/product-event.d.ts +39 -0
  111. package/dist/events/product-event.js +19 -0
  112. package/dist/events/types/enrich.types.d.ts +25 -0
  113. package/dist/events/types/enrich.types.js +1 -0
  114. package/dist/events/types/events.types.d.ts +112 -0
  115. package/dist/events/types/events.types.js +1 -0
  116. package/dist/events/types/llm-call.types.d.ts +79 -0
  117. package/dist/events/types/llm-call.types.js +1 -0
  118. package/dist/events/types/repo-snapshot.types.d.ts +32 -0
  119. package/dist/events/types/repo-snapshot.types.js +1 -0
  120. package/dist/feature/constants/feature.constants.d.ts +10 -0
  121. package/dist/feature/constants/feature.constants.js +10 -0
  122. package/dist/feature/index.d.ts +6 -0
  123. package/dist/feature/index.js +6 -0
  124. package/dist/feature/ticket-candidates.d.ts +13 -0
  125. package/dist/feature/ticket-candidates.js +26 -0
  126. package/dist/git/constants/git.constants.d.ts +84 -0
  127. package/dist/git/constants/git.constants.js +113 -0
  128. package/dist/git/git-context.d.ts +52 -0
  129. package/dist/git/git-context.js +226 -0
  130. package/dist/git/index.d.ts +9 -0
  131. package/dist/git/index.js +3 -0
  132. package/dist/git/remote-sanitize.d.ts +26 -0
  133. package/dist/git/remote-sanitize.js +92 -0
  134. package/dist/git/repo-snapshot.d.ts +40 -0
  135. package/dist/git/repo-snapshot.js +95 -0
  136. package/dist/git/types/git.types.d.ts +36 -0
  137. package/dist/git/types/git.types.js +1 -0
  138. package/dist/git/types/snapshot.types.d.ts +25 -0
  139. package/dist/git/types/snapshot.types.js +1 -0
  140. package/dist/otlp/constants/otlp.constants.d.ts +84 -0
  141. package/dist/otlp/constants/otlp.constants.js +99 -0
  142. package/dist/otlp/http.d.ts +24 -0
  143. package/dist/otlp/http.js +37 -0
  144. package/dist/otlp/index.d.ts +9 -0
  145. package/dist/otlp/index.js +3 -0
  146. package/dist/otlp/normalize.d.ts +14 -0
  147. package/dist/otlp/normalize.js +404 -0
  148. package/dist/otlp/types/otlp.types.d.ts +69 -0
  149. package/dist/otlp/types/otlp.types.js +1 -0
  150. package/dist/pipeline/constants/pipeline.constants.d.ts +23 -0
  151. package/dist/pipeline/constants/pipeline.constants.js +22 -0
  152. package/dist/pipeline/hook-pipeline.d.ts +14 -0
  153. package/dist/pipeline/hook-pipeline.js +297 -0
  154. package/dist/pipeline/index.d.ts +6 -0
  155. package/dist/pipeline/index.js +1 -0
  156. package/dist/pipeline/types/pipeline.types.d.ts +48 -0
  157. package/dist/pipeline/types/pipeline.types.js +1 -0
  158. package/dist/privacy/constants/privacy.constants.d.ts +23 -0
  159. package/dist/privacy/constants/privacy.constants.js +38 -0
  160. package/dist/privacy/index.d.ts +7 -0
  161. package/dist/privacy/index.js +2 -0
  162. package/dist/privacy/sanitizer.d.ts +20 -0
  163. package/dist/privacy/sanitizer.js +52 -0
  164. package/dist/privacy/types/privacy.types.d.ts +13 -0
  165. package/dist/privacy/types/privacy.types.js +1 -0
  166. package/dist/providers/antigravity/antigravity.adapter.d.ts +54 -0
  167. package/dist/providers/antigravity/antigravity.adapter.js +311 -0
  168. package/dist/providers/antigravity/antigravity.detect.d.ts +25 -0
  169. package/dist/providers/antigravity/antigravity.detect.js +64 -0
  170. package/dist/providers/antigravity/antigravity.hooks.d.ts +24 -0
  171. package/dist/providers/antigravity/antigravity.hooks.js +126 -0
  172. package/dist/providers/antigravity/antigravity.provider.d.ts +2 -0
  173. package/dist/providers/antigravity/antigravity.provider.js +22 -0
  174. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +72 -0
  175. package/dist/providers/antigravity/constants/antigravity.constants.js +75 -0
  176. package/dist/providers/antigravity/schemas/antigravity.schema.d.ts +521 -0
  177. package/dist/providers/antigravity/schemas/antigravity.schema.js +64 -0
  178. package/dist/providers/antigravity/types/antigravity.types.d.ts +13 -0
  179. package/dist/providers/antigravity/types/antigravity.types.js +1 -0
  180. package/dist/providers/claude/claude.adapter.d.ts +15 -0
  181. package/dist/providers/claude/claude.adapter.js +141 -0
  182. package/dist/providers/claude/claude.detect.d.ts +20 -0
  183. package/dist/providers/claude/claude.detect.js +57 -0
  184. package/dist/providers/claude/claude.hooks.d.ts +23 -0
  185. package/dist/providers/claude/claude.hooks.js +94 -0
  186. package/dist/providers/claude/claude.otel.d.ts +95 -0
  187. package/dist/providers/claude/claude.otel.js +331 -0
  188. package/dist/providers/claude/claude.provider.d.ts +2 -0
  189. package/dist/providers/claude/claude.provider.js +26 -0
  190. package/dist/providers/claude/constants/claude.constants.d.ts +34 -0
  191. package/dist/providers/claude/constants/claude.constants.js +54 -0
  192. package/dist/providers/claude/constants/claude.otel.constants.d.ts +17 -0
  193. package/dist/providers/claude/constants/claude.otel.constants.js +17 -0
  194. package/dist/providers/claude/schemas/claude.schema.d.ts +72 -0
  195. package/dist/providers/claude/schemas/claude.schema.js +32 -0
  196. package/dist/providers/claude/types/claude.types.d.ts +3 -0
  197. package/dist/providers/claude/types/claude.types.js +1 -0
  198. package/dist/providers/codex/codex.adapter.d.ts +11 -0
  199. package/dist/providers/codex/codex.adapter.js +106 -0
  200. package/dist/providers/codex/codex.detect.d.ts +30 -0
  201. package/dist/providers/codex/codex.detect.js +58 -0
  202. package/dist/providers/codex/codex.hooks.d.ts +27 -0
  203. package/dist/providers/codex/codex.hooks.js +129 -0
  204. package/dist/providers/codex/codex.otel.d.ts +51 -0
  205. package/dist/providers/codex/codex.otel.js +325 -0
  206. package/dist/providers/codex/codex.provider.d.ts +2 -0
  207. package/dist/providers/codex/codex.provider.js +25 -0
  208. package/dist/providers/codex/constants/codex.constants.d.ts +41 -0
  209. package/dist/providers/codex/constants/codex.constants.js +62 -0
  210. package/dist/providers/codex/constants/codex.otel.constants.d.ts +22 -0
  211. package/dist/providers/codex/constants/codex.otel.constants.js +22 -0
  212. package/dist/providers/codex/schemas/codex.schema.d.ts +70 -0
  213. package/dist/providers/codex/schemas/codex.schema.js +32 -0
  214. package/dist/providers/codex/types/codex.types.d.ts +3 -0
  215. package/dist/providers/codex/types/codex.types.js +1 -0
  216. package/dist/providers/constants/provider.constants.d.ts +33 -0
  217. package/dist/providers/constants/provider.constants.js +33 -0
  218. package/dist/providers/cursor/constants/cursor.constants.d.ts +58 -0
  219. package/dist/providers/cursor/constants/cursor.constants.js +95 -0
  220. package/dist/providers/cursor/cursor.adapter.d.ts +11 -0
  221. package/dist/providers/cursor/cursor.adapter.js +331 -0
  222. package/dist/providers/cursor/cursor.detect.d.ts +23 -0
  223. package/dist/providers/cursor/cursor.detect.js +66 -0
  224. package/dist/providers/cursor/cursor.hooks.d.ts +25 -0
  225. package/dist/providers/cursor/cursor.hooks.js +95 -0
  226. package/dist/providers/cursor/cursor.provider.d.ts +2 -0
  227. package/dist/providers/cursor/cursor.provider.js +27 -0
  228. package/dist/providers/cursor/schemas/cursor.schema.d.ts +130 -0
  229. package/dist/providers/cursor/schemas/cursor.schema.js +62 -0
  230. package/dist/providers/cursor/types/cursor.types.d.ts +3 -0
  231. package/dist/providers/cursor/types/cursor.types.js +1 -0
  232. package/dist/providers/gemini/constants/gemini.constants.d.ts +36 -0
  233. package/dist/providers/gemini/constants/gemini.constants.js +58 -0
  234. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +34 -0
  235. package/dist/providers/gemini/constants/gemini.otel.constants.js +48 -0
  236. package/dist/providers/gemini/gemini.adapter.d.ts +15 -0
  237. package/dist/providers/gemini/gemini.adapter.js +146 -0
  238. package/dist/providers/gemini/gemini.detect.d.ts +23 -0
  239. package/dist/providers/gemini/gemini.detect.js +78 -0
  240. package/dist/providers/gemini/gemini.hooks.d.ts +22 -0
  241. package/dist/providers/gemini/gemini.hooks.js +93 -0
  242. package/dist/providers/gemini/gemini.otel.d.ts +62 -0
  243. package/dist/providers/gemini/gemini.otel.js +274 -0
  244. package/dist/providers/gemini/gemini.provider.d.ts +2 -0
  245. package/dist/providers/gemini/gemini.provider.js +22 -0
  246. package/dist/providers/gemini/schemas/gemini.schema.d.ts +81 -0
  247. package/dist/providers/gemini/schemas/gemini.schema.js +35 -0
  248. package/dist/providers/gemini/types/gemini.types.d.ts +3 -0
  249. package/dist/providers/gemini/types/gemini.types.js +1 -0
  250. package/dist/providers/index.d.ts +14 -0
  251. package/dist/providers/index.js +8 -0
  252. package/dist/providers/provider.d.ts +16 -0
  253. package/dist/providers/provider.js +149 -0
  254. package/dist/providers/registry.d.ts +12 -0
  255. package/dist/providers/registry.js +23 -0
  256. package/dist/providers/shared/constants/hook-refusal.constants.d.ts +6 -0
  257. package/dist/providers/shared/constants/hook-refusal.constants.js +6 -0
  258. package/dist/providers/shared/constants/tooling.constants.d.ts +25 -0
  259. package/dist/providers/shared/constants/tooling.constants.js +25 -0
  260. package/dist/providers/shared/event-builder.d.ts +85 -0
  261. package/dist/providers/shared/event-builder.js +166 -0
  262. package/dist/providers/shared/hook-config.d.ts +80 -0
  263. package/dist/providers/shared/hook-config.js +164 -0
  264. package/dist/providers/shared/hook-refusal.d.ts +16 -0
  265. package/dist/providers/shared/hook-refusal.js +33 -0
  266. package/dist/providers/shared/install-record.d.ts +75 -0
  267. package/dist/providers/shared/install-record.js +113 -0
  268. package/dist/providers/shared/tooling.d.ts +58 -0
  269. package/dist/providers/shared/tooling.js +103 -0
  270. package/dist/providers/shared/types/adapter.types.d.ts +54 -0
  271. package/dist/providers/shared/types/adapter.types.js +1 -0
  272. package/dist/providers/shared/types/hook-config.types.d.ts +32 -0
  273. package/dist/providers/shared/types/hook-config.types.js +1 -0
  274. package/dist/providers/types/provider.types.d.ts +98 -0
  275. package/dist/providers/types/provider.types.js +1 -0
  276. package/dist/snapshot/branch-selection.d.ts +37 -0
  277. package/dist/snapshot/branch-selection.js +69 -0
  278. package/dist/snapshot/budget.d.ts +41 -0
  279. package/dist/snapshot/budget.js +67 -0
  280. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +11 -0
  281. package/dist/snapshot/constants/snapshot-stages.constants.js +11 -0
  282. package/dist/snapshot/constants/snapshot.constants.d.ts +56 -0
  283. package/dist/snapshot/constants/snapshot.constants.js +56 -0
  284. package/dist/snapshot/index.d.ts +16 -0
  285. package/dist/snapshot/index.js +6 -0
  286. package/dist/snapshot/snapshot-event.d.ts +17 -0
  287. package/dist/snapshot/snapshot-event.js +66 -0
  288. package/dist/snapshot/snapshot-pipeline.d.ts +14 -0
  289. package/dist/snapshot/snapshot-pipeline.js +163 -0
  290. package/dist/snapshot/snapshot-state.d.ts +55 -0
  291. package/dist/snapshot/snapshot-state.js +100 -0
  292. package/dist/snapshot/types/snapshot.types.d.ts +86 -0
  293. package/dist/snapshot/types/snapshot.types.js +1 -0
  294. package/dist/storage/atomic-file.d.ts +25 -0
  295. package/dist/storage/atomic-file.js +76 -0
  296. package/dist/storage/constants/storage.constants.d.ts +34 -0
  297. package/dist/storage/constants/storage.constants.js +35 -0
  298. package/dist/storage/index.d.ts +10 -0
  299. package/dist/storage/index.js +5 -0
  300. package/dist/storage/install-state.d.ts +20 -0
  301. package/dist/storage/install-state.js +40 -0
  302. package/dist/storage/json-file.d.ts +13 -0
  303. package/dist/storage/json-file.js +31 -0
  304. package/dist/storage/lock.d.ts +15 -0
  305. package/dist/storage/lock.js +70 -0
  306. package/dist/storage/paths.d.ts +14 -0
  307. package/dist/storage/paths.js +42 -0
  308. package/dist/storage/schemas/storage.schema.d.ts +128 -0
  309. package/dist/storage/schemas/storage.schema.js +27 -0
  310. package/dist/storage/types/storage.types.d.ts +36 -0
  311. package/dist/storage/types/storage.types.js +1 -0
  312. package/dist/transport/constants/transport.constants.d.ts +47 -0
  313. package/dist/transport/constants/transport.constants.js +47 -0
  314. package/dist/transport/cooldown.d.ts +35 -0
  315. package/dist/transport/cooldown.js +62 -0
  316. package/dist/transport/delivery-stats.d.ts +65 -0
  317. package/dist/transport/delivery-stats.js +186 -0
  318. package/dist/transport/delivery.d.ts +26 -0
  319. package/dist/transport/delivery.js +80 -0
  320. package/dist/transport/headers.d.ts +12 -0
  321. package/dist/transport/headers.js +19 -0
  322. package/dist/transport/http-transport.d.ts +39 -0
  323. package/dist/transport/http-transport.js +106 -0
  324. package/dist/transport/index.d.ts +13 -0
  325. package/dist/transport/index.js +7 -0
  326. package/dist/transport/queue.d.ts +177 -0
  327. package/dist/transport/queue.js +474 -0
  328. package/dist/transport/schemas/queue.schema.d.ts +30 -0
  329. package/dist/transport/schemas/queue.schema.js +18 -0
  330. package/dist/transport/transport.d.ts +6 -0
  331. package/dist/transport/transport.js +1 -0
  332. package/dist/transport/types/transport.types.d.ts +102 -0
  333. package/dist/transport/types/transport.types.js +1 -0
  334. package/dist/turns/aggregate-usage.d.ts +20 -0
  335. package/dist/turns/aggregate-usage.js +269 -0
  336. package/dist/turns/claude-transcript.d.ts +18 -0
  337. package/dist/turns/claude-transcript.js +80 -0
  338. package/dist/turns/constants/turns.constants.d.ts +69 -0
  339. package/dist/turns/constants/turns.constants.js +86 -0
  340. package/dist/turns/cursor-transcript.d.ts +21 -0
  341. package/dist/turns/cursor-transcript.js +66 -0
  342. package/dist/turns/index.d.ts +17 -0
  343. package/dist/turns/index.js +7 -0
  344. package/dist/turns/transcript.d.ts +74 -0
  345. package/dist/turns/transcript.js +188 -0
  346. package/dist/turns/turn-state.d.ts +94 -0
  347. package/dist/turns/turn-state.js +234 -0
  348. package/dist/turns/turn-summary.d.ts +27 -0
  349. package/dist/turns/turn-summary.js +164 -0
  350. package/dist/turns/turn-tracker.d.ts +14 -0
  351. package/dist/turns/turn-tracker.js +521 -0
  352. package/dist/turns/types/aggregate-usage.types.d.ts +26 -0
  353. package/dist/turns/types/aggregate-usage.types.js +1 -0
  354. package/dist/turns/types/transcript.types.d.ts +41 -0
  355. package/dist/turns/types/transcript.types.js +1 -0
  356. package/dist/turns/types/turn-state.types.d.ts +37 -0
  357. package/dist/turns/types/turn-state.types.js +1 -0
  358. package/dist/turns/types/turn-summary.types.d.ts +106 -0
  359. package/dist/turns/types/turn-summary.types.js +1 -0
  360. package/dist/turns/types/turn-tracker.types.d.ts +27 -0
  361. package/dist/turns/types/turn-tracker.types.js +1 -0
  362. package/example/README.md +43 -0
  363. package/example/server.mjs +240 -0
  364. package/package.json +89 -0
@@ -0,0 +1,13 @@
1
+ import type { Env } from './types/core.types.js';
2
+ /**
3
+ * Locate an executable on PATH.
4
+ *
5
+ * Hand-rolled rather than shelling out to `which`: agent detection runs on the
6
+ * hook path, where a child process per lookup is the most expensive thing the
7
+ * hook would do.
8
+ *
9
+ * @param env - Environment supplying PATH and the platform.
10
+ * @param name - Executable name without extension.
11
+ * @returns Absolute path of the first match, or undefined when not found.
12
+ */
13
+ export declare function findExecutable(env: Env, name: string): string | undefined;
@@ -0,0 +1,57 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { POSIX_EXECUTABLE_MASK, WINDOWS_EXECUTABLE_EXTENSIONS } from './constants/core.constants.js';
4
+ /**
5
+ * Locate an executable on PATH.
6
+ *
7
+ * Hand-rolled rather than shelling out to `which`: agent detection runs on the
8
+ * hook path, where a child process per lookup is the most expensive thing the
9
+ * hook would do.
10
+ *
11
+ * @param env - Environment supplying PATH and the platform.
12
+ * @param name - Executable name without extension.
13
+ * @returns Absolute path of the first match, or undefined when not found.
14
+ */
15
+ export function findExecutable(env, name) {
16
+ const dirs = (env.vars['PATH'] ?? '').split(path.delimiter).filter(Boolean);
17
+ const candidates = executableCandidates(env.platform, name);
18
+ for (const dir of dirs) {
19
+ for (const candidate of candidates) {
20
+ const full = path.join(dir, candidate);
21
+ if (isExecutableFile(full, env.platform))
22
+ return full;
23
+ }
24
+ }
25
+ return undefined;
26
+ }
27
+ /**
28
+ * File names to probe for one executable, in resolution order.
29
+ *
30
+ * @param platform - Host platform.
31
+ * @param name - Executable name without extension.
32
+ * @returns Candidate file names.
33
+ */
34
+ function executableCandidates(platform, name) {
35
+ if (platform !== 'win32')
36
+ return [name];
37
+ return [...WINDOWS_EXECUTABLE_EXTENSIONS.map((extension) => `${name}${extension}`), name];
38
+ }
39
+ /**
40
+ * Whether a path is a file this platform would execute.
41
+ *
42
+ * @param full - Absolute candidate path.
43
+ * @param platform - Host platform; Windows has no executable bit.
44
+ * @returns True when the file exists and is executable.
45
+ */
46
+ function isExecutableFile(full, platform) {
47
+ try {
48
+ const stat = fs.statSync(full);
49
+ if (!stat.isFile())
50
+ return false;
51
+ return platform === 'win32' || (stat.mode & POSIX_EXECUTABLE_MASK) !== 0;
52
+ }
53
+ catch {
54
+ // Not here (or not readable); keep looking.
55
+ return false;
56
+ }
57
+ }
@@ -0,0 +1,23 @@
1
+ import type { EnforcementDecision } from '../types/enforcement.types.js';
2
+ /** The two decisions, as both the wire and the cache file spell them. */
3
+ export declare const DECISION_ALLOW = "allow";
4
+ export declare const DECISION_BLOCK = "block";
5
+ /**
6
+ * The answer every failure degrades to.
7
+ *
8
+ * Shared as one frozen value so no code path can build an "allow" that carries
9
+ * anything else.
10
+ */
11
+ export declare const ALLOW: EnforcementDecision;
12
+ /** Local cache file under the data directory. */
13
+ export declare const ENFORCEMENT_CACHE_FILE_NAME = "enforcement-cache.json";
14
+ /**
15
+ * Entries kept in the cache file.
16
+ *
17
+ * A machine has one backend token and, through per-repository git identities, a
18
+ * handful of developer ids; the cap exists so a pathological setup cannot grow
19
+ * the file without bound, not because 16 is ever reached.
20
+ */
21
+ export declare const MAX_CACHE_ENTRIES = 16;
22
+ /** Query parameter the endpoint reads the identity from. */
23
+ export declare const DEVELOPER_ID_PARAM = "developer_id";
@@ -0,0 +1,22 @@
1
+ /** The two decisions, as both the wire and the cache file spell them. */
2
+ export const DECISION_ALLOW = 'allow';
3
+ export const DECISION_BLOCK = 'block';
4
+ /**
5
+ * The answer every failure degrades to.
6
+ *
7
+ * Shared as one frozen value so no code path can build an "allow" that carries
8
+ * anything else.
9
+ */
10
+ export const ALLOW = Object.freeze({ decision: DECISION_ALLOW });
11
+ /** Local cache file under the data directory. */
12
+ export const ENFORCEMENT_CACHE_FILE_NAME = 'enforcement-cache.json';
13
+ /**
14
+ * Entries kept in the cache file.
15
+ *
16
+ * A machine has one backend token and, through per-repository git identities, a
17
+ * handful of developer ids; the cap exists so a pathological setup cannot grow
18
+ * the file without bound, not because 16 is ever reached.
19
+ */
20
+ export const MAX_CACHE_ENTRIES = 16;
21
+ /** Query parameter the endpoint reads the identity from. */
22
+ export const DEVELOPER_ID_PARAM = 'developer_id';
@@ -0,0 +1,57 @@
1
+ import type { EnforcementDecision } from './types/enforcement.types.js';
2
+ /**
3
+ * The decision, memoised on disk for the TTL the platform caches it for.
4
+ *
5
+ * Hooks are separate short-lived processes, so "this developer is allowed" has
6
+ * to survive between them or the check would be a round trip per turn. Every
7
+ * failure — a missing file, an unparseable one, an entry this code cannot read,
8
+ * a write that fails — is a miss: the cache exists to save a request, never to
9
+ * decide anything.
10
+ */
11
+ export declare class DecisionCache {
12
+ private readonly file;
13
+ private readonly now;
14
+ /**
15
+ * Bind the cache to its file.
16
+ *
17
+ * @param file - Where decisions are persisted.
18
+ * @param now - Clock, injectable for tests.
19
+ */
20
+ constructor(file: string, now: () => Date);
21
+ /**
22
+ * The unexpired decision for one key.
23
+ *
24
+ * @param key - Key from {@link decisionKey}.
25
+ * @returns The decision, or undefined on a miss.
26
+ */
27
+ read(key: string): Promise<EnforcementDecision | undefined>;
28
+ /**
29
+ * Store one decision, pruning what has expired.
30
+ *
31
+ * @param key - Key from {@link decisionKey}.
32
+ * @param decision - The decision to keep.
33
+ * @param ttlMs - How long it stays usable.
34
+ */
35
+ write(key: string, decision: EnforcementDecision, ttlMs: number): Promise<void>;
36
+ /**
37
+ * Raw entries of the cache file.
38
+ *
39
+ * @returns The entries, or an empty bag when the file is absent or unusable.
40
+ */
41
+ private entries;
42
+ }
43
+ /**
44
+ * The cache key for one question.
45
+ *
46
+ * Hashed rather than composed in the clear: the file would otherwise hold the
47
+ * backend token and the developer's email next to a dollar figure, and neither
48
+ * is needed to read an entry back. Including the URL and the token means a
49
+ * re-pointed or re-credentialed Edge starts with a cold cache instead of
50
+ * answering from another backend's decisions.
51
+ *
52
+ * @param url - The decision endpoint.
53
+ * @param token - Edge token the question is asked with.
54
+ * @param developerId - Identity the question is about.
55
+ * @returns The key.
56
+ */
57
+ export declare function decisionKey(url: string, token: string, developerId: string): string;
@@ -0,0 +1,138 @@
1
+ import crypto from 'node:crypto';
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 { readJsonFile } from '../storage/json-file.js';
6
+ import { MAX_CACHE_ENTRIES } from './constants/enforcement.constants.js';
7
+ import { cachedDecisionSchema } from './schemas/enforcement.schema.js';
8
+ /**
9
+ * The decision, memoised on disk for the TTL the platform caches it for.
10
+ *
11
+ * Hooks are separate short-lived processes, so "this developer is allowed" has
12
+ * to survive between them or the check would be a round trip per turn. Every
13
+ * failure — a missing file, an unparseable one, an entry this code cannot read,
14
+ * a write that fails — is a miss: the cache exists to save a request, never to
15
+ * decide anything.
16
+ */
17
+ export class DecisionCache {
18
+ file;
19
+ now;
20
+ /**
21
+ * Bind the cache to its file.
22
+ *
23
+ * @param file - Where decisions are persisted.
24
+ * @param now - Clock, injectable for tests.
25
+ */
26
+ constructor(file, now) {
27
+ this.file = file;
28
+ this.now = now;
29
+ }
30
+ /**
31
+ * The unexpired decision for one key.
32
+ *
33
+ * @param key - Key from {@link decisionKey}.
34
+ * @returns The decision, or undefined on a miss.
35
+ */
36
+ async read(key) {
37
+ const entries = await this.entries();
38
+ return usableEntry(entries[key], this.now().getTime())?.decision;
39
+ }
40
+ /**
41
+ * Store one decision, pruning what has expired.
42
+ *
43
+ * @param key - Key from {@link decisionKey}.
44
+ * @param decision - The decision to keep.
45
+ * @param ttlMs - How long it stays usable.
46
+ */
47
+ async write(key, decision, ttlMs) {
48
+ const at = this.now().getTime();
49
+ const next = { ...liveEntries(await this.entries(), at), [key]: { decision, expiresAt: at + ttlMs } };
50
+ try {
51
+ // 0600: an entry holds the alert's sentence, which names a person and
52
+ // what they spent.
53
+ await writeFileAtomic(this.file, JSON.stringify(bounded(next)), SECRET_FILE_MODE);
54
+ }
55
+ catch {
56
+ // A decision that cannot be stored is still a decision: the caller has
57
+ // its answer and the next hook simply asks again.
58
+ }
59
+ }
60
+ /**
61
+ * Raw entries of the cache file.
62
+ *
63
+ * @returns The entries, or an empty bag when the file is absent or unusable.
64
+ */
65
+ async entries() {
66
+ const result = await readJsonFile(this.file);
67
+ if (result.state !== 'ok')
68
+ return {};
69
+ return asRecord(result.value) ?? {};
70
+ }
71
+ }
72
+ /**
73
+ * The cache key for one question.
74
+ *
75
+ * Hashed rather than composed in the clear: the file would otherwise hold the
76
+ * backend token and the developer's email next to a dollar figure, and neither
77
+ * is needed to read an entry back. Including the URL and the token means a
78
+ * re-pointed or re-credentialed Edge starts with a cold cache instead of
79
+ * answering from another backend's decisions.
80
+ *
81
+ * @param url - The decision endpoint.
82
+ * @param token - Edge token the question is asked with.
83
+ * @param developerId - Identity the question is about.
84
+ * @returns The key.
85
+ */
86
+ export function decisionKey(url, token, developerId) {
87
+ return crypto.createHash('sha256').update(`${url}|${token}|${developerId}`).digest('hex');
88
+ }
89
+ /**
90
+ * One entry, if it both validates and is still live.
91
+ *
92
+ * The whole fail-open invariant rests on this test — an entry an older version
93
+ * wrote, a key that collided, something edited by hand must read as a miss
94
+ * rather than as an answer — so it exists once and both readers go through it.
95
+ *
96
+ * @param value - Raw entry from the file.
97
+ * @param at - Current epoch milliseconds.
98
+ * @returns The entry, or undefined when it cannot be used.
99
+ */
100
+ function usableEntry(value, at) {
101
+ const parsed = cachedDecisionSchema.safeParse(value);
102
+ if (!parsed.success || parsed.data.expiresAt <= at)
103
+ return undefined;
104
+ return parsed.data;
105
+ }
106
+ /**
107
+ * The entries that are still usable, validated on the way through.
108
+ *
109
+ * @param entries - Raw entries of the file.
110
+ * @param at - Current epoch milliseconds.
111
+ * @returns Only the usable entries.
112
+ */
113
+ function liveEntries(entries, at) {
114
+ const out = {};
115
+ for (const [key, value] of Object.entries(entries)) {
116
+ const entry = usableEntry(value, at);
117
+ if (!entry)
118
+ continue;
119
+ out[key] = entry;
120
+ }
121
+ return out;
122
+ }
123
+ /**
124
+ * The newest entries, when a pathological setup has grown the file.
125
+ *
126
+ * @param entries - Entries about to be written.
127
+ * @returns At most {@link MAX_CACHE_ENTRIES} of them, the longest-lived first.
128
+ */
129
+ function bounded(entries) {
130
+ const pairs = Object.entries(entries);
131
+ if (pairs.length <= MAX_CACHE_ENTRIES)
132
+ return entries;
133
+ const out = {};
134
+ const kept = pairs.sort((left, right) => right[1].expiresAt - left[1].expiresAt).slice(0, MAX_CACHE_ENTRIES);
135
+ for (const [key, value] of kept)
136
+ out[key] = value;
137
+ return out;
138
+ }
@@ -0,0 +1,14 @@
1
+ import type { AnsweredDecision, DecisionRequest } from './types/enforcement.types.js';
2
+ /**
3
+ * Ask the platform whether one developer may make an LLM call.
4
+ *
5
+ * Never throws, and answers `undefined` — "nobody said no" — for everything
6
+ * that is not a complete, valid decision: a timeout, a network error, any
7
+ * non-2xx status, a body that is not JSON, and a body whose decision this code
8
+ * cannot read. Only the caller's own allow default gets built out of those; a
9
+ * refusal can only ever come from a body that validates.
10
+ *
11
+ * @param request - Destination, credentials, identity and timeout.
12
+ * @returns The platform's decision, or undefined when it did not give one.
13
+ */
14
+ export declare function requestDecision(request: DecisionRequest): Promise<AnsweredDecision | undefined>;
@@ -0,0 +1,84 @@
1
+ import { debugLog } from '../core/logger.js';
2
+ import { edgeHeaders } from '../transport/headers.js';
3
+ import { DEVELOPER_ID_PARAM } from './constants/enforcement.constants.js';
4
+ import { cacheTtlSchema, decisionSchema } from './schemas/enforcement.schema.js';
5
+ /**
6
+ * Ask the platform whether one developer may make an LLM call.
7
+ *
8
+ * Never throws, and answers `undefined` — "nobody said no" — for everything
9
+ * that is not a complete, valid decision: a timeout, a network error, any
10
+ * non-2xx status, a body that is not JSON, and a body whose decision this code
11
+ * cannot read. Only the caller's own allow default gets built out of those; a
12
+ * refusal can only ever come from a body that validates.
13
+ *
14
+ * @param request - Destination, credentials, identity and timeout.
15
+ * @returns The platform's decision, or undefined when it did not give one.
16
+ */
17
+ export async function requestDecision(request) {
18
+ const fetchFn = request.fetchFn ?? fetch;
19
+ try {
20
+ const response = await fetchFn(decisionUrl(request), {
21
+ method: 'GET',
22
+ // A GET carries no body, so no content type: the identifying triple is all
23
+ // the platform needs to resolve the tenant.
24
+ headers: edgeHeaders(request.token, request.installationId),
25
+ signal: AbortSignal.timeout(request.timeoutMs)
26
+ });
27
+ if (!response.ok) {
28
+ debugLog(`enforcement: HTTP ${response.status}; allowing`);
29
+ return undefined;
30
+ }
31
+ return readDecision(await response.json());
32
+ }
33
+ catch (error) {
34
+ // Never log the response body: the message names a person and what they
35
+ // spent, and this line goes to the developer's terminal.
36
+ debugLog('enforcement: check failed; allowing:', error.name || 'network error');
37
+ return undefined;
38
+ }
39
+ }
40
+ /**
41
+ * The endpoint with the identity attached.
42
+ *
43
+ * @param request - The request being made.
44
+ * @returns The full URL.
45
+ */
46
+ function decisionUrl(request) {
47
+ const url = new URL(request.url);
48
+ url.searchParams.set(DEVELOPER_ID_PARAM, request.developerId);
49
+ return url.toString();
50
+ }
51
+ /**
52
+ * A decoded body, if it is a decision at all.
53
+ *
54
+ * @param body - Whatever the endpoint returned.
55
+ * @returns The decision, or undefined when the body is not one.
56
+ */
57
+ function readDecision(body) {
58
+ const parsed = decisionSchema.safeParse(body);
59
+ if (!parsed.success) {
60
+ debugLog('enforcement: unreadable decision; allowing');
61
+ return undefined;
62
+ }
63
+ return { ...parsed.data, cacheTtlMs: readCacheTtlMs(body) };
64
+ }
65
+ /**
66
+ * How long the platform asked this answer to be kept, when it asked usably.
67
+ *
68
+ * Read after the decision and separately from it, so a TTL this side cannot make
69
+ * sense of costs nothing but the advice: an unreadable number means the local
70
+ * configuration decides, exactly as it does when the platform sends none.
71
+ *
72
+ * @param body - Whatever the endpoint returned.
73
+ * @returns The advised TTL, or undefined when there is no usable advice.
74
+ */
75
+ function readCacheTtlMs(body) {
76
+ if (typeof body !== 'object' || body === null)
77
+ return undefined;
78
+ const parsed = cacheTtlSchema.safeParse(body.cache_ttl_ms);
79
+ if (!parsed.success) {
80
+ debugLog('enforcement: unusable cache_ttl_ms; keeping the configured TTL');
81
+ return undefined;
82
+ }
83
+ return parsed.data;
84
+ }
@@ -0,0 +1,17 @@
1
+ import type { EnforcementDecision, EnforcementOptions } from './types/enforcement.types.js';
2
+ /**
3
+ * Whether this developer may start a turn right now.
4
+ *
5
+ * The single rule of this module: only an explicit `block` from the platform,
6
+ * carrying the sentence that explains it, is a refusal. Not configured, turned
7
+ * off, nobody to ask about, a timeout, a network error, any other status, a body
8
+ * this code cannot read — every one of them allows the turn. The check sits in
9
+ * front of every developer's tooling, so a check that failed closed would turn
10
+ * an alerts-service hiccup into an outage for a whole engineering organization.
11
+ *
12
+ * Never throws: a caller on the hook path has to answer the agent either way.
13
+ *
14
+ * @param options - Effective config, paths, the identity to ask about, clock.
15
+ * @returns The decision to act on.
16
+ */
17
+ export declare function resolveEnforcement(options: EnforcementOptions): Promise<EnforcementDecision>;
@@ -0,0 +1,90 @@
1
+ import path from 'node:path';
2
+ import { enforcementUrl } from '../config/config.js';
3
+ import { debugLog } from '../core/logger.js';
4
+ import { ALLOW, ENFORCEMENT_CACHE_FILE_NAME } from './constants/enforcement.constants.js';
5
+ import { DecisionCache, decisionKey } from './decision-cache.js';
6
+ import { requestDecision } from './decision-client.js';
7
+ /**
8
+ * Whether this developer may start a turn right now.
9
+ *
10
+ * The single rule of this module: only an explicit `block` from the platform,
11
+ * carrying the sentence that explains it, is a refusal. Not configured, turned
12
+ * off, nobody to ask about, a timeout, a network error, any other status, a body
13
+ * this code cannot read — every one of them allows the turn. The check sits in
14
+ * front of every developer's tooling, so a check that failed closed would turn
15
+ * an alerts-service hiccup into an outage for a whole engineering organization.
16
+ *
17
+ * Never throws: a caller on the hook path has to answer the agent either way.
18
+ *
19
+ * @param options - Effective config, paths, the identity to ask about, clock.
20
+ * @returns The decision to act on.
21
+ */
22
+ export async function resolveEnforcement(options) {
23
+ const url = enforcementUrl(options.config);
24
+ const token = options.config.token;
25
+ const developerId = options.developerId;
26
+ // Nothing was asked, so nobody said no.
27
+ if (!options.config.enforcement.enabled || !url || !token || !developerId)
28
+ return ALLOW;
29
+ try {
30
+ return await decideThroughCache(options, url, token, developerId);
31
+ }
32
+ catch (error) {
33
+ debugLog('enforcement: check threw; allowing:', error);
34
+ return ALLOW;
35
+ }
36
+ }
37
+ /**
38
+ * The decision, from the local cache when it holds a live one.
39
+ *
40
+ * A miss asks the platform and stores whatever it answered. A *failure* is not
41
+ * stored: it is not a decision, and caching it as an allow would extend one
42
+ * unreachable moment across the whole TTL.
43
+ *
44
+ * @param options - As given to {@link resolveEnforcement}.
45
+ * @param url - The decision endpoint.
46
+ * @param token - Edge token.
47
+ * @param developerId - Identity to ask about.
48
+ * @returns The decision to act on.
49
+ */
50
+ async function decideThroughCache(options, url, token, developerId) {
51
+ const cache = new DecisionCache(path.join(options.paths.dataDir, ENFORCEMENT_CACHE_FILE_NAME), options.now);
52
+ const key = decisionKey(url, token, developerId);
53
+ const cached = await cache.read(key);
54
+ if (cached)
55
+ return cached;
56
+ const answered = await requestDecision({
57
+ url,
58
+ token,
59
+ developerId,
60
+ installationId: options.config.installationId,
61
+ timeoutMs: options.config.enforcement.timeoutMs,
62
+ fetchFn: options.fetchFn
63
+ });
64
+ if (!answered)
65
+ return ALLOW;
66
+ const { cacheTtlMs, ...decision } = answered;
67
+ await cache.write(key, decision, effectiveTtlMs(cacheTtlMs, options.config.enforcement.cacheTtlMs));
68
+ return decision;
69
+ }
70
+ /**
71
+ * How long this answer may be reused.
72
+ *
73
+ * The platform asks for a TTL because it is the side that knows how close the
74
+ * scope came to its cap; this side clamps it to what the machine's owner allowed
75
+ * and never above. So the platform can make an answer fresher — which is what a
76
+ * developer approaching a cap needs — and cannot make one last longer than the
77
+ * configured ceiling, which is what keeps the setting meaningful.
78
+ *
79
+ * No advice means the configured value, which is what a platform that predates
80
+ * the field produces.
81
+ *
82
+ * @param asked - What the platform asked for, if anything.
83
+ * @param configured - This machine's own TTL, and its ceiling.
84
+ * @returns The TTL to store the entry with.
85
+ */
86
+ function effectiveTtlMs(asked, configured) {
87
+ if (asked === undefined)
88
+ return configured;
89
+ return Math.min(asked, configured);
90
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * The pre-turn budget check: one question to the platform before a developer's
3
+ * agent starts a turn, and a refusal only when the platform explicitly says so.
4
+ *
5
+ * `resolveEnforcement` is the whole contract. The client, the cache and the
6
+ * validators are how it keeps that contract, not part of it; tests reach for
7
+ * them directly.
8
+ */
9
+ export { resolveEnforcement } from './enforcement.js';
10
+ export { DECISION_BLOCK, ENFORCEMENT_CACHE_FILE_NAME } from './constants/enforcement.constants.js';
11
+ export type { EnforcementDecision, EnforcementOptions } from './types/enforcement.types.js';
@@ -0,0 +1,10 @@
1
+ /**
2
+ * The pre-turn budget check: one question to the platform before a developer's
3
+ * agent starts a turn, and a refusal only when the platform explicitly says so.
4
+ *
5
+ * `resolveEnforcement` is the whole contract. The client, the cache and the
6
+ * validators are how it keeps that contract, not part of it; tests reach for
7
+ * them directly.
8
+ */
9
+ export { resolveEnforcement } from './enforcement.js';
10
+ export { DECISION_BLOCK, ENFORCEMENT_CACHE_FILE_NAME } from './constants/enforcement.constants.js';
@@ -0,0 +1,30 @@
1
+ import { z } from 'zod';
2
+ import type { CachedDecision, EnforcementDecision } from '../types/enforcement.types.js';
3
+ /**
4
+ * The two boundaries a decision crosses: the wire and the cache file.
5
+ *
6
+ * Both are parsed, never asserted. A refusal is the one thing this package
7
+ * produces that costs the developer their turn, so it may only ever come from a
8
+ * body that validates completely — a `block` with no message, an unknown
9
+ * decision, or a hand-edited cache entry has to read as "no answer", which the
10
+ * caller turns into an allow.
11
+ *
12
+ * Each schema is annotated with the vocabulary type it must produce: if the
13
+ * unions in `enforcement.types.ts` and these validators stop describing the same
14
+ * thing, this file stops compiling.
15
+ */
16
+ /** What the platform may answer. */
17
+ export declare const decisionSchema: z.ZodType<EnforcementDecision>;
18
+ /**
19
+ * The freshness the platform asked for, if it asked for anything usable.
20
+ *
21
+ * Its own schema, parsed on its own, and never combined with `decisionSchema`
22
+ * into one shape: an intersection would make a nonsense TTL invalidate the
23
+ * refusal beside it, so `{"decision":"block","message":"…","cache_ttl_ms":"bad"}`
24
+ * would read as no answer at all and allow the turn. The decision is the thing
25
+ * that costs a developer their turn; advice about how long to keep it is not
26
+ * allowed a vote on whether it is readable.
27
+ */
28
+ export declare const cacheTtlSchema: z.ZodNumber;
29
+ /** One cache entry: a decision plus the moment it stops being usable. */
30
+ export declare const cachedDecisionSchema: z.ZodType<CachedDecision>;
@@ -0,0 +1,36 @@
1
+ import { z } from 'zod';
2
+ import { DECISION_ALLOW, DECISION_BLOCK } from '../constants/enforcement.constants.js';
3
+ /**
4
+ * The two boundaries a decision crosses: the wire and the cache file.
5
+ *
6
+ * Both are parsed, never asserted. A refusal is the one thing this package
7
+ * produces that costs the developer their turn, so it may only ever come from a
8
+ * body that validates completely — a `block` with no message, an unknown
9
+ * decision, or a hand-edited cache entry has to read as "no answer", which the
10
+ * caller turns into an allow.
11
+ *
12
+ * Each schema is annotated with the vocabulary type it must produce: if the
13
+ * unions in `enforcement.types.ts` and these validators stop describing the same
14
+ * thing, this file stops compiling.
15
+ */
16
+ /** What the platform may answer. */
17
+ export const decisionSchema = z.discriminatedUnion('decision', [
18
+ z.object({ decision: z.literal(DECISION_ALLOW) }),
19
+ z.object({ decision: z.literal(DECISION_BLOCK), message: z.string().trim().min(1) })
20
+ ]);
21
+ /**
22
+ * The freshness the platform asked for, if it asked for anything usable.
23
+ *
24
+ * Its own schema, parsed on its own, and never combined with `decisionSchema`
25
+ * into one shape: an intersection would make a nonsense TTL invalidate the
26
+ * refusal beside it, so `{"decision":"block","message":"…","cache_ttl_ms":"bad"}`
27
+ * would read as no answer at all and allow the turn. The decision is the thing
28
+ * that costs a developer their turn; advice about how long to keep it is not
29
+ * allowed a vote on whether it is readable.
30
+ */
31
+ export const cacheTtlSchema = z.number().finite().nonnegative();
32
+ /** One cache entry: a decision plus the moment it stops being usable. */
33
+ export const cachedDecisionSchema = z.object({
34
+ decision: decisionSchema,
35
+ expiresAt: z.number().finite()
36
+ });