@agent-watch-ai/edge 0.2.5 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (346) hide show
  1. package/CHANGELOG.md +512 -0
  2. package/README.md +217 -96
  3. package/SECURITY.md +69 -0
  4. package/dist/billing/session-billing.d.ts +19 -0
  5. package/dist/billing/session-billing.js +52 -0
  6. package/dist/cli/args.d.ts +10 -0
  7. package/dist/cli/args.js +20 -0
  8. package/dist/cli/constants/cli.constants.d.ts +50 -4
  9. package/dist/cli/constants/cli.constants.js +54 -5
  10. package/dist/cli/context.d.ts +33 -2
  11. package/dist/cli/context.js +84 -14
  12. package/dist/cli/doctor.js +309 -32
  13. package/dist/cli/hook-check.d.ts +23 -0
  14. package/dist/cli/hook-check.js +114 -0
  15. package/dist/cli/hook.js +118 -7
  16. package/dist/cli/index.d.ts +3 -1
  17. package/dist/cli/index.js +3 -1
  18. package/dist/cli/misc.d.ts +11 -0
  19. package/dist/cli/misc.js +80 -4
  20. package/dist/cli/npx-install.d.ts +37 -0
  21. package/dist/cli/npx-install.js +79 -0
  22. package/dist/cli/open-browser.d.ts +39 -0
  23. package/dist/cli/open-browser.js +62 -0
  24. package/dist/cli/setup.d.ts +17 -8
  25. package/dist/cli/setup.js +439 -98
  26. package/dist/cli/status.js +82 -13
  27. package/dist/cli/toggle.d.ts +9 -0
  28. package/dist/cli/toggle.js +113 -0
  29. package/dist/cli/types/cli.types.d.ts +37 -3
  30. package/dist/cli/ui.d.ts +7 -0
  31. package/dist/cli/ui.js +10 -1
  32. package/dist/cli/uninstall.js +39 -2
  33. package/dist/cli/update.d.ts +17 -0
  34. package/dist/cli/update.js +76 -0
  35. package/dist/cli.js +100 -13
  36. package/dist/config/config-store.d.ts +57 -0
  37. package/dist/config/config-store.js +250 -12
  38. package/dist/config/config.d.ts +53 -6
  39. package/dist/config/config.js +66 -6
  40. package/dist/config/constants/config.constants.d.ts +113 -6
  41. package/dist/config/constants/config.constants.js +126 -8
  42. package/dist/config/destination.d.ts +24 -0
  43. package/dist/config/destination.js +33 -0
  44. package/dist/config/index.d.ts +7 -4
  45. package/dist/config/index.js +5 -3
  46. package/dist/config/repo-config.d.ts +11 -7
  47. package/dist/config/repo-config.js +64 -15
  48. package/dist/config/root-config.d.ts +72 -0
  49. package/dist/config/root-config.js +170 -0
  50. package/dist/config/schemas/config.schema.d.ts +721 -84
  51. package/dist/config/schemas/config.schema.js +388 -15
  52. package/dist/config/types/config.types.d.ts +15 -1
  53. package/dist/config/types/destination.types.d.ts +8 -0
  54. package/dist/core/async.d.ts +36 -0
  55. package/dist/core/async.js +68 -0
  56. package/dist/core/index.d.ts +1 -1
  57. package/dist/core/index.js +1 -1
  58. package/dist/core/object.d.ts +5 -0
  59. package/dist/core/object.js +9 -4
  60. package/dist/core/pipe.d.ts +0 -13
  61. package/dist/core/pipe.js +1 -9
  62. package/dist/core/types/core.types.d.ts +9 -0
  63. package/dist/core/types/core.types.js +0 -3
  64. package/dist/core/which.d.ts +14 -0
  65. package/dist/core/which.js +43 -3
  66. package/dist/credentials/budget.d.ts +9 -0
  67. package/dist/credentials/budget.js +16 -0
  68. package/dist/credentials/command-runner.d.ts +16 -0
  69. package/dist/credentials/command-runner.js +37 -0
  70. package/dist/credentials/constants/credentials.constants.d.ts +111 -0
  71. package/dist/credentials/constants/credentials.constants.js +112 -0
  72. package/dist/credentials/credential-status.d.ts +14 -0
  73. package/dist/credentials/credential-status.js +34 -0
  74. package/dist/credentials/credentials.d.ts +72 -0
  75. package/dist/credentials/credentials.js +253 -0
  76. package/dist/credentials/device-api.d.ts +64 -0
  77. package/dist/credentials/device-api.js +150 -0
  78. package/dist/credentials/device-state.d.ts +31 -0
  79. package/dist/credentials/device-state.js +51 -0
  80. package/dist/credentials/identity.d.ts +62 -0
  81. package/dist/credentials/identity.js +90 -0
  82. package/dist/credentials/index.d.ts +7 -0
  83. package/dist/credentials/index.js +5 -0
  84. package/dist/credentials/migration.d.ts +46 -0
  85. package/dist/credentials/migration.js +164 -0
  86. package/dist/credentials/schemas/device-api.schema.d.ts +77 -0
  87. package/dist/credentials/schemas/device-api.schema.js +33 -0
  88. package/dist/credentials/schemas/device-state.schema.d.ts +51 -0
  89. package/dist/credentials/schemas/device-state.schema.js +20 -0
  90. package/dist/credentials/secret-store.d.ts +54 -0
  91. package/dist/credentials/secret-store.js +217 -0
  92. package/dist/credentials/sign-in.d.ts +18 -0
  93. package/dist/credentials/sign-in.js +86 -0
  94. package/dist/credentials/token-refresher.d.ts +39 -0
  95. package/dist/credentials/token-refresher.js +185 -0
  96. package/dist/credentials/types/credentials.types.d.ts +195 -0
  97. package/dist/credentials/types/credentials.types.js +1 -0
  98. package/dist/enforcement/constants/enforcement.constants.d.ts +47 -1
  99. package/dist/enforcement/constants/enforcement.constants.js +56 -0
  100. package/dist/enforcement/decision-cache.d.ts +20 -1
  101. package/dist/enforcement/decision-cache.js +65 -2
  102. package/dist/enforcement/decision-client.d.ts +9 -8
  103. package/dist/enforcement/decision-client.js +62 -16
  104. package/dist/enforcement/enforcement.d.ts +23 -2
  105. package/dist/enforcement/enforcement.js +103 -15
  106. package/dist/enforcement/index.d.ts +4 -3
  107. package/dist/enforcement/index.js +3 -2
  108. package/dist/enforcement/types/enforcement.types.d.ts +64 -0
  109. package/dist/enrollment/constants/enrollment.constants.d.ts +2 -6
  110. package/dist/enrollment/constants/enrollment.constants.js +2 -6
  111. package/dist/enrollment/enrollment.d.ts +16 -0
  112. package/dist/enrollment/enrollment.js +54 -0
  113. package/dist/enrollment/index.d.ts +3 -7
  114. package/dist/enrollment/index.js +1 -1
  115. package/dist/enrollment/types/enrollment.types.d.ts +9 -13
  116. package/dist/events/constants/enrich.constants.d.ts +15 -0
  117. package/dist/events/constants/enrich.constants.js +15 -0
  118. package/dist/events/constants/events.constants.d.ts +6 -2
  119. package/dist/events/constants/events.constants.js +5 -1
  120. package/dist/events/enrich.js +92 -10
  121. package/dist/events/event-id.d.ts +0 -8
  122. package/dist/events/event-id.js +0 -10
  123. package/dist/events/index.d.ts +2 -2
  124. package/dist/events/index.js +1 -1
  125. package/dist/events/product-event.d.ts +9 -6
  126. package/dist/events/types/repo-snapshot.types.d.ts +7 -0
  127. package/dist/events/types/session-billing.types.d.ts +16 -0
  128. package/dist/events/types/session-billing.types.js +1 -0
  129. package/dist/feature/constants/feature.constants.d.ts +7 -0
  130. package/dist/feature/constants/feature.constants.js +7 -0
  131. package/dist/feature/index.d.ts +1 -1
  132. package/dist/feature/index.js +1 -1
  133. package/dist/feature/ticket-candidates.d.ts +14 -0
  134. package/dist/feature/ticket-candidates.js +26 -8
  135. package/dist/git/blob-hash.d.ts +21 -0
  136. package/dist/git/blob-hash.js +69 -0
  137. package/dist/git/checkout-root.d.ts +27 -0
  138. package/dist/git/checkout-root.js +75 -0
  139. package/dist/git/constants/git.constants.d.ts +160 -0
  140. package/dist/git/constants/git.constants.js +181 -0
  141. package/dist/git/fingerprint.d.ts +74 -0
  142. package/dist/git/fingerprint.js +219 -0
  143. package/dist/git/gate-checkout.d.ts +44 -0
  144. package/dist/git/gate-checkout.js +201 -0
  145. package/dist/git/git-context.d.ts +45 -0
  146. package/dist/git/git-context.js +61 -3
  147. package/dist/git/index.d.ts +4 -2
  148. package/dist/git/index.js +2 -1
  149. package/dist/git/manifest-repository.d.ts +13 -0
  150. package/dist/git/manifest-repository.js +92 -0
  151. package/dist/git/repo-snapshot.d.ts +29 -3
  152. package/dist/git/repo-snapshot.js +110 -7
  153. package/dist/git/repository-root.d.ts +39 -0
  154. package/dist/git/repository-root.js +131 -0
  155. package/dist/git/types/git.types.d.ts +55 -0
  156. package/dist/git/types/repository-root.types.d.ts +11 -0
  157. package/dist/git/types/repository-root.types.js +1 -0
  158. package/dist/git/types/snapshot.types.d.ts +9 -0
  159. package/dist/pipeline/constants/pipeline.constants.d.ts +7 -0
  160. package/dist/pipeline/constants/pipeline.constants.js +7 -0
  161. package/dist/pipeline/hook-pipeline.js +360 -32
  162. package/dist/pipeline/types/pipeline.types.d.ts +39 -4
  163. package/dist/privacy/constants/privacy.constants.js +15 -1
  164. package/dist/privacy/index.d.ts +1 -0
  165. package/dist/privacy/index.js +1 -0
  166. package/dist/privacy/product-capture.d.ts +12 -0
  167. package/dist/privacy/product-capture.js +73 -0
  168. package/dist/privacy/sanitizer.d.ts +21 -3
  169. package/dist/privacy/sanitizer.js +52 -8
  170. package/dist/process/ancestors.d.ts +39 -0
  171. package/dist/process/ancestors.js +121 -0
  172. package/dist/process/constants/process.constants.d.ts +34 -0
  173. package/dist/process/constants/process.constants.js +34 -0
  174. package/dist/process/index.d.ts +7 -0
  175. package/dist/process/index.js +2 -0
  176. package/dist/process/types/process.types.d.ts +23 -0
  177. package/dist/process/types/process.types.js +1 -0
  178. package/dist/providers/antigravity/antigravity.adapter.d.ts +12 -1
  179. package/dist/providers/antigravity/antigravity.adapter.js +21 -3
  180. package/dist/providers/antigravity/antigravity.detect.d.ts +0 -9
  181. package/dist/providers/antigravity/antigravity.detect.js +1 -1
  182. package/dist/providers/antigravity/antigravity.provider.js +3 -2
  183. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +2 -0
  184. package/dist/providers/antigravity/constants/antigravity.constants.js +2 -0
  185. package/dist/providers/claude/claude.adapter.d.ts +11 -1
  186. package/dist/providers/claude/claude.adapter.js +26 -5
  187. package/dist/providers/claude/claude.otel.d.ts +32 -18
  188. package/dist/providers/claude/claude.otel.js +81 -6
  189. package/dist/providers/claude/claude.provider.js +5 -2
  190. package/dist/providers/claude/constants/claude.constants.d.ts +2 -0
  191. package/dist/providers/claude/constants/claude.constants.js +2 -0
  192. package/dist/providers/claude/constants/claude.otel.constants.d.ts +4 -0
  193. package/dist/providers/claude/constants/claude.otel.constants.js +8 -0
  194. package/dist/providers/codex/codex.adapter.d.ts +15 -1
  195. package/dist/providers/codex/codex.adapter.js +29 -5
  196. package/dist/providers/codex/codex.otel.d.ts +24 -2
  197. package/dist/providers/codex/codex.otel.js +147 -30
  198. package/dist/providers/codex/codex.provider.js +5 -2
  199. package/dist/providers/codex/constants/codex.constants.d.ts +2 -0
  200. package/dist/providers/codex/constants/codex.constants.js +16 -0
  201. package/dist/providers/codex/constants/codex.otel.constants.d.ts +5 -0
  202. package/dist/providers/codex/constants/codex.otel.constants.js +5 -0
  203. package/dist/providers/constants/provider.constants.d.ts +0 -3
  204. package/dist/providers/constants/provider.constants.js +0 -3
  205. package/dist/providers/cursor/constants/cursor.constants.d.ts +7 -0
  206. package/dist/providers/cursor/constants/cursor.constants.js +7 -0
  207. package/dist/providers/cursor/cursor.adapter.d.ts +33 -1
  208. package/dist/providers/cursor/cursor.adapter.js +52 -3
  209. package/dist/providers/cursor/cursor.detect.d.ts +0 -7
  210. package/dist/providers/cursor/cursor.detect.js +1 -1
  211. package/dist/providers/cursor/cursor.provider.js +5 -2
  212. package/dist/providers/gemini/constants/gemini.constants.d.ts +9 -0
  213. package/dist/providers/gemini/constants/gemini.constants.js +9 -0
  214. package/dist/providers/gemini/constants/gemini.otel.constants.d.ts +3 -1
  215. package/dist/providers/gemini/constants/gemini.otel.constants.js +3 -0
  216. package/dist/providers/gemini/gemini.adapter.d.ts +14 -1
  217. package/dist/providers/gemini/gemini.adapter.js +25 -5
  218. package/dist/providers/gemini/gemini.detect.d.ts +0 -7
  219. package/dist/providers/gemini/gemini.detect.js +1 -1
  220. package/dist/providers/gemini/gemini.otel.d.ts +19 -20
  221. package/dist/providers/gemini/gemini.otel.js +121 -17
  222. package/dist/providers/gemini/gemini.provider.js +2 -1
  223. package/dist/providers/index.d.ts +1 -1
  224. package/dist/providers/index.js +1 -1
  225. package/dist/providers/loaders.d.ts +10 -0
  226. package/dist/providers/loaders.js +40 -0
  227. package/dist/providers/provider.d.ts +11 -0
  228. package/dist/providers/provider.js +1 -1
  229. package/dist/providers/registry.d.ts +11 -8
  230. package/dist/providers/registry.js +11 -15
  231. package/dist/providers/shared/constants/hook-refusal.constants.d.ts +7 -0
  232. package/dist/providers/shared/constants/hook-refusal.constants.js +7 -0
  233. package/dist/providers/shared/constants/shell-directories.constants.d.ts +30 -0
  234. package/dist/providers/shared/constants/shell-directories.constants.js +39 -0
  235. package/dist/providers/shared/constants/tooling.constants.d.ts +18 -2
  236. package/dist/providers/shared/constants/tooling.constants.js +19 -3
  237. package/dist/providers/shared/event-builder.d.ts +12 -14
  238. package/dist/providers/shared/event-builder.js +20 -14
  239. package/dist/providers/shared/exporter-allowlist.d.ts +20 -0
  240. package/dist/providers/shared/exporter-allowlist.js +49 -0
  241. package/dist/providers/shared/hook-config.d.ts +2 -21
  242. package/dist/providers/shared/hook-config.js +5 -4
  243. package/dist/providers/shared/hook-refusal.d.ts +12 -0
  244. package/dist/providers/shared/hook-refusal.js +17 -1
  245. package/dist/providers/shared/install-record.d.ts +12 -2
  246. package/dist/providers/shared/install-record.js +5 -2
  247. package/dist/providers/shared/shell-directories.d.ts +24 -0
  248. package/dist/providers/shared/shell-directories.js +90 -0
  249. package/dist/providers/shared/tooling.d.ts +12 -1
  250. package/dist/providers/shared/tooling.js +18 -0
  251. package/dist/providers/shared/types/adapter.types.d.ts +1 -2
  252. package/dist/providers/types/provider.types.d.ts +57 -1
  253. package/dist/snapshot/constants/snapshot.constants.d.ts +32 -0
  254. package/dist/snapshot/constants/snapshot.constants.js +33 -0
  255. package/dist/snapshot/snapshot-event.js +52 -11
  256. package/dist/snapshot/snapshot-pipeline.js +1 -1
  257. package/dist/snapshot/types/snapshot.types.d.ts +2 -0
  258. package/dist/storage/atomic-file.d.ts +7 -0
  259. package/dist/storage/atomic-file.js +1 -1
  260. package/dist/storage/constants/storage.constants.d.ts +17 -0
  261. package/dist/storage/constants/storage.constants.js +17 -0
  262. package/dist/storage/disabled.d.ts +13 -0
  263. package/dist/storage/disabled.js +24 -0
  264. package/dist/storage/index.d.ts +2 -0
  265. package/dist/storage/index.js +2 -0
  266. package/dist/storage/paths.js +3 -2
  267. package/dist/storage/schemas/storage.schema.d.ts +72 -0
  268. package/dist/storage/schemas/storage.schema.js +6 -0
  269. package/dist/storage/sweep-marker.d.ts +19 -0
  270. package/dist/storage/sweep-marker.js +55 -0
  271. package/dist/storage/types/storage.types.d.ts +2 -0
  272. package/dist/storage/uninstalled.d.ts +58 -0
  273. package/dist/storage/uninstalled.js +107 -0
  274. package/dist/transport/auth-block.d.ts +66 -0
  275. package/dist/transport/auth-block.js +129 -0
  276. package/dist/transport/constants/transport.constants.d.ts +82 -3
  277. package/dist/transport/constants/transport.constants.js +83 -4
  278. package/dist/transport/cooldown.js +8 -1
  279. package/dist/transport/delivery.d.ts +14 -6
  280. package/dist/transport/delivery.js +80 -55
  281. package/dist/transport/http-transport.d.ts +1 -0
  282. package/dist/transport/http-transport.js +52 -10
  283. package/dist/transport/index.d.ts +6 -3
  284. package/dist/transport/index.js +3 -0
  285. package/dist/transport/queue-partition.d.ts +91 -0
  286. package/dist/transport/queue-partition.js +143 -0
  287. package/dist/transport/queue.d.ts +99 -20
  288. package/dist/transport/queue.js +210 -69
  289. package/dist/transport/response-body.d.ts +25 -0
  290. package/dist/transport/response-body.js +64 -0
  291. package/dist/transport/send.d.ts +11 -0
  292. package/dist/transport/send.js +17 -0
  293. package/dist/transport/types/delivery-flow.types.d.ts +19 -0
  294. package/dist/transport/types/delivery-flow.types.js +1 -0
  295. package/dist/transport/types/transport.types.d.ts +45 -0
  296. package/dist/turns/claude-transcript.d.ts +19 -1
  297. package/dist/turns/claude-transcript.js +46 -1
  298. package/dist/turns/codex-originator.d.ts +11 -0
  299. package/dist/turns/codex-originator.js +31 -0
  300. package/dist/turns/codex-transcript.d.ts +30 -0
  301. package/dist/turns/codex-transcript.js +88 -0
  302. package/dist/turns/constants/turns.constants.d.ts +141 -5
  303. package/dist/turns/constants/turns.constants.js +155 -5
  304. package/dist/turns/file-identity.d.ts +27 -0
  305. package/dist/turns/file-identity.js +48 -0
  306. package/dist/turns/gemini-transcript.d.ts +30 -0
  307. package/dist/turns/gemini-transcript.js +96 -0
  308. package/dist/turns/index.d.ts +3 -3
  309. package/dist/turns/index.js +1 -1
  310. package/dist/turns/inherited-checkout.d.ts +54 -0
  311. package/dist/turns/inherited-checkout.js +155 -0
  312. package/dist/turns/native-session-titles.d.ts +26 -0
  313. package/dist/turns/native-session-titles.js +102 -0
  314. package/dist/turns/transcript.d.ts +3 -2
  315. package/dist/turns/transcript.js +5 -1
  316. package/dist/turns/turn-state.d.ts +224 -3
  317. package/dist/turns/turn-state.js +456 -21
  318. package/dist/turns/turn-summary.d.ts +1 -14
  319. package/dist/turns/turn-summary.js +87 -51
  320. package/dist/turns/turn-tracker.d.ts +21 -2
  321. package/dist/turns/turn-tracker.js +379 -56
  322. package/dist/turns/types/transcript.types.d.ts +5 -0
  323. package/dist/turns/types/turn-state.types.d.ts +116 -5
  324. package/dist/turns/types/turn-summary.types.d.ts +64 -14
  325. package/dist/turns/types/turn-tracker.types.d.ts +27 -1
  326. package/dist/turns/work-checkout.d.ts +65 -0
  327. package/dist/turns/work-checkout.js +666 -0
  328. package/dist/untraced/constants/untraced.constants.d.ts +31 -0
  329. package/dist/untraced/constants/untraced.constants.js +63 -0
  330. package/dist/untraced/untraced.d.ts +35 -0
  331. package/dist/untraced/untraced.js +105 -0
  332. package/dist/update/constants/update.constants.d.ts +18 -0
  333. package/dist/update/constants/update.constants.js +20 -0
  334. package/dist/update/update-check.d.ts +52 -0
  335. package/dist/update/update-check.js +113 -0
  336. package/docs/AUDIT_PROMPT.md +129 -0
  337. package/docs/DATA_HANDLING.md +648 -0
  338. package/docs/ENTERPRISE_DEPLOYMENT.md +179 -0
  339. package/docs/PERFORMANCE.md +81 -0
  340. package/package.json +14 -4
  341. package/dist/enrollment/enrollment-provider.d.ts +0 -5
  342. package/dist/enrollment/manual-enrollment.d.ts +0 -32
  343. package/dist/enrollment/manual-enrollment.js +0 -72
  344. package/example/README.md +0 -43
  345. package/example/server.mjs +0 -240
  346. /package/dist/{enrollment/enrollment-provider.js → config/types/destination.types.js} +0 -0
@@ -1,10 +1,11 @@
1
1
  import path from 'node:path';
2
2
  import { isRecord } from '../core/object.js';
3
3
  import { collectGitContext } from '../git/git-context.js';
4
+ import { checkoutOf } from '../git/checkout-root.js';
4
5
  import { featureCandidatesFromBranch } from '../feature/ticket-candidates.js';
5
6
  import { sanitizeValue } from '../privacy/sanitizer.js';
6
7
  import { TURN_CLOSING_EVENT_TYPE } from './constants/events.constants.js';
7
- import { FILE_PATH_METADATA_KEY, HOME_PLACEHOLDER, HOME_PLACEHOLDER_PREFIX, PATH_BOUNDARY_LOOKAHEAD, REPO_ROOT_PLACEHOLDER, RE_REGEXP_METACHARACTERS } from './constants/enrich.constants.js';
8
+ import { FILE_PATH_METADATA_KEY, HOME_PLACEHOLDER, HOME_PLACEHOLDER_PREFIX, EMPTY_REPOSITORIES, EXTERNAL_PATH_METADATA_KEY, PATH_BOUNDARY_LOOKAHEAD, REPO_ROOT_PLACEHOLDER, REPOSITORY_PATH_METADATA_KEY, RE_REGEXP_METACHARACTERS } from './constants/enrich.constants.js';
8
9
  /**
9
10
  * Attach development context to canonical events and scrub them.
10
11
  *
@@ -23,18 +24,19 @@ export async function enrichEvents(events, options) {
23
24
  const git = await resolveGitContext(events, options);
24
25
  const featureCandidates = featureCandidatesFromBranch(git.branch);
25
26
  const rewriter = buildPathRewriter(git.repositoryRoot, options.home);
27
+ const repositories = await resolveFileRepositories(events, options);
26
28
  const enriched = [];
27
29
  for (const event of events) {
28
- enriched.push(sanitizeValue(enrichEvent(event, { git, featureCandidates, rewriter, options })));
30
+ enriched.push(sanitizeValue(enrichEvent(event, { git, featureCandidates, rewriter, repositories, options })));
29
31
  }
30
32
  return enriched;
31
33
  }
32
34
  /**
33
35
  * Repository context for this batch, at the cheapest sufficient depth.
34
36
  *
35
- * Full context (branch, commit, remote, status) costs up to five git processes
36
- * and is only consumed when a turn closes — the summary reads it off the Stop
37
- * event. Every other hook runs on the agent's critical path, often once per
37
+ * Full context (branch, commit, remote) costs up to four git processes and is
38
+ * only consumed when a turn closes — the summary falls back to it when the turn
39
+ * named no checkout of its own. Every other hook runs on the agent's critical path, often once per
38
40
  * tool call, and needs nothing but the repository root for path rewriting.
39
41
  *
40
42
  * @param events - The batch being enriched.
@@ -48,7 +50,9 @@ async function resolveGitContext(events, options) {
48
50
  try {
49
51
  return await collectGitContext({
50
52
  cwd: options.cwd,
51
- includeChangedFiles: options.config.capture.files && needsFullGit,
53
+ // Never the folder's whole dirty tree: a turn reports the files it
54
+ // changed, and those come from the tracker's fingerprints.
55
+ includeChangedFiles: false,
52
56
  timeoutMs: options.gitTimeoutMs,
53
57
  rootOnly: !needsFullGit
54
58
  });
@@ -57,6 +61,36 @@ async function resolveGitContext(events, options) {
57
61
  return {};
58
62
  }
59
63
  }
64
+ /**
65
+ * The checkout each file of this batch lies in, wherever that is.
66
+ *
67
+ * A file's path is reported relative to its own checkout, and the turn tracker
68
+ * keeps that checkout's root beside it: which checkout the turn worked in is
69
+ * decided when it closes, against the tenant and the start folder, so nothing
70
+ * is refused here — only placed. A session started inside one repository finds
71
+ * that repository for its own files, exactly as before.
72
+ *
73
+ * Resolved up front, for the batch, so enriching one event stays synchronous.
74
+ * The walk is `stat` calls only: no tool hook pays a git process for it.
75
+ *
76
+ * @param events - The batch being enriched.
77
+ * @param options - Effective config and working directory.
78
+ * @returns Absolute file path → its checkout root; empty when git capture is off.
79
+ */
80
+ async function resolveFileRepositories(events, options) {
81
+ if (!options.config.capture.git)
82
+ return EMPTY_REPOSITORIES;
83
+ const roots = new Map();
84
+ for (const event of events) {
85
+ const filePath = event.metadata?.[FILE_PATH_METADATA_KEY];
86
+ if (typeof filePath !== 'string' || !path.isAbsolute(filePath) || roots.has(filePath))
87
+ continue;
88
+ const checkout = await checkoutOf(filePath).catch(() => undefined);
89
+ if (checkout)
90
+ roots.set(filePath, checkout);
91
+ }
92
+ return roots;
93
+ }
60
94
  /**
61
95
  * One event with development context attached.
62
96
  *
@@ -98,11 +132,37 @@ function enrichMetadata(metadata, context) {
98
132
  if (!metadata)
99
133
  return undefined;
100
134
  const filePath = metadata[FILE_PATH_METADATA_KEY];
101
- const withSafePath = typeof filePath === 'string'
102
- ? { ...metadata, [FILE_PATH_METADATA_KEY]: toSafePath(filePath, context.git.repositoryRoot) }
103
- : metadata;
135
+ const withSafePath = typeof filePath === 'string' ? { ...metadata, ...pathFields(filePath, context) } : metadata;
104
136
  return rewritePathsDeep(withSafePath, context.rewriter);
105
137
  }
138
+ /**
139
+ * The path fields for one tool call: the safe path, plus which checkout it is
140
+ * relative to when it lies in one.
141
+ *
142
+ * @param filePath - Absolute path from a tool payload.
143
+ * @param context - Batch-wide resolved context.
144
+ * @returns The metadata fields to overwrite.
145
+ */
146
+ function pathFields(filePath, context) {
147
+ const checkout = context.repositories.get(filePath);
148
+ if (!checkout) {
149
+ // With git capture off no checkout was resolved, so in-repo files land here
150
+ // too and would ship the repository's layout. ponytail: such a machine sends
151
+ // no external paths at all; telling them apart would cost the git lookups the
152
+ // flag turned off.
153
+ const external = context.options.config.capture.git ? externalPath(filePath, context.git.repositoryRoot, context.options.home) : undefined;
154
+ const fields = { [FILE_PATH_METADATA_KEY]: toSafePath(filePath, context.git.repositoryRoot) };
155
+ return external ? { ...fields, [EXTERNAL_PATH_METADATA_KEY]: external } : fields;
156
+ }
157
+ const { root, relative } = checkout;
158
+ return {
159
+ [FILE_PATH_METADATA_KEY]: relative,
160
+ // Relative, never absolute: the machine's layout is not the product's
161
+ // business. The turn tracker anchors it to this same hook's cwd when it
162
+ // records the call, because the next hook's cwd may not be this one.
163
+ [REPOSITORY_PATH_METADATA_KEY]: relativize(context.options.cwd, root)
164
+ };
165
+ }
106
166
  /**
107
167
  * Pre-compile the path substitutions for one enrichment pass.
108
168
  *
@@ -205,6 +265,28 @@ function relativize(root, target) {
205
265
  const relative = path.relative(root, target);
206
266
  return relative === '' ? REPO_ROOT_PLACEHOLDER : relative;
207
267
  }
268
+ /**
269
+ * Where a file outside every checkout lies, without the home directory's name.
270
+ *
271
+ * A spreadsheet in `~/Documents` is the target of a session with no repository,
272
+ * so it is kept — but as `~/Documents/a.xlsx`: the home directory names the
273
+ * person. A path outside home is kept as it is; with no home to compare against
274
+ * nothing is kept, since the path could be the home itself.
275
+ *
276
+ * @param filePath - Path from a tool payload.
277
+ * @param repositoryRoot - The hook's repository root, when inside one.
278
+ * @param home - Developer home directory, when known.
279
+ * @returns The path to send, or undefined when the file is in the repository or unplaceable.
280
+ */
281
+ function externalPath(filePath, repositoryRoot, home) {
282
+ if (!home || !path.isAbsolute(filePath) || (repositoryRoot && isInside(repositoryRoot, filePath)))
283
+ return undefined;
284
+ return isInside(home, filePath) ? HOME_PLACEHOLDER_PREFIX + path.relative(home, filePath) : filePath;
285
+ }
286
+ function isInside(root, filePath) {
287
+ const relative = path.relative(root, filePath);
288
+ return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
289
+ }
208
290
  /**
209
291
  * A file path safe to transmit: repo-relative inside the repository, bare
210
292
  * basename outside it.
@@ -220,7 +302,7 @@ function toSafePath(filePath, repositoryRoot) {
220
302
  if (!repositoryRoot)
221
303
  return path.basename(filePath);
222
304
  const relative = path.relative(repositoryRoot, filePath);
223
- if (relative.startsWith('..') || path.isAbsolute(relative))
305
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
224
306
  return path.basename(filePath);
225
307
  return relative;
226
308
  }
@@ -12,14 +12,6 @@ export type { EventIdInput } from './types/events.types.js';
12
12
  * @returns The `evt_`-prefixed id.
13
13
  */
14
14
  export declare function deriveEventId(input: EventIdInput): string;
15
- /**
16
- * Event id built from an id the provider already guarantees to be unique.
17
- *
18
- * @param provider - Internal provider id, which scopes the namespace.
19
- * @param rawId - The provider's own identifier.
20
- * @returns The namespaced event id.
21
- */
22
- export declare function providerEventId(provider: string, rawId: string): string;
23
15
  /**
24
16
  * SHA-256 of a string, hex encoded.
25
17
  *
@@ -25,16 +25,6 @@ export function deriveEventId(input) {
25
25
  ]);
26
26
  return EVENT_ID_PREFIX + sha256Hex(canonical).slice(0, EVENT_ID_HEX_LENGTH);
27
27
  }
28
- /**
29
- * Event id built from an id the provider already guarantees to be unique.
30
- *
31
- * @param provider - Internal provider id, which scopes the namespace.
32
- * @param rawId - The provider's own identifier.
33
- * @returns The namespaced event id.
34
- */
35
- export function providerEventId(provider, rawId) {
36
- return `${EVENT_ID_PREFIX}${provider}_${rawId}`;
37
- }
38
28
  /**
39
29
  * SHA-256 of a string, hex encoded.
40
30
  *
@@ -4,11 +4,11 @@
4
4
  */
5
5
  export type { AgentWatchEvent, CanonicalEventType, ContentEvidence, EventAi, EventGit, EventIdInput, EventPatch, EventSession, EventTool, EventUsage, FeatureCandidate, InternalHookEventType, ProductEventType, UsageBillingMode, UsageSource } from './types/events.types.js';
6
6
  export type { BuildLlmCallInput, LlmCallCorrelation, LlmCallEvent, LlmCallStatus, LlmCallUsage } from './types/llm-call.types.js';
7
- export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
7
+ export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotCommitFile, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
8
8
  export type { EnrichOptions, PathRewriter, PathRule } from './types/enrich.types.js';
9
9
  export type { ProductEvent } from './product-event.js';
10
10
  export { CANONICAL_EVENT_TYPES, EVENT_SCHEMA_VERSION, INTERNAL_HOOK_EVENT_TYPES, PRODUCT_EVENT_TYPES, PRODUCT_EVENT_TYPE_SET, TURN_CLOSING_EVENT_TYPE } from './constants/events.constants.js';
11
- export { deriveEventId, providerEventId, sha256Hex } from './event-id.js';
11
+ export { deriveEventId, sha256Hex } from './event-id.js';
12
12
  export { buildLlmCall } from './llm-call.js';
13
13
  export { isProductEvent } from './product-event.js';
14
14
  export { enrichEvents } from './enrich.js';
@@ -1,5 +1,5 @@
1
1
  export { CANONICAL_EVENT_TYPES, EVENT_SCHEMA_VERSION, INTERNAL_HOOK_EVENT_TYPES, PRODUCT_EVENT_TYPES, PRODUCT_EVENT_TYPE_SET, TURN_CLOSING_EVENT_TYPE } from './constants/events.constants.js';
2
- export { deriveEventId, providerEventId, sha256Hex } from './event-id.js';
2
+ export { deriveEventId, sha256Hex } from './event-id.js';
3
3
  export { buildLlmCall } from './llm-call.js';
4
4
  export { isProductEvent } from './product-event.js';
5
5
  export { enrichEvents } from './enrich.js';
@@ -1,21 +1,24 @@
1
+ import type { TurnSummaryEvent } from '../turns/types/turn-summary.types.js';
1
2
  import type { LlmCallEvent } from './types/llm-call.types.js';
2
3
  import type { RepoSnapshotEvent } from './types/repo-snapshot.types.js';
3
- import type { TurnSummaryEvent } from '../turns/types/turn-summary.types.js';
4
+ import type { SessionBillingEvent } from './types/session-billing.types.js';
4
5
  export { PRODUCT_EVENT_TYPES } from './constants/events.constants.js';
5
6
  export type { ProductEventType } from './types/events.types.js';
6
7
  export type { LlmCallEvent, LlmCallCorrelation, LlmCallStatus } from './types/llm-call.types.js';
7
- export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
8
+ export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotCommitFile, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
9
+ export type { SessionBillingEvent } from './types/session-billing.types.js';
8
10
  export type { AgentUsageSummary, TurnSummaryEvent, TurnUsageStatus } from '../turns/types/turn-summary.types.js';
9
11
  /**
10
12
  * The complete public AgentWatch domain contract.
11
13
  *
12
- * Three record types, deliberately: `llm.call` is the lossless per-request
13
- * usage ledger, `turn.summary` is the human unit of work, and `repo.snapshot`
14
- * is what the working copy says the work *is* when no tracker can be asked. No
14
+ * Four record types, deliberately: `llm.call` is the lossless per-request
15
+ * usage ledger, `turn.summary` is the human unit of work, `repo.snapshot`
16
+ * is what the working copy says the work *is* when no tracker can be asked, and
17
+ * `session.billing` is how the session's developer pays. No
15
18
  * lifecycle or tool event is public — those exist only to assemble a summary
16
19
  * locally.
17
20
  */
18
- export type ProductEvent = LlmCallEvent | TurnSummaryEvent | RepoSnapshotEvent;
21
+ export type ProductEvent = LlmCallEvent | TurnSummaryEvent | RepoSnapshotEvent | SessionBillingEvent;
19
22
  /** The least a value must look like for {@link isProductEvent} to judge it. */
20
23
  export interface EventTypeCarrier {
21
24
  readonly event?: {
@@ -1,9 +1,16 @@
1
1
  import type { AgentWatchEvent } from './events.types.js';
2
+ /** One file a commit changed: the path from the repository root, and git's name-status letter. */
3
+ export interface RepoSnapshotCommitFile {
4
+ readonly path: string;
5
+ readonly status: string;
6
+ }
2
7
  /** One commit of a branch's delta, as the backend receives it. */
3
8
  export interface RepoSnapshotCommit {
4
9
  readonly sha: string;
5
10
  readonly subject: string;
6
11
  readonly authored_at?: string;
12
+ /** Names only, never contents. Absent when the listing failed or ran out of time. */
13
+ readonly files?: readonly RepoSnapshotCommitFile[];
7
14
  }
8
15
  /** One branch of a snapshot, with the commits that are its own. */
9
16
  export interface RepoSnapshotBranch {
@@ -0,0 +1,16 @@
1
+ import type { AgentWatchEvent } from './events.types.js';
2
+ /**
3
+ * How the developer pays for one session, stated once when it opens.
4
+ *
5
+ * The fourth product record. A turn summary carries the same fact, but only a
6
+ * turn that reaches its Stop hook produces one; a session killed mid-turn,
7
+ * interrupted or compacted would otherwise leave its calls with no mode, and a
8
+ * call with no mode is priced as metered. Never sent for `unknown`: the
9
+ * backend takes the absence of a fact as not knowing.
10
+ */
11
+ export interface SessionBillingEvent extends AgentWatchEvent<'session.billing'> {
12
+ readonly provider: string;
13
+ readonly surface: string;
14
+ readonly session_id: string;
15
+ readonly billing_mode: 'api' | 'subscription';
16
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -8,3 +8,10 @@
8
8
  export declare const RE_TICKET_KEY: RegExp;
9
9
  /** Where a candidate was found; carried on the event as provenance. */
10
10
  export declare const BRANCH_EVIDENCE_SOURCE = "git.branch";
11
+ /**
12
+ * Most ticket keys one branch name or one prompt contributes. Matches core's
13
+ * `MAX_TICKET_KEYS`, the turn summary contract's bound on `jira_ids` and
14
+ * `prompt_jira_ids`; a pasted backlog past that would get the whole summary
15
+ * refused.
16
+ */
17
+ export declare const MAX_TICKET_KEYS = 50;
@@ -8,3 +8,10 @@
8
8
  export const RE_TICKET_KEY = /\b([A-Z][A-Z0-9]{1,9}-\d{1,6})\b/g;
9
9
  /** Where a candidate was found; carried on the event as provenance. */
10
10
  export const BRANCH_EVIDENCE_SOURCE = 'git.branch';
11
+ /**
12
+ * Most ticket keys one branch name or one prompt contributes. Matches core's
13
+ * `MAX_TICKET_KEYS`, the turn summary contract's bound on `jira_ids` and
14
+ * `prompt_jira_ids`; a pasted backlog past that would get the whole summary
15
+ * refused.
16
+ */
17
+ export const MAX_TICKET_KEYS = 50;
@@ -3,4 +3,4 @@
3
3
  * piece of work a turn belongs to. Attribution itself happens in the backend.
4
4
  */
5
5
  export { RE_TICKET_KEY } from './constants/feature.constants.js';
6
- export { featureCandidatesFromBranch } from './ticket-candidates.js';
6
+ export { featureCandidatesFromBranch, ticketKeysInText } from './ticket-candidates.js';
@@ -3,4 +3,4 @@
3
3
  * piece of work a turn belongs to. Attribution itself happens in the backend.
4
4
  */
5
5
  export { RE_TICKET_KEY } from './constants/feature.constants.js';
6
- export { featureCandidatesFromBranch } from './ticket-candidates.js';
6
+ export { featureCandidatesFromBranch, ticketKeysInText } from './ticket-candidates.js';
@@ -11,3 +11,17 @@ import type { FeatureCandidate } from '../events/canonical-event.js';
11
11
  * @returns Ticket candidates, empty when the branch names none.
12
12
  */
13
13
  export declare function featureCandidatesFromBranch(branch: string | undefined): FeatureCandidate[];
14
+ /**
15
+ * Ticket keys a prompt names, and nothing else of it.
16
+ *
17
+ * The key is the one part of a prompt that may leave the machine without
18
+ * consent. A prompt is free text, so an invoice number matches this syntax as
19
+ * well as a ticket does; the edge sends every candidate unfiltered and the
20
+ * platform keeps only keys it knows. Same syntax as the branch rule, so a key
21
+ * means the same thing wherever it was found. The order named is kept because
22
+ * the backend takes the first key it knows.
23
+ *
24
+ * @param text - Prompt text, harness blocks already removed.
25
+ * @returns Keys in order of first appearance, deduped, at most `MAX_TICKET_KEYS`.
26
+ */
27
+ export declare function ticketKeysInText(text: string): readonly string[];
@@ -1,4 +1,4 @@
1
- import { BRANCH_EVIDENCE_SOURCE, RE_TICKET_KEY } from './constants/feature.constants.js';
1
+ import { BRANCH_EVIDENCE_SOURCE, MAX_TICKET_KEYS, RE_TICKET_KEY } from './constants/feature.constants.js';
2
2
  /**
3
3
  * Extract feature-correlation *evidence* (Jira/Linear ticket keys) from a
4
4
  * branch name.
@@ -13,14 +13,32 @@ import { BRANCH_EVIDENCE_SOURCE, RE_TICKET_KEY } from './constants/feature.const
13
13
  export function featureCandidatesFromBranch(branch) {
14
14
  if (!branch)
15
15
  return [];
16
- const candidates = [];
16
+ return ticketKeysInText(branch).map((key) => ({ type: 'ticket', value: key, source: BRANCH_EVIDENCE_SOURCE }));
17
+ }
18
+ /**
19
+ * Ticket keys a prompt names, and nothing else of it.
20
+ *
21
+ * The key is the one part of a prompt that may leave the machine without
22
+ * consent. A prompt is free text, so an invoice number matches this syntax as
23
+ * well as a ticket does; the edge sends every candidate unfiltered and the
24
+ * platform keeps only keys it knows. Same syntax as the branch rule, so a key
25
+ * means the same thing wherever it was found. The order named is kept because
26
+ * the backend takes the first key it knows.
27
+ *
28
+ * @param text - Prompt text, harness blocks already removed.
29
+ * @returns Keys in order of first appearance, deduped, at most `MAX_TICKET_KEYS`.
30
+ */
31
+ export function ticketKeysInText(text) {
32
+ const keys = [];
17
33
  const seen = new Set();
18
- for (const match of branch.matchAll(RE_TICKET_KEY)) {
19
- const ticket = match[1];
20
- if (!ticket || seen.has(ticket))
34
+ for (const match of text.matchAll(RE_TICKET_KEY)) {
35
+ if (keys.length === MAX_TICKET_KEYS)
36
+ break;
37
+ const key = match[1];
38
+ if (!key || seen.has(key))
21
39
  continue;
22
- seen.add(ticket);
23
- candidates.push({ type: 'ticket', value: ticket, source: BRANCH_EVIDENCE_SOURCE });
40
+ seen.add(key);
41
+ keys.push(key);
24
42
  }
25
- return candidates;
43
+ return keys;
26
44
  }
@@ -0,0 +1,21 @@
1
+ import type { ContentHash } from './types/git.types.js';
2
+ /**
3
+ * Git's blob id for some bytes: sha1 over `blob <byte length>\0` and the bytes.
4
+ * The length is bytes, not characters: "é" is one character and two bytes.
5
+ *
6
+ * @param bytes - The file's bytes.
7
+ * @returns 40 hex characters, equal to `git hash-object` for the same file.
8
+ */
9
+ export declare function blobSha(bytes: Buffer): string;
10
+ /**
11
+ * One-way content ids of the files a turn's tools named, in a folder with no git.
12
+ *
13
+ * Reads only the named files, in memory, and keeps nothing but the id: no
14
+ * content reaches an event, a log or the queue. Fails open per file.
15
+ *
16
+ * @param files - Absolute paths, in priority order (edits first, then reads).
17
+ * @param root - The session folder; paths are reported relative to it.
18
+ * @param budgetMs - Time allowed; the files not reached by then are skipped.
19
+ * @returns Up to MAX_CONTENT_HASHES `{path, blob_sha}`; unreadable, oversized or outside-root files are skipped.
20
+ */
21
+ export declare function contentHashes(files: readonly string[], root: string, budgetMs?: number): Promise<ContentHash[]>;
@@ -0,0 +1,69 @@
1
+ import { createHash } from 'node:crypto';
2
+ import fs from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import { withinBudget } from '../core/async.js';
5
+ import { debugLog } from '../core/logger.js';
6
+ import { HASH_BUDGET_MS, MAX_CONTENT_HASHES, MAX_HASHED_FILE_BYTES, RE_SECRET_FILE } from './constants/git.constants.js';
7
+ /**
8
+ * Git's blob id for some bytes: sha1 over `blob <byte length>\0` and the bytes.
9
+ * The length is bytes, not characters: "é" is one character and two bytes.
10
+ *
11
+ * @param bytes - The file's bytes.
12
+ * @returns 40 hex characters, equal to `git hash-object` for the same file.
13
+ */
14
+ export function blobSha(bytes) {
15
+ return createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
16
+ }
17
+ /**
18
+ * One-way content ids of the files a turn's tools named, in a folder with no git.
19
+ *
20
+ * Reads only the named files, in memory, and keeps nothing but the id: no
21
+ * content reaches an event, a log or the queue. Fails open per file.
22
+ *
23
+ * @param files - Absolute paths, in priority order (edits first, then reads).
24
+ * @param root - The session folder; paths are reported relative to it.
25
+ * @param budgetMs - Time allowed; the files not reached by then are skipped.
26
+ * @returns Up to MAX_CONTENT_HASHES `{path, blob_sha}`; unreadable, oversized or outside-root files are skipped.
27
+ */
28
+ export async function contentHashes(files, root, budgetMs = HASH_BUDGET_MS) {
29
+ const out = [];
30
+ // Raced, as the process walk is: one read that hangs on a network mount must
31
+ // not hold the Stop hook. Node cannot cancel that read, so the CLI ends the
32
+ // process by force once the turn is queued (see `hasAbandonedWork`).
33
+ const hashed = await withinBudget(hashInto(out, files, root, performance.now() + budgetMs).then(() => true), budgetMs);
34
+ if (!hashed)
35
+ debugLog('hashing the named files ran out of time');
36
+ // A copy: the abandoned loop may still push after the deadline.
37
+ return out.slice();
38
+ }
39
+ async function hashInto(out, files, root, deadline) {
40
+ // Both sides canonical: $TMPDIR is /var/... where a cwd is /private/var/...,
41
+ // and a lexical comparison would drop every file with no sign of why.
42
+ const realRoot = await fs.realpath(root).catch(() => undefined);
43
+ if (!realRoot)
44
+ return;
45
+ for (const file of new Set(files)) {
46
+ if (out.length >= MAX_CONTENT_HASHES || performance.now() >= deadline)
47
+ break;
48
+ // A one-way hash of a credentials file is still an oracle for a guessable one.
49
+ if (RE_SECRET_FILE.test(path.basename(file)))
50
+ continue;
51
+ try {
52
+ // A symlink inside the folder may point out of it: judge the real target.
53
+ const real = await fs.realpath(file);
54
+ const inside = path.relative(realRoot, real);
55
+ // Outside the session folder the path would ship the machine's layout.
56
+ if (!inside || inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside))
57
+ continue;
58
+ if (RE_SECRET_FILE.test(path.basename(real)))
59
+ continue;
60
+ const stat = await fs.stat(real);
61
+ if (!stat.isFile() || stat.size > MAX_HASHED_FILE_BYTES)
62
+ continue;
63
+ out.push({ path: inside.split(path.sep).join('/'), blob_sha: blobSha(await fs.readFile(real)) });
64
+ }
65
+ catch (error) {
66
+ debugLog('could not hash a named file:', error);
67
+ }
68
+ }
69
+ }
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The checkout a path lies in, as its real root.
3
+ *
4
+ * The path may name a file, or a directory a command is about to create, so the
5
+ * walk first climbs to a directory that exists. `stat`s only, no git: this runs
6
+ * on tool hooks, and for every directory a shell command names. Real, because a
7
+ * symlink inside one folder can lead into another tenant's checkout, and two
8
+ * spellings of one checkout are one candidate.
9
+ *
10
+ * @param target - Absolute file or directory path.
11
+ * @returns The canonical checkout root, or undefined outside any repository.
12
+ */
13
+ export declare function checkoutRootOf(target: string): Promise<string | undefined>;
14
+ /**
15
+ * The checkout a path lies in, and the path relative to it.
16
+ *
17
+ * The walk for `.git` starts from the real directory, not the spelling: a
18
+ * symlink into a checkout's subdirectory leads nowhere when walked up
19
+ * lexically, and the path is then made relative to where it really is.
20
+ *
21
+ * @param target - Absolute file or directory path.
22
+ * @returns The canonical root and the target relative to it, or undefined outside any repository.
23
+ */
24
+ export declare function checkoutOf(target: string): Promise<{
25
+ root: string;
26
+ relative: string;
27
+ } | undefined>;
@@ -0,0 +1,75 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { canonicalRoot } from '../config/root-config.js';
4
+ import { GATE_MAX_WALK_DEPTH } from './constants/git.constants.js';
5
+ import { findGitDir } from './gate-checkout.js';
6
+ /**
7
+ * The checkout a path lies in, as its real root.
8
+ *
9
+ * The path may name a file, or a directory a command is about to create, so the
10
+ * walk first climbs to a directory that exists. `stat`s only, no git: this runs
11
+ * on tool hooks, and for every directory a shell command names. Real, because a
12
+ * symlink inside one folder can lead into another tenant's checkout, and two
13
+ * spellings of one checkout are one candidate.
14
+ *
15
+ * @param target - Absolute file or directory path.
16
+ * @returns The canonical checkout root, or undefined outside any repository.
17
+ */
18
+ export async function checkoutRootOf(target) {
19
+ return (await checkoutOf(target))?.root;
20
+ }
21
+ /**
22
+ * The checkout a path lies in, and the path relative to it.
23
+ *
24
+ * The walk for `.git` starts from the real directory, not the spelling: a
25
+ * symlink into a checkout's subdirectory leads nowhere when walked up
26
+ * lexically, and the path is then made relative to where it really is.
27
+ *
28
+ * @param target - Absolute file or directory path.
29
+ * @returns The canonical root and the target relative to it, or undefined outside any repository.
30
+ */
31
+ export async function checkoutOf(target) {
32
+ const resolved = path.resolve(target);
33
+ // The target itself first: a symlink to a file lives in one checkout and
34
+ // points into another, and the one it points into is where the work lands.
35
+ const realTarget = await fs.realpath(resolved).catch(() => undefined);
36
+ const directory = realTarget === undefined ? await existingDirectory(resolved) : await directoryOf(realTarget);
37
+ if (directory === undefined)
38
+ return undefined;
39
+ const real = realTarget === undefined ? await fs.realpath(directory).catch(() => directory) : directory;
40
+ const location = await findGitDir(real);
41
+ if (!location)
42
+ return undefined;
43
+ const root = canonicalRoot(location.root);
44
+ const realPath = realTarget ?? path.join(real, path.relative(directory, resolved));
45
+ return { root, relative: path.relative(root, realPath) };
46
+ }
47
+ /**
48
+ * The directory an existing path is, or lies in.
49
+ *
50
+ * @param real - A real, existing path.
51
+ * @returns It, when a directory; else its parent.
52
+ */
53
+ async function directoryOf(real) {
54
+ const stat = await fs.stat(real).catch(() => undefined);
55
+ return stat?.isDirectory() ? real : path.dirname(real);
56
+ }
57
+ /**
58
+ * The nearest existing directory at or above a path.
59
+ *
60
+ * @param target - Absolute path.
61
+ * @returns The directory, or undefined when none could be found.
62
+ */
63
+ async function existingDirectory(target) {
64
+ let current = path.resolve(target);
65
+ for (let depth = 0; depth < GATE_MAX_WALK_DEPTH; depth++) {
66
+ const stat = await fs.stat(current).catch(() => undefined);
67
+ if (stat?.isDirectory())
68
+ return current;
69
+ const parent = path.dirname(current);
70
+ if (parent === current)
71
+ return undefined;
72
+ current = parent;
73
+ }
74
+ return undefined;
75
+ }